kvgit 0.3.5__tar.gz → 0.3.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.5
+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.5 → 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.5 → kvgit-0.3.7}/kvgit/__init__.py

@@ -2,6 +2,7 @@
 
 from .content_types import MergeFn, counter, last_writer_wins
 from .errors import ConcurrencyError, MergeConflict
+from .merges import CantMark, TextMergeFn, make_text_merge, text
 from .namespaced import Namespaced
 from .staged import Staged
 from .store import delete_branches, delete_tags, store
@@ -9,6 +10,7 @@ from .versioned.kv import VersionedKV
 from .versioned.protocol import MergeResult, TagInfo, Versioned
 
 __all__ = [
+    "CantMark",
     "ConcurrencyError",
     "MergeConflict",
     "MergeFn",
@@ -16,11 +18,14 @@ __all__ = [
     "Namespaced",
     "Staged",
     "TagInfo",
+    "TextMergeFn",
     "Versioned",
     "VersionedKV",
     "counter",
     "delete_branches",
     "delete_tags",
     "last_writer_wins",
+    "make_text_merge",
     "store",
+    "text",
 ]

kvgit-0.3.7/kvgit/merges.py

@@ -0,0 +1,247 @@
+"""Text merge with conflict markers.
+
+A batteries-included ``BytesMergeFn`` for line-oriented text: disjoint
+changes merge cleanly, overlapping changes come back with git-style
+``<<<<<<<`` markers instead of raising. Register it as a per-key fn or
+as ``default_merge`` wherever text blobs merge (see ``resolve_merge``).
+
+Anything that cannot be marked — undecodable bytes, NUL bytes, inputs
+over the size cap — raises :class:`CantMark`, which the merge machinery
+files as an ordinary conflict. Callers that need to tell "no encoding"
+from "too big" catch it themselves; callers that don't let it flow.
+"""
+
+from __future__ import annotations
+
+import difflib
+from collections.abc import Callable
+
+from .versioned.protocol import BytesMergeFn
+
+#: Inputs whose combined size exceeds this are refused with
+#: :class:`CantMark` rather than merged. Line-diffing is quadratic-ish
+#: in the worst case (minified single-line megabytes); a merge this big
+#: is a whole-file conflict by inspection anyway.
+MAX_MARK_BYTES = 1024 * 1024
+
+
+class CantMark(Exception):
+    """A value cannot be marker-merged: not text, or too big.
+
+    Raised instead of returning bytes when the inputs are undecodable as
+    UTF-8, contain NUL bytes, or exceed ``MAX_MARK_BYTES`` combined.
+    The merge machinery reports it as a conflict for that key.
+    """
+
+
+def _decode(data: bytes | None) -> list[str]:
+    """Split one side into lines; a removed side is the empty list.
+
+    The markers then show one populated side against nothing, which
+    reads correctly.
+    """
+    if data is None:
+        return []
+    if b"\x00" in data:
+        raise CantMark("NUL byte: not text")
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError as e:
+        raise CantMark(f"not UTF-8: {e}") from e
+    return text.splitlines(keepends=True)
+
+
+def _changes(base: list[str], side: list[str]) -> list[tuple[int, int, list[str]]]:
+    """Non-equal opcode intervals of ``side`` against ``base``.
+
+    Each tuple is ``(base_start, base_end, replacement_lines)``;
+    pure insertions have ``base_start == base_end``.
+    """
+    matcher = difflib.SequenceMatcher(None, base, side, autojunk=False)
+    return [
+        (i1, i2, side[j1:j2])
+        for tag, i1, i2, j1, j2 in matcher.get_opcodes()
+        if tag != "equal"
+    ]
+
+
+def _terminate(lines: list[str]) -> list[str]:
+    """Ensure every non-final line ends with a newline.
+
+    A line without a trailing newline glued onto following output would
+    corrupt both; clean regions stay byte-exact (a final line keeps its
+    missing newline), markers pay the newline tax.
+    """
+    fixed: list[str] = []
+    for i, ln in enumerate(lines):
+        if not ln.endswith("\n") and i + 1 < len(lines):
+            ln += "\n"
+        fixed.append(ln)
+    return fixed
+
+
+def _replay(base: list[str], start: int, end: int, events: list[tuple]) -> list[str]:
+    """One side's full content over ``base[start:end]``.
+
+    Base lines outside the side's own hunks, replacement lines inside.
+    Same-side events come from one SequenceMatcher pass, so they are
+    disjoint and the replay is well-defined. Without this, overlapping
+    groups spanning different base ranges would emit only replacement
+    lines and silently drop the base lines between them.
+    """
+    out: list[str] = []
+    pos = start
+    for _, s, e, lines in sorted(events, key=lambda ev: (ev[1], ev[2])):
+        out.extend(base[pos:s])
+        out.extend(lines)
+        pos = max(pos, e)
+    out.extend(base[pos:end])
+    return out
+
+
+def _merge_lines(
+    base: list[str],
+    ours: list[str],
+    theirs: list[str],
+    ours_label: str,
+    theirs_label: str,
+    ours_deleted: bool = False,
+    theirs_deleted: bool = False,
+) -> tuple[list[str], bool]:
+    """Three-way line merge. Returns ``(lines, conflicted)``.
+
+    The ``*_deleted`` flags record raw ``None`` inputs (a removed side),
+    tracked separately from decoded emptiness: an empty base file that
+    one side deletes and the other writes is a modify/delete conflict,
+    not a clean add. Still-absent on an added/added merge (base itself
+    missing) is not a deletion.
+    """
+    if ours == theirs:
+        return list(ours), False
+
+    # Whole-file deletion on one side against any change on the other is
+    # a modify/delete conflict with the survivor shown whole — the
+    # interval machinery below only sees hunks and would drop the
+    # surviving context. (Unchanged-vs-deleted resolves above through
+    # the empty-changes fast paths.)
+    if ours_deleted and theirs != base:
+        return _terminate(
+            [
+                f"<<<<<<< {ours_label}\n",
+                "=======\n",
+                *theirs,
+                f">>>>>>> {theirs_label}\n",
+            ]
+        ), True
+    if theirs_deleted and ours != base:
+        return _terminate(
+            [
+                f"<<<<<<< {ours_label}\n",
+                *ours,
+                "=======\n",
+                f">>>>>>> {theirs_label}\n",
+            ]
+        ), True
+
+    our_changes = _changes(base, ours)
+    their_changes = _changes(base, theirs)
+    if not our_changes:
+        return list(theirs), False
+    if not their_changes:
+        return list(ours), False
+
+    # Merge overlapping change intervals into conflict groups; disjoint
+    # intervals resolve independently. Intervals are half-open over base
+    # positions; pure insertions are points. Join on strict overlap, plus
+    # same-point inserts colliding with each other — an insert merely
+    # adjacent to a change interval resolves cleanly beside it, while two
+    # different inserts at one point genuinely conflict.
+    events = [("ours", s, e, lines) for s, e, lines in our_changes]
+    events += [("theirs", s, e, lines) for s, e, lines in their_changes]
+    events.sort(key=lambda ev: (ev[1], ev[2]))
+
+    # Each group tracks its member events plus its max base end, since
+    # overlap is against the group's full span, not the last event.
+    groups: list[list[tuple]] = []
+    group_ends: list[int] = []
+    for ev in events:
+        _, s, e, _ = ev
+        if groups and (
+            s < group_ends[-1]
+            or (s == e and any(g[1] == g[2] == s for g in groups[-1]))
+        ):
+            groups[-1].append(ev)
+            group_ends[-1] = max(group_ends[-1], e)
+        else:
+            groups.append([ev])
+            group_ends.append(e)
+
+    out: list[str] = []
+    conflicted = False
+    pos = 0
+    for group in groups:
+        start = min(ev[1] for ev in group)
+        end = max(ev[2] for ev in group)
+        out.extend(base[pos:start])
+        ours_ev = [ev for ev in group if ev[0] == "ours"]
+        theirs_ev = [ev for ev in group if ev[0] == "theirs"]
+        if not theirs_ev:
+            out.extend(_replay(base, start, end, ours_ev))
+        elif not ours_ev:
+            out.extend(_replay(base, start, end, theirs_ev))
+        else:
+            ours_full = _replay(base, start, end, ours_ev)
+            theirs_full = _replay(base, start, end, theirs_ev)
+            if ours_full == theirs_full:
+                out.extend(ours_full)
+            else:
+                conflicted = True
+                out.append(f"<<<<<<< {ours_label}\n")
+                out.extend(ours_full)
+                out.append("=======\n")
+                out.extend(theirs_full)
+                out.append(f">>>>>>> {theirs_label}\n")
+        pos = end
+    out.extend(base[pos:])
+
+    return _terminate(out), conflicted
+
+
+def make_text_merge(
+    *, ours_label: str = "ours", theirs_label: str = "theirs"
+) -> BytesMergeFn:
+    """Build a marker-merge fn with custom conflict labels.
+
+    Labels ride git's positions (``<<<<<<< <ours>`` /
+    ``>>>>>>> <theirs>``); pass branch names so conflicts read
+    attributably. Labels may not contain newlines.
+    """
+    for name, label in (("ours_label", ours_label), ("theirs_label", theirs_label)):
+        if "\n" in label:
+            raise ValueError(f"{name} may not contain a newline: {label!r}")
+
+    def merge(old: bytes | None, ours: bytes | None, theirs: bytes | None) -> bytes:
+        total = sum(len(d) for d in (old, ours, theirs) if d is not None)
+        if total > MAX_MARK_BYTES:
+            raise CantMark(f"inputs total {total} bytes over cap {MAX_MARK_BYTES}")
+        merged, _ = _merge_lines(
+            _decode(old),
+            _decode(ours),
+            _decode(theirs),
+            ours_label,
+            theirs_label,
+            ours_deleted=ours is None and old is not None,
+            theirs_deleted=theirs is None and old is not None,
+        )
+        return "".join(merged).encode("utf-8")
+
+    return merge
+
+
+def text(old: bytes | None, ours: bytes | None, theirs: bytes | None) -> bytes:
+    """Marker-merge with default labels. Usable as ``default_merge`` directly."""
+    return make_text_merge()(old, ours, theirs)
+
+
+TextMergeFn = Callable[[bytes | None, bytes | None, bytes | None], bytes]
+"""Type of what :func:`make_text_merge` builds (== ``BytesMergeFn``)."""

{kvgit-0.3.5 → 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.5 → 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.5 → 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.5 → 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.5 → kvgit-0.3.7}/kvgit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.5
+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.5 → kvgit-0.3.7}/kvgit.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ kvgit/content_types.py
 kvgit/encoding.py
 kvgit/errors.py
 kvgit/hamt.py
