kvgit 0.3.6__tar.gz → 0.3.7__tar.gz

{kvgit-0.3.6 → kvgit-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.6
+Version: 0.3.7
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT
@@ -94,6 +94,38 @@ main.tag("v1")
 print(main.peek("score", tag="v1"))  # 0
 ```
 
+## Merging
+
+`Staged.merge()` merges another head -- usually another branch's HEAD --
+into the current branch: lowest common ancestor, three-way resolve, and
+a two-parent merge commit guarded on your own head:
+
+```python
+dev["score"] = 500
+dev.commit()
+
+result = main.merge(dev.current_commit)  # True when merged
+print(main["score"])  # 500 (fast-forward: main hadn't diverged)
+```
+
+Overlapping changes need a merge function per key, or a `default_merge`
+fallback. `kvgit.merges.text` resolves line-oriented text with git-style
+`<<<<<<<` markers (see `make_text_merge` for custom labels); anything it
+cannot mark -- binary, non-UTF-8, oversized -- raises `CantMark`, filed
+as an ordinary conflict:
+
+```python
+from kvgit.merges import text
+
+result = main.merge(dev.current_commit, default_merge=text)
+```
+
+A `post_check(key, merged_bytes)` predicate runs over every
+merge-produced value; returning `False` files that key as conflicted.
+`on_conflict="abandon"` leaves the branch untouched instead of raising.
+Merging refuses with `ValueError` when the staging buffer holds
+uncommitted changes -- commit or reset first.
+
 ## Chunked codecs (numpy / pandas)
 
 Large numpy arrays and pandas DataFrames -- and any sliced views of them -- can be stored once and shared across keys, commits, and branches:

{kvgit-0.3.6 → kvgit-0.3.7}/README.md

@@ -45,6 +45,38 @@ main.tag("v1")
 print(main.peek("score", tag="v1"))  # 0
 ```
 
+## Merging
+
+`Staged.merge()` merges another head -- usually another branch's HEAD --
+into the current branch: lowest common ancestor, three-way resolve, and
+a two-parent merge commit guarded on your own head:
+
+```python
+dev["score"] = 500
+dev.commit()
+
+result = main.merge(dev.current_commit)  # True when merged
+print(main["score"])  # 500 (fast-forward: main hadn't diverged)
+```
+
+Overlapping changes need a merge function per key, or a `default_merge`
+fallback. `kvgit.merges.text` resolves line-oriented text with git-style
+`<<<<<<<` markers (see `make_text_merge` for custom labels); anything it
+cannot mark -- binary, non-UTF-8, oversized -- raises `CantMark`, filed
+as an ordinary conflict:
+
+```python
+from kvgit.merges import text
+
+result = main.merge(dev.current_commit, default_merge=text)
+```
+
+A `post_check(key, merged_bytes)` predicate runs over every
+merge-produced value; returning `False` files that key as conflicted.
+`on_conflict="abandon"` leaves the branch untouched instead of raising.
+Merging refuses with `ValueError` when the staging buffer holds
+uncommitted changes -- commit or reset first.
+
 ## Chunked codecs (numpy / pandas)
 
 Large numpy arrays and pandas DataFrames -- and any sliced views of them -- can be stored once and shared across keys, commits, and branches:

{kvgit-0.3.6 → kvgit-0.3.7}/kvgit/staged.py

@@ -8,7 +8,13 @@ from typing import Any
 from .codecs._hash import hash_bytes
 from .content_types import MergeFn
 from .versioned.kv import CHUNK_PREFIX, VersionedKV
-from .versioned.protocol import BytesMergeFn, MergeResult, TagInfo, Versioned
+from .versioned.protocol import (
+    BytesMergeFn,
+    MergeResult,
+    PostCheck,
+    TagInfo,
+    Versioned,
+)
 
 
 class _ChunkSink:
@@ -355,6 +361,55 @@ class Staged(MutableMapping[str, Any]):
             self._cache.clear()
         return result
 
+    def merge(
+        self,
+        their_head: str,
+        *,
+        on_conflict: str = "raise",
+        merge_fns: dict[str, MergeFn] | None = None,
+        default_merge: MergeFn | None = None,
+        post_check: PostCheck | None = None,
+        info: dict | None = None,
+    ) -> MergeResult:
+        """Merge another head (usually another branch's HEAD) into this branch.
+
+        Lowest common ancestor + three-way resolve + a two-parent merge
+        commit, CAS-guarded on our own head. Refuses with ``ValueError``
+        when the staging buffer holds uncommitted changes — commit or
+        reset first, so the merge reads committed heads on both sides.
+
+        ``merge_fns`` / ``default_merge`` take decoded values (wrapped
+        like :meth:`commit`); ``post_check`` takes merged bytes.
+        """
+        if self._updates or self._removals:
+            raise ValueError("cannot merge with staged changes; commit or reset first")
+        # Same assembly as commit(): registered fns first, per-call
+        # overrides on top — a configured Staged merges without repeats.
+        effective_fns = dict(self._merge_fns)
+        if merge_fns:
+            effective_fns.update(merge_fns)
+        effective_default = default_merge or self._default_merge
+        bytes_merge_fns = (
+            {key: self._wrap_merge_fn(fn) for key, fn in effective_fns.items()}
+            if effective_fns
+            else None
+        )
+        bytes_default = (
+            self._wrap_merge_fn(effective_default) if effective_default else None
+        )
+        result = self._versioned.merge_heads(
+            their_head,
+            on_conflict=on_conflict,
+            merge_fns=bytes_merge_fns,
+            default_merge=bytes_default,
+            post_check=post_check,
+            info=info,
+        )
+        if result.merged:
+            # HEAD moved: cached values may be stale after a merge.
+            self._cache.clear()
+        return result
+
     def reset(self) -> None:
         """Discard all staged changes."""
         self._updates.clear()

{kvgit-0.3.6 → kvgit-0.3.7}/kvgit/versioned/base.py

@@ -6,7 +6,7 @@ from collections.abc import Iterable
 from ..errors import ConcurrencyError, MergeConflict
 from .helpers import diff_keysets, walk_history
 from .merge import MergeResolution, resolve_merge
-from .protocol import BytesMergeFn, DiffResult, MergeResult
+from .protocol import BytesMergeFn, DiffResult, MergeResult, PostCheck
 
 
 class VersionedBase(ABC):
@@ -223,10 +223,20 @@ class VersionedBase(ABC):
         on_conflict: str,
         merge_fns: dict[str, BytesMergeFn] | None,
         default_merge: BytesMergeFn | None,
+        post_check: PostCheck | None = None,
         info: dict | None,
         saved_state: tuple | None = None,
+        cas_from: str | None = None,
+        parents: tuple[str, str] | None = None,
     ) -> MergeResult:
