vcti-tree 1.0.0__py3-none-any.whl

vcti/tree/__init__.py

@@ -0,0 +1,41 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.tree — Tree protocols and generic algorithms for the vcti ecosystem."""
+
+from importlib.metadata import version
+
+from .dict_tree import DictTree, DictTreeHandle
+from .locking import (
+    collect_deletable_subtree,
+    ensure_payload_unlocked,
+    ensure_structure_unlocked,
+)
+from .navigation import ancestors, depth, descendants, path
+from .protocols import LockableTree, MutableTree, ReadOnlyTree
+from .walking import bfs, dfs_postorder, dfs_preorder
+
+__version__ = version("vcti-tree")
+
+__all__ = [
+    "__version__",
+    # Protocols
+    "ReadOnlyTree",
+    "MutableTree",
+    "LockableTree",
+    # Walking
+    "dfs_preorder",
+    "dfs_postorder",
+    "bfs",
+    # Navigation
+    "ancestors",
+    "depth",
+    "path",
+    "descendants",
+    # Locking guards
+    "collect_deletable_subtree",
+    "ensure_structure_unlocked",
+    "ensure_payload_unlocked",
+    # Reference implementation
+    "DictTree",
+    "DictTreeHandle",
+]

vcti/tree/dict_tree.py

@@ -0,0 +1,240 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""DictTree — minimal dict-backed reference implementation of LockableTree.
+
+A simple in-memory tree backed by a Python dict of node records, used
+internally for testing the generic algorithms in
+:mod:`vcti.tree.walking`, :mod:`vcti.tree.navigation`, and
+:mod:`vcti.tree.locking` without pulling in numpy or other heavy
+dependencies. Also serves as a working example of how to implement
+:class:`~vcti.tree.protocols.LockableTree` from scratch.
+
+This is **not** the recommended production implementation — for
+numpy-backed storage at file-structure-tree scale, use
+``vcti-nptree``'s ``ArrayTree``.
+
+Handle representation
+---------------------
+
+Handles are ``DictTreeHandle(tree_id, key)`` named tuples:
+
+- ``tree_id`` is a process-global counter incremented on each
+  ``DictTree`` construction, so handles from different trees compare
+  unequal (the cross-tree inequality requirement of the protocol).
+- ``key`` is an integer slot key auto-generated inside the tree.
+
+The tuple wrapping is the minimum needed to satisfy cross-tree
+inequality on top of bare keys.
+"""
+
+from collections.abc import Hashable, Iterable, Iterator
+from dataclasses import dataclass, field
+from itertools import count
+from typing import NamedTuple
+
+from .locking import collect_deletable_subtree
+
+# Process-global counter; one tag per DictTree instance.
+_tree_id_counter = count(1)
+
+
+class DictTreeHandle(NamedTuple):
+    """Opaque handle to a node in a :class:`DictTree`."""
+
+    tree_id: int
+    key: int
+
+
+@dataclass
+class _NodeRecord[T]:
+    """Internal storage for one node."""
+
+    parent: int | None  # parent key; None for root
+    children: list[int] = field(default_factory=list)
+    payload: T | None = None
+    active: bool = True
+    structure_locked: bool = False
+    payload_locked: bool = False
+
+
+class DictTree[T]:
+    """Dict-backed reference implementation of
+    :class:`~vcti.tree.protocols.LockableTree`.
+
+    Satisfies ``LockableTree[T, DictTreeHandle]`` via the structural-
+    typing protocol. Soft-delete model (matches the ``ArrayTree``
+    semantics): :meth:`delete_subtree` marks nodes inactive but leaves
+    them in the parent's children list; ``children()`` filters them out.
+
+    Locks are flat bitsets propagated across the whole active subtree
+    on each ``lock_*`` / ``unlock_*`` call (no refcount).
+    """
+
+    def __init__(self, root_data: T | None = None) -> None:
+        self._tree_id: int = next(_tree_id_counter)
+        self._next_key: int = 0
+        self._records: dict[int, _NodeRecord[T]] = {}
+        self._active_count: int = 0
+        # Allocate root at key 0 with parent=None.
+        root_key = self._allocate(parent=None, data=root_data)
+        self._root_key: int = root_key
+
+    # ---- handle (un)wrapping ----
+
+    def _unwrap(self, handle: DictTreeHandle) -> int:
+        if handle.tree_id != self._tree_id:
+            raise LookupError(
+                f"Handle {handle} is from a different tree (this tree's id={self._tree_id})"
+            )
+        if handle.key not in self._records:
+            raise KeyError(f"Handle {handle} refers to a key that was never allocated")
+        return handle.key
+
+    def _wrap(self, key: int) -> DictTreeHandle:
+        return DictTreeHandle(self._tree_id, key)
+
+    def _require_active(self, handle: DictTreeHandle) -> tuple[int, "_NodeRecord[T]"]:
+        """Unwrap ``handle`` and return ``(key, record)`` for a live node.
+
+        Raises:
+            LookupError: handle is from a different tree.
+            KeyError: handle's key was never allocated.
+            ValueError: the node has been soft-deleted.
+        """
+        key = self._unwrap(handle)
+        rec = self._records[key]
+        if not rec.active:
+            raise ValueError(f"Node {handle} has been deleted")
+        return key, rec
+
+    # ---- internal allocation ----
+
+    def _allocate(self, parent: int | None, data: T | None) -> int:
+        key = self._next_key
+        self._next_key += 1
+        self._records[key] = _NodeRecord(parent=parent, payload=data)
+        self._active_count += 1
+        return key
+
+    # ---- ReadOnlyTree ----
+
+    @property
+    def root_handle(self) -> DictTreeHandle:
+        return self._wrap(self._root_key)
+
+    def payload(self, handle: DictTreeHandle) -> T | None:
+        _, rec = self._require_active(handle)
+        return rec.payload
+
+    def parent(self, handle: DictTreeHandle) -> DictTreeHandle | None:
+        _, rec = self._require_active(handle)
+        return None if rec.parent is None else self._wrap(rec.parent)
+
+    def children(self, handle: DictTreeHandle) -> Iterable[DictTreeHandle]:
+        _, rec = self._require_active(handle)
+        # Walk the full child list, skip inactive — do not terminate early.
+        return [
+            self._wrap(child_key) for child_key in rec.children if self._records[child_key].active
+        ]
+
+    def __contains__(self, handle: object) -> bool:
+        if not isinstance(handle, DictTreeHandle):
+            return False
+        if handle.tree_id != self._tree_id:
+            return False
+        rec = self._records.get(handle.key)
+        return rec is not None and rec.active
+
+    def __iter__(self) -> Iterator[DictTreeHandle]:
+        for key, rec in self._records.items():
+            if rec.active:
+                yield self._wrap(key)
+
+    def __len__(self) -> int:
+        return self._active_count
+
+    # ---- MutableTree ----
+
+    def set_payload(self, handle: DictTreeHandle, data: T | None) -> None:
+        _, rec = self._require_active(handle)
+        if rec.payload_locked:
+            raise RuntimeError(f"Node {handle} is payload-locked")
+        rec.payload = data
+
+    def create_child(self, parent: DictTreeHandle, data: T | None = None) -> DictTreeHandle:
+        parent_key, parent_rec = self._require_active(parent)
+        if parent_rec.structure_locked:
+            raise RuntimeError(f"Parent {parent} is structure-locked")
+        child_key = self._allocate(parent=parent_key, data=data)
+        parent_rec.children.append(child_key)
+        return self._wrap(child_key)
+
+    def delete_subtree(self, handle: DictTreeHandle) -> None:
+        _, rec = self._require_active(handle)
+        if rec.parent is None:
+            raise RuntimeError("Cannot delete the root")
+        # Fail-fast collect via the shared protocol-level helper (raises if
+        # any node in the subtree is structure-locked), then deactivate the
+        # whole set atomically — no partial deletion on a locked subtree.
+        to_delete = collect_deletable_subtree(self, handle)
+        for h in to_delete:
+            self._records[h.key].active = False
+        self._active_count -= len(to_delete)
+
+    # ---- LockableTree ----
+
+    def is_structure_locked(self, handle: DictTreeHandle) -> bool:
+        _, rec = self._require_active(handle)
+        return rec.structure_locked
+
+    def is_payload_locked(self, handle: DictTreeHandle) -> bool:
+        _, rec = self._require_active(handle)
+        return rec.payload_locked
+
+    def lock_structure(self, handle: DictTreeHandle) -> None:
+        self._apply_flag(handle, "structure_locked", True)
+
+    def unlock_structure(self, handle: DictTreeHandle) -> None:
+        self._apply_flag(handle, "structure_locked", False)
+
+    def lock_payload(self, handle: DictTreeHandle) -> None:
+        self._apply_flag(handle, "payload_locked", True)
+
+    def unlock_payload(self, handle: DictTreeHandle) -> None:
+        self._apply_flag(handle, "payload_locked", False)
+
+    def _apply_flag(self, handle: DictTreeHandle, attr: str, value: bool) -> None:
+        """Set ``attr=value`` on ``handle`` and all active descendants.
+
+        Raises if ``handle`` itself is not a live node (so lock/unlock on a
+        deleted handle fails loudly, consistent with the rest of the surface
+        rather than silently no-op'ing). Inactive *descendants* are skipped:
+        propagation covers the active subtree only.
+        """
+        root_key, _ = self._require_active(handle)
+        # Walk the subtree skipping inactive nodes; full child-chain walk.
+        stack: list[int] = [root_key]
+        while stack:
+            k = stack.pop()
+            rec = self._records[k]
+            if not rec.active:
+                continue
+            setattr(rec, attr, value)
+            for child_key in reversed(rec.children):
+                stack.append(child_key)
+
+
+# Static structural conformance check (mypy will see this).
+def _check_protocol_conformance() -> None:  # pragma: no cover
+    from .protocols import LockableTree, MutableTree, ReadOnlyTree
+
+    tree: DictTree[str] = DictTree("root")
+    _ro: ReadOnlyTree[str, DictTreeHandle] = tree
+    _mu: MutableTree[str, DictTreeHandle] = tree
+    _lo: LockableTree[str, DictTreeHandle] = tree
+    _ = _ro, _mu, _lo
+
+
+def _is_hashable_handle() -> None:  # pragma: no cover
+    # Sanity: DictTreeHandle must satisfy H: Hashable bound.
+    _: Hashable = DictTreeHandle(1, 0)