+kvgit/merges.py
 kvgit/namespaced.py
 kvgit/py.typed
 kvgit/staged.py
@@ -37,6 +38,7 @@ kvgit/versioned/protocol.py
 tests/test_content_types.py
 tests/test_delete_branches.py
 tests/test_hamt.py
+tests/test_merges.py
 tests/test_namespaced.py
 tests/test_staged.py
 tests/test_store_factory.py

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

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

kvgit-0.3.7/tests/test_merges.py

@@ -0,0 +1,300 @@
+"""Tests for kvgit.merges: marker-merge with git-verified expectations."""
+
+import random
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from kvgit import MergeConflict, VersionedKV as Versioned
+from kvgit.kv.memory import Memory
+from kvgit.merges import CantMark, make_text_merge, text
+
+GIT = shutil.which("git")
+needs_git = pytest.mark.skipif(GIT is None, reason="git binary not available")
+
+_ALPHABET = ["alpha", "beta", "gamma", "delta", "epsilon", "zeta", ""]
+
+BASE = b"a\nb\nc\nd\n"
+
+
+class TestCleanMerges:
+    def test_disjoint_edits_merge(self):
+        assert text(BASE, b"a\nB\nc\nd\n", b"a\nb\nc\nD\n") == b"a\nB\nc\nD\n"
+
+    def test_identical_edits_agree(self):
+        assert text(BASE, b"a\nX\nc\nd\n", b"a\nX\nc\nd\n") == b"a\nX\nc\nd\n"
+
+    def test_one_side_unchanged(self):
+        assert text(BASE, BASE, b"a\nb\nc\nD\n") == b"a\nb\nc\nD\n"
+        assert text(BASE, b"a\nB\nc\nd\n", BASE) == b"a\nB\nc\nd\n"
+
+    def test_added_one_side(self):
+        assert text(None, None, b"new\n") == b"new\n"
+        assert text(None, b"new\n", None) == b"new\n"
+
+    def test_both_deleted(self):
+        assert text(BASE, None, None) == b""
+
+    def test_deleted_vs_unchanged_deletes(self):
+        assert text(BASE, None, BASE) == b""
+        assert text(BASE, BASE, None) == b""
+
+    def test_no_trailing_newline_preserved(self):
+        assert text(b"a\nb", b"a\nB", b"a\nb") == b"a\nB"
+
+    def test_empty_inputs(self):
+        assert text(b"", b"", b"") == b""
+
+
+class TestConflicts:
+    def test_overlap_markers(self):
+        out = text(BASE, b"a\nX\nc\nd\n", b"a\nY\nc\nd\n")
+        assert out == b"a\n<<<<<<< ours\nX\n=======\nY\n>>>>>>> theirs\nc\nd\n"
+
+    def test_added_added_different(self):
+        out = text(None, b"hello\n", b"world\n")
+        assert out == b"<<<<<<< ours\nhello\n=======\nworld\n>>>>>>> theirs\n"
+
+    def test_added_added_same(self):
+        assert text(None, b"same\n", b"same\n") == b"same\n"
+
+    def test_delete_vs_modify(self):
+        out = text(BASE, None, b"a\nb\nc\nD\n")
+        assert out == (b"<<<<<<< ours\n=======\na\nb\nc\nD\n>>>>>>> theirs\n")
+
+    def test_modify_vs_delete(self):
+        out = text(BASE, b"a\nB\nc\nd\n", None)
+        assert out == (b"<<<<<<< ours\na\nB\nc\nd\n=======\n>>>>>>> theirs\n")
+
+    def test_custom_labels(self):
+        fn = make_text_merge(ours_label="main", theirs_label="dev")
+        out = fn(BASE, b"a\nX\nc\nd\n", b"a\nY\nc\nd\n")
+        assert b"<<<<<<< main\n" in out
+        assert b">>>>>>> dev\n" in out
+
+    def test_label_newline_rejected(self):
+        with pytest.raises(ValueError):
+            make_text_merge(ours_label="a\nb")
+
+    def test_deterministic(self):
+        args = (BASE, b"a\nX\nc\nd\n", b"a\nY\nc\nd\n")
+        assert text(*args) == text(*args)
+
+
+class TestReviewRegression:
+    """Regression tests for PR #34 review findings (all reproduced)."""
+
+    def test_overlapping_groups_keep_full_span(self):
+        """P1: overlapping hunks over different base spans must show each
+        side's full content over the union — resolving to ours must not
+        drop unchanged lines (here: `c`). Verified byte-identical to
+        `git merge-file`."""
+        out = text(b"a\nb\nc\n", b"a\nB\nc\n", b"a\nY\nZ\n")
+        assert out == b"a\n<<<<<<< ours\nB\nc\n=======\nY\nZ\n>>>>>>> theirs\n"
+
+    def test_empty_base_delete_vs_write_conflicts(self):
+        """P2: an empty base file one side deletes and the other writes
+        is modify/delete, not a clean add."""
+        out = text(b"", None, b"x\n")
+        assert out == b"<<<<<<< ours\n=======\nx\n>>>>>>> theirs\n"
+        out = text(b"", b"x\n", None)
+        assert out == b"<<<<<<< ours\nx\n=======\n>>>>>>> theirs\n"
+
+    def test_unterminated_survivor_terminated(self):
+        """P2: whole-file delete/modify where the survivor lacks a trailing
+        newline must not glue content to the closing marker."""
+        assert text(b"a", None, b"B") == b"<<<<<<< ours\n=======\nB\n>>>>>>> theirs\n"
+        assert text(b"a", b"B", None) == b"<<<<<<< ours\nB\n=======\n>>>>>>> theirs\n"
+
+
+class TestDocumentedDivergence:
+    def test_adjacent_insert_merges_clean(self):
+        """Ours changes line 2, theirs inserts right after it.
+
+        git merge-file reports a conflict here (hunk-context overlap);
+        the regions genuinely don't overlap, so we merge cleanly. Pinned
+        as a known, safe-direction divergence: clean-where-git-conflicts
+        can never silently lose content the way the reverse could.
+        """
+        out = text(BASE, b"a\nB\nc\nd\n", b"a\nb\nX\nc\nd\n")
+        assert out == b"a\nB\nX\nc\nd\n"
+
+
+class TestCantMark:
+    def test_nul_byte(self):
+        with pytest.raises(CantMark):
+            text(BASE, b"a\x00b", BASE)
+
+    def test_invalid_utf8(self):
+        with pytest.raises(CantMark):
+            text(BASE, b"\xff\xfe binary", BASE)
+
+    def test_oversize(self):
+        big = b"x" * (1024 * 1024 + 1)
+        with pytest.raises(CantMark):
+            text(b"", big, b"")
+
+
+def _git_merge(old: bytes, ours: bytes, theirs: bytes) -> tuple[bytes, int]:
+    """Run git merge-file; returns (stdout, exit code)."""
+    assert GIT is not None
+    with tempfile.TemporaryDirectory() as d:
+        paths = []
+        for name, data in (("old", old), ("ours", ours), ("theirs", theirs)):
+            p = Path(d) / name
+            p.write_bytes(data)
+            paths.append(str(p))
+        proc = subprocess.run(
+            [
+                GIT,
+                "merge-file",
+                "-p",
+                "-L",
+                "ours",
+                "-L",
+                "base",
+                "-L",
+                "theirs",
+                paths[1],
+                paths[0],
+                paths[2],
+            ],
+            capture_output=True,
+            env={"LC_ALL": "C", "PATH": "/usr/bin:/bin"},
+        )
+        return proc.stdout, proc.returncode
+
+
+@needs_git
+class TestGitDifferential:
+    """Ours must match git merge-file byte-exactly on agreement-zone inputs.
+
+    The generator keeps edits separated so hunk contexts cannot overlap
+    (the zone where both algorithms provably agree); trickier shapes live
+    as pinned cases above or in the adversarial test below. Seed-pinned:
+    failures reproduce deterministically.
+    """
+
+    def _triple(self, rng: random.Random) -> tuple[bytes, bytes, bytes]:
+        n = rng.randint(2, 8)
+        base = [rng.choice(_ALPHABET) + f"-{i}" for i in range(n)]
+        ours, theirs = list(base), list(base)
+        # Edits at distinct positions with at least one untouched line
+        # between any two edit sites.
+        positions = rng.sample(range(n), k=min(n, rng.randint(0, 3)))
+        positions.sort()
+        ok = True
+        for prev, cur in zip([-10, *positions], positions, strict=False):
+            if prev != -10 and cur - prev < 2:
+                ok = False
+        if not ok:
+            return self._triple(rng)
+        for p in positions:
+            choice = rng.random()
+            if choice < 0.4:
+                ours[p] = f"ours-{p}"
+                theirs[p] = f"ours-{p}"  # identical edit: must agree
+            elif choice < 0.7:
+                ours[p] = f"ours-{p}"
+            else:
+                theirs[p] = f"theirs-{p}"
+
+        def join(lines: list[str]) -> bytes:
+            return ("".join(line + "\n" for line in lines)).encode()
+
+        return join(base), join(ours), join(theirs)
+
+    def test_matches_git(self):
+        rng = random.Random(0xC0FFEE)
+        checked_clean = 0
+        for _ in range(150):
+            old, ours, theirs = self._triple(rng)
+            git_out, code = _git_merge(old, ours, theirs)
+            mine = text(old, ours, theirs)
+            if code == 0:
+                # Clean merges are uniquely determined: byte equality.
+                assert mine == git_out
+                checked_clean += 1
+            else:
+                # Conflict: agreement on conflict-hood.
+                assert b"<<<<<<< ours\n" in mine
+        assert checked_clean > 50  # generator must exercise clean merges
+
+    def test_adversarial_properties(self):
+        """Where we may legitimately diverge from git (adjacent edits,
+        unterminated lines), assert the sound properties instead: clean
+        git merges still match byte-exactly, and our output never
+        invents lines or emits unbalanced markers."""
+        rng = random.Random(0xBEEF)
+        checked_clean = 0
+        for _ in range(150):
+            old, ours, theirs = self._triple(rng)
+            if rng.random() < 0.5:
+                # Strip a trailing newline: the adjacency trigger.
+                if rng.random() < 0.5 and ours.endswith(b"\n"):
+                    ours = ours.removesuffix(b"\n")
+                elif theirs.endswith(b"\n"):
+                    theirs = theirs.removesuffix(b"\n")
+            git_out, code = _git_merge(old, ours, theirs)
+            mine = text(old, ours, theirs)
+            if code == 0:
+                assert mine == git_out
+                checked_clean += 1
+                continue
+            inputs = {
+                ln.removesuffix("\n")
+                for data in (old, ours, theirs)
+                for ln in data.decode("utf-8").splitlines(keepends=True)
+            }
+            opens = closes = mids = 0
+            for ln in mine.decode("utf-8").splitlines(keepends=True):
+                if ln.startswith("<<<<<<< "):
+                    opens += 1
+                elif ln.startswith(">>>>>>> "):
+                    closes += 1
+                elif ln == "=======\n":
+                    mids += 1
+                else:
+                    # No invented content (modulo the terminator): every
+                    # emitted line comes verbatim from some input.
+                    assert ln.removesuffix("\n") in inputs
+            assert opens == mids == closes
+        assert checked_clean > 0  # the net must catch clean merges too
+
+
+class TestVersionedIntegration:
+    def _two_branches(self):
+        store = Memory()
+        v1 = Versioned(store)
+        v1.commit({"doc": b"a\nb\nc\nd\n"})
+        v2 = Versioned(store)
+        return v1, v2
+
+    def test_default_merge_automerges_text(self):
+        from kvgit.merges import text as text_merge
+
+        v1, v2 = self._two_branches()
+        v1.commit({"doc": b"a\nB\nc\nd\n"})
+        result = v2.commit({"doc": b"a\nb\nc\nD\n"}, default_merge=text_merge)
+        assert result
+        assert v2.get("doc") == b"a\nB\nc\nD\n"
+
+    def test_conflict_filed_without_fn(self):
+        v1, v2 = self._two_branches()
+        v1.commit({"doc": b"a\nB\nc\nd\n"})
+        with pytest.raises(MergeConflict) as exc_info:
+            v2.commit({"doc": b"a\nb\nc\nD\n"})
+        assert "doc" in exc_info.value.conflicting_keys
+
+    def test_binary_conflict_carries_cantmark(self):
+        from kvgit.merges import text as text_merge
+
+        v1, v2 = self._two_branches()
+        v1.commit({"doc": b"a\x00b"})
+        with pytest.raises(MergeConflict) as exc_info:
+            v2.commit({"doc": b"a\nb\nc\nD\n"}, default_merge=text_merge)
+        assert "doc" in exc_info.value.conflicting_keys
+        assert isinstance(exc_info.value.merge_errors["doc"], CantMark)