kvgit 0.3.2__tar.gz → 0.3.3__tar.gz

{kvgit-0.3.2 → kvgit-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.2
+Version: 0.3.3
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT
@@ -42,7 +42,7 @@ Requires-Dist: pandas>=2.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: diskcache; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
 Requires-Dist: numpy>=1.24; extra == "dev"
 Requires-Dist: pandas>=2.0; extra == "dev"
 Dynamic: license-file

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/codecs/numpy.py

@@ -33,7 +33,7 @@ storing each unique buffer once instead of N times.)
 
 from __future__ import annotations
 
-from typing import Any, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     import numpy as np
@@ -66,7 +66,7 @@ def _descr_to_dtype(descr):
     return npf.descr_to_dtype(descr)
 
 
-def _root_and_offset(arr: "np.ndarray") -> tuple["np.ndarray", int]:
+def _root_and_offset(arr: np.ndarray) -> tuple[np.ndarray, int]:
     """Walk ``.base`` to the root buffer; return (root, byte_offset).
 
     Returns ``(arr, 0)`` if the .base chain leads somewhere we can't

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/codecs/pickler.py

@@ -16,7 +16,8 @@ from __future__ import annotations
 
 import io
 import pickle
-from typing import Any, Iterable
+from collections.abc import Iterable
+from typing import Any
 
 from .base import ChunkReader, ChunkSink, Codec
 

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/content_types.py

@@ -1,6 +1,7 @@
 """Merge functions for typed values."""
 
-from typing import Any, Callable
+from collections.abc import Callable
+from typing import Any
 
 MergeFn = Callable[[Any | None, Any, Any], Any]
 """Merge function: (old_value | None, our_value, their_value) -> merged_value.

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/encoding.py

@@ -28,5 +28,6 @@ def safe_loads(raw: bytes):
     """
     try:
         return json.loads(raw)
-    except Exception:
+    except Exception:  # noqa: BLE001 — the point of the function: any
+        # decode failure (garbage, partial write, version skew) is a miss.
         return None

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/kv/indexeddb.py

@@ -47,8 +47,8 @@ the handler is set, causing a deadlock.
 
 from collections.abc import Iterable, Mapping
 
-from pyodide.ffi import create_proxy, run_sync, to_js  # type: ignore[import-not-found]
 from js import Promise, indexedDB, undefined  # type: ignore[import-not-found]
+from pyodide.ffi import create_proxy, run_sync, to_js  # type: ignore[import-not-found]
 
 from .base import KVStore
 
@@ -155,8 +155,9 @@ def _to_bytes(js_value) -> bytes | None:
         return None
     try:
         return js_value.to_py().tobytes()
-    except Exception:
-        # Corrupted or unexpected JS value — treat as missing
+    except Exception:  # noqa: BLE001 — a JS->Python conversion can fail
+        # with anything the FFI decides to raise; there is no narrower
+        # type to name. Corrupted or unexpected JS value — treat as missing.
         return None
 
 

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/namespaced.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from collections.abc import Iterator, MutableMapping
-from typing import Any, Iterable
+from collections.abc import Iterable, Iterator, MutableMapping
+from typing import Any
 
 
 class Namespaced(MutableMapping[str, Any]):

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/staged.py

@@ -2,8 +2,8 @@
 
 import inspect
 import pickle
-from collections.abc import Iterable, Iterator, MutableMapping
-from typing import Any, Callable
+from collections.abc import Callable, Iterable, Iterator, MutableMapping
+from typing import Any
 
 from .codecs._hash import hash_bytes
 from .content_types import MergeFn

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/store.py

@@ -1,8 +1,8 @@
 """Store factory function."""
 
 import pickle
-from collections.abc import Iterable
-from typing import Any, Callable, Literal
+from collections.abc import Callable, Iterable
+from typing import Any, Literal
 
 from .kv.base import KVStore
 from .kv.memory import Memory
@@ -123,6 +123,11 @@ def delete_branches(
     not swept out from under it; an admin who knows the store is quiet
     can pass ``0`` to reclaim young commits immediately.
 
+    That sweep does not reclaim chunks — the content-addressed bytes a
+    chunked codec writes — because a chunk key is not the deleted
+    branch's to give away. On a store using chunked codecs, follow up
+    with ``deep_clean`` on a quiescent store to get that space back.
+
     Args:
         names: Branch names to delete — one name or an iterable of
             them. Missing names are no-ops. (A bare string is treated

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/versioned/base.py

@@ -1,7 +1,7 @@
 """Shared commit/merge orchestration for versioned stores."""
 
 from abc import ABC, abstractmethod
-from typing import Iterable
+from collections.abc import Iterable
 
 from ..errors import ConcurrencyError, MergeConflict
 from .helpers import diff_keysets, walk_history

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/versioned/helpers.py

@@ -1,7 +1,7 @@
 """Shared diff and history helpers."""
 
 from collections import deque
-from typing import Callable, Iterable
+from collections.abc import Callable, Iterable
 
 from .protocol import DiffResult
 

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/versioned/kv.py

@@ -13,6 +13,11 @@ Storage layout (v3):
 - ``kvgit:chunk:<chunk_hash>``         — content-addressed chunk bytes (v3)
 - ``<commit_hash>:<user_key>``         — blob value bytes
 
+``__branch_head_prev__`` is written only after a HEAD swap succeeds, so
+it always names a commit ``__branch_head__`` really held. Recovery reads
+it, so a value that was never HEAD would graft onto the branch a lineage
+it never had.
+
 The keyset (key -> blob_pointer + meta) is stored as a content-addressable
 HAMT, so unchanged subtrees are shared across commits by hash equality. A
 single-key change writes O(log N) new nodes instead of rewriting a full
@@ -20,8 +25,15 @@ keyset snapshot per commit.
 
 Chunks (v3) are content-addressed bytes referenced by per-key
 ``MetaEntry.chunks``. They let chunked codecs (numpy, pandas, ...) share
-large buffers across keys, commits, and branches. ``clean_orphans``
-sweeps unreferenced chunks subject to the usual ``min_age`` guard.
+large buffers across keys, commits, and branches.
+
+Chunks are the *only* class above keyed purely by content. Blobs carry
+the commit hash in the key; HAMT nodes embed that blob pointer, so a
+node hash is commit-scoped too. That difference decides who may delete
+what: ``clean_orphans`` never deletes chunks, because a chunk an orphan
+owns may be the same key a commit made a moment ago just deduped onto,
+and the sweep has no way to know. Only ``deep_clean``, which requires a
+quiescent store, reclaims chunks.
 
 v3 is a strict superset of v2:
 
@@ -139,12 +151,22 @@ def _load_root(store: KVStore, commit_hash: str) -> str | None:
     return val if isinstance(val, str) else None
 
 
-def _resolve_head(store: KVStore, branch: str, *, repair: bool = True) -> str | None:
+def _resolve_head(store: KVStore, branch: str) -> str | None:
     """Resolve a branch HEAD, falling back to prev HEAD or commit scan.
 
