graphrefly 0.1.0__py3-none-any.whl

graphrefly/core/subgraph_locks.py

@@ -0,0 +1,296 @@
+"""Union-find registry for per-subgraph write locking (roadmap 0.4).
+
+Contract (aligned with callbag-recharge-py and GRAPHREFLY-SPEC §6.1):
+
+- ``get()`` does not take the subgraph write lock; it uses a per-node ``threading.Lock``
+  (``NodeImpl._cache_lock``) so the cached value is read/written with proper synchronization
+  under free-threaded Python (nogil), independent of the component ``RLock``.
+- Mutations that change node state or topology (``down``, recompute, subscribe /
+  unsubscribe) run under the subgraph RLock for the node's union component.
+- ``union_nodes`` merges components when nodes are linked by dependency edges so one
+  logical subgraph serializes writes on one lock.
+- ``defer_set`` / ``defer_down`` queue cross-subgraph work until the current write lock
+  is released, avoiding deadlocks.
+
+Each thread has its own defer queue (TLS), matching :func:`graphrefly.core.protocol.batch`
+isolation per thread.
+"""
+
+from __future__ import annotations
+
+import threading
+import weakref
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+
+class _LockBox:
+    """Mutable holder for a component RLock; redirect ``.lock`` on union."""
+
+    __slots__ = ("lock",)
+
+    def __init__(self) -> None:
+        self.lock = threading.RLock()
+
+
+_MAX_LOCK_RETRIES: int = 100
+
+
+class _SubgraphRegistry:
+    __slots__ = ("_children", "_meta_lock", "_parent", "_rank", "_boxes", "_refs")
+
+    def __init__(self) -> None:
+        self._meta_lock = threading.RLock()
+        self._parent: dict[int, int] = {}
+        self._rank: dict[int, int] = {}
+        self._boxes: dict[int, _LockBox] = {}
+        self._refs: dict[int, weakref.ref[object]] = {}
+        self._children: dict[int, set[int]] = {}
+
+    def _on_gc(self, node_id: int, ref_obj: weakref.ref[object]) -> None:
+        with self._meta_lock:
+            if self._refs.get(node_id) is not ref_obj:
+                return
+            self._refs.pop(node_id, None)
+            parent = self._parent.get(node_id)
+            if parent is None:
+                return
+
+            direct_children = list(self._children.get(node_id, ()))
+
+            if parent == node_id:
+                if direct_children:
+                    new_root = direct_children[0]
+                    self._parent[new_root] = new_root
+                    new_root_kids = self._children.setdefault(new_root, set())
+                    for child in direct_children[1:]:
+                        self._parent[child] = new_root
+                        new_root_kids.add(child)
+                        kids = self._children.get(child)
+                        if kids is not None:
+                            kids.discard(node_id)
+
+                    box = self._boxes.get(node_id)
+                    if box is not None:
+                        self._boxes[new_root] = box
+                    self._rank[new_root] = self._rank.get(new_root, self._rank.get(node_id, 0))
+            else:
+                parent_kids = self._children.get(parent)
+                if parent_kids is not None:
+                    parent_kids.discard(node_id)
+                for child in direct_children:
+                    self._parent[child] = parent
+                    if parent_kids is not None:
+                        parent_kids.add(child)
+
+            self._children.pop(node_id, None)
+            self._parent.pop(node_id, None)
+            self._rank.pop(node_id, None)
+            self._boxes.pop(node_id, None)
+
+    def _find_locked(self, node_id: int) -> int:
+        parent = self._parent.get(node_id)
+        if parent is None:
+            return node_id
+        if parent != node_id:
+            root = self._find_locked(parent)
+            if root != parent:
+                old_parent = parent
+                self._parent[node_id] = root
+                # Maintain _children reverse map during path compression.
+                old_kids = self._children.get(old_parent)
+                if old_kids is not None:
+                    old_kids.discard(node_id)
+                self._children.setdefault(root, set()).add(node_id)
+            return root
+        return node_id
+
+    def _ensure_locked(self, node: object) -> int:
+        node_id = id(node)
+        existing_ref = self._refs.get(node_id)
+        existing_obj = existing_ref() if existing_ref is not None else None
+
+        if node_id not in self._parent or existing_obj is None:
+            self._parent[node_id] = node_id
+            self._rank[node_id] = 0
+            self._boxes[node_id] = _LockBox()
+            self._children[node_id] = set()
+            self._refs[node_id] = weakref.ref(node, lambda _ref: self._on_gc(node_id, _ref))
+        return node_id
+
+    def ensure_node(self, node: object) -> None:
+        with self._meta_lock:
+            self._ensure_locked(node)
+
+    def union(self, node_a: object, node_b: object) -> None:
+        with self._meta_lock:
+            id_a = self._ensure_locked(node_a)
+            id_b = self._ensure_locked(node_b)
+
+            root_a = self._find_locked(id_a)
+            root_b = self._find_locked(id_b)
+            if root_a == root_b:
+                return
+
+            rank_a = self._rank.get(root_a, 0)
+            rank_b = self._rank.get(root_b, 0)
+            if rank_a < rank_b:
+                root_a, root_b = root_b, root_a
+            self._parent[root_b] = root_a
+            self._children.setdefault(root_a, set()).add(root_b)
+            if rank_a == rank_b:
+                self._rank[root_a] = rank_a + 1
+
+            canonical_lock = self._boxes[root_a].lock
+            box_b = self._boxes.get(root_b)
+            if box_b is not None:
+                box_b.lock = canonical_lock
+
+    @contextmanager
+    def lock_for(self, node: object) -> Generator[None]:
+        for _attempt in range(_MAX_LOCK_RETRIES):
+            with self._meta_lock:
+                node_id = self._ensure_locked(node)
+                root = self._find_locked(node_id)
+                box = self._boxes.get(root)
+                if box is None:
+                    box = _LockBox()
+                    self._boxes[root] = box
+                lock = box.lock
+
+            lock.acquire()
+            valid = False
+            try:
+                with self._meta_lock:
+                    current_root = self._find_locked(node_id)
+                    current_box = self._boxes.get(current_root)
+                    if current_box is None:
+                        current_box = _LockBox()
+                        self._boxes[current_root] = current_box
+                    valid = current_box.lock is lock
+                if valid:
+                    yield
+                    return
+            finally:
+                lock.release()
+        raise RuntimeError(
+            f"subgraph lock acquisition failed after {_MAX_LOCK_RETRIES} retries "
+            "(continuous union activity?)"
+        )
+
+
+_REGISTRY = _SubgraphRegistry()
+
+
+def ensure_registered(node: object) -> None:
+    """Register *node* in the subgraph registry (weak-ref; auto cleanup on GC)."""
+    _REGISTRY.ensure_node(node)
+
+
+def union_nodes(a: object, b: object) -> None:
+    """Merge the subgraph components containing *a* and *b* (same write lock)."""
+    _REGISTRY.union(a, b)
+
+
+@contextmanager
+def acquire_subgraph_write_lock(node: object) -> Generator[None]:
+    """Acquire the write lock for the component containing *node*."""
+    with _REGISTRY.lock_for(node):
+        yield
+
+
+# --- defer_set / defer_down (TLS queue, flushed when defer-aware lock exits) ---
+
+_deferred_tls = threading.local()
+
+
+def _get_deferred_depth() -> int:
+    return getattr(_deferred_tls, "depth", 0)
+
+
+def _inc_deferred_depth() -> None:
+    _deferred_tls.depth = getattr(_deferred_tls, "depth", 0) + 1
+
+
+def _dec_deferred_depth() -> int:
+    current = getattr(_deferred_tls, "depth", 0)
+    if current <= 0:
+        raise RuntimeError("deferred depth underflow: lock/defer bookkeeping out of balance")
+    depth = current - 1
+    _deferred_tls.depth = depth
+    return depth
+
+
+def _get_deferred_queue() -> list[Callable[[], None]]:
+    q: list[Callable[[], None]] | None = getattr(_deferred_tls, "queue", None)
+    if q is None:
+        q = []
+        _deferred_tls.queue = q
+    return q
+
+
+@contextmanager
+def acquire_subgraph_write_lock_with_defer(node: object) -> Generator[None]:
+    """Acquire the subgraph write lock; flush deferred cross-subgraph work on exit."""
+    _inc_deferred_depth()
+    try:
+        with _REGISTRY.lock_for(node):
+            yield
+    finally:
+        if _dec_deferred_depth() == 0:
+            queue = _get_deferred_queue()
+            errors: list[Exception] = []
+            first_base: BaseException | None = None
+            while queue:
+                pending = queue[:]
+                queue.clear()
+                for fn in pending:
+                    try:
+                        fn()
+                    except Exception as e:
+                        errors.append(e)
+                    except BaseException as e:
+                        if first_base is None:
+                            first_base = e
+            if first_base is not None:
+                raise first_base
+            if len(errors) == 1:
+                raise errors[0]
+            if len(errors) > 1:
+                raise ExceptionGroup("deferred subgraph work", errors)
+
+
+def defer_set(target: Any, value: Any) -> None:
+    """Schedule ``target.set(value)`` after the current defer-aware lock exits.
+
+    If not inside :func:`acquire_subgraph_write_lock_with_defer`, runs immediately.
+    *target* must provide a ``set`` method (e.g. future state sugar).
+    """
+    if _get_deferred_depth() > 0:
+        _get_deferred_queue().append(lambda: target.set(value))
+    else:
+        target.set(value)
+
+
+def defer_down(node: Any, messages: Any) -> None:
+    """Schedule ``node.down(messages)`` after the current defer-aware lock exits.
+
+    If not inside :func:`acquire_subgraph_write_lock_with_defer`, runs immediately.
+    """
+    if _get_deferred_depth() > 0:
+        _get_deferred_queue().append(lambda: node.down(messages))
+    else:
+        node.down(messages)
+
+
+__all__ = [
+    "acquire_subgraph_write_lock",
+    "acquire_subgraph_write_lock_with_defer",
+    "defer_down",
+    "defer_set",
+    "ensure_registered",
+    "union_nodes",
+]

