kvgit 0.1.6__tar.gz → 0.1.8__tar.gz

{kvgit-0.1.6 → kvgit-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.1.6
+Version: 0.1.8
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT

{kvgit-0.1.6 → kvgit-0.1.8}/kvgit/kv/indexeddb.py

@@ -117,10 +117,17 @@ async def _idb_tx_complete(tx):
 
 
 def _to_bytes(js_value) -> bytes | None:
-    """Convert a JS result to bytes, or None if absent."""
+    """Convert a JS result to bytes, or None if absent.
+
+    Uses Uint8Array.to_py() for fast memcpy from JS to WASM memory,
+    avoiding the slow element-wise iteration of bytes(js_proxy).
+    """
     if js_value is None or js_value is undefined:
         return None
-    return bytes(js_value)
+    from js import Uint8Array  # type: ignore[import-not-found]
+
+    arr = Uint8Array.new(js_value)
+    return arr.to_py().tobytes()
 
 
 class IndexedDB(KVStore):
@@ -206,7 +213,7 @@ class IndexedDB(KVStore):
                 def on_success(event):
                     cursor = event.target.result
                     if cursor:
-                        results.append((str(cursor.key), bytes(cursor.value)))
+                        results.append((str(cursor.key), _to_bytes(cursor.value)))
                         cursor.continue_()
                     else:
                         resolve(None)

{kvgit-0.1.6 → kvgit-0.1.8}/kvgit/store.py

@@ -6,7 +6,6 @@ from typing import Any, Callable, Literal
 from .kv.base import KVStore
 from .kv.memory import Memory
 from .staged import Staged
-from .versioned.gc import GCVersionedKV
 from .versioned.kv import VersionedKV
 from .versioned.protocol import Versioned
 
@@ -19,9 +18,6 @@ def store(
     branch: str = "main",
     encoder: Callable[[Any], bytes] = pickle.dumps,
     decoder: Callable[[bytes], Any] = pickle.loads,
-    high_water_bytes: int | None = None,
-    low_water_bytes: int | None = None,
-    is_protected: Callable[[str], bool] | None = None,
 ) -> Staged:
     """Create a Staged store with sensible defaults.
 
@@ -34,14 +30,6 @@ def store(
         branch: Branch name (default ``"main"``).
         encoder: Value encoder (default ``pickle.dumps``).
         decoder: Value decoder (default ``pickle.loads``).
-        high_water_bytes: Enable GC with this high-water threshold.
-            Not supported with ``kind="git"``.
-        low_water_bytes: GC low-water threshold (defaults to 80%
-            of high_water). Not supported with ``kind="git"``.
-        is_protected: Callable that returns True for keys GC should
-            never drop. Only used when ``high_water_bytes`` is set.
-            Defaults to protecting keys starting with ``__``.
-            Not supported with ``kind="git"``.
 
     Returns:
         A ``Staged`` store instance.
@@ -49,12 +37,6 @@ def store(
     versioned: Versioned
 
     if kind == "git":
-        if (
-            high_water_bytes is not None
-            or low_water_bytes is not None
-            or is_protected is not None
-        ):
-            raise ValueError("GC parameters are not supported with kind='git'")
         if path is None:
             raise ValueError("path is required when kind='git'")
         from .versioned.gp import VersionedGP
@@ -78,16 +60,6 @@ def store(
         else:
             raise ValueError(f"Unknown kind: {kind!r}")
 
-        if high_water_bytes is not None:
-            gc_kwargs: dict[str, Any] = {
-                "branch": branch,
-                "high_water_bytes": high_water_bytes,
-                "low_water_bytes": low_water_bytes,
-            }
-            if is_protected is not None:
-                gc_kwargs["is_protected"] = is_protected
-            versioned = GCVersionedKV(backend, **gc_kwargs)
-        else:
-            versioned = VersionedKV(backend, branch=branch)
+        versioned = VersionedKV(backend, branch=branch)
 
     return Staged(versioned, encoder=encoder, decoder=decoder)

{kvgit-0.1.6 → kvgit-0.1.8}/kvgit/versioned/__init__.py

@@ -1,13 +1,11 @@
 """Versioned store implementations."""
 
-from .gc import GCVersionedKV
 from .kv import VersionedKV
 from .protocol import BytesMergeFn, DiffResult, MergeResult, Versioned
 
 __all__ = [
     "BytesMergeFn",
     "DiffResult",
-    "GCVersionedKV",
     "MergeResult",
     "Versioned",
     "VersionedKV",

{kvgit-0.1.6 → kvgit-0.1.8}/kvgit/versioned/kv.py

@@ -2,6 +2,7 @@
 
 import hashlib
 import json
+import logging
 import time
 
 from ..encoding import MetaEntry, from_bytes, meta_from_bytes, meta_to_bytes, to_bytes
@@ -397,13 +398,14 @@ class VersionedKV(VersionedBase):
         return VersionedKV(self.store, commit_hash=target, branch=name)
 
     def delete_branch(self, name: str) -> None:
-        """Delete a branch by name."""
+        """Delete a branch and clean up orphaned commits."""
         if name == self._branch:
             raise ValueError("Cannot delete the current branch")
         branch_key = BRANCH_HEAD % name
         if self.store.get(branch_key) is None:
             raise ValueError(f"Branch '{name}' does not exist")
         self.store.remove(branch_key)
+        self.clean_orphans(min_age=0)
 
     def switch_branch(self, name: str) -> None:
         """Switch this instance to a different branch in-place."""
@@ -461,6 +463,99 @@ class VersionedKV(VersionedBase):
             return None
         return from_bytes(info_bytes)
 
+    # -- Orphan cleanup --
+
+    def clean_orphans(self, min_age: float = 3600) -> int:
+        """Remove orphaned commits unreachable from any branch HEAD.
+
+        Traces all reachable commits from live branch HEADs, then
+        deletes commit metadata and versioned keys for any commit
+        not in the reachable set. Only deletes blobs that are not
+        referenced by any reachable commit.
+
+        The ``min_age`` guard (default 1 hour) prevents recently
+        created commits from being falsely swept during concurrent
+        writes. Use ``min_age=0`` when concurrency is not a concern
+        (e.g. single-user browser environments).
+
+        Returns:
+            Number of orphaned commits removed.
+        """
+        logger = logging.getLogger("kvgit.orphans")
+
+        # Mark phase: find all reachable commits and their blob keys
+        reachable: set[str] = set()
+        reachable_blobs: set[str] = set()
+        prefix = BRANCH_HEAD.replace("%s", "")
+        for key in self.store.keys():
+            if isinstance(key, str) and key.startswith(prefix):
+                head_bytes = self.store.get(key)
+                if head_bytes is None:
+                    continue
+                branch_head = from_bytes(head_bytes)
+                for commit in self.history(commit_hash=branch_head, all_parents=True):
+                    if commit not in reachable:
+                        reachable.add(commit)
+                        ks_bytes = self.store.get(COMMIT_KEYSET % commit)
+                        if ks_bytes:
+                            try:
+                                for vk in from_bytes(ks_bytes).values():
+                                    reachable_blobs.add(vk)
+                            except Exception:
+                                pass
+
+        # Sweep phase: find orphaned commits by scanning for meta keys
+        meta_prefix = META_KEY.replace("%s", "")
+        cutoff_time = time.time() - min_age
+        orphans: list[str] = []
+
+        for key in self.store.keys():
+            if not isinstance(key, str) or not key.startswith(meta_prefix):
+                continue
+            commit_hash = key[len(meta_prefix) :]
+            if not commit_hash or commit_hash in reachable:
+                continue
+            # Check age
+            meta_bytes = self.store.get(key)
+            if meta_bytes is None:
+                continue
+            try:
+                meta = meta_from_bytes(meta_bytes)
+                if meta:
+                    newest = max(e.created_at for e in meta.values())
+                    if newest < cutoff_time:
+                        orphans.append(commit_hash)
+                else:
+                    orphans.append(commit_hash)
+            except (json.JSONDecodeError, TypeError, KeyError):
+                continue
+
+        # Delete orphaned commits — only remove blobs not used by reachable commits
+        for orphan_hash in orphans:
+            keyset_bytes = self.store.get(COMMIT_KEYSET % orphan_hash)
+            if keyset_bytes:
+                try:
+                    keyset = from_bytes(keyset_bytes)
+                    orphan_only = [
+                        vk for vk in keyset.values() if vk not in reachable_blobs
+                    ]
+                    if orphan_only:
+                        self.store.remove_many(*orphan_only)
+                except Exception:
+                    pass
+            self.store.remove_many(
+                META_KEY % orphan_hash,
+                COMMIT_KEYSET % orphan_hash,
+                PARENT_COMMIT % orphan_hash,
+                TOTAL_VAR_SIZE_KEY % orphan_hash,
+                INFO_KEY % orphan_hash,
+            )
+
+        if orphans:
+            logger.debug("Cleaned %d orphaned commit(s)", len(orphans))
+
+        return len(orphans)
+
     # -- Internal --
 
     def _touch(self, key: str) -> None:

{kvgit-0.1.6 → kvgit-0.1.8}/kvgit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.1.6
+Version: 0.1.8
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT

{kvgit-0.1.6 → kvgit-0.1.8}/kvgit.egg-info/SOURCES.txt

@@ -22,7 +22,6 @@ kvgit/kv/indexeddb.py
 kvgit/kv/memory.py
 kvgit/versioned/__init__.py
 kvgit/versioned/base.py
-kvgit/versioned/gc.py
 kvgit/versioned/gp.py
 kvgit/versioned/helpers.py
 kvgit/versioned/kv.py

{kvgit-0.1.6 → kvgit-0.1.8}/pyproject.toml

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

{kvgit-0.1.6 → kvgit-0.1.8}/tests/test_store_factory.py

@@ -3,7 +3,6 @@
 import pytest
 
 from kvgit import Staged, store
-from kvgit.versioned.gc import GCVersionedKV as GCVersioned
 
 
 class TestStoreFactory:
@@ -19,11 +18,6 @@ class TestStoreFactory:
         with pytest.raises(ValueError, match="path is required"):
             store(kind="disk")
 
-    def test_gc_versioned(self):
-        s = store(high_water_bytes=5000)
-        assert isinstance(s, Staged)
-        assert isinstance(s.versioned, GCVersioned)
-
     def test_branch_parameter(self):
         s = store(branch="dev")
         assert isinstance(s, Staged)

kvgit-0.1.6/kvgit/versioned/gc.py

@@ -1,334 +0,0 @@
-"""GCVersionedKV: VersionedKV with automatic garbage collection."""
-
-import json
-import time
-from dataclasses import dataclass
-from typing import Callable
-
-from ..errors import ConcurrencyError
-from ..kv.base import KVStore
-from ..encoding import MetaEntry, from_bytes, meta_from_bytes, meta_to_bytes, to_bytes
-from .protocol import MergeResult
-from .kv import (
-    BRANCH_HEAD,
-    COMMIT_KEYSET,
-    INFO_KEY,
-    META_KEY,
-    PARENT_COMMIT,
-    TOTAL_VAR_SIZE_KEY,
-    VersionedKV,
-    content_hash,
-)
-
-
-def is_system_key(key: str) -> bool:
-    """Check if a key is a system/protected key (starts with ``__``).
-
-    Handles both direct keys (``"__foo__"``) and namespaced keys
-    (``"ns/__foo__"``) by extracting the base key name.
-
-    This is the default ``is_protected`` policy for ``GCVersionedKV``.
-    """
-    base_key = key.split("/")[-1] if "/" in key else key
-    return base_key.startswith("__")
-
-
-@dataclass(frozen=True)
-class RebaseResult:
-    """Result of a rebase/GC operation."""
-
-    performed: bool
-    new_commit: str | None
-    dropped_keys: tuple[str, ...]
-    kept_keys: tuple[str, ...]
-    total_size_before: int
-    total_size_after: int
-    orphans_cleaned: int = 0
-
-
-class GCVersionedKV(VersionedKV):
-    """VersionedKV with built-in garbage collection via rebase.
-
-    Rebase strategy (high/low water):
-    - Track total persisted user-var size from commit metadata.
-    - If total <= high_water_bytes: no-op.
-    - If total > high_water_bytes: drop coldest user keys (oldest touch,
-      then largest) until total <= low_water_bytes (default 80% of high).
-    - Protected keys (as determined by ``is_protected``) are always retained.
-    - Write a fresh root commit with only retained keys, then delete
-      dropped blobs and orphaned commits.
-
-    Every ``commit()`` auto-runs the high/low check.
-    """
-
-    def __init__(
-        self,
-        store: KVStore | None = None,
-        *,
-        commit_hash: str | None = None,
-        branch: str = "main",
-        high_water_bytes: int,
-        low_water_bytes: int | None = None,
-        is_protected: Callable[[str], bool] = is_system_key,
-    ) -> None:
-        super().__init__(store, commit_hash=commit_hash, branch=branch)
-        if high_water_bytes <= 0:
-            raise ValueError("high_water_bytes must be > 0")
-        self.high_water = high_water_bytes
-        self.low_water = (
-            low_water_bytes
-            if low_water_bytes is not None
-            else int(high_water_bytes * 0.8)
-        )
-        if self.low_water <= 0 or self.low_water > self.high_water:
-            self.low_water = int(high_water_bytes * 0.8)
-        self._is_protected = is_protected
-        self.last_rebase_result: RebaseResult | None = None
-
-    def commit(
-        self,
-        updates: dict[str, bytes] | None = None,
-        removals: set[str] | None = None,
-        *,
-        on_conflict: str = "raise",
-        merge_fns=None,
-        default_merge=None,
-        info: dict | None = None,
-    ) -> "MergeResult":
-        """Commit changes, then run GC if above high water mark."""
-
-        result = super().commit(
-            updates,
-            removals,
-            on_conflict=on_conflict,
-            merge_fns=merge_fns,
-            default_merge=default_merge,
-            info=info,
-        )
-        if result.merged:
-            rebase_result = self.maybe_rebase()
-            self.last_rebase_result = rebase_result
-        return result
-
-    def maybe_rebase(self) -> RebaseResult:
-        """Run rebase only if total size exceeds high water mark."""
-        total = self._load_total_size()
-        if total <= self.high_water:
-            return RebaseResult(
-                performed=False,
-                new_commit=None,
-                dropped_keys=(),
-                kept_keys=tuple(self._commit_keys.keys()),
-                total_size_before=total,
-                total_size_after=total,
-            )
-        return self.rebase()
-
-    def rebase(
-        self,
-        keep_keys: set[str] | None = None,
-        *,
-        info: dict | None = None,
-    ) -> RebaseResult:
-        """Rebase: create a fresh root commit, dropping cold keys."""
-        meta = self._meta
-        total_before = self._load_total_size(
-            default=sum(e.size or 0 for e in meta.values())
-        )
-
-        # Identify protected and user keys
-        protected_keys = {
-            k: v for k, v in self._commit_keys.items() if self._is_protected(k)
-        }
-        user_meta = {k: v for k, v in meta.items() if not self._is_protected(k)}
-
-        retained_keys = set(protected_keys.keys()) | set(user_meta.keys())
-        total = sum(e.size or 0 for e in user_meta.values())
-        dropped: list[str] = []
-
-        if keep_keys is not None:
-            # Explicit keep set — drop everything not in it (except protected keys)
-            for key in list(retained_keys):
-                if self._is_protected(key):
-                    continue
-                if key not in keep_keys:
-                    retained_keys.discard(key)
-                    dropped.append(key)
-                    total -= (user_meta.get(key) and user_meta[key].size) or 0
-        else:
-            # High/low water strategy: drop coldest until under low water
-            candidates: list[tuple[str, MetaEntry]] = sorted(
-                user_meta.items(),
-                key=lambda kv: (kv[1].last_touch, -(kv[1].size or 0)),
-            )
-            for key, entry in candidates:
-                if total <= self.low_water:
-                    break
-                retained_keys.discard(key)
-                dropped.append(key)
-                total -= entry.size or 0
-
-        # Build new commit with retained keys
-
-        # Collect retained data
-        new_commit_keys: dict[str, str] = {}
-        new_meta: dict[str, MetaEntry] = {}
-        retained_data: dict[str, bytes] = {}
-
-        for key in retained_keys:
-            versioned_key = self._commit_keys.get(key)
-            if not versioned_key:
-                continue
-            value = self.store.get(versioned_key)
-            if value is None:
-                continue
-            if key in meta:
-                new_meta[key] = meta[key]
-            if not self._is_protected(key):
-                retained_data[key] = value
-
-        # Content-addressable hash for the rebase commit (parent=None, fresh root)
-        preview_keys: dict[str, str] = {}
-        for key in protected_keys:
-            preview_keys[key] = protected_keys[key]
-        for key in retained_data:
-            preview_keys[key] = f"<pending:{key}>"
-        new_hash = content_hash((), preview_keys, retained_data, info=info)
-
-        # Build the write batch
-        diffs: dict[str, bytes] = {}
-
-        # Protected keys — copy blobs with new versioned keys
-        for key, old_vk in protected_keys.items():
-            value = self.store.get(old_vk)
-            if value is None:
-                continue
-            new_vk = f"{new_hash}:{key}"
-            new_commit_keys[key] = new_vk
-            diffs[new_vk] = value
-
-        # Retained user keys
-        for key, value in retained_data.items():
-            new_vk = f"{new_hash}:{key}"
-            new_commit_keys[key] = new_vk
-            diffs[new_vk] = value
-
-        # Commit metadata
-        diffs[COMMIT_KEYSET % new_hash] = to_bytes(new_commit_keys)
-        diffs[PARENT_COMMIT % new_hash] = to_bytes([])
-        diffs[META_KEY % new_hash] = meta_to_bytes(new_meta)
-        total_after = sum(e.size or 0 for e in new_meta.values())
-        diffs[TOTAL_VAR_SIZE_KEY % new_hash] = to_bytes(total_after)
-        if info is not None:
-            diffs[INFO_KEY % new_hash] = to_bytes(info)
-
-        self.store.set_many(**diffs)
-
-        # CAS HEAD to the new rebase commit
-        branch_key = BRANCH_HEAD % self._branch
-        expected = to_bytes(self._base_commit)
-        if not self.store.cas(branch_key, to_bytes(new_hash), expected=expected):
-            raise ConcurrencyError("HEAD changed during rebase.")
-
-        # Delete dropped blobs
-        to_delete = []
-        for key in dropped:
-            vk = self._commit_keys.get(key)
-            if vk:
-                to_delete.append(vk)
-        if to_delete:
-            self.store.remove_many(*to_delete)
-
-        # Update in-memory state
-        self._commit_keys = new_commit_keys
-        self._current_commit = new_hash
-        self._base_commit = new_hash
-        self._meta = new_meta
-
-        # Clean orphaned commits
-        orphans_cleaned = self.clean_orphans()
-
-        return RebaseResult(
-            performed=True,
-            new_commit=new_hash,
-            dropped_keys=tuple(dropped),
-            kept_keys=tuple(retained_keys),
-            total_size_before=total_before,
-            total_size_after=total_after,
-            orphans_cleaned=orphans_cleaned,
-        )
-
-    def clean_orphans(self, min_age: float = 3600) -> int:
-        """Remove orphaned commits unreachable from any branch HEAD.
-
-        Advisory: this is not atomic. Concurrent writers may create
-        commits between the mark and sweep phases. The ``min_age``
-        guard (default 1 hour) prevents recently created commits from
-        being falsely swept.
-        """
-        # Mark phase: find all reachable commits across ALL branches
-        reachable: set[str] = set()
-        prefix = BRANCH_HEAD.replace("%s", "")
-        for key in self.store.keys():
-            if isinstance(key, str) and key.startswith(prefix):
-                head_bytes = self.store.get(key)
-                if head_bytes is None:
-                    continue
-                branch_head = from_bytes(head_bytes)
-                for commit in self.history(commit_hash=branch_head, all_parents=True):
-                    reachable.add(commit)
-
-        # Sweep phase: find orphaned commits by scanning for meta keys
-        meta_prefix = META_KEY.replace("%s", "")
-        cutoff_time = time.time() - min_age
-        orphans: list[str] = []
-
-        for key in self.store.keys():
-            if not isinstance(key, str) or not key.startswith(meta_prefix):
-                continue
-            commit_hash = key[len(meta_prefix) :]
-            if not commit_hash or commit_hash in reachable:
-                continue
-            # Check age
-            meta_bytes = self.store.get(key)
-            if meta_bytes is None:
-                continue
-            try:
-                meta = meta_from_bytes(meta_bytes)
-                if meta:
-                    first_entry = next(iter(meta.values()), None)
-                    if first_entry and first_entry.created_at < cutoff_time:
-                        orphans.append(commit_hash)
-            except (json.JSONDecodeError, TypeError, KeyError):
-                continue
-
-        # Delete orphaned commits and their data
-        for orphan_hash in orphans:
-            keyset_bytes = self.store.get(COMMIT_KEYSET % orphan_hash)
-            if keyset_bytes:
-                try:
-                    keyset = from_bytes(keyset_bytes)
-                    blob_keys = list(keyset.values())
-                    if blob_keys:
-                        self.store.remove_many(*blob_keys)
-                except Exception:
-                    pass
-            self.store.remove_many(
-                META_KEY % orphan_hash,
-                COMMIT_KEYSET % orphan_hash,
-                PARENT_COMMIT % orphan_hash,
-                TOTAL_VAR_SIZE_KEY % orphan_hash,
-                INFO_KEY % orphan_hash,
-            )
-
-        return len(orphans)
-
-    def _load_total_size(self, default: int = 0) -> int:
-        """Load the total variable size for the current commit."""
-        total_bytes = self.store.get(TOTAL_VAR_SIZE_KEY % self._current_commit)
-        if total_bytes is None:
-            return default
-        try:
-            return from_bytes(total_bytes)
-        except Exception:
-            return default