-    When *repair* is True (default), a corrupt HEAD is automatically
-    healed by writing the recovered commit hash back to the store.
-    Pass ``repair=False`` for side-effect-free reads (e.g. properties).
+    **Never writes.** Every read path in the library goes through here,
+    so healing the damage in place would make an ordinary ``get`` a
+    mutation — impossible for a read-only consumer, and a race between
+    two readers repairing the same branch to different answers. The
+    recovery is returned to the caller and forgotten; :func:`repair_head`
+    is the explicit call that makes it durable, and the write path heals
+    HEAD itself as part of the CAS that has to move it anyway.
+
+    The cost of not persisting is paid per read on a damaged store: two
+    extra ``get`` calls for the prev-HEAD tier, and a full store scan
+    for the tier below it. That scan already ran per *write* before this
+    change (``latest_head`` never repaired), and a store sitting on a
+    corrupt HEAD has a bigger problem than read latency.
 
     Returns a valid commit hash, or None if unrecoverable.
     """
@@ -158,7 +180,7 @@ def _resolve_head(store: KVStore, branch: str, *, repair: bool = True) -> str |
         ):
             return commit_hash
 
-    # 2. Try previous HEAD (backup written before each CAS)
+    # 2. Try previous HEAD (backup written after each successful CAS)
     prev_bytes = store.get(BRANCH_HEAD_PREV % branch)
     if prev_bytes is not None:
         commit_hash = safe_loads(prev_bytes)
@@ -169,8 +191,6 @@ def _resolve_head(store: KVStore, branch: str, *, repair: bool = True) -> str |
             logger.warning(
                 "Branch '%s': HEAD corrupt, recovered from prev HEAD", branch
             )
-            if repair:
-                store.set(BRANCH_HEAD % branch, dumps(commit_hash))
             return commit_hash
 
     # 3. HEAD existed but is corrupt and no prev — scan for best commit
@@ -180,8 +200,6 @@ def _resolve_head(store: KVStore, branch: str, *, repair: bool = True) -> str |
             logger.warning(
                 "Branch '%s': HEAD corrupt, recovered via commit scan", branch
             )
-            if repair:
-                store.set(BRANCH_HEAD % branch, dumps(commit_hash))
             return commit_hash
 
     return None
@@ -208,7 +226,9 @@ def _scan_for_best_commit(store: KVStore, branch: str) -> str | None:
                 val = safe_loads(time_bytes)
                 if isinstance(val, (int, float)):
                     ts = float(val)
-            except Exception:
+            except Exception:  # noqa: BLE001 — recovery scan over a store
+                # already known to be damaged; an unreadable timestamp
+                # must degrade to 0.0, never abort the scan.
                 pass
         all_commits[h] = ts
 
@@ -266,12 +286,81 @@ def _scan_for_best_commit(store: KVStore, branch: str) -> str | None:
     return max(tips, key=lambda h: all_commits.get(h, 0))
 
 
+def _heal_head(store: KVStore, branch: str, recovered: bytes) -> bool:
+    """Atomically replace an unresolvable HEAD with a recovered value.
+
+    Returns True only when HEAD was damaged *and* this call is the one
+    that replaced it. Three cases are deliberately left alone:
+
+    * HEAD resolves fine — it did not break, it *moved*, and another
+      writer won a legitimate race. Overwriting it would destroy a good
+      commit to make a losing CAS succeed.
+    * HEAD already holds ``recovered`` — nothing to do.
+    * HEAD is absent — the branch was deleted. Re-creating the key is
+      exactly the resurrection ``delete_branch`` drops the prev-HEAD
+      backup to prevent.
+
+    The replacement is a CAS against the exact damaged bytes, so two
+    processes healing the same branch cannot both win, and a HEAD that
+    someone else repaired (or advanced) in the meantime is never
+    clobbered.
+    """
+    branch_key = BRANCH_HEAD % branch
+    raw = store.get(branch_key)
+    if raw is None or raw == recovered:
+        return False
+    commit_hash = safe_loads(raw)
+    if (
+        isinstance(commit_hash, str)
+        and store.get(COMMIT_ROOT % commit_hash) is not None
+    ):
+        return False
+    if not store.cas(branch_key, recovered, expected=raw):
+        return False
+    logger.warning("Branch '%s': corrupt HEAD replaced with recovered commit", branch)
+    return True
+
+
+def repair_head(store: KVStore, branch: str = "main") -> str | None:
+    """Persist a recovered HEAD for a damaged branch.
+
+    Read paths recover a corrupt ``__branch_head__`` in memory and leave
+    the store untouched, so the damage stays visible until someone
+    decides what to do about it. This is that decision: resolve the
+    branch the way a read would, and write the answer back.
+
+    Handle-independent, like :func:`clean_orphans` — it takes a raw
+    ``KVStore`` and touches nothing else, so it works with or without a
+    ``VersionedKV`` anchored on the branch.
+
+    Idempotent, and a no-op on a healthy branch. The write is a CAS
+    against the damaged bytes, so it cannot overwrite a HEAD another
+    process fixed, or advanced, in the meantime.
+
+    When that CAS does not win — another process repaired the branch,
+    advanced it, or deleted it between resolving and healing — the
+    recovery candidate is stale, and returning it would name an older
+    commit than HEAD actually holds. The branch is re-resolved instead,
+    so the answer describes the store rather than the attempt.
+
+    Returns:
+        The commit HEAD now names, or None if the branch does not exist
+        or nothing recoverable was found.
+    """
+    commit_hash = _resolve_head(store, branch)
+    if commit_hash is None:
+        return None
+    if _heal_head(store, branch, dumps(commit_hash)):
+        return commit_hash
+    return _resolve_head(store, branch)
+
+
 def clean_orphans(store: KVStore, 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, blobs, and HAMT nodes that are not reachable from
-    any reachable commit.
+    the commit metadata, blobs and HAMT nodes owned by the orphaned
+    commits and not shared with anything still reachable.
 
     Handle-independent by design: it marks from ALL live branch HEADs
     and touches nothing but ``store``, so it works with or without a
@@ -279,12 +368,63 @@ def clean_orphans(store: KVStore, min_age: float = 3600) -> int:
     and the anchor-free admin path (:func:`kvgit.delete_branches`)
     share this one implementation.
 
-    The ``min_age`` guard (default 1 hour) prevents recently created
-    commits from being falsely swept during concurrent writes.
+    Safe under concurrent writers: every deletion candidate is
+    discovered by walking an orphan commit's own keyset, and every
+    class it deletes is commit-scoped (blob keys carry the commit
+    hash; HAMT nodes embed that pointer), so a commit that lands
+    mid-sweep can never contribute one.
+
+    **Does not reclaim chunks.** Chunk keys are pure content hashes,
+    so an orphan's chunk and a brand-new commit's chunk are the same
+    key whenever the bytes match — "the orphan owned it" does not
+    imply "safe to delete", at any window size. Chunks are the large
+    objects (numpy and pandas buffers), so on a store using chunked
+    codecs they accumulate between maintenance passes; a store that
+    never uses a chunked codec has none and loses nothing here. Run
+    :func:`deep_clean` on a quiescent store to reclaim them, along
+    with nodes and chunks no commit points at.
+
+    The ``min_age`` guard (default 1 hour) still applies: it decides
+    which unreachable commits are old enough to delete at all.
 
     Returns:
         Number of orphaned commits removed.
     """
