statepatch 0.1.0__tar.gz

statepatch-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+node_modules
+.next
+dist
+dist-test
+.wrangler
+.DS_Store
+.env
+.env.local
+.dev.vars
+*.tsbuildinfo
+.harness-runs
+*.rdb
+.source
+next-env.d.ts
+__pycache__
+.venv
+.pytest_cache
+*.egg-info
+
+# agentdoc mounted docs
+/d[0-9]*.md
+/doc_*.md
+apps/docs/.docs
+/.agentdoc/
+/.deepsec/
+.vercel
+.env*

statepatch-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.5
+Name: statepatch
+Version: 0.1.0
+Summary: Immer-style ops over a plain JSON tree: observables that emit every mutation as an op
+Project-URL: Repository, https://github.com/assistant-ui/harness-sdk
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# statepatch
+
+Immer-style ops over a plain JSON tree.
+
+`observable(initial)` wraps one value: `.value` reads it, every mutation applies to the tree and emits the matching op (`replace` / `add` / `remove`) to subscribers. Observables compose: an observable stored inside another mounts its op stream at that path.
+
+```python
+from statepatch import observable
+
+state = observable({"runs": []})
+state.subscribe(print)
+
+run = observable({"runId": "r1", "queue": []})
+state["runs"].append(run)          # add op at ["runs", 0]
+run["queue"].append({"id": "q1"})  # forwarded as add at ["runs", 0, "queue", 0]
+state["runs"].pop(0)               # remove op; run is detached and reusable
+```

statepatch-0.1.0/README.md

@@ -0,0 +1,17 @@
+# statepatch
+
+Immer-style ops over a plain JSON tree.
+
+`observable(initial)` wraps one value: `.value` reads it, every mutation applies to the tree and emits the matching op (`replace` / `add` / `remove`) to subscribers. Observables compose: an observable stored inside another mounts its op stream at that path.
+
+```python
+from statepatch import observable
+
+state = observable({"runs": []})
+state.subscribe(print)
+
+run = observable({"runId": "r1", "queue": []})
+state["runs"].append(run)          # add op at ["runs", 0]
+run["queue"].append({"id": "q1"})  # forwarded as add at ["runs", 0, "queue", 0]
+state["runs"].pop(0)               # remove op; run is detached and reusable
+```

statepatch-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "statepatch"
+version = "0.1.0"
+description = "Immer-style ops over a plain JSON tree: observables that emit every mutation as an op"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/assistant-ui/harness-sdk"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/statepatch"]

statepatch-0.1.0/src/statepatch/__init__.py

