lorebase-core 0.2.3__py3-none-any.whl

lorebase_core/revision/__init__.py

@@ -0,0 +1,59 @@
+"""Revisions, changesets, ancestry and merge base (design 6.3, 6.4, 6.8)."""
+
+from lorebase_core.revision.ancestry import (
+    InMemoryRevisionGraph,
+    MergeBaseError,
+    MergeBaseResult,
+    MergeStatus,
+    RevisionGraph,
+    UnknownRevisionError,
+    VirtualBaseBuilder,
+    VirtualRevision,
+    is_ancestor,
+    lowest_common_ancestors,
+    merge_base,
+)
+from lorebase_core.revision.changeset import (
+    ChangesetEntry,
+    changeset_between,
+    changeset_stats,
+    changeset_tree_changes,
+)
+from lorebase_core.revision.revision import (
+    ROOT_GENERATION,
+    Author,
+    Hash,
+    Origin,
+    Revision,
+    RevisionStats,
+    format_timestamp,
+    next_generation,
+    revision_id,
+)
+
+__all__ = [
+    "ROOT_GENERATION",
+    "Author",
+    "ChangesetEntry",
+    "Hash",
+    "InMemoryRevisionGraph",
+    "MergeBaseError",
+    "MergeBaseResult",
+    "MergeStatus",
+    "Origin",
+    "Revision",
+    "RevisionGraph",
+    "RevisionStats",
+    "UnknownRevisionError",
+    "VirtualBaseBuilder",
+    "VirtualRevision",
+    "changeset_between",
+    "changeset_stats",
+    "changeset_tree_changes",
+    "format_timestamp",
+    "is_ancestor",
+    "lowest_common_ancestors",
+    "merge_base",
+    "next_generation",
+    "revision_id",
+]

lorebase_core/revision/ancestry.py