-        """Perform a three-way merge between our branch and their HEAD."""
+        """Perform a three-way merge between our branch and their HEAD.
+
+        ``their_head`` is any commit in the store — the moved HEAD of our
+        own branch (the concurrent-write path) or another branch's HEAD
+        (cross-branch merge). ``cas_from`` names the commit the merge
+        commits on top of (defaults to ``their_head``, the concurrent
+        case); cross-branch callers pass their own head.
+        """
         lca = self._find_lca(self._current_commit, their_head)
         if lca is None:
             if saved_state is not None:
@@ -275,6 +285,14 @@ class VersionedBase(ABC):
                 merge_fns=effective_fns,
                 default_merge=effective_default,
             )
+            if post_check is not None:
+                refused = {
+                    key
+                    for key, value in resolution.merged_values.items()
+                    if not post_check(key, value)
+                }
+                if refused:
+                    raise MergeConflict(refused)
         except MergeConflict:
             if saved_state is not None:
                 self._restore_state(saved_state)
@@ -291,14 +309,19 @@ class VersionedBase(ABC):
             raise
 
         auto_merged = resolution.auto_merged_keys
-        parents = (their_head, self._current_commit)
+        if parents is None:
+            # Concurrent-write default: keep following the moved HEAD, as
+            # before. Cross-branch callers pass (our_head, their_head) so
+            # linear history stays on the merging branch (git convention).
+            parents = (their_head, self._current_commit)
 
         self._create_merge_commit(resolution, parents, info)
         merge_hash = self._current_commit
         merged_keyset = self._commit_keys
 