@@ -0,0 +1,524 @@
+"""Immer-style ops over a plain JSON tree.
+
+An ``Observable`` wraps one value: ``.value`` reads a plain snapshot, every
+mutation applies to the tree and emits the matching ``Op`` to subscribers.
+Observables compose: an observable stored inside another mounts its op
+stream at that path; removing it detaches it, live and reusable.
+"""
+
+import math
+from datetime import datetime
+from typing import Any, Callable, Iterator, NamedTuple
+
+Segment = str | int
+Path = tuple[Segment, ...]
+
+
+class Op(NamedTuple):
+    kind: str  # "replace" | "add" | "remove"
+    path: Path
+    value: Any = None
+
+
+Listener = Callable[[Op], None]
+
+_MAX_SAFE_INT = 2**53 - 1
+_MISSING: Any = object()
+
+
+def _snapshot(node: Any) -> Any:
+    if isinstance(node, Observable):
+        return _snapshot(node._state)
+    if isinstance(node, dict):
+        return {key: _snapshot(item) for key, item in node.items()}
+    if isinstance(node, list):
+        return [_snapshot(item) for item in node]
+    return node
+
+
+def plain(value: Any) -> Any:
+    """Resolve a proxy or observable to a plain snapshot; pass anything else through."""
+    if isinstance(value, Proxy):
+        _owner, _rel, node = value._target()
+        return _snapshot(node)
+    if isinstance(value, Observable):
+        return _snapshot(value._state)
+    return value
+
+
+def _adopt(value: Any, base: Path) -> tuple[Any, list[tuple[Path, "Observable"]]]:
+    """Validated deep copy keeping ``Observable`` nodes in place; returns the
+    stored tree and the mount points found inside it (paths rooted at ``base``)."""
+    mounts: list[tuple[Path, Observable]] = []
+
+    def walk(value: Any, path: Path) -> Any:
+        if isinstance(value, Observable):
+            mounts.append((path, value))
+            return value
+        if isinstance(value, Proxy):
+            value = plain(value)
+        if isinstance(value, bool) or value is None or isinstance(value, str):
+            return value
+        if isinstance(value, float):
+            if math.isnan(value) or math.isinf(value):
+                raise ValueError(f"{value!r} is not wire-encodable; floats must be finite")
+            return value
+        if isinstance(value, int):
+            if abs(value) > _MAX_SAFE_INT:
+                raise ValueError(
+                    f"integer {value} exceeds the JS safe range (|n| <= 2**53-1); send it as a string"
+                )
+            return value
+        if isinstance(value, datetime):
+            if value.tzinfo is None or value.tzinfo.utcoffset(value) is None:
+                raise ValueError("naive datetime is not wire-encodable; attach a timezone")
+            return value
+        if isinstance(value, (list, tuple)):
+            return [walk(item, path + (i,)) for i, item in enumerate(value)]
+        if isinstance(value, dict):
+            out: dict[str, Any] = {}
+            for key, item in value.items():
+                if not isinstance(key, str):
+                    raise TypeError(f"object keys must be strings, got {type(key).__name__}")
+                out[key] = walk(item, path + (key,))
+            return out
+        raise TypeError(f"{type(value).__name__} is not wire-encodable")
+
+    return walk(value, base), mounts
+
+
+def _index(container: Any, key: Any) -> Any:
+    if isinstance(container, list) and isinstance(key, int) and key < 0:
+        return key + len(container)
+    return key
+
+
+class Observable:
+    __slots__ = ("_state", "_listeners", "_mounts", "_parent")
+
+    def __init__(self, initial: Any = None) -> None:
+        if isinstance(initial, Observable):
+            raise TypeError("an observable cannot wrap another observable; nest it inside a container")
+        self._listeners: list[Listener] = []
+        self._mounts: dict[int, tuple[Observable, Path, Callable[[], None]]] = {}
+        self._parent: Observable | None = None
+        stored, mounts = _adopt(initial, ())
+        self._admit(mounts)
+        self._state = stored
+        for path, child in mounts:
+            self._attach(child, path)
+
+    @property
+    def value(self) -> Any:
+        return _snapshot(self._state)
+
+    @value.setter
+    def value(self, value: Any) -> None:
+        if isinstance(value, Observable):
+            raise TypeError("an observable cannot wrap another observable; nest it inside a container")
+        stored, mounts = _adopt(value, ())
+        self._admit(mounts, ())
+        for child, _path, unsubscribe in list(self._mounts.values()):
+            unsubscribe()
+            child._parent = None
+        self._mounts.clear()
+        self._state = stored
+        for path, child in mounts:
+            self._attach(child, path)
+        self._emit(Op("replace", (), _snapshot(stored)))
+
+    def subscribe(self, listener: Listener) -> Callable[[], None]:
+        self._listeners.append(listener)
+
+        def unsubscribe() -> None:
+            if listener in self._listeners:
+                self._listeners.remove(listener)
+
+        return unsubscribe
+
+    def _emit(self, op: Op) -> None:
+        for listener in list(self._listeners):
+            listener(op)
+
+    def _admit(
+        self,
+        mounts: list[tuple[Path, "Observable"]],
+        detach_root: Path | None = None,
+        seen: set[int] | None = None,
+    ) -> None:
+        """Validate pending mounts before any tree mutation; ``detach_root``
+        exempts children this write is about to detach from ``self``."""
+        seen = seen if seen is not None else set()
+        for _path, child in mounts:
+            if id(child) in seen:
+                raise ValueError("observable appears more than once in one write")
+            seen.add(id(child))
+            if child._parent is not None:
+                current = self._mounts.get(id(child))
+                freed = (
+                    detach_root is not None
+                    and current is not None
+                    and current[1][: len(detach_root)] == detach_root
+                )
+                if not freed:
+                    raise ValueError("observable is already mounted; detach it first")
+            node: Observable | None = self
+            while node is not None:
+                if node is child:
+                    raise ValueError("mounting this observable would create a cycle")
+                node = node._parent
+
+    def _attach(self, child: "Observable", path: Path) -> None:
+        if child._parent is not None:
+            raise ValueError("observable is already mounted; detach it first")
+        node: Observable | None = self
+        while node is not None:
+            if node is child:
+                raise ValueError("mounting this observable would create a cycle")
+            node = node._parent
+        child._parent = self
+        unsubscribe = child.subscribe(lambda op, child=child: self._forward(child, op))
+        self._mounts[id(child)] = (child, path, unsubscribe)
+
+    def _forward(self, child: "Observable", op: Op) -> None:
+        entry = self._mounts.get(id(child))
+        if entry is None:
+            return
+        _child, path, _unsubscribe = entry
+        self._emit(Op(op.kind, path + op.path, op.value))
+
+    def _detach_under(self, path: Path) -> None:
+        for key, (child, mount_path, unsubscribe) in list(self._mounts.items()):
+            if mount_path[: len(path)] == path:
+                unsubscribe()
+                child._parent = None
+                del self._mounts[key]
+
+    def _shift(self, parent: Path, start: int, delta: int) -> None:
+        depth = len(parent)
+        for key, (child, path, unsubscribe) in list(self._mounts.items()):
+            if (
+                len(path) > depth
+                and path[:depth] == parent
+                and isinstance(path[depth], int)
+                and path[depth] >= start
+            ):
+                self._mounts[key] = (
+                    child,
+                    parent + (path[depth] + delta,) + path[depth + 1 :],
+                    unsubscribe,
+                )
+
+    def _target(self, path: Path) -> tuple["Observable", Path, Any]:
+        """Deepest observable owning ``path``, the path relative to it, and the node there."""
+        node = self._state
+        for i, segment in enumerate(path):
+            if isinstance(node, Observable):
+                return node._target(path[i:])
+            node = node[segment]
+        if isinstance(node, Observable):
+            return node._target(())
+        return self, path, node
+
+    def __getitem__(self, key: Any) -> Any:
+        return Proxy(self, ())[key]
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        Proxy(self, ())[key] = value
+
+    def __delitem__(self, key: Any) -> None:
+        proxy = Proxy(self, ())
+        del proxy[key]
+
+    def __contains__(self, item: Any) -> bool:
+        return item in Proxy(self, ())
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(Proxy(self, ()))
+
+    def __len__(self) -> int:
+        return len(Proxy(self, ()))
+
+    def __repr__(self) -> str:
+        return f"observable({self.value!r})"
+
+    def append(self, item: Any) -> None:
+        Proxy(self, ()).append(item)
+
+    def insert(self, index: int, item: Any) -> None:
+        Proxy(self, ()).insert(index, item)
+
+    def pop(self, *args: Any) -> Any:
+        return Proxy(self, ()).pop(*args)
+
+    def remove(self, item: Any) -> None:
+        Proxy(self, ()).remove(item)
+
+    def clear(self) -> None:
+        Proxy(self, ()).clear()
+
+    def extend(self, items: Any) -> None:
+        Proxy(self, ()).extend(items)
+
+    def update(self, other: Any) -> None:
+        Proxy(self, ()).update(other)
+
+    def get(self, key: Any, default: Any = None) -> Any:
+        return Proxy(self, ()).get(key, default)
+
+    def setdefault(self, key: Any, default: Any = None) -> Any:
+        return Proxy(self, ()).setdefault(key, default)
+
+    def keys(self):
+        return Proxy(self, ()).keys()
+
+    def values(self):
+        return Proxy(self, ()).values()
+
+    def items(self):
+        return Proxy(self, ()).items()
+
+
+def observable(initial: Any = None) -> Observable:
+    """A mini statewire: ``.value`` reads it, every mutation is an op."""
+    return Observable(initial)
+
+
+class Proxy:
+    """Mutation cursor into an observable's tree; reads resolve live, writes
+    apply and record ops on the owning (deepest mounted) observable."""
+
+    __slots__ = ("_root", "_path")
+
+    def __init__(self, root: Observable, path: Path) -> None:
+        self._root = root
+        self._path = path
+
+    def _target(self) -> tuple[Observable, Path, Any]:
+        return self._root._target(self._path)
+
+    def __getitem__(self, key: Any) -> Any:
+        _owner, _rel, node = self._target()
+        key = _index(node, key)
+        value = node[key]
+        if isinstance(value, (dict, list, Observable)):
+            return Proxy(self._root, self._path + (key,))
+        return value
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        owner, rel, container = self._target()
+        key = _index(container, key)
+        if isinstance(container, dict) and not isinstance(key, str):
+            raise TypeError(f"object keys must be strings, got {type(key).__name__}")
+        if isinstance(container, list) and (
+            isinstance(key, bool) or not isinstance(key, int)
+        ):
+            raise TypeError(f"list indices must be integers, got {type(key).__name__}")
+        old = (
+            container.get(key, _MISSING)
+            if isinstance(container, dict)
+            else container[key]
+        )
+        path = rel + (key,)
+        if isinstance(old, str) and isinstance(value, str) and value.startswith(old):
+            if value == old:
+                return
+            container[key] = value
+            owner._emit(Op("add", path + (len(old),), value[len(old) :]))
+            return
+        stored, mounts = _adopt(value, path)
+        owner._admit(mounts, path)
+        owner._detach_under(path)
+        container[key] = stored
+        for mount_path, child in mounts:
+            owner._attach(child, mount_path)
+        owner._emit(Op("replace", path, _snapshot(stored)))
+
+    def append(self, item: Any) -> None:
+        owner, rel, container = self._target()
+        if not isinstance(container, list):
+            raise TypeError(f"append on non-list at path {list(self._path)!r}")
+        index = len(container)
+        path = rel + (index,)
+        stored, mounts = _adopt(item, path)
+        owner._admit(mounts)
+        container.append(stored)
+        for mount_path, child in mounts:
+            owner._attach(child, mount_path)
+        owner._emit(Op("add", path, _snapshot(stored)))
+
+    def insert(self, index: int, item: Any) -> None:
+        owner, rel, container = self._target()
+        if not isinstance(container, list):
+            raise TypeError(f"insert on non-list at path {list(self._path)!r}")
+        index = max(0, min(index + len(container) if index < 0 else index, len(container)))
+        path = rel + (index,)
+        stored, mounts = _adopt(item, path)
+        owner._admit(mounts)
+        owner._shift(rel, index, 1)
+        container.insert(index, stored)
+        for mount_path, child in mounts:
+            owner._attach(child, mount_path)
+        owner._emit(Op("add", path, _snapshot(stored)))
+
+    def _remove_at(
+        self, owner: Observable, rel: Path, container: list, index: int
+    ) -> Any:
+        value = _snapshot(container[index])
+        path = rel + (index,)
+        owner._detach_under(path)
+        del container[index]
+        owner._shift(rel, index + 1, -1)
+        owner._emit(Op("remove", path))
+        return value
+
+    def __delitem__(self, key: Any) -> None:
+        owner, rel, container = self._target()
+        key = _index(container, key)
+        if isinstance(container, list):
+            container[key]
+            self._remove_at(owner, rel, container, key)
+            return
+        if key not in container:
+            raise KeyError(key)
+        path = rel + (key,)
+        owner._detach_under(path)
+        del container[key]
+        owner._emit(Op("remove", path))
+
+    def pop(self, *args: Any) -> Any:
+        owner, rel, container = self._target()
+        if isinstance(container, list):
+            index = _index(container, args[0] if args else -1)
+            container[index]
+            return self._remove_at(owner, rel, container, index)
+        if not args:
+            raise TypeError("pop expected at least 1 argument, got 0")
+        if args[1:] and args[0] not in container:
+            return args[1]
+        key = args[0]
+        value = _snapshot(container[key])
+        path = rel + (key,)
+        owner._detach_under(path)
+        del container[key]
+        owner._emit(Op("remove", path))
+        return value
+
+    def remove(self, item: Any) -> None:
+        owner, rel, container = self._target()
+        if not isinstance(container, list):
+            raise TypeError(f"remove on non-list at path {list(self._path)!r}")
+        target = plain(item)
+        index = next(
+            (i for i, node in enumerate(container) if _snapshot(node) == target), None
+        )
+        if index is None:
+            raise ValueError(f"{target!r} not in list")
+        self._remove_at(owner, rel, container, index)
+
+    def clear(self) -> None:
+        owner, rel, container = self._target()
+        owner._detach_under(rel)
+        container.clear()
+        owner._emit(Op("replace", rel, _snapshot(container)))
+
+    def extend(self, items: Any) -> None:
+        owner, rel, container = self._target()
+        if not isinstance(container, list):
+            raise TypeError(f"extend on non-list at path {list(self._path)!r}")
+        adopted = [
+            _adopt(item, rel + (index,))
+            for index, item in enumerate(items, start=len(container))
+        ]
+        seen: set[int] = set()
+        for _stored, mounts in adopted:
+            owner._admit(mounts, seen=seen)
+        for stored, mounts in adopted:
+            container.append(stored)
+            for mount_path, child in mounts:
+                owner._attach(child, mount_path)
+        owner._emit(Op("replace", rel, _snapshot(container)))
+
+    def update(self, other: Any) -> None:
+        owner, rel, container = self._target()
+        if not isinstance(container, dict):
+            raise TypeError(f"update on non-dict at path {list(self._path)!r}")
+        adopted = []
+        for key, item in dict(plain(other) if isinstance(other, Proxy) else other).items():
+            if not isinstance(key, str):
+                raise TypeError(f"object keys must be strings, got {type(key).__name__}")
+            adopted.append((key, *_adopt(item, rel + (key,))))
+        seen: set[int] = set()
+        for key, _stored, mounts in adopted:
+            owner._admit(mounts, rel + (key,), seen)
+        for key, stored, mounts in adopted:
+            owner._detach_under(rel + (key,))
+            container[key] = stored
+            for mount_path, child in mounts:
+                owner._attach(child, mount_path)
+        owner._emit(Op("replace", rel, _snapshot(container)))
+
+    def get(self, key: Any, default: Any = None) -> Any:
+        try:
+            return self[key]
+        except (KeyError, IndexError):
+            return default
+
+    def setdefault(self, key: Any, default: Any = None) -> Any:
+        _owner, _rel, container = self._target()
+        if not isinstance(container, dict):
+            raise TypeError(f"setdefault on non-dict at path {list(self._path)!r}")
+        if key not in container:
+            self[key] = default
+        return self[key]
+
+    def keys(self):
+        _owner, _rel, node = self._target()
+        return node.keys()
+
+    def values(self):
+        _owner, _rel, node = self._target()
+        return (self[key] for key in node.keys())
+
+    def items(self):
+        _owner, _rel, node = self._target()
+        return ((key, self[key]) for key in node.keys())
+
+    def index(self, item: Any) -> int:
+        _owner, _rel, node = self._target()
+        target = plain(item)
+        found = next(
+            (i for i, entry in enumerate(node) if _snapshot(entry) == target), None
+        )
+        if found is None:
+            raise ValueError(f"{target!r} not in list")
+        return found
+
+    def __contains__(self, item: Any) -> bool:
+        _owner, _rel, node = self._target()
+        target = plain(item)
+        if isinstance(node, list):
+            return any(_snapshot(entry) == target for entry in node)
+        return target in node
+
+    def __iter__(self) -> Iterator[Any]:
+        _owner, _rel, node = self._target()
+        if isinstance(node, list):
+            return (self[i] for i in range(len(node)))
+        return iter(list(node))
+
+    def __len__(self) -> int:
+        _owner, _rel, node = self._target()
+        return len(node)
+
+    def __eq__(self, other: Any) -> bool:
+        _owner, _rel, node = self._target()
+        return _snapshot(node) == plain(other)
+
+    def __bool__(self) -> bool:
+        _owner, _rel, node = self._target()
+        return bool(node)
+
+    def __repr__(self) -> str:
+        _owner, _rel, node = self._target()
+        return repr(_snapshot(node))