+    return _sweep(store, min_age, deep=False)
+
+
+def deep_clean(store: KVStore, min_age: float = 3600) -> int:
+    """Sweep orphans *and* every unreferenced node and chunk. Unsafe.
+
+    Does everything :func:`clean_orphans` does, then additionally scans
+    the whole ``kvgit:keyset:`` and ``kvgit:chunk:`` namespaces and
+    deletes anything not reachable from a live branch head or a young
+    orphan commit. That namespace scan is the only way to reclaim
+    nodes and chunks that no commit references any more — leftovers
+    from a crash, from an interrupted write, or from a store swept by
+    an earlier kvgit — because no orphan keyset points at them.
+
+    It is also the only way to reclaim **any** chunk at all, including
+    ones a deleted orphan uniquely owned: the incremental sweep leaves
+    every chunk in place, so on a store using chunked codecs this is
+    the maintenance pass that gives the space back.
+
+    **Not safe against concurrent writers.** The scan runs after the
+    mark phase, so it sees, and deletes, artifacts written by any
+    commit that landed in between — including a commit that has since
+    become a live branch HEAD. Run it only on a quiescent store: no
+    other process or thread writing, for the whole call. ``min_age``
+    does not protect you here; it governs commit deletion, not the
+    namespace scan.
+
+    Returns:
+        Number of orphaned commits removed.
+    """
+    return _sweep(store, min_age, deep=True)
+
+
+def _sweep(store: KVStore, min_age: float, *, deep: bool) -> int:
+    """Shared mark-and-sweep behind ``clean_orphans`` / ``deep_clean``."""
     gc_logger = logging.getLogger("kvgit.orphans")
     cutoff_time = time.time() - min_age
 