@@ -0,0 +1,272 @@
+"""Revision ancestry: generation numbers, lowest common ancestors and merge base.
+
+Design 6.4 and 6.8 step 0, AC-13.
+"""
+
+from __future__ import annotations
+
+import heapq
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Protocol, runtime_checkable
+
+from lorebase_core.revision.revision import Revision, next_generation, revision_id
+
+__all__ = [
+    "InMemoryRevisionGraph",
+    "MergeBaseError",
+    "MergeBaseResult",
+    "MergeStatus",
+    "RevisionGraph",
+    "UnknownRevisionError",
+    "VirtualBaseBuilder",
+    "VirtualRevision",
+    "is_ancestor",
+    "lowest_common_ancestors",
+    "merge_base",
+]
+
+
+class UnknownRevisionError(KeyError):
+    """Raised when a Revision id is not in the graph."""
+
+
+class MergeBaseError(ValueError):
+    """Raised when a merge base cannot be determined."""
+
+
+@runtime_checkable
+class RevisionGraph(Protocol):
+    """Read access to the Revision DAG."""
+
+    def parents(self, revision_id: bytes) -> Sequence[bytes]: ...
+
+    def generation(self, revision_id: bytes) -> int: ...
+
+
+class InMemoryRevisionGraph:
+    """Dictionary-backed :class:`RevisionGraph`."""
+
+    def __init__(self) -> None:
+        self._parents: dict[bytes, tuple[bytes, ...]] = {}
+        self._generations: dict[bytes, int] = {}
+
+    def add(self, revision: bytes, parents: Iterable[bytes] = ()) -> int:
+        """Register a Revision whose parents are already known; return its generation."""
+        parent_ids = tuple(parents)
+        known = self._parents.get(revision)
+        if known is not None:
+            if known != parent_ids:
+                raise ValueError("revision already registered with different parents")
+            return self._generations[revision]
+        generation = next_generation(self.generation(p) for p in parent_ids)
+        self._parents[revision] = parent_ids
+        self._generations[revision] = generation
+        return generation
+
+    def add_revision(self, revision: Revision) -> bytes:
+        """Register a Revision object and return its id."""
+        rev_id = revision_id(revision)
+        self.add(rev_id, revision.parents)
+        return rev_id
+
+    def parents(self, revision_id: bytes) -> Sequence[bytes]:
+        try:
+            return self._parents[revision_id]
+        except KeyError:
+            raise UnknownRevisionError(revision_id.hex()) from None
+
+    def generation(self, revision_id: bytes) -> int:
+        try:
+            return self._generations[revision_id]
+        except KeyError:
+            raise UnknownRevisionError(revision_id.hex()) from None
+
+    def __contains__(self, revision_id: object) -> bool:
+        return revision_id in self._parents
+
+
+def is_ancestor(graph: RevisionGraph, ancestor: bytes, descendant: bytes) -> bool:
+    """True when ``ancestor`` is ``descendant`` or reachable from it through parents."""
+    if ancestor == descendant:
+        graph.generation(ancestor)
+        return True
+    floor = graph.generation(ancestor)
+    seen = {descendant}
+    stack = [descendant]
+    while stack:
+        for parent in graph.parents(stack.pop()):
+            if parent == ancestor:
+                return True
+            # Parents always have a lower generation, so nothing at or below
+            # the ancestor's generation can lead to it.
+            if parent not in seen and graph.generation(parent) > floor:
+                seen.add(parent)
+                stack.append(parent)
+    return False
+
+
+_OURS = 1
+_THEIRS = 2
+_STALE = 4
+_BOTH = _OURS | _THEIRS
+
+
+def lowest_common_ancestors(graph: RevisionGraph, a: bytes, b: bytes) -> tuple[bytes, ...]:
+    """All lowest common ancestors of ``a`` and ``b``, ordered by (generation, id).
+
+    Walks both histories at once in decreasing generation order. Parents always
+    have a lower generation than their children, so when a Revision is visited
+    every path from ``a`` or ``b`` to it has already been seen: a Revision
+    reached from both sides is a common ancestor, and everything below it is
+    marked stale. The walk stops as soon as no unvisited, non-stale Revision
+    is reachable from both sides.
+    """
+    if a == b:
+        graph.generation(a)
+        return (a,)
+    flags = {a: _OURS, b: _THEIRS}
+    heap = [(-graph.generation(a), a), (-graph.generation(b), b)]
+    heapq.heapify(heap)
+    pending: dict[int, set[bytes]] = {_OURS: {a}, _THEIRS: {b}}
+    visited: set[bytes] = set()
+    found: list[bytes] = []
+    while pending[_OURS] and pending[_THEIRS]:
+        _, current = heapq.heappop(heap)
+        if current in visited:
+            continue
+        visited.add(current)
+        pending[_OURS].discard(current)
+        pending[_THEIRS].discard(current)
+        state = flags[current]
+        if state & _BOTH == _BOTH and not state & _STALE:
+            found.append(current)
+            state |= _STALE
+            flags[current] = state
+        for parent in graph.parents(current):
+            old = flags.get(parent, 0)
+            new = old | state
+            if new == old:
+                continue
+            flags[parent] = new
+            heapq.heappush(heap, (-graph.generation(parent), parent))
+            for side in (_OURS, _THEIRS):
+                if new & side and not new & _STALE:
+                    pending[side].add(parent)
+                else:
+                    pending[side].discard(parent)
+    return tuple(sorted(found, key=lambda rev: (graph.generation(rev), rev)))
+
+
+class MergeStatus(StrEnum):
+    UP_TO_DATE = "up_to_date"
+    """Theirs is already contained in ours: nothing to merge."""
+    FAST_FORWARD = "fast_forward"
+    """Ours is an ancestor of theirs: the target can move to theirs."""
+    MERGE = "merge"
+    """Histories diverged: a three-way merge against ``base`` is needed."""
+    UNRELATED = "unrelated"
+    """No common ancestor: merge against the empty tree."""
+
+
+class VirtualBaseBuilder(Protocol):
+    """Builds a synthetic merge of two Revisions and returns its Revision id.
+
+    Called with the merge base of the pair (``None`` when they share no
+    ancestor). Implemented by the merge engine; the result is never committed.
+    """
+
+    def __call__(self, base: bytes | None, ours: bytes, theirs: bytes) -> bytes: ...
+
+
+@dataclass(frozen=True, slots=True)
+class VirtualRevision:
+    """A synthetic Revision produced while building a virtual merge base."""
+
+    id: bytes
+    parents: tuple[bytes, bytes]
+
+
+@dataclass(frozen=True, slots=True)
+class MergeBaseResult:
+    status: MergeStatus
+    base: bytes | None
+    """Revision to use as merge base: a real ancestor, a virtual Revision, or ``None``."""
+    common_ancestors: tuple[bytes, ...]
+    """The lowest common ancestors, ordered by (generation, id)."""
+    virtual_revisions: tuple[VirtualRevision, ...] = ()
+    """Synthetic Revisions built for criss-cross histories, in creation order."""
+
+    @property
+    def virtual(self) -> bool:
+        return bool(self.virtual_revisions)
+
+
+def merge_base(
+    graph: RevisionGraph,
+    ours: bytes,
+    theirs: bytes,
+    build_virtual: VirtualBaseBuilder | None = None,
+) -> MergeBaseResult:
+    """Determine how to merge ``theirs`` (source head) into ``ours`` (target head).
+
+    With several lowest common ancestors (criss-cross history) they are merged
+    pairwise and recursively into a virtual base through ``build_virtual``.
+    """
+    common = lowest_common_ancestors(graph, ours, theirs)
+    if theirs in common:
+        return MergeBaseResult(MergeStatus.UP_TO_DATE, theirs, common)
+    if ours in common:
+        return MergeBaseResult(MergeStatus.FAST_FORWARD, ours, common)
+    if not common:
+        return MergeBaseResult(MergeStatus.UNRELATED, None, common)
+    if len(common) == 1:
+        return MergeBaseResult(MergeStatus.MERGE, common[0], common)
+    if build_virtual is None:
+        raise MergeBaseError("several lowest common ancestors and no virtual base builder")
+    overlay = _OverlayGraph(graph)
+    base = _virtual_base(overlay, common, build_virtual)
+    return MergeBaseResult(MergeStatus.MERGE, base, common, tuple(overlay.added))
+
+
+def _virtual_base(
+    graph: _OverlayGraph, ancestors: Sequence[bytes], build: VirtualBaseBuilder
+) -> bytes:
+    merged = ancestors[0]
+    for following in ancestors[1:]:
+        inner = lowest_common_ancestors(graph, merged, following)
+        if not inner:
+            base: bytes | None = None
+        elif len(inner) == 1:
+            base = inner[0]
+        else:
+            base = _virtual_base(graph, inner, build)
+        virtual = build(base, merged, following)
+        graph.add_virtual(virtual, (merged, following))
+        merged = virtual
+    return merged
+
+
+class _OverlayGraph:
+    """A graph extended with the virtual Revisions of one merge-base computation."""
+
+    def __init__(self, base: RevisionGraph) -> None:
+        self._base = base
+        self._virtual: dict[bytes, tuple[tuple[bytes, bytes], int]] = {}
+        self.added: list[VirtualRevision] = []
+
+    def add_virtual(self, revision: bytes, parents: tuple[bytes, bytes]) -> None:
+        if revision in self._virtual:
+            raise MergeBaseError("virtual base builder returned a duplicate Revision id")
+        generation = next_generation(self.generation(p) for p in parents)
+        self._virtual[revision] = (parents, generation)
+        self.added.append(VirtualRevision(revision, parents))
+
+    def parents(self, revision_id: bytes) -> Sequence[bytes]:
+        entry = self._virtual.get(revision_id)
+        return entry[0] if entry is not None else self._base.parents(revision_id)
+
+    def generation(self, revision_id: bytes) -> int:
+        entry = self._virtual.get(revision_id)
+        return entry[1] if entry is not None else self._base.generation(revision_id)