vcti/tree/locking.py

@@ -0,0 +1,78 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Locking guards over any :class:`LockableTree`.
+
+Two complementary helpers:
+
+- :func:`collect_deletable_subtree` is the fused common-case for
+  ``delete_subtree`` implementations — single-pass walk + structure-lock
+  check, fail-fast on the first locked node.
+- :func:`ensure_structure_unlocked` and :func:`ensure_payload_unlocked`
+  are predicate-only forms for arbitrary handle iterables (e.g.,
+  user-supplied selections) that don't need subtree walking.
+
+All three operate against the :class:`LockableTree` protocol — never
+against any concrete implementation.
+"""
+
+from collections.abc import Hashable, Iterable
+
+from .protocols import LockableTree
+from .walking import dfs_preorder
+
+
+def collect_deletable_subtree[T, H: Hashable](tree: LockableTree[T, H], root_handle: H) -> list[H]:
+    """Walk the subtree at ``root_handle`` DFS pre-order and verify
+    no node is structure-locked.
+
+    Returns the list of handles in DFS pre-order; callers can then
+    deactivate them atomically without rolling back.
+
+    Intentionally fused (walks + validates in a single pass) rather
+    than composing :func:`descendants` + :func:`ensure_structure_unlocked`,
+    so that an early-locked node fails fast without materialising the
+    rest of the subtree.
+
+    Raises:
+        RuntimeError: If any node in the subtree is structure-locked.
+    """
+    nodes: list[H] = []
+    for h in dfs_preorder(tree, root_handle):
+        if tree.is_structure_locked(h):
+            raise RuntimeError(
+                f"Cannot delete subtree at {root_handle}: node {h} is structure-locked"
+            )
+        nodes.append(h)
+    return nodes
+
+
+def ensure_structure_unlocked[T, H: Hashable](
+    tree: LockableTree[T, H], handles: Iterable[H]
+) -> None:
+    """Raise on the first structure-locked handle in ``handles``.
+
+    Use this when the caller already has a handle list (e.g., a
+    user-supplied selection or a result from a separate walk) and
+    doesn't need subtree collection. For the subtree-delete common
+    case, prefer :func:`collect_deletable_subtree` which does both
+    in a single pass.
+
+    Raises:
+        RuntimeError: On the first structure-locked handle.
+    """
+    for h in handles:
+        if tree.is_structure_locked(h):
+            raise RuntimeError(f"Node {h} is structure-locked")
+
+
+def ensure_payload_unlocked[T, H: Hashable](
+    tree: LockableTree[T, H], handles: Iterable[H]
+) -> None:
+    """Raise on the first payload-locked handle in ``handles``.
+
+    Raises:
+        RuntimeError: On the first payload-locked handle.
+    """
+    for h in handles:
+        if tree.is_payload_locked(h):
+            raise RuntimeError(f"Node {h} is payload-locked")

vcti/tree/navigation.py

@@ -0,0 +1,57 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Relationship-oriented navigation helpers over any :class:`ReadOnlyTree`.
+
+These are the "answers" layer: given a handle, return its ancestors,
+depth, path, or descendants as concrete handles. The iterator-oriented
+walks live in :mod:`vcti.tree.walking`; this module composes them with
+the parent-chain query exposed by the protocol.
+"""
+
+from collections.abc import Hashable, Iterator
+
+from .protocols import ReadOnlyTree
+from .walking import dfs_preorder
+
+
+def ancestors[T, H: Hashable](tree: ReadOnlyTree[T, H], handle: H) -> Iterator[H]:
+    """Yield ancestors of ``handle`` from parent up to (and including) root.
+
+    Yields nothing if ``handle`` is the root.
+    """
+    nid = tree.parent(handle)
+    while nid is not None:
+        yield nid
+        nid = tree.parent(nid)
+
+
+def depth[T, H: Hashable](tree: ReadOnlyTree[T, H], handle: H) -> int:
+    """Distance from ``handle`` to the root. ``depth(root_handle) == 0``."""
+    return sum(1 for _ in ancestors(tree, handle))
+
+
+def path[T, H: Hashable](tree: ReadOnlyTree[T, H], handle: H) -> list[H]:
+    """List of handles from root to ``handle`` (inclusive).
+
+    For the root, returns ``[root_handle]``.
+    """
+    result = [handle]
+    result.extend(ancestors(tree, handle))
+    result.reverse()
+    return result
+
+
+def descendants[T, H: Hashable](
+    tree: ReadOnlyTree[T, H], handle: H, *, include_self: bool = False
+) -> Iterator[H]:
+    """DFS pre-order descendants of ``handle``.
+
+    With ``include_self=False`` (the default), ``handle`` itself is not
+    yielded; the first yielded item is the first child (if any).
+    With ``include_self=True``, ``handle`` is yielded first.
+    """
+    walker = dfs_preorder(tree, handle)
+    first = next(walker, None)
+    if include_self and first is not None:
+        yield first
+    yield from walker