statepatch-0.1.0/tests/test_observable.py

@@ -0,0 +1,228 @@
+"""Contract: observables apply mutations to the tree and emit the matching op;
+mounted observables forward their op streams at the mount path."""
+
+from datetime import datetime, timezone
+
+import pytest
+from statepatch import Op, observable
+
+
+def collect(obs):
+    ops = []
+    obs.subscribe(ops.append)
+    return ops
+
+
+def test_scalar_value_set_emits_root_replace():
+    flag = observable(False)
+    ops = collect(flag)
+    flag.value = True
+    assert flag.value is True
+    assert ops == [Op("replace", (), True)]
+
+
+def test_dict_and_list_mutations_emit_wire_shaped_ops():
+    state = observable({"status": "idle", "messages": []})
+    ops = collect(state)
+    state["status"] = "streaming"
+    state["messages"].append({"id": "m1", "content": ""})
+    state["messages"][0]["content"] = "hel"
+    state["messages"][0]["content"] = "hello"  # suffix diff -> string add
+    state["messages"].pop(0)
+    assert ops == [
+        Op("replace", ("status",), "streaming"),
+        Op("add", ("messages", 0), {"id": "m1", "content": ""}),
+        Op("add", ("messages", 0, "content", 0), "hel"),
+        Op("add", ("messages", 0, "content", 3), "lo"),
+        Op("remove", ("messages", 0)),
+    ]
+    assert state.value == {"status": "streaming", "messages": []}
+
+
+def test_values_are_dealised_on_write():
+    state = observable({})
+    held = {"a": [1]}
+    state["x"] = held
+    held["a"].append(2)
+    assert state.value == {"x": {"a": [1]}}
+
+
+def test_invalid_values_fail_fast():
+    state = observable({})
+    with pytest.raises(ValueError):
+        state["x"] = float("nan")
+    with pytest.raises(ValueError):
+        state["x"] = 2**53
+    with pytest.raises(ValueError):
+        state["x"] = datetime(2026, 1, 1)  # naive
+    with pytest.raises(TypeError):
+        state["x"] = {1: "non-string key"}
+    with pytest.raises(TypeError):
+        state["x"] = object()
+    state["x"] = datetime(2026, 1, 1, tzinfo=timezone.utc)  # aware is fine
+
+
+def test_mount_in_initial_value_forwards_ops():
+    child = observable({"n": 0})
+    parent = observable({"child": child, "other": 1})
+    ops = collect(parent)
+    child["n"] = 5
+    assert ops == [Op("replace", ("child", "n"), 5)]
+    assert parent.value == {"child": {"n": 5}, "other": 1}
+
+
+def test_mount_via_append_and_detach_via_pop():
+    run = observable({"runId": "r1", "queue": []})
+    state = observable({"runs": []})
+    ops = collect(state)
+    state["runs"].append(run)
+    run["queue"].append("q1")
+    state["runs"].pop(0)
+    run["queue"].append("q2")  # after detach: not forwarded
+    assert ops == [
+        Op("add", ("runs", 0), {"runId": "r1", "queue": []}),
+        Op("add", ("runs", 0, "queue", 0), "q1"),
+        Op("remove", ("runs", 0)),
+    ]
+    assert state.value == {"runs": []}
+    assert run.value == {"runId": "r1", "queue": ["q1", "q2"]}
+    # detached observables are re-mountable
+    state["runs"].append(run)
+    run["queue"].append("q3")
+    assert ops[-1] == Op("add", ("runs", 0, "queue", 2), "q3")
+
+
+def test_mount_paths_shift_with_list_splices():
+    a, b = observable({"id": "a"}), observable({"id": "b"})
+    state = observable({"runs": []})
+    state["runs"].append(a)
+    state["runs"].append(b)
+    ops = collect(state)
+    state["runs"].pop(0)
+    b["id"] = "x2"
+    assert ops == [
+        Op("remove", ("runs", 0)),
+        Op("replace", ("runs", 0, "id"), "x2"),
+    ]
+    state["runs"].insert(0, {"id": "plain"})
+    b["id"] = "y3"
+    assert ops[-1] == Op("replace", ("runs", 1, "id"), "y3")
+
+
+def test_double_mount_and_cycles_fail_fast():
+    child = observable({})
+    parent = observable({"a": child})
+    other = observable({})
+    with pytest.raises(ValueError):
+        other["x"] = child
+    with pytest.raises(ValueError):
+        child["up"] = parent
+
+
+def test_overwrite_detaches_mount():
+    child = observable({"n": 0})
+    parent = observable({"slot": child})
+    ops = collect(parent)
+    parent["slot"] = None
+    child["n"] = 1
+    assert ops == [Op("replace", ("slot",), None)]
+    assert child._parent is None
+
+
+def test_reads_and_mutations_cross_mounts():
+    child = observable({"queue": ["x"]})
+    parent = observable({"child": child})
+    child_ops = collect(child)
+    parent_ops = collect(parent)
+    # a mutation addressed through the parent is recorded by the child
+    parent["child"]["queue"].append("y")
+    assert child_ops == [Op("add", ("queue", 1), "y")]
+    assert parent_ops == [Op("add", ("child", "queue", 1), "y")]
+    assert parent["child"]["queue"][1] == "y"
+    assert len(parent["child"]["queue"]) == 2
+
+
+def test_snapshot_ops_carry_plain_values_for_nested_mounts():
+    child = observable({"n": 0})
+    parent = observable({})
+    ops = collect(parent)
+    parent["wrap"] = {"inner": child}
+    assert ops == [Op("replace", ("wrap",), {"inner": {"n": 0}})]
+    child["n"] = 7
+    assert ops[-1] == Op("replace", ("wrap", "inner", "n"), 7)
+
+
+def test_container_helpers():
+    state = observable({"d": {"a": 1}, "l": [1, 2, 3]})
+    ops = collect(state)
+    assert state["d"].setdefault("a", 9) == 1
+    assert state["d"].setdefault("b", 2) == 2
+    assert state["d"].get("missing", "dflt") == "dflt"
+    assert list(state["d"].keys()) == ["a", "b"]
+    assert state["l"].index(2) == 1
+    assert 3 in state["l"]
+    state["l"].remove(2)
+    state["l"].extend([4, 5])
+    state["l"].clear()
+    state["d"].update({"c": 3})
+    assert state.value == {"d": {"a": 1, "b": 2, "c": 3}, "l": []}
+    assert [op.kind for op in ops] == ["replace", "remove", "replace", "replace", "replace"]
+
+
+def test_unsubscribe_stops_delivery():
+    state = observable({})
+    ops = []
+    unsubscribe = state.subscribe(ops.append)
+    state["a"] = 1
+    unsubscribe()
+    state["a"] = 2
+    assert len(ops) == 1
+
+
+def test_failed_writes_leave_the_tree_and_mounts_untouched():
+    child = observable({"n": 0})
+    home = observable({"slot": child})
+    state = observable({"runs": [child2 := observable({"id": "a"})], "d": {}})
+    seen = []
+    state.subscribe(seen.append)
+    for bad in (
+        lambda: state["runs"].insert(0, object()),
+        lambda: state["runs"].append(child),
+        lambda: state["runs"].extend([1, child]),
+        lambda: state.update({"x": child}),
+        lambda: state.__setitem__("slot2", {"inner": child}),
+        lambda: state["d"].__setitem__(1, "x"),
+        lambda: state["runs"].__setitem__("x", 1),
+    ):
+        with pytest.raises((TypeError, ValueError)):
+            bad()
+    assert state.value == {"runs": [{"id": "a"}], "d": {}}
+    assert seen == []
+    child2["id"] = "b"  # mount path did not shift on the failed insert
+    assert seen == [Op("replace", ("runs", 0, "id"), "b")]
+    child["n"] = 1  # child stays healthy in its own home
+    assert home.value == {"slot": {"n": 1}}
+
+
+def test_listener_detaching_the_mount_mid_emit_is_safe():
+    child = observable({"n": 0})
+    parent = observable({})
+    fired = []
+
+    def detach_once(op):
+        fired.append(op)
+        if len(fired) == 1:
+            parent["slot"] = None
+
+    child.subscribe(detach_once)
+    parent["slot"] = child
+    child["n"] = 1
+    assert parent.value == {"slot": None}
+
+
+def test_remounting_a_child_onto_its_own_path_works():
+    child = observable({"n": 0})
+    home = observable({"slot": child})
+    home["slot"] = child
+    child["n"] = 1
+    assert home.value == {"slot": {"n": 1}}