@@ -304,6 +444,11 @@ def clean_orphans(store: KVStore, min_age: float = 3600) -> int:
     reachable_commits: set[str] = set()
     reachable_blobs: set[str] = set()
     reachable_nodes: set[str] = set()
+    # Only the deep path deletes chunks, and it is the only consumer of
+    # this set. The incremental path leaves it empty on purpose rather
+    # than paying to accumulate every chunk hash in the store — if you
+    # ever add a chunk deletion outside the ``if deep:`` block below,
+    # you must populate this unconditionally first.
     reachable_chunks: set[str] = set()
 
     def _walk_commit_for_marks(commit_hash: str) -> None:
@@ -319,7 +464,7 @@ def clean_orphans(store: KVStore, min_age: float = 3600) -> int:
         entries, new_nodes = Keyset(store, root=root).walk(skip_nodes=reachable_nodes)
         for entry in entries.values():
             reachable_blobs.add(entry.blob)
-            if entry.meta.chunks:
+            if deep and entry.meta.chunks:
                 reachable_chunks.update(entry.meta.chunks)
         reachable_nodes.update(new_nodes)
 
@@ -368,29 +513,56 @@ def clean_orphans(store: KVStore, min_age: float = 3600) -> int:
         except (TypeError, ValueError):
             continue
 
-    # Protect chunks referenced by young orphan commits — those
-    # may belong to in-flight writers whose CAS has not landed yet.
+    # Protect what young orphan commits reference — they may belong to
+    # in-flight writers whose CAS has not landed yet. Their nodes and
+    # blobs matter to both paths (an aged orphan sharing a subtree with
+    # a young one must not take it down); their chunks matter to
+    # ``deep_clean``, whose namespace scan would otherwise eat them.
     for young in young_orphan_commits:
         _walk_commit_for_marks(young)
 
     # Collect everything to delete in one batch so the sweep is atomic
     # at the store level (defends against partial sweeps under crash).
     all_removals: list[str] = []
+    keyset_prefix = Keyset.DEFAULT_PREFIX
 
+    # Every deletion candidate comes from walking an orphan's own
+    # keyset — never from a namespace scan. That is what makes this
+    # safe under concurrent writers: a commit that lands after the
+    # mark phase is in nobody's orphan tree, so nothing it wrote can
+    # end up on this list. ``skip_nodes=reachable_nodes`` prunes
+    # subtrees shared with a live commit or a young orphan, which is
+    # both the correct thing (nothing under them is deletable) and
+    # the cheap thing (shared structure is walked once, not per
+    # orphan). Two orphans sharing a subtree may each name the same
+    # hash; ``remove_many`` tolerates duplicates.
+    #
+    # Chunks are deliberately absent here. Blob keys are
+    # ``<commit_hash>:<key>`` and HAMT nodes embed that pointer, so
+    # both are commit-scoped: an orphan's node hash can only collide
+    # with a commit in its own ancestry, which the mark phase already
+    # covered. A chunk key is ``kvgit:chunk:<content_hash>`` and
+    # carries nothing commit-derived, so an orphan's chunk and a
+    # brand-new commit's chunk are the *same key* whenever the bytes
+    # match. "In the orphan's tree" therefore does not imply "safe to
+    # delete", and no amount of scoping fixes that — the new commit
+    # was never marked. Chunk reclamation lives in ``deep_clean``.
     for orphan_hash in orphans:
         orphan_root = _load_root(store, orphan_hash)
         if orphan_root is not None and orphan_root != EMPTY_HASH:
             try:
-                # Batched walk for the orphan's blob references.
-                orphan_entries = Keyset(store, root=orphan_root).materialize()
-                for entry in orphan_entries.values():
-                    if entry.blob not in reachable_blobs:
-                        all_removals.append(entry.blob)
-                    # Chunks in the orphan are only swept later via
-                    # the chunk-namespace scan below; here we only
-                    # need to ensure we've picked up the blob refs.
-            except Exception:
-                pass
+                orphan_entries, orphan_nodes = Keyset(store, root=orphan_root).walk(
+                    skip_nodes=reachable_nodes
+                )
+            except Exception:  # noqa: BLE001 — deliberate: a damaged
+                # orphan must not stall the sweep; drop its payload and
+                # still reclaim its commit metadata. Narrowing this would
+                # let one corrupt keyset block GC for the whole store.
+                orphan_entries, orphan_nodes = {}, set()
+            for entry in orphan_entries.values():
+                if entry.blob not in reachable_blobs:
+                    all_removals.append(entry.blob)
+            all_removals.extend(keyset_prefix + node for node in orphan_nodes)
         all_removals.extend(
             [
                 COMMIT_ROOT % orphan_hash,
@@ -400,23 +572,26 @@ def clean_orphans(store: KVStore, min_age: float = 3600) -> int:
             ]
         )
 
-    # Orphan HAMT nodes: any keyset node not reachable from a live commit
-    keyset_prefix = Keyset.DEFAULT_PREFIX
-    for key in store.keys():
-        if not (isinstance(key, str) and key.startswith(keyset_prefix)):
-            continue
-        node_hash = key[len(keyset_prefix) :]
-        if node_hash and node_hash not in reachable_nodes:
-            all_removals.append(key)
+    if deep:
+        # Namespace scans. The node scan reclaims nodes no orphan
+        # keyset points at; the chunk scan is the *only* place chunks
+        # are ever deleted, orphan-owned ones included. Both are
+        # unsafe against a concurrent writer, because anything
+        # committed since the mark phase looks unreferenced here.
+        # Quiescent stores only.
+        for key in store.keys():
+            if not (isinstance(key, str) and key.startswith(keyset_prefix)):
+                continue
+            node_hash = key[len(keyset_prefix) :]
+            if node_hash and node_hash not in reachable_nodes:
+                all_removals.append(key)
 
-    # Orphan chunks: any chunk not reachable from a live commit
-    # (or a young orphan, see above) is fair game.
-    for key in store.keys():
-        if not (isinstance(key, str) and key.startswith(CHUNK_PREFIX)):
-            continue
-        chunk_hash = key[len(CHUNK_PREFIX) :]
-        if chunk_hash and chunk_hash not in reachable_chunks:
-            all_removals.append(key)
+        for key in store.keys():
+            if not (isinstance(key, str) and key.startswith(CHUNK_PREFIX)):
+                continue
+            chunk_hash = key[len(CHUNK_PREFIX) :]
+            if chunk_hash and chunk_hash not in reachable_chunks:
+                all_removals.append(key)
 
     if all_removals:
         store.remove_many(*all_removals)
@@ -497,7 +672,7 @@ class VersionedKV(VersionedBase):
     @property
     def latest_head(self) -> str | None:
         """Read HEAD directly from the KV store (reflects other writers)."""
-        return _resolve_head(self.store, self._branch, repair=False)
+        return _resolve_head(self.store, self._branch)
 
     # -- Read operations --
 
@@ -729,13 +904,46 @@ class VersionedKV(VersionedBase):
     def _cas_head(self, expected: str, new_head: str) -> bool:
         """Atomically advance branch HEAD via KVStore CAS.
 
-        Saves the current HEAD as prev HEAD before advancing, so a
-        corrupt write can be recovered from.
+        The prev-HEAD backup is written **after** the swap succeeds,
+        never before. Written first, it lands whether or not the CAS
+        does, so a writer that loses the race still leaves its own stale
+        ``expected`` as the branch's recovery target — clobbering the
+        winner's backup, and, when ``expected`` came from the commit
+        scan, naming a commit that was never HEAD at all. Writing it
+        afterwards makes it always a value ``__branch_head__`` really
+        held.
+
+        What this does **not** buy is a backup that is always exactly
+        one commit back. The swap and the backup write are two steps,
+        and anything that separates them — a crash, or simply losing
+        the CPU while another writer completes both of its own — lets
+        the older writer's backup land last. HEAD then sits two or more
+        commits ahead of a backup that is still a real former HEAD, and
+        recovery skips whatever came between.
+
+        So the guarantee is the narrower one: the backup always names a
+        commit ``__branch_head__`` really held, never a commit invented
+        by a losing writer. Recovery may lose more than one commit; it
+        cannot graft on a lineage the branch never had. There is no way
+        to do better with what the store offers — ``KVStore.cas`` takes
+        a single key and no backend exposes a transaction spanning two,
+        so HEAD and its backup cannot move in one step.
+
+        A CAS that fails against a *damaged* HEAD is retried once
+        through :func:`_heal_head`, which repairs it atomically. That is
+        the only place a corrupt HEAD is written back, now that reads
+        do not.
         """
         branch_key = BRANCH_HEAD % self._branch