graphrefly/core/sugar.py

@@ -0,0 +1,138 @@
+"""Sugar constructors over :func:`graphrefly.core.node.node` (GRAPHREFLY-SPEC §2.7, §4.1)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from graphrefly.core.node import Node, NodeFn, node
+
+type PipeOperator = Callable[[Node[Any]], Node[Any]]
+
+
+def state(initial: Any, **opts: Any) -> Node[Any]:
+    """Create a manually-settable source node with a fixed initial value.
+
+    Args:
+        initial: The initial cached value for the node.
+        **opts: Additional node options passed through to :func:`~graphrefly.core.node.node`.
+
+    Returns:
+        A :class:`~graphrefly.core.node.Node` with no deps and no compute function.
+
+    Example:
+        ```python
+        from graphrefly import state
+        counter = state(0, name="counter")
+        counter.down([("DATA", 1)])
+        assert counter.get() == 1
+        ```
+    """
+    return node([], {**opts, "initial": initial})
+
+
+def producer(fn: NodeFn, **opts: Any) -> Node[Any]:
+    """Create an auto-starting producer node with no dependencies.
+
+    Args:
+        fn: The compute function invoked when the first sink subscribes.
+        **opts: Additional node options passed through to :func:`~graphrefly.core.node.node`.
+
+    Returns:
+        A :class:`~graphrefly.core.node.Node` whose producer starts on first subscribe.
+
+    Example:
+        ```python
+        from graphrefly import producer
+        from graphrefly.core.protocol import MessageType
+
+        def ticker(deps, actions):
+            actions.emit(42)
+            actions.down([(MessageType.COMPLETE,)])
+            return lambda: None
+
+        p = producer(ticker, name="once")
+        ```
+    """
+    return node(fn, describe_kind="producer", **opts)
+
+
+def derived(deps: Sequence[Node[Any]], fn: NodeFn, **opts: Any) -> Node[Any]:
+    """Create a derived node that recomputes whenever its dependencies settle.
+
+    Args:
+        deps: Upstream nodes whose settled values are passed to ``fn``.
+        fn: Compute function receiving ``(dep_values, actions)``; may return a
+            value to emit or a cleanup callable.
+        **opts: Additional node options passed through to :func:`~graphrefly.core.node.node`.
+
+    Returns:
+        A :class:`~graphrefly.core.node.Node` that reacts to its upstream deps.
+
+    Example:
+        ```python
+        from graphrefly import state, derived
+        x = state(2)
+        doubled = derived([x], lambda deps, _: deps[0] * 2)
+        ```
+    """
+    return node(list(deps), fn, describe_kind="derived", **opts)
+
+
+def effect(deps: Sequence[Node[Any]], fn: NodeFn, **opts: Any) -> Node[Any]:
+    """Create a side-effect leaf node; ``fn`` should return ``None`` (no auto-emit).
+
+    Args:
+        deps: Upstream nodes whose settled values trigger ``fn``.
+        fn: Side-effect function receiving ``(dep_values, actions)``; return value
+            is ignored unless it is a cleanup callable.
+        **opts: Additional node options passed through to :func:`~graphrefly.core.node.node`.
+
+    Returns:
+        A :class:`~graphrefly.core.node.Node` that runs ``fn`` on each settlement
+        but does not emit reactive values downstream.
+
+    Example:
+        ```python
+        from graphrefly import state, effect
+        x = state(0)
+        log = []
+        e = effect([x], lambda deps, _: log.append(deps[0]))
+        x.down([("DATA", 1)])
+        ```
+    """
+    return node(list(deps), fn, describe_kind="effect", **opts)
+
+
+def pipe(source: Node[Any], *ops: PipeOperator) -> Node[Any]:
+    """Compose a linear pipeline of unary operators over ``source``.
+
+    Args:
+        source: The root node to pipe through operators.
+        *ops: Unary operator callables each transforming ``Node -> Node``.
+
+    Returns:
+        The last node in the pipeline (result of applying all operators in order).
+
+    Example:
+        ```python
+        from graphrefly import state, pipe
+        from graphrefly.extra import map_val, filter_val
+        x = state(0)
+        result = pipe(x, map_val(lambda v: v * 2), filter_val(lambda v: v > 0))
+        ```
+    """
+    cur: Node[Any] = source
+    for op in ops:
+        cur = op(cur)
+    return cur
+
+
+__all__ = [
+    "PipeOperator",
+    "derived",
+    "effect",
+    "pipe",
+    "producer",
+    "state",
+]

graphrefly/core/versioning.py

@@ -0,0 +1,193 @@
+"""Node versioning — GRAPHREFLY-SPEC §7.
+
+Progressive, optional versioning for node identity and change tracking.
+
+- **V0**: ``id`` + ``version`` — identity & change detection (~16 bytes overhead)
+- **V1**: + ``cid`` + ``prev`` — content addressing & linked history (~60 bytes overhead)
+
+**Lifecycle notes:**
+
+- Version advances only on DATA (not RESOLVED, INVALIDATE, or TEARDOWN).
+- ``reset_on_teardown`` clears the cached value but does NOT reset versioning state.
+  After teardown, ``v.cid`` still reflects the last DATA value, not the cleared cache.
+  The invariant ``hash(node.get()) == v.cid`` only holds in ``settled``/``resolved`` status.
+- Resubscribable nodes preserve versioning across subscription lifetimes (monotonic counter).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = [
+    "V0",
+    "V1",
+    "NodeVersionInfo",
+    "VersioningLevel",
+    "HashFn",
+    "create_versioning",
+    "advance_version",
+    "default_hash",
+    "canonicalize_for_hash",
+    "is_v1",
+]
+
+type VersioningLevel = int  # 0 or 1; extensible to 2, 3 later
+type HashFn = Callable[[Any], str]
+
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class V0:
+    """V0: identity + monotonic version counter."""
+
+    id: str
+    version: int = 0
+
+
+@dataclass
+class V1(V0):
+    """V1: V0 + content-addressed identifier + previous cid link."""
+
+    cid: str = ""
+    prev: str | None = None
+
+
+# Union alias for type hints.
+type NodeVersionInfo = V0 | V1
+
+
+# ---------------------------------------------------------------------------
+# Canonical normalizer
+# ---------------------------------------------------------------------------
+
+
+def canonicalize_for_hash(value: Any) -> Any:
+    """Normalize *value* into a JSON-safe canonical form for deterministic hashing.
+
+    - ``None`` → ``None``
+    - ``float``: rejects non-finite (``NaN``, ``±Inf``) with ``TypeError``;
+      normalizes integer-valued floats to ``int`` (``1.0`` → ``1``).
+    - ``int``, ``str``, ``bool``: pass through unchanged.
+    - ``list`` / ``tuple``: recursively canonicalize each element, return as ``list``.
+    - ``dict``: sort keys, recursively canonicalize values, return as sorted ``dict``.
+    - Fallback: return ``None``.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, float):
+        if math.isnan(value) or math.isinf(value):
+            msg = f"Cannot canonicalize non-finite float: {value}"
+            raise TypeError(msg)
+        if value == int(value):
+            iv = int(value)
+            if abs(iv) > 2**53 - 1:
+                msg = (
+                    f"Cannot hash integer outside safe range (|n| > 2^53-1): {value}. "
+                    "Cross-language cid parity is not guaranteed for unsafe integers."
+                )
+                raise TypeError(msg)
+            return iv
+        return value
+    if isinstance(value, int):
+        if abs(value) > 2**53 - 1:
+            msg = (
+                f"Cannot hash integer outside safe range (|n| > 2^53-1): {value}. "
+                "Cross-language cid parity is not guaranteed for unsafe integers."
+            )
+            raise TypeError(msg)
+        return value
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (list, tuple)):
+        return [canonicalize_for_hash(item) for item in value]
+    if isinstance(value, dict):
+        return {k: canonicalize_for_hash(v) for k, v in sorted(value.items())}
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Default hash
+# ---------------------------------------------------------------------------
+
+
+def default_hash(value: Any) -> str:
+    """SHA-256 of deterministic JSON, truncated to 16 hex chars (~64-bit).
+
+    Object keys are sorted for determinism. Values are canonicalized first
+    via :func:`canonicalize_for_hash`.
+    """
+    canonical = canonicalize_for_hash(value)
+    json_bytes = json.dumps(canonical, sort_keys=True, separators=(",", ":")).encode()
+    return hashlib.sha256(json_bytes).hexdigest()[:16]
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+
+def create_versioning(
+    level: VersioningLevel,
+    initial_value: Any = None,
+    *,
+    id: str | None = None,
+    hash_fn: HashFn | None = None,
+) -> NodeVersionInfo:
+    """Create initial versioning state for a node.
+
+    Args:
+        level: 0 for V0, 1 for V1.
+        initial_value: The node's initial cached value (used for V1 cid).
+        id: Override auto-generated id.
+        hash_fn: Custom hash function for V1 cid (default: SHA-256 truncated).
+    """
+    # RFC 4122 string with hyphens — matches TypeScript `crypto.randomUUID()`.
+    node_id = id or str(uuid.uuid4())
+    if level == 0:
+        return V0(id=node_id)
+    h = hash_fn or default_hash
+    cid = h(initial_value)
+    return V1(id=node_id, cid=cid, prev=None)
+
+
+# ---------------------------------------------------------------------------
+# Advance
+# ---------------------------------------------------------------------------
+
+
+def advance_version(
+    info: NodeVersionInfo,
+    new_value: Any,
+    hash_fn: HashFn,
+) -> None:
+    """Advance versioning state after a DATA emission (value changed).
+
+    Mutates ``info`` in place for performance (called on every DATA).
+    Only call when the cached value has actually changed (not on RESOLVED).
+    """
+    info.version += 1
+    if isinstance(info, V1):
+        info.prev = info.cid
+        info.cid = hash_fn(new_value)
+
+
+# ---------------------------------------------------------------------------
+# Guards
+# ---------------------------------------------------------------------------
+
+
+def is_v1(info: NodeVersionInfo) -> bool:
+    """Type guard: is this V1 versioning info?"""
+    return isinstance(info, V1)