vcti/tree/protocols.py

@@ -0,0 +1,180 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Tree protocols — ReadOnlyTree, MutableTree, LockableTree.
+
+Defines what a tree IS in the vcti ecosystem, parameterised in payload
+type ``T`` and handle type ``H``. The protocols specify semantics (what
+a tree must support); they do not prescribe storage. Any backing that
+satisfies the protocols gets the generic algorithms in
+:mod:`vcti.tree.walking`, :mod:`vcti.tree.navigation`, and
+:mod:`vcti.tree.locking` for free.
+
+See the module-level docs for each protocol for the contract details
+(root invariant, active-membership semantics, cross-tree handle
+inequality requirement, handle validity rules).
+"""
+
+from collections.abc import Hashable, Iterable, Iterator
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ReadOnlyTree[T, H: Hashable](Protocol):
+    """A tree of T-valued nodes addressed by handles of type H.
+
+    Every Tree has a root from construction onward. Implementations
+    decide how the root is allocated and how active membership is
+    tracked, but the protocol-level contract requires:
+
+    - ``tree.root_handle`` always returns a handle to a live node.
+    - ``parent(tree.root_handle)`` returns ``None``.
+    - ``len(tree) >= 1`` always; the empty-tree state does not exist.
+    - Handles obtained from different tree instances must compare
+      unequal (implementations satisfy this via tagged handles, node
+      object identity, or key wrapping — protocol does not prescribe
+      the mechanism).
+    - ``__contains__``, ``__iter__``, and ``children`` must agree on
+      what "currently active" means. The representation
+      (soft-delete bit, hard-delete, tombstones, generation counters,
+      etc.) is implementation choice; the obligation is
+      self-consistency.
+
+    The iterable returned by :meth:`children` should be treated as
+    transient: unless an implementation documents stronger
+    guarantees, mutating the tree may invalidate any previously
+    obtained child iterable. Materialise first
+    (``list(tree.children(h))``) if mutation during traversal is
+    required.
+    """
+
+    @property
+    def root_handle(self) -> H:
+        """The handle of the root node. Always valid."""
+        ...
+
+    def payload(self, handle: H) -> T | None:
+        """Return the payload at the handle.
+
+        Raises:
+            Implementation-specific exceptions if the handle is not
+            currently a live node (out of range, soft-deleted, from
+            another tree, or held across a structural invalidation
+            event). The convention is to raise ``LookupError`` or a
+            subclass for handle-validity failures.
+        """
+        ...
+
+    def parent(self, handle: H) -> H | None:
+        """Return the parent handle, or ``None`` for the root."""
+        ...
+
+    def children(self, handle: H) -> Iterable[H]:
+        """Return an iterable over the active children of ``handle``."""
+        ...
+
+    def __contains__(self, handle: object) -> bool:
+        """Report current active membership.
+
+        ``handle in tree`` is ``True`` iff ``handle`` refers to a
+        currently active node, and ``False`` in every other case —
+        including non-handle inputs, foreign-tree handles, and
+        stale handles. This method does not raise.
+        """
+        ...
+
+    def __iter__(self) -> Iterator[H]:
+        """Iterate over active handles in implementation-defined order."""
+        ...
+
+    def __len__(self) -> int:
+        """Count of currently active nodes. Always ``>= 1``."""
+        ...
+
+
+@runtime_checkable
+class MutableTree[T, H: Hashable](ReadOnlyTree[T, H], Protocol):
+    """A :class:`ReadOnlyTree` that supports mutation.
+
+    ``create_child`` is the only operation that adds a node, and the
+    new node is always allocated as a child of an existing one — the
+    root is established by the constructor (implementation-specific)
+    and cannot be added or removed through the protocol.
+
+    ``delete_subtree`` removes a handle and all its descendants
+    atomically. There is no protocol-level distinction between
+    leaf-delete and subtree-delete; callers that want leaf-only
+    semantics should check ``tree.children(handle)`` first.
+    """
+
+    def set_payload(self, handle: H, data: T | None) -> None:
+        """Write the payload at the handle."""
+        ...
+
+    def create_child(self, parent: H, data: T | None = None) -> H:
+        """Allocate a new child of ``parent`` and return its handle."""
+        ...
+
+    def delete_subtree(self, handle: H) -> None:
+        """Remove ``handle`` and all its descendants.
+
+        Calling this on the root handle must raise (the root cannot
+        be removed). The exact exception type is implementation
+        choice; the *behaviour* is protocol-required.
+        """
+        ...
+
+
+@runtime_checkable
+class LockableTree[T, H: Hashable](MutableTree[T, H], Protocol):
+    """A :class:`MutableTree` with per-node structure/payload locks.
+
+    Lock semantics:
+
+    - **Subtree-propagating.** ``lock_structure(h)`` sets the lock on
+      ``h`` and on every active descendant; ``unlock_structure(h)``
+      clears it on the same set.
+    - **Flat bitset (no refcount).** Unlocking an outer subtree clears
+      the lock on any nested independently-locked subtrees too.
+    - **Guards are enforced in mutators.** ``STRUCTURE_LOCKED`` blocks
+      ``create_child(locked_node, ...)``, ``delete_subtree(locked_node)``,
+      and ``delete_subtree`` of any ancestor whose subtree contains a
+      structure-locked node (atomic — no partial deletion).
+      ``PAYLOAD_LOCKED`` blocks ``set_payload(locked_node, value)``.
+    - **Predicates are pure reads.** ``is_structure_locked`` /
+      ``is_payload_locked`` do not mutate and do not raise *because of*
+      lock state — a locked node is a valid read, returning ``True``.
+    - **Handle validity applies uniformly.** Every method here other
+      than the membership test follows the same handle-validity contract
+      as :class:`ReadOnlyTree`: the predicates and the ``lock_*`` /
+      ``unlock_*`` mutators raise on a stale, foreign, or inactive
+      (deleted) handle rather than silently returning stale state or
+      no-op'ing. Only ``__contains__`` tolerates a bad handle (it
+      returns ``False``).
+    - Locks do **not** prevent in-place mutation of payload objects
+      (``tree.payload(h).data = ...``). That is the payload type's
+      concern, not the tree's.
+    """
+
+    def is_structure_locked(self, handle: H) -> bool:
+        """Whether the structure lock is set on ``handle``."""
+        ...
+
+    def is_payload_locked(self, handle: H) -> bool:
+        """Whether the payload lock is set on ``handle``."""
+        ...
+
+    def lock_structure(self, handle: H) -> None:
+        """Lock structure on ``handle`` and all active descendants."""
+        ...
+
+    def unlock_structure(self, handle: H) -> None:
+        """Unlock structure on ``handle`` and all active descendants."""
+        ...
+
+    def lock_payload(self, handle: H) -> None:
+        """Lock payload on ``handle`` and all active descendants."""
+        ...
+
+    def unlock_payload(self, handle: H) -> None:
+        """Unlock payload on ``handle`` and all active descendants."""
+        ...

vcti/tree/walking.py

@@ -0,0 +1,74 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Walking algorithms over any :class:`ReadOnlyTree`.
+
+Free functions following Python's ``sorted(iterable)`` / ``itertools.*``
+tradition. They allocate their own stack/queue and call back into the
+tree only through :attr:`~ReadOnlyTree.root_handle` and
+:meth:`~ReadOnlyTree.children` — they do not touch any implementation
+internals.
+
+All three walks start at ``start`` if provided, otherwise at
+``tree.root_handle``, and yield handles lazily as the walk progresses.
+"""
+
+from collections import deque
+from collections.abc import Hashable, Iterator
+
+from .protocols import ReadOnlyTree
+
+
+def dfs_preorder[T, H: Hashable](tree: ReadOnlyTree[T, H], start: H | None = None) -> Iterator[H]:
+    """DFS pre-order traversal from ``start``.
+
+    Yields ``start`` first, then each of its subtrees in left-to-right
+    order, each subtree recursively in pre-order. Defaults to the
+    tree's root.
+    """
+    nid = tree.root_handle if start is None else start
+    stack: list[H] = [nid]
+    while stack:
+        n = stack.pop()
+        yield n
+        # Push children in reverse so leftmost is popped first.
+        children = list(tree.children(n))
+        for c in reversed(children):
+            stack.append(c)
+
+
+def dfs_postorder[T, H: Hashable](tree: ReadOnlyTree[T, H], start: H | None = None) -> Iterator[H]:
+    """DFS post-order traversal from ``start``.
+
+    Yields each subtree in left-to-right post-order (children before
+    parent). Defaults to the tree's root.
+
+    Implemented with an explicit stack of ``(handle, expanded)`` pairs
+    rather than Python recursion, so deep trees don't hit the Python
+    recursion limit.
+    """
+    nid = tree.root_handle if start is None else start
+    stack: list[tuple[H, bool]] = [(nid, False)]
+    while stack:
+        n, expanded = stack.pop()
+        if expanded:
+            yield n
+        else:
+            stack.append((n, True))
+            children = list(tree.children(n))
+            for c in reversed(children):
+                stack.append((c, False))
+
+
+def bfs[T, H: Hashable](tree: ReadOnlyTree[T, H], start: H | None = None) -> Iterator[H]:
+    """Breadth-first (level-order) traversal from ``start``.
+
+    Yields ``start`` first, then all nodes at depth 1, then depth 2,
+    and so on. Defaults to the tree's root.
+    """
+    nid = tree.root_handle if start is None else start
+    queue: deque[H] = deque([nid])
+    while queue:
+        n = queue.popleft()
+        yield n
+        for c in tree.children(n):
+            queue.append(c)