-        prev_key = BRANCH_HEAD_PREV % self._branch
-        self.store.set(prev_key, dumps(expected))
-        return self.store.cas(branch_key, dumps(new_head), expected=dumps(expected))
+        expected_bytes = dumps(expected)
+        new_bytes = dumps(new_head)
+
+        won = self.store.cas(branch_key, new_bytes, expected=expected_bytes)
+        if not won and _heal_head(self.store, self._branch, expected_bytes):
+            won = self.store.cas(branch_key, new_bytes, expected=expected_bytes)
+        if won:
+            self.store.set(BRANCH_HEAD_PREV % self._branch, expected_bytes)
+        return won
 
     def _load_keyset(self, commit_hash: str) -> dict[str, str]:
         """Load just the keyset for a commit (key -> versioned_key mapping).
@@ -807,7 +1015,7 @@ class VersionedKV(VersionedBase):
         """Reload state from HEAD."""
         commit_hash = _resolve_head(self.store, self._branch)
         if commit_hash is None:
-            raise ValueError("No HEAD commit found for branch %s" % self._branch)
+            raise ValueError(f"No HEAD commit found for branch {self._branch}")
         self._load_commit(commit_hash, update_base=True)
 
     def checkout(
@@ -912,6 +1120,21 @@ class VersionedKV(VersionedBase):
             return None
         return loads(info_bytes)
 
+    # -- Recovery --
+
+    def repair_head(self) -> str | None:
+        """Persist a recovered HEAD for this branch.
+
+        Thin instance wrapper over :func:`repair_head`. Reads recover a
+        damaged HEAD without writing it back; this is the explicit call
+        that makes the recovery durable.
+
+        Returns:
+            The commit HEAD now names, or None if nothing was
+            recoverable.
+        """
+        return repair_head(self.store, self._branch)
+
     # -- Orphan cleanup --
 
     def clean_orphans(self, min_age: float = 3600) -> int:
@@ -921,11 +1144,32 @@ class VersionedKV(VersionedBase):
         mark-and-sweep against ``self.store``. Kept as a method so
         existing callers (and ``delete_branch``) read naturally.
 
+        Reclaims commit metadata, blobs and HAMT nodes, but **not
+        chunks** — see :func:`clean_orphans` for why, and
+        :meth:`deep_clean` for the pass that reclaims them.
+
         Returns:
             Number of orphaned commits removed.
         """
         return clean_orphans(self.store, min_age)
 
+    def deep_clean(self, min_age: float = 3600) -> int:
+        """Orphan sweep plus a full unreferenced-node/chunk scan.
+
+        Thin instance wrapper over :func:`deep_clean`. **Requires a
+        quiescent store** — the namespace scan will delete artifacts
+        written by a concurrent writer, including ones a live branch
+        HEAD has since come to depend on. Use :meth:`clean_orphans`
+        for routine cleanup; schedule this one when you can quiesce
+        the store, since it is the only pass that reclaims chunks —
+        both the ones no commit references and the ones deleted
+        orphans owned.
+
+        Returns:
+            Number of orphaned commits removed.
+        """
+        return deep_clean(self.store, min_age)
+
     # -- Internal --
 
     def _load_commit(self, commit_hash: str, *, update_base: bool) -> None:

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/versioned/merge.py

@@ -1,12 +1,11 @@
 """Shared three-way merge resolution."""
 
+from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Callable
 
 from ..errors import MergeConflict
 from .protocol import BytesMergeFn, DiffResult
 
-
 BlobReader = Callable[[str], bytes | None]
 """Read a blob by its content identifier (versioned key or hex SHA)."""
 
