starfish-wal 3.0.0a20__tar.gz

starfish_wal-3.0.0a20/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: starfish-wal
+Version: 3.0.0a20
+Summary: Starfish WAL extension — append-only CRDT op-log document model (LWW register + RGA list + text) core, cross-language conformant with the TypeScript package
+Requires-Python: >=3.11
+Requires-Dist: starfish-protocol
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"

starfish_wal-3.0.0a20/README.md

@@ -0,0 +1,31 @@
+# starfish-wal (Python)
+
+Cross-language CRDT core for the [Starfish](https://github.com/Drakkar-Software/starfish)
+write-ahead-log document model.
+
+This package ships the deterministic clock + fold that mirrors the TypeScript
+`@drakkar.software/starfish-wal` package and conforms to the shared vectors in
+`tests/test-vectors/wal-crdt.json`. The fold is commutative, idempotent, and
+byte-identical across languages:
+
+- **LWW typed register** (`set` / `del`) — objects / scalar fields,
+- **RGA sequence** (`ins` / `rmv`) — ordered lists,
+- **text** — an RGA of single characters.
+
+```python
+from starfish_wal import WalCrdt
+
+crdt = WalCrdt()
+crdt.fold([
+    {"t": "set", "reg": "title", "clock": {"c": 1, "r": "a"}, "value": "Hello"},
+    {"t": "ins", "list": "body", "id": "1@a", "after": "", "clock": {"c": 2, "r": "a"}, "value": "h"},
+    {"t": "ins", "list": "body", "id": "2@a", "after": "1@a", "clock": {"c": 3, "r": "a"}, "value": "i"},
+])
+crdt.materialize()  # {"body": ["h", "i"], "title": "Hello"}
+crdt.text("body")   # "hi"
+```
+
+The client document-log layer (`WalDocument`: commit / materialize / snapshot)
+currently ships in the TypeScript package; Python parity is planned.
+
+Full reference: [`docs/ts/wal/01-overview.md`](../../../docs/ts/wal/01-overview.md)

starfish_wal-3.0.0a20/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "starfish-wal"
+version = "3.0.0a20"
+description = "Starfish WAL extension — append-only CRDT op-log document model (LWW register + RGA list + text) core, cross-language conformant with the TypeScript package"
+requires-python = ">=3.11"
+dependencies = [
+  "starfish-protocol",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+]
+
+[tool.uv.sources]
+starfish-protocol = { path = "../protocol", editable = true }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

starfish_wal-3.0.0a20/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

starfish_wal-3.0.0a20/starfish_wal/__init__.py

@@ -0,0 +1,27 @@
+"""starfish-wal — write-ahead-log / doc-diff collections with CRDT semantics.
+
+This package ships the deterministic, cross-language CRDT core (clock + fold)
+that mirrors ``@drakkar.software/starfish-wal`` and conforms to
+``tests/test-vectors/wal-crdt.json``. The client document-log layer
+(``WalDocument``: commit / materialize / snapshot) currently ships in the
+TypeScript package; Python parity is planned.
+"""
+
+from starfish_wal.clock import (
+    Clock,
+    LamportClock,
+    clock_greater,
+    compare_clocks,
+    derive_replica_id,
+)
+from starfish_wal.crdt import Op, WalCrdt
+
+__all__ = [
+    "Clock",
+    "LamportClock",
+    "clock_greater",
+    "compare_clocks",
+    "derive_replica_id",
+    "Op",
+    "WalCrdt",
+]

starfish_wal-3.0.0a20/starfish_wal/clock.py

@@ -0,0 +1,68 @@
+"""Causal clock for the WAL CRDT.
+
+Every CRDT op carries a :class:`Clock`: a Lamport counter ``c`` plus a stable,
+per-session ``replicaId`` ``r``. The pair ``(c, r)`` is a **total order with no
+ties** — two concurrent ops may share a counter but never a replica id, so the
+LWW tie-break is always decidable and byte-identical to the TypeScript
+implementation (Python compares strings by Unicode code point, matching the
+protocol's ``stable_stringify`` key sort).
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class Clock(TypedDict):
+    """A Lamport counter (``c``) tie-broken by a stable replica id (``r``)."""
+
+    c: int
+    r: str
+
+
+def _cmp_str(a: str, b: str) -> int:
+    # Python orders strings by Unicode code point already.
+    return (a > b) - (a < b)
+
+
+def compare_clocks(a: Clock, b: Clock) -> int:
+    """Total order over clocks: counter first, replica id second.
+
+    Returns a negative/positive int for ``a < b`` / ``a > b`` and ``0`` only when
+    the clocks are identical (i.e. the same op, given unique replica ids).
+    """
+    if a["c"] != b["c"]:
+        return a["c"] - b["c"]
+    return _cmp_str(a["r"], b["r"])
+
+
+def clock_greater(a: Clock, b: Clock) -> bool:
+    """True iff clock ``a`` strictly dominates ``b``."""
+    return compare_clocks(a, b) > 0
+
+
+class LamportClock:
+    """A monotonic Lamport clock for one replica."""
+
+    def __init__(self, replica_id: str, start: int = 0) -> None:
+        self.replica_id = replica_id
+        self._counter = start
+
+    @property
+    def value(self) -> int:
+        return self._counter
+
+    def tick(self) -> Clock:
+        """Advance and return the next clock to stamp on a local op."""
+        self._counter += 1
+        return {"c": self._counter, "r": self.replica_id}
+
+    def observe(self, clock: Clock) -> None:
+        """Advance past an observed clock (Lamport receive rule)."""
+        if clock["c"] > self._counter:
+            self._counter = clock["c"]
+
+
+def derive_replica_id(author_pub_hex: str, session_nonce: str) -> str:
+    """Stable, unique-per-session replica id from author key + session nonce."""
+    return f"{author_pub_hex}:{session_nonce}"

starfish_wal-3.0.0a20/starfish_wal/crdt.py

@@ -0,0 +1,237 @@
+"""The deterministic, op-based CRDT at the heart of ``starfish-wal``.
+
+This is the Python mirror of ``packages/ts/wal/src/crdt.ts``; both fold the same
+ops to byte-identical materialized state, locked by
+``tests/test-vectors/wal-crdt.json``. The fold is commutative (order-independent)
+and idempotent (re-applying an op is a structural no-op), so a server-reordered
+or retried op-log converges without a dedup set.
+
+Two CRDT shapes, addressed by name within one document:
+
+* **LWW typed register** (``set`` / ``del``) — objects / scalar fields; the value
+  is opaque JSON written whole, highest ``(clock)`` wins, ties broken on replica
+  id.
+* **RGA sequence** (``ins`` / ``rmv``) — ordered lists, and **text** as a
+  sequence of single-character values.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from .clock import Clock, _cmp_str, clock_greater, compare_clocks
+
+# An op is a JSON dict discriminated by ``t``: "set" | "del" | "ins" | "rmv".
+Op = dict[str, Any]
+
+
+class _Reg:
+    __slots__ = ("clock", "value", "deleted")
+
+    def __init__(self, clock: Clock, value: Any, deleted: bool) -> None:
+        self.clock = clock
+        self.value = value
+        self.deleted = deleted
+
+
+class _Node:
+    __slots__ = ("id", "after", "clock", "value", "deleted", "pending")
+
+    def __init__(
+        self, id: str, after: str, clock: Clock, value: Any, deleted: bool, pending: bool
+    ) -> None:
+        self.id = id
+        self.after = after
+        self.clock = clock
+        self.value = value
+        self.deleted = deleted
+        # True for a tombstone created by a ``rmv`` whose ``ins`` has not yet
+        # arrived: its after/clock/value are placeholders the insert fills in.
+        self.pending = pending
+
+
+class WalCrdt:
+    """A bag of named LWW registers and named RGA sequences."""
+
+    def __init__(self) -> None:
+        self._regs: dict[str, _Reg] = {}
+        self._lists: dict[str, dict[str, _Node]] = {}
+
+    # ── ingest ──────────────────────────────────────────────────────────────────
+
+    def apply(self, op: Op) -> None:
+        """Apply one op (commutative and idempotent)."""
+        kind = op["t"]
+        if kind == "set":
+            self._apply_reg(op["reg"], op["clock"], op["value"], False)
+        elif kind == "del":
+            self._apply_reg(op["reg"], op["clock"], None, True)
+        elif kind == "ins":
+            self._apply_ins(op)
+        elif kind == "rmv":
+            self._apply_rmv(op)
+
+    def fold(self, ops: Iterable[Op]) -> None:
+        for op in ops:
+            self.apply(op)
+
+    def _apply_reg(self, reg: str, clock: Clock, value: Any, deleted: bool) -> None:
+        cur = self._regs.get(reg)
+        # LWW: keep the highest clock; equal clock => identical op => no-op.
+        if cur is not None and not clock_greater(clock, cur.clock):
+            return
+        self._regs[reg] = _Reg(clock, value, deleted)
+
+    def _apply_ins(self, op: Op) -> None:
+        nodes = self._lists.setdefault(op["list"], {})
+        existing = nodes.get(op["id"])
+        if existing is not None:
+            # If a ``rmv`` arrived first it left a *pending* tombstone with no
+            # real position; the insert now supplies the true after/clock/value
+            # (the element stays deleted). This keeps the fold commutative under
+            # out-of-order delivery — the placeholder must not own the anchor.
+            # A non-pending hit is a verbatim replay => no-op.
+            if existing.pending:
+                existing.after = op["after"]
+                existing.clock = op["clock"]
+                existing.value = op["value"]
+                existing.pending = False
+            return
+        nodes[op["id"]] = _Node(op["id"], op["after"], op["clock"], op["value"], False, False)
+
+    def _apply_rmv(self, op: Op) -> None:
+        # The remove may be delivered before any insert; create the list so the
+        # *pending* tombstone placeholder survives until the insert fills in its
+        # real position (see _apply_ins). Its ``after: ""`` never owns the anchor.
+        nodes = self._lists.setdefault(op["list"], {})
+        node = nodes.get(op["id"])
+        if node is None:
+            nodes[op["id"]] = _Node(op["id"], "", op["clock"], None, True, True)
+            return
+        node.deleted = True
+
+    # ── projection ──────────────────────────────────────────────────────────────
+
+    def _list_order(self, nodes: dict[str, _Node]) -> list[_Node]:
+        # RGA: siblings sharing an ``after`` anchor are ordered by DESCENDING
+        # clock (newest-first); pre-order DFS from the head ("").
+        from functools import cmp_to_key
+
+        children: dict[str, list[_Node]] = {}
+        for node in nodes.values():
+            children.setdefault(node.after, []).append(node)
+        for bucket in children.values():
+            # Descending clock; break exact-clock ties on the unique element id so
+            # the order is total even for malformed ops with decoupled id/clock.
+            bucket.sort(
+                key=cmp_to_key(
+                    lambda a, b: compare_clocks(b.clock, a.clock) or _cmp_str(b.id, a.id)
+                )
+            )
+
+        # Iterative pre-order DFS (an explicit stack, NOT recursion): a long
+        # linear chain — e.g. a multi-thousand-character text run — would
+        # otherwise blow Python's recursion limit. Push each bucket reversed so
+        # siblings pop in bucket order.
+        out: list[_Node] = []
+        stack: list[_Node] = list(reversed(children.get("", [])))
+        while stack:
+            node = stack.pop()
+            out.append(node)
+            stack.extend(reversed(children.get(node.id, [])))
+        return out
+
+    def list_values(self, list_name: str) -> list[Any]:
+        """Live element values of a named list, in RGA order."""
+        nodes = self._lists.get(list_name)
+        if not nodes:
+            return []
+        return [n.value for n in self._list_order(nodes) if not n.deleted]
+
+    def list_ids(self, list_name: str) -> list[str]:
+        """Live element ids of a named list, in RGA order."""
+        nodes = self._lists.get(list_name)
+        if not nodes:
+            return []
+        return [n.id for n in self._list_order(nodes) if not n.deleted]
+
+    def text(self, list_name: str) -> str:
+        """A named list materialized as a string (1-char element values)."""
+        return "".join(v for v in self.list_values(list_name) if isinstance(v, str))
+
+    def get_register(self, reg: str) -> Any:
+        cur = self._regs.get(reg)
+        if cur is None or cur.deleted:
+            return None
+        return cur.value
+
+    def materialize(self) -> dict[str, Any]:
+        """Project the current document (live registers + lists as arrays)."""
+        keys: set[str] = set()
+        for reg, st in self._regs.items():
+            if not st.deleted:
+                keys.add(reg)
+        keys.update(self._lists.keys())
+        out: dict[str, Any] = {}
+        for key in sorted(keys):
+            reg = self._regs.get(key)
+            if reg is not None and not reg.deleted:
+                out[key] = reg.value
+            else:
+                out[key] = self.list_values(key)
+        return out
+
+    # ── snapshot state ──────────────────────────────────────────────────────────
+
+    def list_names(self) -> list[str]:
+        """Names of all RGA lists currently present (live or tombstoned)."""
+        return sorted(self._lists.keys())
+
+    def export_state(self) -> dict[str, Any]:
+        """Export full CRDT state (tombstones included) for a snapshot. Clocks
+        are deep-copied so an exported state (and ``clone``) never aliases the
+        live document's nested clock dicts."""
+        regs = {
+            reg: {"clock": dict(st.clock), "value": st.value, "deleted": st.deleted}
+            for reg, st in self._regs.items()
+        }
+        lists = {
+            name: [
+                {
+                    "id": n.id,
+                    "after": n.after,
+                    "clock": dict(n.clock),
+                    "value": n.value,
+                    "deleted": n.deleted,
+                    "pending": n.pending,
+                }
+                for n in nodes.values()
+            ]
+            for name, nodes in self._lists.items()
+        }
+        return {"v": 1, "regs": regs, "lists": lists}
+
+    def import_state(self, state: dict[str, Any]) -> None:
+        """Replace state from a snapshot's ``state`` (bootstrap readers)."""
+        self._regs = {
+            reg: _Reg(dict(st["clock"]), st["value"], st["deleted"])
+            for reg, st in state["regs"].items()
+        }
+        self._lists = {}
+        for name, nodes in state["lists"].items():
+            self._lists[name] = {
+                n["id"]: _Node(
+                    n["id"],
+                    n["after"],
+                    dict(n["clock"]),
+                    n["value"],
+                    n["deleted"],
+                    n.get("pending", False),
+                )
+                for n in nodes
+            }
+
+    def clone(self) -> "WalCrdt":
+        c = WalCrdt()
+        c.import_state(self.export_state())
+        return c

starfish_wal-3.0.0a20/starfish_wal.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: starfish-wal
+Version: 3.0.0a20
+Summary: Starfish WAL extension — append-only CRDT op-log document model (LWW register + RGA list + text) core, cross-language conformant with the TypeScript package
+Requires-Python: >=3.11
+Requires-Dist: starfish-protocol
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"

starfish_wal-3.0.0a20/starfish_wal.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+starfish_wal/__init__.py
+starfish_wal/clock.py
+starfish_wal/crdt.py
+starfish_wal.egg-info/PKG-INFO
+starfish_wal.egg-info/SOURCES.txt
+starfish_wal.egg-info/dependency_links.txt
+starfish_wal.egg-info/requires.txt
+starfish_wal.egg-info/top_level.txt
+tests/test_clock.py
+tests/test_crdt.py
+tests/test_vectors.py

starfish_wal-3.0.0a20/starfish_wal.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

starfish_wal-3.0.0a20/starfish_wal.egg-info/requires.txt

@@ -0,0 +1,4 @@
+starfish-protocol
+
+[dev]
+pytest>=7.0

starfish_wal-3.0.0a20/starfish_wal.egg-info/top_level.txt

@@ -0,0 +1 @@
+starfish_wal

starfish_wal-3.0.0a20/tests/test_clock.py

@@ -0,0 +1,36 @@
+from starfish_wal import (
+    LamportClock,
+    clock_greater,
+    compare_clocks,
+    derive_replica_id,
+)
+
+
+def _sign(n: int) -> int:
+    return (n > 0) - (n < 0)
+
+
+def test_orders_by_counter_first():
+    assert _sign(compare_clocks({"c": 1, "r": "z"}, {"c": 2, "r": "a"})) == -1
+    assert clock_greater({"c": 3, "r": "a"}, {"c": 2, "r": "z"})
+
+
+def test_ties_break_on_replica_id():
+    assert _sign(compare_clocks({"c": 2, "r": "a"}, {"c": 2, "r": "b"})) == -1
+    assert _sign(compare_clocks({"c": 2, "r": "b"}, {"c": 2, "r": "a"})) == 1
+
+
+def test_identical_clocks_compare_equal():
+    assert compare_clocks({"c": 7, "r": "abc"}, {"c": 7, "r": "abc"}) == 0
+
+
+def test_lamport_tick_and_observe():
+    clk = LamportClock("r1")
+    assert clk.tick() == {"c": 1, "r": "r1"}
+    assert clk.tick() == {"c": 2, "r": "r1"}
+    clk.observe({"c": 10, "r": "other"})
+    assert clk.tick() == {"c": 11, "r": "r1"}
+
+
+def test_replica_id_is_session_unique():
+    assert derive_replica_id("pub", "s1") != derive_replica_id("pub", "s2")

starfish_wal-3.0.0a20/tests/test_crdt.py

@@ -0,0 +1,179 @@
+from starfish_wal import WalCrdt, compare_clocks
+from functools import cmp_to_key
+
+
+def _fold(ops):
+    c = WalCrdt()
+    c.fold(ops)
+    return c
+
+
+def _perms(ops):
+    return [
+        ops,
+        list(reversed(ops)),
+        sorted(ops, key=cmp_to_key(lambda a, b: compare_clocks(a["clock"], b["clock"]))),
+        sorted(ops, key=cmp_to_key(lambda a, b: compare_clocks(b["clock"], a["clock"]))),
+    ]
+
+
+def test_lww_highest_clock_wins():
+    ops = [
+        {"t": "set", "reg": "title", "clock": {"c": 1, "r": "a"}, "value": "draft"},
+        {"t": "set", "reg": "title", "clock": {"c": 2, "r": "a"}, "value": "final"},
+        {"t": "set", "reg": "title", "clock": {"c": 2, "r": "b"}, "value": "other"},
+    ]
+    for p in _perms(ops):
+        assert _fold(p).materialize() == {"title": "other"}
+
+
+def test_delete_tombstone_and_resurrect():
+    ops = [
+        {"t": "set", "reg": "x", "clock": {"c": 1, "r": "a"}, "value": "v1"},
+        {"t": "del", "reg": "x", "clock": {"c": 2, "r": "a"}},
+        {"t": "set", "reg": "x", "clock": {"c": 3, "r": "a"}, "value": "v2"},
+    ]
+    for p in _perms(ops):
+        assert _fold(p).materialize() == {"x": "v2"}
+
+
+def test_stale_delete_cannot_erase_newer_set():
+    c = _fold([
+        {"t": "set", "reg": "k", "clock": {"c": 5, "r": "a"}, "value": "keep"},
+        {"t": "del", "reg": "k", "clock": {"c": 2, "r": "b"}},
+    ])
+    assert c.get_register("k") == "keep"
+
+
+def test_rga_concurrent_head_insert_tiebreak():
+    ops = [
+        {"t": "ins", "list": "l", "id": "1@a", "after": "", "clock": {"c": 1, "r": "a"}, "value": "A"},
+        {"t": "ins", "list": "l", "id": "1@b", "after": "", "clock": {"c": 1, "r": "b"}, "value": "B"},
+        {"t": "ins", "list": "l", "id": "2@a", "after": "1@a", "clock": {"c": 2, "r": "a"}, "value": "C"},
+    ]
+    for p in _perms(ops):
+        assert _fold(p).list_values("l") == ["B", "A", "C"]
+
+
+def test_rga_delete_keeps_anchor():
+    ops = [
+        {"t": "ins", "list": "l", "id": "1@a", "after": "", "clock": {"c": 1, "r": "a"}, "value": "x"},
+        {"t": "ins", "list": "l", "id": "2@a", "after": "1@a", "clock": {"c": 2, "r": "a"}, "value": "y"},
+        {"t": "rmv", "list": "l", "id": "1@a", "clock": {"c": 3, "r": "a"}},
+    ]
+    for p in _perms(ops):
+        assert _fold(p).list_values("l") == ["y"]
+
+
+def test_rga_insert_idempotent():
+    ins = {"t": "ins", "list": "l", "id": "1@a", "after": "", "clock": {"c": 1, "r": "a"}, "value": "x"}
+    assert _fold([ins, ins, ins]).list_values("l") == ["x"]
+
+
+def test_remove_before_insert():
+    c = _fold([
+        {"t": "rmv", "list": "l", "id": "1@a", "clock": {"c": 2, "r": "a"}},
+        {"t": "ins", "list": "l", "id": "1@a", "after": "", "clock": {"c": 1, "r": "a"}, "value": "x"},
+    ])
+    assert c.list_values("l") == []
+
+
+def test_remove_before_insert_with_live_descendant():
+    # Regression: the rmv-before-ins tombstone must not be mis-anchored at the
+    # head and drag its live subtree (3@a) to the wrong position.
+    ops = [
+        {"t": "ins", "list": "l", "id": "1@a", "after": "", "clock": {"c": 1, "r": "a"}, "value": "A"},
+        {"t": "ins", "list": "l", "id": "2@a", "after": "1@a", "clock": {"c": 2, "r": "a"}, "value": "B"},
+        {"t": "rmv", "list": "l", "id": "2@a", "clock": {"c": 3, "r": "a"}},
+        {"t": "ins", "list": "l", "id": "3@a", "after": "2@a", "clock": {"c": 4, "r": "a"}, "value": "C"},
+    ]
+    for p in _perms(ops):
+        assert _fold(p).list_values("l") == ["A", "C"]
+
+
+def test_sibling_identical_clock_orders_by_id():
+    # Malformed ops (id decoupled from clock) sharing an exact clock must still
+    # converge via the id tie-break, independent of fold order.
+    ops = [
+        {"t": "ins", "list": "l", "id": "A", "after": "", "clock": {"c": 1, "r": "x"}, "value": "first"},
+        {"t": "ins", "list": "l", "id": "B", "after": "", "clock": {"c": 1, "r": "x"}, "value": "second"},
+    ]
+    assert _fold(ops).list_values("l") == ["second", "first"]
+    assert _fold(list(reversed(ops))).list_values("l") == ["second", "first"]
+
+
+def test_text_materializes_as_string():
+    c = _fold([
+        {"t": "ins", "list": "t", "id": "1@a", "after": "", "clock": {"c": 1, "r": "a"}, "value": "h"},
+        {"t": "ins", "list": "t", "id": "2@a", "after": "1@a", "clock": {"c": 2, "r": "a"}, "value": "i"},
+    ])
+    assert c.text("t") == "hi"
+
+
+def test_state_round_trip_with_tombstones():
+    src = _fold([
+        {"t": "set", "reg": "a", "clock": {"c": 1, "r": "a"}, "value": 1},
+        {"t": "ins", "list": "l", "id": "1@a", "after": "", "clock": {"c": 2, "r": "a"}, "value": "x"},
+        {"t": "rmv", "list": "l", "id": "1@a", "clock": {"c": 3, "r": "a"}},
+    ])
+    restored = WalCrdt()
+    restored.import_state(src.export_state())
+    assert restored.materialize() == src.materialize()
+    restored.apply({"t": "ins", "list": "l", "id": "2@a", "after": "1@a", "clock": {"c": 4, "r": "a"}, "value": "y"})
+    assert restored.list_values("l") == ["y"]
+
+
+def test_clone_is_independent():
+    src = _fold([{"t": "set", "reg": "a", "clock": {"c": 1, "r": "a"}, "value": 1}])
+    copy = src.clone()
+    copy.apply({"t": "set", "reg": "a", "clock": {"c": 2, "r": "a"}, "value": 2})
+    assert src.get_register("a") == 1
+    assert copy.get_register("a") == 2
+
+
+def test_export_deep_copies_clocks():
+    src = _fold([
+        {"t": "set", "reg": "a", "clock": {"c": 5, "r": "a"}, "value": 1},
+        {"t": "ins", "list": "l", "id": "1@a", "after": "", "clock": {"c": 6, "r": "a"}, "value": "x"},
+    ])
+    exported = src.export_state()
+    # Mutate the exported clocks in place — the live document must be unaffected.
+    exported["regs"]["a"]["clock"]["c"] = 999
+    exported["lists"]["l"][0]["clock"]["c"] = 999
+    after = src.export_state()
+    assert after["regs"]["a"]["clock"]["c"] == 5
+    assert after["lists"]["l"][0]["clock"]["c"] == 6
+
+
+def test_export_state_idempotent_under_refold():
+    ops = [
+        {"t": "set", "reg": "a", "clock": {"c": 1, "r": "a"}, "value": 1},
+        {"t": "ins", "list": "l", "id": "1@a", "after": "", "clock": {"c": 2, "r": "a"}, "value": "x"},
+        {"t": "rmv", "list": "l", "id": "1@a", "clock": {"c": 3, "r": "a"}},
+    ]
+    c = WalCrdt()
+    c.fold(ops)
+    before = c.export_state()
+    c.fold(ops)
+    assert c.export_state() == before
+
+
+def test_materializes_long_linear_chain_without_recursion_error():
+    # A long text run is a deep RGA chain; _list_order must not recurse per node
+    # (Python's default recursion limit is ~1000).
+    n = 50_000
+    ops = [
+        {
+            "t": "ins",
+            "list": "body",
+            "id": f"{i}@a",
+            "after": "" if i == 0 else f"{i - 1}@a",
+            "clock": {"c": i + 1, "r": "a"},
+            "value": "x",
+        }
+        for i in range(n)
+    ]
+    c = WalCrdt()
+    c.fold(ops)
+    assert len(c.list_values("body")) == n
+    assert len(c.text("body")) == n

starfish_wal-3.0.0a20/tests/test_vectors.py

@@ -0,0 +1,47 @@
+"""Cross-language conformance: the Python CRDT must fold the shared vectors to
+the same materialized state as the TypeScript implementation."""
+
+import json
+from functools import cmp_to_key
+from pathlib import Path
+
+from starfish_wal import WalCrdt, compare_clocks
+
+VECTORS = json.loads(
+    (Path(__file__).resolve().parents[4] / "tests" / "test-vectors" / "wal-crdt.json").read_text()
+)
+
+
+def _sign(n: int) -> int:
+    return (n > 0) - (n < 0)
+
+
+def test_clock_total_order():
+    for case in VECTORS["clockOrder"]:
+        assert _sign(compare_clocks(case["a"], case["b"])) == case["sign"]
+
+
+def test_fold_cases_converge_and_are_idempotent():
+    for f in VECTORS["fold"]:
+        ops = f["ops"]
+        expected = f["expected"]
+
+        forward = WalCrdt()
+        forward.fold(ops)
+        assert forward.materialize() == expected, f["name"]
+
+        reverse = WalCrdt()
+        reverse.fold(list(reversed(ops)))
+        assert reverse.materialize() == expected, f["name"]
+
+        by_clock = WalCrdt()
+        by_clock.fold(sorted(ops, key=cmp_to_key(lambda a, b: compare_clocks(a["clock"], b["clock"]))))
+        assert by_clock.materialize() == expected, f["name"]
+
+        twice = WalCrdt()
+        twice.fold(ops)
+        twice.fold(ops)
+        assert twice.materialize() == expected, f["name"]
+
+        for list_name, text in f.get("expectedText", {}).items():
+            assert forward.text(list_name) == text, f["name"]