vcti_tree-1.0.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: vcti-tree
+Version: 1.0.0
+Summary: Tree protocols and generic algorithms for the vcti ecosystem. Zero-dependency abstractions; pluggable backings.
+Author: Visual Collaboration Technologies Inc.
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/vcollab/vcti-python-tree
+Project-URL: Repository, https://github.com/vcollab/vcti-python-tree
+Project-URL: Changelog, https://github.com/vcollab/vcti-python-tree/blob/main/CHANGELOG.md
+Keywords: tree,protocol,traversal,dfs,bfs,data-structure,generic-algorithms
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy; extra == "typecheck"
+Dynamic: license-file
+
+# vcti-tree
+
+Tree protocols and generic algorithms for the vcti ecosystem.
+Zero-dependency abstractions; pluggable backings.
+
+## Overview
+
+`vcti-tree` defines what a tree is in the vcti ecosystem: three
+Protocols (`ReadOnlyTree`, `MutableTree`, `LockableTree`)
+parameterised in payload type `T` and handle type `H`, plus generic
+algorithms — DFS and BFS walks, ancestor/depth/path queries,
+locking guards — written against those Protocols. The Protocols
+specify *semantics* (what a tree must support); they do not
+prescribe storage. Any backing — numpy-array, pointer-based,
+dict-based — that satisfies the Protocols gets the algorithms for
+free. The package has no numpy or other heavy dependency; it is a
+pure-Python abstraction layer that downstream tree packages depend
+on.
+
+## Why this exists
+
+Tree code in the Python ecosystem typically bundles storage,
+mutation, and traversal into a single class — every new tree
+implementation re-implements its own walker, its own navigation
+helpers, its own delete semantics. This package brings across a
+pattern that's well-established in C++: a small abstract interface
+defining what a tree *is*, multiple concrete implementations
+choosing their own storage, and generic algorithms written once
+against the interface and reused across every backing. The result
+is that adding a new tree implementation (numpy-backed,
+pointer-backed, persistent, …) doesn't mean rewriting walkers and
+guards — it means satisfying three small Protocols and inheriting
+the entire algorithm library. See [docs/design.md](docs/design.md)
+for the full background and the design decisions.
+
+## Installation
+
+```bash
+pip install vcti-tree
+```
+
+### In `requirements.txt`
+
+```
+vcti-tree>=1.0.0
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-tree>=1.0.0",
+]
+```
+
+---
+
+## Quick Start
+
+The protocols and algorithms are the API; you bring (or import) a
+backing. `DictTree` is the bundled dict-backed reference
+implementation — enough to build a tree and run the generic algorithms
+against it:
+
+```python
+from vcti.tree import DictTree, dfs_preorder, ancestors, depth
+
+tree = DictTree[str]("root")            # every tree has a root from the start
+a = tree.create_child(tree.root_handle, "a")
+b = tree.create_child(tree.root_handle, "b")
+tree.create_child(a, "a1")
+
+# Generic walks/queries work against any tree that satisfies the protocols.
+print([tree.payload(h) for h in dfs_preorder(tree)])   # ['root', 'a', 'a1', 'b']
+print([tree.payload(h) for h in ancestors(tree, a)])   # ['root']
+print(depth(tree, a))                                  # 1
+```
+
+The protocols (`ReadOnlyTree`, `MutableTree`, `LockableTree`) and the
+rest of the algorithm set are importable from the same package root:
+
+```python
+from vcti.tree import ReadOnlyTree, MutableTree, LockableTree
+from vcti.tree import dfs_preorder, dfs_postorder, bfs
+from vcti.tree import ancestors, depth, path, descendants
+```
+
+---
+
+## Dependencies
+
+None. Standard library only.