lorebase_core/revision/changeset.py

@@ -0,0 +1,62 @@
+"""Changesets: the delta of a Revision against its first parent (design 6.3)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+
+from lorebase_core.canonical import HASH_SIZE
+from lorebase_core.revision.revision import RevisionStats
+from lorebase_core.tree import NodeStore, TreeChange, tree_diff
+
+__all__ = ["ChangesetEntry", "changeset_between", "changeset_stats", "changeset_tree_changes"]
+
+_NO_PROVENANCE: Mapping[str, str] = MappingProxyType({})
+
+
+@dataclass(frozen=True, slots=True)
+class ChangesetEntry:
+    """One changed element: ``None`` hashes mean absent.
+
+    ``provenance`` maps each changed Attribute id to its provenance entry id;
+    it is not part of any content hash (AC-08).
+    """
+
+    partition: str
+    key: str
+    old_hash: bytes | None
+    new_hash: bytes | None
+    provenance: Mapping[str, str] = field(default=_NO_PROVENANCE, compare=False)
+
+    def __post_init__(self) -> None:
+        if self.old_hash == self.new_hash:
+            raise ValueError("a changeset entry must change the element")
+        for h in (self.old_hash, self.new_hash):
+            if h is not None and len(h) != HASH_SIZE:
+                raise ValueError(f"hashes are {HASH_SIZE} bytes")
+
+
+def changeset_between(
+    store: NodeStore, parent_root: bytes | None, root: bytes
+) -> list[ChangesetEntry]:
+    """Changeset of ``root`` against its first parent's root, without provenance."""
+    return [
+        ChangesetEntry(d.partition, d.key, d.hash_a, d.hash_b)
+        for d in tree_diff(store, parent_root, root)
+    ]
+
+
+def changeset_tree_changes(entries: Iterable[ChangesetEntry]) -> list[TreeChange]:
+    """Tree changes that turn the parent tree into the Revision tree."""
+    return [TreeChange(e.partition, e.key, e.new_hash) for e in entries]
+
+
+def changeset_stats(entries: Iterable[ChangesetEntry]) -> RevisionStats:
+    """Revision stats derived from a changeset."""
+    partitions: set[str] = set()
+    changes = 0
+    for entry in entries:
+        partitions.add(entry.partition)
+        changes += 1
+    return RevisionStats(partitions_changed=len(partitions), changes=changes)