-        # CAS HEAD from their_head to merge_hash
-        if self._cas_head(their_head, merge_hash):
+        # CAS HEAD onto the merge commit: from their_head in the
+        # concurrent-write path, from our own head cross-branch.
+        if self._cas_head(cas_from or their_head, merge_hash):
             self._base_commit = merge_hash
             result = MergeResult(
                 merged=True,
@@ -330,6 +353,47 @@ class VersionedBase(ABC):
             "HEAD changed during three-way merge. Refresh and retry."
         )
 
+    def merge_heads(
+        self,
+        their_head: str,
+        *,
+        on_conflict: str = "raise",
+        merge_fns: dict[str, BytesMergeFn] | None = None,
+        default_merge: BytesMergeFn | None = None,
+        post_check: PostCheck | None = None,
+        info: dict | None = None,
+    ) -> MergeResult:
+        """Merge another head into this branch.
+
+        ``their_head`` is any commit in the store — usually another
+        branch's HEAD. Finds the lowest common ancestor with our head,
+        three-way resolves, and creates a two-parent merge commit,
+        CAS-guarded on our own head (a race raises ``ConcurrencyError``
+        and changes nothing). No common ancestor raises
+        ``ConcurrencyError`` likewise without changing anything; retrying
+        cannot help that case, unlike a race.
+
+        ``post_check`` runs over each merge-function-produced value;
+        a False files that key as conflicted (handled per
+        ``on_conflict`` like any other conflict).
+        """
+        if on_conflict not in ("raise", "abandon"):
+            raise ValueError(
+                f"on_conflict must be 'raise' or 'abandon', got {on_conflict!r}"
+            )
+        our_head = self._current_commit
+        return self._three_way_merge(
+            their_head,
+            on_conflict=on_conflict,
+            merge_fns=merge_fns,
+            default_merge=default_merge,
+            post_check=post_check,
+            info=info,
+            saved_state=self._snapshot_state(),
+            cas_from=our_head,
+            parents=(our_head, their_head),
+        )
+
     # -- Abstract methods (implemented by subclasses) --
 
     @property

{kvgit-0.3.6 → kvgit-0.3.7}/kvgit/versioned/kv.py

@@ -1182,14 +1182,19 @@ class VersionedKV(VersionedBase):
             diffs[vk] = value
 
         # Build merged meta from the parents' meta. ``self._meta`` is
-        # already our parent's meta (in memory). Their parent's meta
-        # we have to walk via the HAMT.
-        their_root = _load_root(self.store, parents[0])
-        their_meta: dict[str, MetaEntry] = {}
-        if their_root is not None:
-            their_ks = Keyset(self.store, root=their_root)
-            for key, entry in their_ks.items():
-                their_meta[key] = entry.meta
+        # already our parent's meta (in memory). Any other parent's meta
+        # we walk via the HAMT — position-independent, since merge
+        # commits record ours-first: union every parent so their-side
+        # keys resolve however the tuple is ordered. Ties keep ours
+        # (checked first below), matching the old parents[0]-is-theirs
+        # behavior exactly.
+        parent_meta: dict[str, MetaEntry] = {}
+        for parent in parents:
+            parent_root = _load_root(self.store, parent)
+            if parent_root is None:
+                continue
+            for key, entry in Keyset(self.store, root=parent_root).items():
+                parent_meta.setdefault(key, entry.meta)
 
         merged_meta: dict[str, MetaEntry] = {}
         for key in merged_keyset:
@@ -1200,8 +1205,8 @@ class VersionedKV(VersionedBase):
                 )
             elif key in self._meta:
                 merged_meta[key] = self._meta[key]
-            elif key in their_meta:
-                merged_meta[key] = their_meta[key]
+            elif key in parent_meta:
+                merged_meta[key] = parent_meta[key]
 
         # Apply the merge result on top of our parent's HAMT. We compute
         # the minimal updates and removals so structural sharing kicks in

{kvgit-0.3.6 → kvgit-0.3.7}/kvgit/versioned/protocol.py

@@ -10,6 +10,15 @@ BytesMergeFn = Callable[[bytes | None, bytes | None, bytes | None], bytes]
 Any argument can be None (key absent or removed on that side).
 """
 
+PostCheck = Callable[[str, bytes], bool]
+"""Post-merge predicate: (key, merged_bytes) -> accept?
+
+Runs over values a merge function produced. Returning False files the
+key as conflicted, as if no merge function had resolved it. kvgit never
+inspects the bytes itself — callers that know what their values mean
+(marker scans, schema checks) decide.
+"""
+
 
 @dataclass(frozen=True)
 class DiffResult:
@@ -110,6 +119,22 @@ class Versioned(Protocol):
         chunk_refs: dict[str, list[str]] | None = None,
     ) -> MergeResult: ...
 
+    def merge_heads(
+        self,
+        their_head: str,
+        *,
+        on_conflict: str = "raise",
+        merge_fns: dict[str, BytesMergeFn] | None = None,
+        default_merge: BytesMergeFn | None = None,
+        post_check: PostCheck | None = None,
+        info: dict | None = None,
+    ) -> MergeResult:
+        """Merge another head (any commit in the store, usually another
+        branch's HEAD) into this branch: LCA + three-way resolve + a
+        two-parent merge commit, CAS-guarded on our own head.
+        """
+        ...
+
     def refresh(self) -> None: ...
 
     def checkout(

{kvgit-0.3.6 → kvgit-0.3.7}/kvgit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.6
+Version: 0.3.7
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT
@@ -94,6 +94,38 @@ main.tag("v1")
 print(main.peek("score", tag="v1"))  # 0
 ```
 
+## Merging
+
+`Staged.merge()` merges another head -- usually another branch's HEAD --
+into the current branch: lowest common ancestor, three-way resolve, and
+a two-parent merge commit guarded on your own head:
+
+```python
+dev["score"] = 500
+dev.commit()
+
+result = main.merge(dev.current_commit)  # True when merged
+print(main["score"])  # 500 (fast-forward: main hadn't diverged)
+```
+
+Overlapping changes need a merge function per key, or a `default_merge`
+fallback. `kvgit.merges.text` resolves line-oriented text with git-style
+`<<<<<<<` markers (see `make_text_merge` for custom labels); anything it
+cannot mark -- binary, non-UTF-8, oversized -- raises `CantMark`, filed
+as an ordinary conflict:
+
+```python
+from kvgit.merges import text
+
+result = main.merge(dev.current_commit, default_merge=text)
+```
+
+A `post_check(key, merged_bytes)` predicate runs over every
+merge-produced value; returning `False` files that key as conflicted.
+`on_conflict="abandon"` leaves the branch untouched instead of raising.
+Merging refuses with `ValueError` when the staging buffer holds
+uncommitted changes -- commit or reset first.
+
 ## Chunked codecs (numpy / pandas)
 
 Large numpy arrays and pandas DataFrames -- and any sliced views of them -- can be stored once and shared across keys, commits, and branches:

{kvgit-0.3.6 → kvgit-0.3.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kvgit"
-version = "0.3.6"
+version = "0.3.7"
 description = "Versioned key-value store with git-like commit, branch, and merge semantics."
 authors = [{ name = "ashenfad" }]
 requires-python = ">=3.10"