lorebase-store 0.2.3__py3-none-any.whl

lorebase_store/models/versioning.py

@@ -0,0 +1,222 @@
+"""Versioning core (design 7.1): Domains, objects, tree nodes, Revisions, changesets, refs."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import (
+    BigInteger,
+    CheckConstraint,
+    ForeignKeyConstraint,
+    Index,
+    Integer,
+    SmallInteger,
+    text,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from lorebase_store.models.base import (
+    H32,
+    HASH_PARTITIONED,
+    Base,
+    DomainKey,
+    domain_fk,
+    h32_check,
+)
+from lorebase_store.models.enums import MATERIALIZATION, REF_KIND, Materialization, RefKind
+
+
+class Domain(Base):
+    """A Domain: the isolation boundary for schema, data, grants and history."""
+
+    __tablename__ = "domains"
+
+    id: Mapped[str] = mapped_column(primary_key=True)
+    display_name: Mapped[str]
+    description: Mapped[str | None]
+    default_branch: Mapped[str] = mapped_column(server_default=text("'main'"))
+    leaf_size: Mapped[int] = mapped_column(Integer)
+    settings: Mapped[dict[str, Any]] = mapped_column(server_default=text("'{}'::jsonb"))
+    created_at: Mapped[datetime]
+    created_by: Mapped[str]
+
+
+class StoredObject(Base):
+    """Content-addressed schema element, Record or Link, stored once per Domain."""
+
+    __tablename__ = "objects"
+    __table_args__ = (h32_check("hash"), domain_fk(), HASH_PARTITIONED)
+
+    domain_id: Mapped[DomainKey]
+    hash: Mapped[H32] = mapped_column(primary_key=True)
+    object_type: Mapped[int] = mapped_column(SmallInteger)
+    body: Mapped[dict[str, Any]]
+    size: Mapped[int] = mapped_column(Integer)
+
+
+class TreeNode(Base):
+    """Binary HAMT node; `body` uses lz4 TOAST compression (set by migration DDL)."""
+
+    __tablename__ = "tree_nodes"
+    __table_args__ = (h32_check("hash"), domain_fk(), HASH_PARTITIONED)
+
+    domain_id: Mapped[DomainKey]
+    hash: Mapped[H32] = mapped_column(primary_key=True)
+    body: Mapped[bytes]
+
+
+class Revision(Base):
+    """Immutable Revision with its generation number (design 6.4)."""
+
+    __tablename__ = "revisions"
+    __table_args__ = (h32_check("id"), h32_check("root"), domain_fk())
+
+    domain_id: Mapped[DomainKey]
+    id: Mapped[H32] = mapped_column(primary_key=True)
+    root: Mapped[H32]
+    generation: Mapped[int] = mapped_column(BigInteger)
+    author: Mapped[str]
+    on_behalf_of: Mapped[str | None]
+    message: Mapped[str]
+    origin: Mapped[dict[str, Any]]
+    stats: Mapped[dict[str, Any]]
+    created_at: Mapped[datetime]
+
+
+class RevisionParent(Base):
+    """Ordered parent edge of a Revision; position 0 is the first parent."""
+
+    __tablename__ = "revision_parents"
+    __table_args__ = (
+        ForeignKeyConstraint(
+            ["domain_id", "revision_id"],
+            ["revisions.domain_id", "revisions.id"],
+            ondelete="CASCADE",
+        ),
+        ForeignKeyConstraint(
+            ["domain_id", "parent_id"],
+            ["revisions.domain_id", "revisions.id"],
+            deferrable=True,
+            initially="DEFERRED",
+        ),
+        Index(None, "domain_id", "parent_id"),
+    )
+
+    domain_id: Mapped[DomainKey]
+    revision_id: Mapped[H32] = mapped_column(primary_key=True)
+    position: Mapped[int] = mapped_column(SmallInteger, primary_key=True)
+    parent_id: Mapped[H32]
+
+
+class ChangesetEntry(Base):
+    """One element change of a Revision against its first parent (design 6.3)."""
+
+    __tablename__ = "changesets"
+    __table_args__ = (
+        ForeignKeyConstraint(
+            ["domain_id", "revision_id"],
+            ["revisions.domain_id", "revisions.id"],
+            ondelete="CASCADE",
+        ),
+    )
+
+    domain_id: Mapped[DomainKey]
+    revision_id: Mapped[H32] = mapped_column(primary_key=True)
+    partition: Mapped[str] = mapped_column(primary_key=True)
+    element_key: Mapped[str] = mapped_column(primary_key=True)
+    old_hash: Mapped[H32 | None]
+    new_hash: Mapped[H32 | None]
+    provenance: Mapped[dict[str, Any] | None]
+
+
+class Provenance(Base):
+    """Where a value came from: origin, actor and time."""
+
+    __tablename__ = "provenance"
+    __table_args__ = (domain_fk(),)
+
+    domain_id: Mapped[DomainKey]
+    id: Mapped[str] = mapped_column(primary_key=True)
+    origin_type: Mapped[str]
+    origin_ref: Mapped[dict[str, Any]] = mapped_column(JSONB)
+    actor: Mapped[str]
+    at: Mapped[datetime]
+
+
+class Ref(Base):
+    """Branch or tag head; moved by compare-and-swap on `(head, version)`.
+
+    An overlay branch (design 6.11) names its base branch and the base head it was forked
+    from (`base_revision`, with its generation): it stores only the rows it changed and reads
+    the base rows as of that point. The three columns are set exactly for overlays.
+
+    `deleted_at` marks a branch whose deletion is in progress (revision 0017): it is hidden
+    from every read and write while a `store.branch_delete` job removes its rows in batches,
+    and its name stays taken until the job deletes the ref.
+    """
+
+    __tablename__ = "refs"
+    __table_args__ = (
+        ForeignKeyConstraint(
+            ["domain_id", "head"],
+            ["revisions.domain_id", "revisions.id"],
+            deferrable=True,
+            initially="DEFERRED",
+        ),
+        ForeignKeyConstraint(
+            ["domain_id", "base_branch"],
+            ["refs.domain_id", "refs.name"],
+            deferrable=True,
+            initially="DEFERRED",
+        ),
+        ForeignKeyConstraint(
+            ["domain_id", "base_revision"],
+            ["revisions.domain_id", "revisions.id"],
+            deferrable=True,
+            initially="DEFERRED",
+        ),
+        CheckConstraint(
+            "(materialization = 'overlay') = (base_branch IS NOT NULL "
+            "AND base_revision IS NOT NULL AND base_generation IS NOT NULL)",
+            name="overlay_base",
+        ),
+        Index(
+            "ix_refs_domain_id_base_branch",
+            "domain_id",
+            "base_branch",
+            postgresql_where=text("base_branch IS NOT NULL"),
+        ),
+        domain_fk(),
+    )
+
+    domain_id: Mapped[DomainKey]
+    name: Mapped[str] = mapped_column(primary_key=True)
+    kind: Mapped[RefKind] = mapped_column(REF_KIND)
+    head: Mapped[H32]
+    protected: Mapped[bool] = mapped_column(server_default=text("false"))
+    materialization: Mapped[Materialization] = mapped_column(MATERIALIZATION)
+    version: Mapped[int] = mapped_column(BigInteger)
+    created_at: Mapped[datetime]
+    created_by: Mapped[str]
+    base_branch: Mapped[str | None]
+    base_revision: Mapped[H32 | None]
+    base_generation: Mapped[int | None] = mapped_column(BigInteger)
+    deleted_at: Mapped[datetime | None]
+
+
+class RefLogEntry(Base):
+    """Every head movement of a ref, kept after the ref is deleted."""
+
+    __tablename__ = "ref_log"
+    __table_args__ = (domain_fk(),)
+
+    domain_id: Mapped[DomainKey]
+    ref_name: Mapped[str] = mapped_column(primary_key=True)
+    seq: Mapped[int] = mapped_column(BigInteger, primary_key=True)
+    old_head: Mapped[H32 | None]
+    new_head: Mapped[H32]
+    reason: Mapped[str]
+    actor: Mapped[str]
+    at: Mapped[datetime]

lorebase_store/models/webhooks.py

@@ -0,0 +1,96 @@
+"""Webhooks of a Domain and their deliveries (design 10.5).
+
+A webhook receives the outbox events of its Domain (optionally narrowed to event types and
+branches) as HMAC-signed POST requests. Only a SHA-256 digest of its secret is kept; the
+digest is the signing key (`lorebase_store.webhooks.signing`), stored sealed in `sealed_key`
+when `webhooks.encryption_key` is set, else usable in `secret_hash` (`webhooks.keys`).
+Deliveries are fanned out from the outbox and retried with backoff until delivered or dead.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import (
+    BigInteger,
+    CheckConstraint,
+    ForeignKeyConstraint,
+    Identity,
+    Index,
+    Integer,
+    UniqueConstraint,
+    text,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from lorebase_store.models.base import H32, Base, DomainKey, domain_fk, h32_check
+
+DELIVERY_STATUSES = ("pending", "delivered", "dead")
+
+
+class Webhook(Base):
+    """An HTTP endpoint notified of the events of a Domain."""
+
+    __tablename__ = "webhooks"
+    __table_args__ = (
+        domain_fk(),
+        h32_check("secret_hash"),
+        CheckConstraint("(secret_hash IS NULL) <> (sealed_key IS NULL)", name="one_signing_key"),
+    )
+
+    domain_id: Mapped[DomainKey]
+    id: Mapped[str] = mapped_column(primary_key=True)
+    url: Mapped[str]
+    description: Mapped[str | None]
+    event_types: Mapped[Any] = mapped_column(JSONB)
+    """Event types delivered (a JSON array of strings)."""
+    branches: Mapped[Any | None] = mapped_column(JSONB)
+    """Branch names whose events are delivered (a JSON array); null for every branch."""
+    clearances: Mapped[Any] = mapped_column(JSONB, server_default=text("'[]'::jsonb"))
+    """Sensitivity tags whose values the webhook receives in clear (a JSON array); values of
+    other sensitive Attributes reach it masked."""
+    secret_hash: Mapped[H32 | None]
+    """The signing key, stored usable (no `webhooks.encryption_key` when it was stored)."""
+    sealed_key: Mapped[bytes | None]
+    """The signing key sealed under `webhooks.encryption_key` (nonce and AES-GCM ciphertext)."""
+    created_by: Mapped[str]
+    created_at: Mapped[datetime] = mapped_column(server_default=text("now()"))
+
+
+class WebhookDelivery(Base):
+    """One outbox event to deliver to one webhook, with its attempts."""
+
+    __tablename__ = "webhook_deliveries"
+    __table_args__ = (
+        ForeignKeyConstraint(
+            ["domain_id", "webhook_id"],
+            ["webhooks.domain_id", "webhooks.id"],
+            ondelete="CASCADE",
+        ),
+        UniqueConstraint("domain_id", "webhook_id", "event_id"),
+        CheckConstraint(
+            "status IN (" + ", ".join(f"'{s}'" for s in DELIVERY_STATUSES) + ")", name="status"
+        ),
+        Index(
+            "ix_webhook_deliveries_due",
+            "next_attempt_at",
+            postgresql_where=text("status = 'pending'"),
+        ),
+    )
+
+    domain_id: Mapped[DomainKey]
+    id: Mapped[int] = mapped_column(BigInteger, Identity(always=True), primary_key=True)
+    webhook_id: Mapped[str]
+    event_id: Mapped[int] = mapped_column(BigInteger)
+    event_type: Mapped[str]
+    payload: Mapped[dict[str, Any]]
+    status: Mapped[str] = mapped_column(server_default=text("'pending'"))
+    attempts: Mapped[int] = mapped_column(Integer, server_default=text("0"))
+    next_attempt_at: Mapped[datetime] = mapped_column(server_default=text("now()"))
+    last_status: Mapped[int | None] = mapped_column(Integer)
+    last_error: Mapped[str | None]
+    delivered_at: Mapped[datetime | None]
+    created_at: Mapped[datetime] = mapped_column(server_default=text("now()"))
+    updated_at: Mapped[datetime] = mapped_column(server_default=text("now()"))

lorebase_store/nodestore.py

@@ -0,0 +1,384 @@
+"""Tree nodes in Postgres (`tree_nodes`), scoped to one Domain.
+
+Two access paths share one process-wide cache:
+
+- `PgNodeStore` implements the synchronous core `NodeStore` protocol over a synchronous
+  `Session`. It is meant to run inside `AsyncSession.run_sync`, where SQLAlchemy drives the
+  async driver from synchronous code. Callers prefetch the nodes a tree operation will read
+  (`prefetch_paths` for a batch of keys) so that the operation reads from memory; a miss falls
+  back to a single-node query. Writes are buffered and handed to the async side in bulk.
+- `NodeRepository` is the async side: batched reads, bulk writes with `ON CONFLICT DO NOTHING`,
+  and streaming scans of whole partitions.
+
+Nodes are immutable and content-addressed, so cached bodies never go stale. The cache only
+holds bodies read from the database; `has()` never answers from it, because a node written by
+a transaction that later rolled back may still be cached.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import OrderedDict, defaultdict
+from collections.abc import AsyncIterator, Iterable, Mapping, Sequence
+from dataclasses import dataclass
+
+from sqlalchemy import Table, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Session
+
+from lorebase_core.canonical import node_hash
+from lorebase_core.tree import (
+    BranchNode,
+    LeafNode,
+    MissingNodeError,
+    NodeType,
+    Tree,
+    decode_node,
+    key_hash,
+)
+from lorebase_store.bulk import bulk_write, chunks
+from lorebase_store.models import metadata
+from lorebase_store.settings import NodeSettings, WriteSettings
+
+TREE_NODES: Table = metadata.tables["tree_nodes"]
+
+_NODE_TYPE_OFFSET = 1
+"""Byte offset of the node type in the node header (after the format version)."""
+
+
+def node_type(body: bytes) -> NodeType:
+    """Type of an encoded node, read from its header without decoding the body."""
+    return NodeType(body[_NODE_TYPE_OFFSET])
+
+
+class NodeCache:
+    """Thread-safe LRU of node bodies keyed by `(domain_id, hash)`, bounded in bytes."""
+
+    def __init__(self, max_bytes: int) -> None:
+        if max_bytes < 0:
+            raise ValueError("max_bytes must not be negative")
+        self._max_bytes = max_bytes
+        self._bytes = 0
+        self._entries: OrderedDict[tuple[str, bytes], bytes] = OrderedDict()
+        self._lock = threading.Lock()
+
+    @classmethod
+    def from_settings(cls, settings: NodeSettings) -> NodeCache:
+        return cls(settings.cache_bytes)
+
+    @property
+    def size_bytes(self) -> int:
+        return self._bytes
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def get(self, domain_id: str, digest: bytes) -> bytes | None:
+        key = (domain_id, digest)
+        with self._lock:
+            body = self._entries.get(key)
+            if body is not None:
+                self._entries.move_to_end(key)
+            return body
+
+    def put(self, domain_id: str, digest: bytes, body: bytes) -> None:
+        if len(body) > self._max_bytes:
+            return
+        key = (domain_id, digest)
+        with self._lock:
+            if key in self._entries:
+                self._entries.move_to_end(key)
+                return
+            self._entries[key] = body
+            self._bytes += len(body)
+            while self._bytes > self._max_bytes:
+                _, evicted = self._entries.popitem(last=False)
+                self._bytes -= len(evicted)
+
+
+@dataclass
+class NodeReadStats:
+    """Counters of a `PgNodeStore`, used to check that reads are batched."""
+
+    queries: int = 0
+    fetched: int = 0
+    misses: int = 0
+
+
+class PgNodeStore:
+    """Synchronous `NodeStore` for one Domain over a synchronous `Session` (see module doc)."""
+
+    def __init__(
+        self,
+        session: Session,
+        domain_id: str,
+        *,
+        cache: NodeCache | None = None,
+        prefetch_batch: int = 1000,
+    ) -> None:
+        self._session = session
+        self._domain = domain_id
+        self._cache = cache
+        self._batch = prefetch_batch
+        self._local: dict[bytes, bytes] = {}
+        self._pending: dict[bytes, bytes] = {}
+        self.stats = NodeReadStats()
+
+    @property
+    def domain_id(self) -> str:
+        return self._domain
+
+    # NodeStore protocol ---------------------------------------------------------------
+
+    def get(self, node_hash: bytes) -> bytes | None:
+        body = self._known(node_hash)
+        if body is None:
+            self.stats.misses += 1
+            self.prefetch([node_hash])
+            body = self._local.get(node_hash)
+        return body
+
+    def put(self, node_hash: bytes, body: bytes) -> None:
+        _verify(node_hash, body)
+        self._pending.setdefault(node_hash, body)
+
+    def has(self, node_hash: bytes) -> bool:
+        if node_hash in self._pending or node_hash in self._local:
+            return True
+        self.prefetch([node_hash], use_cache=False)
+        return node_hash in self._local
+
+    # Batched reads ------------------------------------------------------------------
+
+    def prefetch(self, hashes: Iterable[bytes], *, use_cache: bool = True) -> None:
+        """Load the given nodes in batched queries; already known nodes are skipped."""
+        missing: list[bytes] = []
+        for digest in dict.fromkeys(hashes):
+            if digest in self._pending or digest in self._local:
+                continue
+            cached = self._cache.get(self._domain, digest) if use_cache and self._cache else None
+            if cached is not None:
+                self._local[digest] = cached
+            else:
+                missing.append(digest)
+        for chunk in chunks(missing, self._batch):
+            rows = self._session.execute(
+                select(TREE_NODES.c.hash, TREE_NODES.c.body).where(
+                    TREE_NODES.c.domain_id == self._domain, TREE_NODES.c.hash.in_(chunk)
+                )
+            )
+            self.stats.queries += 1
+            for digest, body in rows:
+                self._local[digest] = body
+                self.stats.fetched += 1
+                if self._cache is not None:
+                    self._cache.put(self._domain, digest, body)
+
+    def prefetch_paths(self, root: bytes | None, keys: Iterable[tuple[str, str]]) -> None:
+        """Load the nodes on the paths from `root` to the given `(partition, key)` entries.
+
+        One query per tree level, so a batch update over the prefetched paths reads no node
+        individually (except when a branch collapses into a leaf and siblings are read).
+        """
+        if root is None:
+            return
+        self.prefetch([root])
+        if self._known(root) is None:
+            raise MissingNodeError(root.hex())
+        partitions = Tree.load(self, root).partitions
+        wanted: dict[str, list[bytes]] = defaultdict(list)
+        for partition, key in keys:
+            if partition in partitions:
+                wanted[partition].append(key_hash(key))
+        frontier = [(partitions[p].root, 0, hashes) for p, hashes in wanted.items()]
+        while frontier:
+            self.prefetch(digest for digest, _, _ in frontier)
+            following: list[tuple[bytes, int, list[bytes]]] = []
+            for digest, depth, hashes in frontier:
+                body = self._known(digest)
+                if body is None:
+                    raise MissingNodeError(digest.hex())
+                if node_type(body) is not NodeType.BRANCH:
+                    continue
+                node = decode_node(body)
+                assert isinstance(node, BranchNode)
+                children = dict(node.children)
+                groups: dict[int, list[bytes]] = defaultdict(list)
+                for placement in hashes:
+                    groups[placement[depth]].append(placement)
+                for index, group in groups.items():
+                    child = children.get(index)
+                    if child is not None:
+                        following.append((child, depth + 1, group))
+            frontier = following
+
+    # Buffered writes ------------------------------------------------------------------
+
+    @property
+    def pending(self) -> Mapping[bytes, bytes]:
+        """Nodes written through this store and not yet persisted."""
+        return self._pending
+
+    def take_pending(self) -> dict[bytes, bytes]:
+        """Return and forget the buffered writes, to persist with `NodeRepository.put_many`."""
+        pending, self._pending = self._pending, {}
+        self._local.update(pending)
+        return pending
+
+    def _known(self, digest: bytes) -> bytes | None:
+        body = self._pending.get(digest) or self._local.get(digest)
+        if body is None and self._cache is not None:
+            body = self._cache.get(self._domain, digest)
+            if body is not None:
+                self._local[digest] = body
+        return body
+
+
+class NodeRepository:
+    """Async batched reads and bulk writes of one Domain's tree nodes."""
+
+    def __init__(
+        self,
+        session: AsyncSession,
+        domain_id: str,
+        *,
+        writes: WriteSettings,
+        cache: NodeCache | None = None,
+        batch: int = 1000,
+    ) -> None:
+        self._session = session
+        self._domain = domain_id
+        self._writes = writes
+        self._cache = cache
+        self._batch = batch
+
+    async def get_many(
+        self, hashes: Iterable[bytes], *, use_cache: bool = True
+    ) -> dict[bytes, bytes]:
+        """Bodies of the given nodes that exist."""
+        found: dict[bytes, bytes] = {}
+        missing: list[bytes] = []
+        for digest in dict.fromkeys(hashes):
+            cached = self._cache.get(self._domain, digest) if use_cache and self._cache else None
+            if cached is None:
+                missing.append(digest)
+            else:
+                found[digest] = cached
+        for chunk in chunks(missing, self._batch):
+            rows = await self._session.execute(
+                select(TREE_NODES.c.hash, TREE_NODES.c.body).where(
+                    TREE_NODES.c.domain_id == self._domain, TREE_NODES.c.hash.in_(chunk)
+                )
+            )
+            for digest, body in rows:
+                found[digest] = body
+                if use_cache and self._cache is not None:
+                    self._cache.put(self._domain, digest, body)
+        return found
+
+    async def put_many(self, nodes: Mapping[bytes, bytes]) -> None:
+        """Persist nodes; nodes already stored are left unchanged."""
+        rows = [
+            {"domain_id": self._domain, "hash": digest, "body": body}
+            for digest, body in nodes.items()
+        ]
+        await bulk_write(self._session, TREE_NODES, rows, writes=self._writes)
+
+    async def load_tree(self, root: bytes) -> Tree:
+        """The partition map of the tree rooted at `root`."""
+        body = (await self.get_many([root])).get(root)
+        if body is None:
+            raise MissingNodeError(root.hex())
+        return Tree.load(_SingleNode(root, body), root)
+
+    async def scan(self, node: bytes) -> AsyncIterator[list[tuple[str, bytes]]]:
+        """Stream the `(element_key, object_hash)` entries of a partition subtree.
+
+        Reads one tree level per round in batched queries and yields the entries of each
+        batch of leaves; memory stays bounded by one batch plus the branch frontier. Scanned
+        nodes do not enter the cache.
+        """
+        frontier: list[bytes] = [node]
+        while frontier:
+            following: list[bytes] = []
+            for chunk in chunks(frontier, self._batch):
+                bodies = await self.get_many(chunk, use_cache=False)
+                entries: list[tuple[str, bytes]] = []
+                for digest in chunk:
+                    body = bodies.get(digest)
+                    if body is None:
+                        raise MissingNodeError(digest.hex())
+                    decoded = decode_node(body)
+                    if isinstance(decoded, LeafNode):
+                        entries.extend(decoded.entries)
+                    elif isinstance(decoded, BranchNode):
+                        following.extend(child for _, child in decoded.children)
+                if entries:
+                    yield entries
+            frontier = following
+
+    async def scan_from(
+        self, node: bytes, *, after: Sequence[int] | None, limit: int
+    ) -> tuple[list[tuple[str, bytes]], list[int] | None]:
+        """Entries of a partition subtree, whole leaves at a time, in a fixed depth-first
+        order: those of the leaves after the leaf at path `after` (child bytes from `node`;
+        `None` starts at the first leaf), until at least `limit` entries. Returns them with
+        the path of the last leaf read, or `None` when no leaf is left.
+
+        The order depends on the subtree only, which never changes, so a caller can resume
+        from the returned path in a later transaction. Each branch node's children are read
+        in one query; scanned nodes do not enter the cache.
+        """
+        entries: list[tuple[str, bytes]] = []
+        bodies = await self.get_many([node], use_cache=False)
+        stack: list[tuple[bytes, list[int], list[int] | None]] = [
+            (node, [], None if after is None else list(after))
+        ]
+        while stack:
+            digest, path, bound = stack.pop()
+            body = bodies.pop(digest, None)
+            if body is None:
+                raise MissingNodeError(digest.hex())
+            decoded = decode_node(body)
+            if isinstance(decoded, LeafNode):
+                if bound is not None:
+                    continue  # the leaf at `after` itself: already read
+                entries.extend(decoded.entries)
+                if len(entries) >= limit:
+                    return entries, path
+                continue
+            if not isinstance(decoded, BranchNode):
+                continue
+            wanted: list[tuple[bytes, list[int], list[int] | None]] = []
+            for byte, child in decoded.children:
+                if bound is not None and bound and byte < bound[0]:
+                    continue
+                inner = bound[1:] if bound is not None and bound and byte == bound[0] else None
+                wanted.append((child, [*path, byte], inner))
+            missing = [child for child, _, _ in wanted if child not in bodies]
+            if missing:
+                bodies.update(await self.get_many(missing, use_cache=False))
+            stack.extend(reversed(wanted))
+        return entries, None
+
+
+class _SingleNode:
+    """Read-only `NodeStore` over one known node."""
+
+    def __init__(self, digest: bytes, body: bytes) -> None:
+        self._digest = digest
+        self._body = body
+
+    def get(self, node_hash: bytes) -> bytes | None:
+        return self._body if node_hash == self._digest else None
+
+    def put(self, node_hash: bytes, body: bytes) -> None:
+        raise TypeError("read-only node store")
+
+    def has(self, node_hash: bytes) -> bool:
+        return node_hash == self._digest
+
+
+def _verify(expected: bytes, body: bytes) -> None:
+    if node_hash(body) != expected:
+        raise ValueError("node hash does not match node body")