lorebase_core/revision/revision.py

@@ -0,0 +1,121 @@
+"""Revision objects and their content hash (design 6.4)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from typing import Annotated
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field, field_validator
+
+from lorebase_core.canonical import HASH_SIZE, from_hex, hex, revision_hash
+
+__all__ = [
+    "ROOT_GENERATION",
+    "Author",
+    "Hash",
+    "Origin",
+    "Revision",
+    "RevisionStats",
+    "format_timestamp",
+    "next_generation",
+    "revision_id",
+]
+
+ROOT_GENERATION = 1
+"""Generation number of a Revision without parents."""
+
+
+def _parse_hash(value: object) -> object:
+    if isinstance(value, str):
+        return from_hex(value)
+    if isinstance(value, bytes) and len(value) != HASH_SIZE:
+        raise ValueError(f"hashes are {HASH_SIZE} bytes")
+    return value
+
+
+Hash = Annotated[bytes, BeforeValidator(_parse_hash)]
+"""A 32-byte hash; accepts raw bytes or lowercase hex."""
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class Author(_Frozen):
+    principal: str = Field(min_length=1)
+    on_behalf_of: str | None = None
+
+
+class Origin(_Frozen):
+    type: str = Field(min_length=1)
+    ref: str | None = None
+
+
+class RevisionStats(_Frozen):
+    partitions_changed: int = Field(ge=0)
+    changes: int = Field(ge=0)
+
+
+class Revision(_Frozen):
+    """An immutable snapshot: tree root, parents and metadata.
+
+    ``parents[0]`` is the first parent (the target branch for merges).
+    """
+
+    parents: tuple[Hash, ...] = ()
+    root: Hash
+    domain: str = Field(min_length=1)
+    author: Author
+    message: str
+    origin: Origin
+    created_at: datetime
+    stats: RevisionStats
+
+    @field_validator("parents")
+    @classmethod
+    def _distinct_parents(cls, parents: tuple[bytes, ...]) -> tuple[bytes, ...]:
+        if len(set(parents)) != len(parents):
+            raise ValueError("parents must be distinct")
+        return parents
+
+    @field_validator("created_at")
+    @classmethod
+    def _utc(cls, value: datetime) -> datetime:
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("created_at must carry a time zone")
+        return value.astimezone(UTC)
+
+    def canonical_payload(self) -> dict[str, object]:
+        """The JSON document whose canonical form is hashed into the Revision id."""
+        return {
+            "parents": [hex(p) for p in self.parents],
+            "root": hex(self.root),
+            "domain": self.domain,
+            "author": self.author.model_dump(),
+            "message": self.message,
+            "origin": self.origin.model_dump(),
+            "created_at": format_timestamp(self.created_at),
+            "stats": self.stats.model_dump(),
+        }
+
+
+def revision_id(revision: Revision) -> bytes:
+    """Revision id: ``sha256("lb1\\x00revision\\x00" + canonical_json)``."""
+    return revision_hash(revision.canonical_payload())
+
+
+def next_generation(parent_generations: Iterable[int]) -> int:
+    """Generation of a Revision: ``1 + max(parent generations)``, or 1 without parents."""
+    return 1 + max(parent_generations, default=ROOT_GENERATION - 1)
+
+
+def format_timestamp(value: datetime) -> str:
+    """RFC 3339 UTC with exactly six fractional digits."""
+    if value.tzinfo is None:
+        raise ValueError("timestamp must carry a time zone")
+    utc = value.astimezone(UTC)
+    return (
+        f"{utc.year:04d}-{utc.month:02d}-{utc.day:02d}"
+        f"T{utc.hour:02d}:{utc.minute:02d}:{utc.second:02d}.{utc.microsecond:06d}Z"
+    )

lorebase_core/tree/__init__.py

@@ -0,0 +1,76 @@
+"""Partitioned canonical HAMT: the Revision manifest (design 6.2, 6.7)."""
+
+from lorebase_core.tree.diff import DiffEntry, tree_diff
+from lorebase_core.tree.hamt import (
+    TreeChange,
+    empty_tree,
+    tree_apply,
+    tree_count,
+    tree_entries,
+    tree_get,
+)
+from lorebase_core.tree.node import (
+    BranchNode,
+    LeafNode,
+    Node,
+    NodeFormatError,
+    NodeType,
+    PartitionRef,
+    RootNode,
+    decode_node,
+    encode_node,
+    key_hash,
+)
+from lorebase_core.tree.params import DEFAULT_LEAF_SIZE, FANOUT, TreeParams
+from lorebase_core.tree.root import (
+    LINK_KEY_SEPARATOR,
+    PARTITION_SCHEMA,
+    Tree,
+    kind_partition,
+    link_key,
+    relation_partition,
+)
+from lorebase_core.tree.store import (
+    InMemoryNodeStore,
+    MemoryNodeStore,
+    MissingNodeError,
+    NodeStore,
+    StagingNodeStore,
+    read_node,
+)
+
+__all__ = [
+    "DEFAULT_LEAF_SIZE",
+    "FANOUT",
+    "LINK_KEY_SEPARATOR",
+    "PARTITION_SCHEMA",
+    "BranchNode",
+    "DiffEntry",
+    "InMemoryNodeStore",
+    "LeafNode",
+    "MemoryNodeStore",
+    "MissingNodeError",
+    "Node",
+    "NodeFormatError",
+    "NodeStore",
+    "NodeType",
+    "PartitionRef",
+    "RootNode",
+    "StagingNodeStore",
+    "Tree",
+    "TreeChange",
+    "TreeParams",
+    "decode_node",
+    "empty_tree",
+    "encode_node",
+    "key_hash",
+    "kind_partition",
+    "link_key",
+    "read_node",
+    "relation_partition",
+    "tree_apply",
+    "tree_count",
+    "tree_diff",
+    "tree_entries",
+    "tree_get",
+]