@@ -117,7 +116,8 @@ def resolve_merge(
             result_val = fn(old_val, our_val, their_val)
             merged_values[key] = result_val
             auto_merged.append(key)
-        except Exception as e:
+        except Exception as e:  # noqa: BLE001 — `fn` is caller-supplied;
+            # any failure it raises is reported as a merge conflict.
             conflicts.add(key)
             merge_errors[key] = e
 

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/versioned/protocol.py

@@ -1,8 +1,8 @@
 """Versioned protocol and types."""
 
+from collections.abc import Callable, Iterable
 from dataclasses import dataclass
-from typing import Callable, Iterable, Protocol, runtime_checkable
-
+from typing import Protocol, runtime_checkable
 
 BytesMergeFn = Callable[[bytes | None, bytes | None, bytes | None], bytes]
 """Merge function: (old_value, our_value, their_value) -> merged_value.

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.2
+Version: 0.3.3
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT
@@ -42,7 +42,7 @@ Requires-Dist: pandas>=2.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: diskcache; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
 Requires-Dist: numpy>=1.24; extra == "dev"
 Requires-Dist: pandas>=2.0; extra == "dev"
 Dynamic: license-file

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit.egg-info/requires.txt

@@ -7,7 +7,7 @@ pandas>=2.0
 [dev]
 pytest
 diskcache
-ruff
+ruff<0.17,>=0.16
 numpy>=1.24
 pandas>=2.0
 

kvgit-0.3.3/pyproject.toml

@@ -0,0 +1,152 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kvgit"
+version = "0.3.3"
+description = "Versioned key-value store with git-like commit, branch, and merge semantics."
+authors = [{ name = "ashenfad" }]
+requires-python = ">=3.10"
+readme = "README.md"
+license = { text = "MIT" }
+keywords = ["versioning", "git", "key-value", "branching", "merge"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+"Homepage" = "https://github.com/ashenfad/kvgit"
+"Bug Tracker" = "https://github.com/ashenfad/kvgit/issues"
+"Documentation" = "https://github.com/ashenfad/kvgit#readme"
+"Source" = "https://github.com/ashenfad/kvgit"
+
+[project.optional-dependencies]
+disk = ["diskcache"]
+numpy = ["numpy>=1.24"]
+pandas = ["numpy>=1.24", "pandas>=2.0"]
+scientific = ["numpy>=1.24", "pandas>=2.0"]
+all = ["diskcache", "numpy>=1.24", "pandas>=2.0"]
+dev = [
+    "pytest",
+    "diskcache",
+    # Pinned to the minor line the [tool.ruff.lint] config below was
+    # written against. Ruff's rule *defaults* move between minors, so a
+    # floating pin makes "lint passes" mean something different on each
+    # upgrade.
+    "ruff>=0.16,<0.17",
+    "numpy>=1.24",
+    "pandas>=2.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["kvgit*"]
+
+[tool.mypy]
+warn_unused_configs = true
+
+[[tool.mypy.overrides]]
+module = ["diskcache"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+# ruff 0.16 formats Python code blocks inside Markdown. This project's docs
+# align trailing comments by hand, so letting the formatter at them produces
+# churn unrelated to whatever change is being made, on any commit touching
+# docs/ -- including docs-only ones. `force-exclude` is required because
+# pre-commit passes filenames explicitly, and ruff ignores `extend-exclude`
+# for explicitly-passed paths without it.
+extend-exclude = ["*.md"]
+force-exclude = true
+
+[tool.ruff.lint]
+# Every rule this project enforces is named here. Ruff's *default*
+# selection is not stable across releases — 0.15 defaulted to
+# `E4,E7,E9,F`, 0.16 replaced that with a far wider recommended set — so
+# relying on the default let "lint passes" change meaning on an upgrade
+# with no code change at all. Naming the linters means a ruff bump can
+# only add rules inside families we opted into, and the `ruff` pin in
+# the `dev` extra keeps even that from arriving unannounced.
+select = [
+    "E4",      # pycodestyle: import placement
+    "E7",      # pycodestyle: statement and comparison errors
+    "E9",      # pycodestyle: syntax and IO errors
+    "W",       # pycodestyle warnings
+    "F",       # pyflakes
+    "I",       # isort
+    "UP",      # pyupgrade
+    "B",       # flake8-bugbear
+    "C4",      # flake8-comprehensions
+    "PIE",     # flake8-pie
+    "SIM",     # flake8-simplify
+    "ASYNC",   # flake8-async
+    "BLE",     # flake8-blind-except
+    "RUF",     # ruff-specific rules
+]
+# E501 is deliberately absent: `ruff format` owns line width, and the
+# two disagree on long strings and comments.
+#
+# PERF is absent for the same reason SIM118 is ignored below: it assumes
+# a dict. Three of its four PERF102 hits sit inside the *definitions* of
+# `Hamt.keys`, `Hamt.values` and `Keyset.values`, where "use the keys()
+# method" is infinite recursion rather than a speedup; the fourth is a
+# KVStore. PERF203/401/403 are style calls we don't want enforced.
+
+ignore = [
+    # SIM118 reads any `x.keys()` as a dict and rewrites `k in x.keys()`
+    # to `k in x`. Every one of the ~37 hits here is `.keys()` on a
+    # KVStore or a Versioned — this project's own protocol, which
+    # deliberately does not implement `__iter__`: `iter(Memory())`,
+    # `iter(Disk(...))` and `iter(VersionedKV(...))` all raise
+    # TypeError. The suggested rewrite is a runtime error at every
+    # site, so the rule is switched off rather than papered over with
+    # three dozen individual noqas.
+    "SIM118",
+    # SIM105 wants `contextlib.suppress` instead of try/except/pass.
+    # Both sites are per-key paths in the store layer (Disk.remove,
+    # Namespaced.get_many), where building a context manager per key
+    # costs more than the bare handler it would replace.
+    "SIM105",
+    # RUF001/2/3 flag en dashes, em dashes and curly quotes as
+    # "ambiguous unicode". The prose in this repo uses them on purpose.
+    "RUF001",
+    "RUF002",
+    "RUF003",
+]
+
+[tool.ruff.lint.isort]
+# Keep `from x import a, b as c` on one statement rather than exploding
+# an aliased name into its own import block.
+combine-as-imports = true
+
+[tool.ruff.lint.per-file-ignores]
+# Codec tests gate themselves with `pytest.importorskip(...)` before
+# importing optional deps (numpy, pandas) and the matching codec modules,
+# which forces module-level imports to follow the skip call. E402 is the
+# wrong rule here — the pattern is the official pytest idiom.
+"tests/codecs/*.py" = ["E402"]
+# The Pyodide FS probes exist to prove that ordinary blocking Python
+# file I/O — exactly what diskcache issues — works over an IDBFS/OPFS
+# mount. ASYNC230 objects to `open()` inside an async def, but the
+# blocking call *is* the thing under test.
+"tests/kv/test_pyodide_fs.py" = ["ASYNC230"]
+# Crash-injection stress harness: it kills workers mid-write and then
+# pokes at whatever survived. Catching Exception at every probe is the
+# design, not an oversight.
+"tests/stress_kill.py" = ["BLE001"]

{kvgit-0.3.2 → kvgit-0.3.3}/tests/test_hamt.py

@@ -8,7 +8,6 @@ import pytest
 from kvgit.hamt import EMPTY_HASH, Hamt, HamtDiff
 from kvgit.kv.memory import Memory
 
-
 # ---- helpers ----
 
 
@@ -315,7 +314,7 @@ def test_batch_update_filters_orphan_intermediates():
     superseded intermediate leaves to pending."""
     store = _store()
     h = Hamt(store, bucket_max=8)
-    new_h, pending = h.updated({f"k{i}": b"v" for i in range(5)})
+    _new_h, pending = h.updated({f"k{i}": b"v" for i in range(5)})
 
     # Only the final leaf should be in pending — no orphans from intermediate steps
     assert len(pending) == 1
@@ -545,7 +544,7 @@ def test_large_random_with_deletes():
 def test_chained_updated_calls_accumulate_pending():
     store = _store()
     h0 = Hamt(store, bucket_max=4)
-    h1, pending1 = h0.updated({f"k{i}": b"v" for i in range(3)})
+    h1, _pending1 = h0.updated({f"k{i}": b"v" for i in range(3)})
     h2, pending2 = h1.updated({f"k{i}": b"w" for i in range(3, 6)})
 
     # Nothing in store yet
@@ -587,7 +586,7 @@ def test_flush_clears_pending():
 def test_pending_not_visible_to_separate_hamt_instance():
     store = _store()
     h0 = Hamt(store, bucket_max=4)
-    new_h, pending = h0.updated({"a": b"1"})
+    new_h, _pending = h0.updated({"a": b"1"})
 
     # A fresh Hamt opened on the same store at the new root cannot see
     # the value, because the underlying nodes haven't been flushed.
@@ -864,7 +863,7 @@ def test_walk_skip_nodes_cumulative_across_shared_subtree():
 
     # First walk seeds the seen-set.
     seen: set[str] = set()
-    items1, nodes1 = h1.walk(skip_nodes=seen)
+    _items1, nodes1 = h1.walk(skip_nodes=seen)
     seen |= nodes1
 
     # Second walk: only the path from h2.root down to the changed

kvgit-0.3.2/pyproject.toml

@@ -1,69 +0,0 @@
-[build-system]
-requires = ["setuptools>=68.0"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "kvgit"
-version = "0.3.2"
-description = "Versioned key-value store with git-like commit, branch, and merge semantics."
-authors = [{ name = "ashenfad" }]
-requires-python = ">=3.10"
-readme = "README.md"
-license = { text = "MIT" }
-keywords = ["versioning", "git", "key-value", "branching", "merge"]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Intended Audience :: Developers",
-    "Topic :: Database",
-    "Topic :: Software Development :: Libraries :: Python Modules",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Programming Language :: Python :: 3.14",
-    "License :: OSI Approved :: MIT License",
-    "Operating System :: OS Independent",
-    "Typing :: Typed",
-]
-dependencies = []
-
-[project.urls]
-"Homepage" = "https://github.com/ashenfad/kvgit"
-"Bug Tracker" = "https://github.com/ashenfad/kvgit/issues"
-"Documentation" = "https://github.com/ashenfad/kvgit#readme"
-"Source" = "https://github.com/ashenfad/kvgit"
-
-[project.optional-dependencies]
-disk = ["diskcache"]
-numpy = ["numpy>=1.24"]
-pandas = ["numpy>=1.24", "pandas>=2.0"]
-scientific = ["numpy>=1.24", "pandas>=2.0"]
-all = ["diskcache", "numpy>=1.24", "pandas>=2.0"]
-dev = [
-    "pytest",
-    "diskcache",
-    "ruff",
-    "numpy>=1.24",
-    "pandas>=2.0",
-]
-
-[tool.setuptools.packages.find]
-include = ["kvgit*"]
-
-[tool.mypy]
-warn_unused_configs = true
-
-[[tool.mypy.overrides]]
-module = ["diskcache"]
-ignore_missing_imports = true
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-
-[tool.ruff.lint.per-file-ignores]
-# Codec tests gate themselves with `pytest.importorskip(...)` before
-# importing optional deps (numpy, pandas) and the matching codec modules,
-# which forces module-level imports to follow the skip call. E402 is the
-# wrong rule here — the pattern is the official pytest idiom.
-"tests/codecs/*.py" = ["E402"]

{kvgit-0.3.2 → kvgit-0.3.3}/kvgit/__init__.py

@@ -3,10 +3,10 @@
 from .content_types import MergeFn, counter, last_writer_wins
 from .errors import ConcurrencyError, MergeConflict
 from .namespaced import Namespaced
-from .versioned.protocol import MergeResult, Versioned
 from .staged import Staged
 from .store import delete_branches, store
 from .versioned.kv import VersionedKV
+from .versioned.protocol import MergeResult, Versioned
 
 __all__ = [
     "ConcurrencyError",