vcti_tree-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+vcti/tree/__init__.py,sha256=86WHsJNF74N78KpDivrIeiY9sFV_Y9wbpBJ9TFWCvdE,1039
+vcti/tree/dict_tree.py,sha256=NvOVElVOhBWheKMeF0sgMSTe7z1Zr8ALcZ_7ka6j96E,9029
+vcti/tree/locking.py,sha256=cblkzVJrEQbFNdBtUy9PDqRXPpwwM5UZjjiAEN6U0rE,2778
+vcti/tree/navigation.py,sha256=q-zwZ2VpaxDZAR7O0Pehc9xF0i3jGXYQRE0b2DmmQ14,1911
+vcti/tree/protocols.py,sha256=U1maKg_eQqMasScWeK4-pR7tVePAJp_G4PN_ApTtcak,7287
+vcti/tree/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vcti/tree/walking.py,sha256=ouEas9CNGkarClkFDoUxVz6OjjrItMkStDl7dyLHOO8,2604
+vcti_tree-1.0.0.dist-info/licenses/LICENSE,sha256=gqRj-E4YRsT7mZ52W76LG6aTTFv6iEOK9QR_fV5EdrI,369
+vcti_tree-1.0.0.dist-info/METADATA,sha256=CWZcQn00x59NKTYF6nb3EzoztkVwC46wooqPPaM-xew,4283
+vcti_tree-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+vcti_tree-1.0.0.dist-info/top_level.txt,sha256=Jl6AIAI3Xhru_BFQAhD_13VeXLmZQd9BqBNUaAKNgKs,5
+vcti_tree-1.0.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+vcti_tree-1.0.0.dist-info/RECORD,,

vcti_tree-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vcti_tree-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_tree-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vcti

vcti_tree-1.0.0.dist-info/zip-safe

@@ -0,0 +1 @@
+