kvgit 0.3.4__tar.gz → 0.3.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.4
+Version: 0.3.5
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT
@@ -56,6 +56,7 @@ Git-style versioning for your data. Commits, branches, and merges -- backed by a
 | **Dict interface** | `MutableMapping[str, Any]` -- reads and writes work like a dict |
 | **Commits** | Immutable, content-addressable snapshots with rollback |
 | **Branches** | Cheap forks with CAS-based optimistic concurrency |
+| **Tags** | Immutable names for commits; a tagged commit outlives every branch that reached it, in every kvgit version |
 | **Three-way merge** | Auto-merges non-overlapping changes; pluggable merge fns for conflicts |
 | **Pluggable backends** | In-memory, disk (diskcache), IndexedDB (Pyodide/browser), or bring your own `KVStore` |
 | **Chunked codecs** | Optional content-addressed dedup for large numpy arrays and pandas DataFrames -- equal buffers stored once across keys, commits, and branches |
@@ -87,6 +88,10 @@ dev.commit()
 
 print(main["score"])  # 0   (main unchanged)
 print(dev["score"])   # 999 (dev branch)
+
+# Tag a commit by name -- immutable, and safe from garbage collection
+main.tag("v1")
+print(main.peek("score", tag="v1"))  # 0
 ```
 
 ## Chunked codecs (numpy / pandas)

{kvgit-0.3.4 → kvgit-0.3.5}/README.md

@@ -7,6 +7,7 @@ Git-style versioning for your data. Commits, branches, and merges -- backed by a
 | **Dict interface** | `MutableMapping[str, Any]` -- reads and writes work like a dict |
 | **Commits** | Immutable, content-addressable snapshots with rollback |
 | **Branches** | Cheap forks with CAS-based optimistic concurrency |
+| **Tags** | Immutable names for commits; a tagged commit outlives every branch that reached it, in every kvgit version |
 | **Three-way merge** | Auto-merges non-overlapping changes; pluggable merge fns for conflicts |
 | **Pluggable backends** | In-memory, disk (diskcache), IndexedDB (Pyodide/browser), or bring your own `KVStore` |
 | **Chunked codecs** | Optional content-addressed dedup for large numpy arrays and pandas DataFrames -- equal buffers stored once across keys, commits, and branches |
@@ -38,6 +39,10 @@ dev.commit()
 
 print(main["score"])  # 0   (main unchanged)
 print(dev["score"])   # 999 (dev branch)
+
+# Tag a commit by name -- immutable, and safe from garbage collection
+main.tag("v1")
+print(main.peek("score", tag="v1"))  # 0
 ```
 
 ## Chunked codecs (numpy / pandas)

{kvgit-0.3.4 → kvgit-0.3.5}/kvgit/__init__.py

@@ -4,9 +4,9 @@ from .content_types import MergeFn, counter, last_writer_wins
 from .errors import ConcurrencyError, MergeConflict
 from .namespaced import Namespaced
 from .staged import Staged
-from .store import delete_branches, store
+from .store import delete_branches, delete_tags, store
 from .versioned.kv import VersionedKV
-from .versioned.protocol import MergeResult, Versioned
+from .versioned.protocol import MergeResult, TagInfo, Versioned
 
 __all__ = [
     "ConcurrencyError",
@@ -15,10 +15,12 @@ __all__ = [
     "MergeResult",
     "Namespaced",
     "Staged",
+    "TagInfo",
     "Versioned",
     "VersionedKV",
     "counter",
     "delete_branches",
+    "delete_tags",
     "last_writer_wins",
     "store",
 ]

{kvgit-0.3.4 → kvgit-0.3.5}/kvgit/staged.py

@@ -8,7 +8,7 @@ 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, Versioned
+from .versioned.protocol import BytesMergeFn, MergeResult, TagInfo, Versioned
 
 
 class _ChunkSink:
@@ -407,10 +407,22 @@ class Staged(MutableMapping[str, Any]):
         )
 
     def checkout(
-        self, commit_hash: str, *, branch: str | None = None
+        self,
+        commit_hash: str | None = None,
+        *,
+        branch: str | None = None,
+        tag: str | None = None,
     ) -> "Staged | None":
-        """Create a new Staged at a specific commit. Returns None if not found."""
-        v = self._versioned.checkout(commit_hash, branch=branch)
+        """Create a new Staged at a specific commit or tag.
+
+        Pass exactly one of ``commit_hash`` or ``tag``. Returns None if
+        the commit or tag is not in the store.
+
+        The handle is a normal writable one on the caller's branch: a
+        commit from it advances that branch when it has not moved, and
+        conflicts when it has.
+        """
+        v = self._versioned.checkout(commit_hash, branch=branch, tag=tag)
         if v is None:
             return None
         return Staged(v, encoder=self._encoder, decoder=self._decoder)
@@ -430,13 +442,46 @@ class Staged(MutableMapping[str, Any]):
         self._removals.clear()
         self._cache.clear()
 
-    def peek(self, key: str, *, branch: str) -> Any:
-        """Read a key from another branch without switching. Returns None if not found."""
-        raw = self._versioned.peek(key, branch=branch)
+    def peek(
+        self, key: str, *, branch: str | None = None, tag: str | None = None
+    ) -> Any:
+        """Read a key from another branch, or from a tag, without switching.
+
+        Pass exactly one of ``branch`` or ``tag``. Returns None if not
+        found.
+        """
+        raw = self._versioned.peek(key, branch=branch, tag=tag)
         if raw is None:
             return None
         return self._decode(raw)
 
+    # -- Tags --
+
+    def tag(self, name: str, *, at: str | None = None, info: dict | None = None) -> str:
+        """Name a commit permanently. Returns the commit hash tagged.
+
+        Tags the **current commit** — the last committed state — not the
+        staging buffer. Staged changes are not part of any commit yet,
+        so there is nothing there to name; commit first if you meant to
+        tag them.
+
+        Immutable: an existing name raises rather than moving. Tags keep
+        their commit's ancestry alive through garbage collection.
+        """
+        return self._versioned.tag(name, at=at, info=info)
+
+    def tags(self) -> dict[str, str]:
+        """Map every tag in the store to the commit it names."""
+        return self._versioned.tags()
+
+    def tag_info(self, name: str) -> TagInfo | None:
+        """Describe one tag, or None if the store has no such tag."""
+        return self._versioned.tag_info(name)
+
+    def delete_tag(self, name: str) -> None:
+        """Delete a tag, then sweep commits nothing else reaches."""
+        self._versioned.delete_tag(name)
+
     def reset_to(self, commit_hash: str) -> bool:
         """Reset HEAD to a specific commit and clear staged changes.
 

{kvgit-0.3.4 → kvgit-0.3.5}/kvgit/store.py

@@ -10,8 +10,11 @@ from .staged import Staged
 from .versioned.kv import (
     BRANCH_HEAD,
     BRANCH_HEAD_PREV,
+    TAG_BRANCH_PREFIX,
+    TAG_INFO_KEY,
     CorruptHeadRecoverer,
     VersionedKV,
+    _assert_supported_version,
     clean_orphans,
 )
 
@@ -137,7 +140,10 @@ def delete_branches(
     just mints a fresh empty ``main`` on next open.
 
     One :func:`clean_orphans` sweep runs after all removals, so commits
-    that only the deleted branches referenced are reclaimed. All heads
+    that only the deleted branches referenced are reclaimed. A tag is a
+    head under the reserved ``refs/tags/`` name, so a tagged commit
+    survives the deletion of every ordinary branch that reached it —
+    the sweep marks from it like any other head. All heads
     (and prev-heads) are gone before the sweep, so it can't mistake a
     doomed branch for a live one. ``min_age`` defaults to
     ``clean_orphans``'s one-hour guard (matching ``delete_branch``), so
@@ -169,6 +175,12 @@ def delete_branches(
         return  # nothing asked: skip the backend open and the sweep
     backend = _make_backend(kind, path=path, db_name=db_name)
     try:
+        # No ``VersionedKV`` is constructed here, so nothing else on this
+        # path checks the store's layout version. Checked before the
+        # first removal rather than leaving it to the sweep: a store this
+        # code cannot read must come out of the call untouched, not with
+        # its branch keys already gone.
+        _assert_supported_version(backend)
         for name in doomed:
             backend.remove(BRANCH_HEAD % name)
             backend.remove(BRANCH_HEAD_PREV % name)
@@ -177,3 +189,59 @@ def delete_branches(
         close = getattr(backend, "close", None)
         if callable(close):
             close()
+
+
+def delete_tags(
+    names: str | Iterable[str],
+    *,
+    kind: Literal["memory", "disk", "indexeddb"] = "disk",
+    path: str | None = None,
+    db_name: str = "kvgit",
+    min_age: float = 3600,
+) -> None:
+    """Delete tags with no branch anchor, then sweep orphans.
+
+    The tag counterpart of :func:`delete_branches`, and anchor-free for
+    the same reason: teardown should not need a handle, and a handle
+    always has a current branch to open on. A tag is stored as a branch
+    head under the reserved name ``refs/tags/<name>``, so for each name
+    that head, its ``__branch_head_prev__`` backup and its
+    ``__tag_info__<name>`` record are removed, then a single
+    :func:`clean_orphans` sweep reclaims commits that only the deleted
+    tags kept alive. The backup is defensive: this code never writes one
+    for a tag, but something that treated the tag as an ordinary branch
+    could have, and a backup outliving its head would let a later tag of
+    the same name resolve to the deleted commit. A name with no tag is
+    skipped — idempotency beats a ``ValueError`` in teardown.
+
+    That sweep does not reclaim chunks; follow up with ``deep_clean`` on
+    a quiescent store if the store uses chunked codecs.
+
+    Args:
+        names: Tag names to delete — one name or an iterable of them.
+            Missing names are no-ops. (A bare string is treated as ONE
+            name, not iterated per character.)
+        kind: ``"disk"`` (default), ``"memory"``, or ``"indexeddb"``.
+        path: Required when ``kind="disk"``. Store directory.
+        db_name: IndexedDB database name (``kind="indexeddb"`` only).
+        min_age: Passed to :func:`clean_orphans` — commits younger than
+            this many seconds survive the sweep.
+    """
+    doomed = {names} if isinstance(names, str) else set(names)
+    if not doomed:
+        return  # nothing asked: skip the backend open and the sweep
+    backend = _make_backend(kind, path=path, db_name=db_name)
+    try:
+        # Same reasoning as delete_branches: no handle is constructed on
+        # this path, so the layout check has to happen here, before
+        # anything is removed.
+        _assert_supported_version(backend)
+        for name in doomed:
+            backend.remove(BRANCH_HEAD % (TAG_BRANCH_PREFIX + name))
+            backend.remove(BRANCH_HEAD_PREV % (TAG_BRANCH_PREFIX + name))
+            backend.remove(TAG_INFO_KEY % name)
+        clean_orphans(backend, min_age=min_age)
+    finally:
+        close = getattr(backend, "close", None)
+        if callable(close):
+            close()

{kvgit-0.3.4 → kvgit-0.3.5}/kvgit/versioned/__init__.py

@@ -1,12 +1,13 @@
 """Versioned store implementations."""
 
 from .kv import VersionedKV
-from .protocol import BytesMergeFn, DiffResult, MergeResult, Versioned
+from .protocol import BytesMergeFn, DiffResult, MergeResult, TagInfo, Versioned
 
 __all__ = [
     "BytesMergeFn",
     "DiffResult",
     "MergeResult",
+    "TagInfo",
     "Versioned",
     "VersionedKV",
 ]

{kvgit-0.3.4 → kvgit-0.3.5}/kvgit/versioned/kv.py

@@ -4,15 +4,23 @@ Storage layout (v3):
 
 - ``__kvgit_version__``                — storage version sentinel
 - ``__branch_head__<branch>``          — current HEAD commit hash
+- ``__branch_head__refs/tags/<tag>``   — commit a tag names
 - ``__branch_head_prev__<branch>``     — previous HEAD (recovery backup)
 - ``__commit_root__<commit>``          — keyset HAMT root hash
 - ``__parent_commit__<commit>``        — list of parent commit hashes
 - ``__commit_time__<commit>``          — wall time the commit was created
 - ``__info__<commit>``                 — optional caller-supplied info dict
+- ``__tag_info__<tag>``                — tag creation time + info
 - ``kvgit:keyset:<node_hash>``         — HAMT node bytes
 - ``kvgit:chunk:<chunk_hash>``         — content-addressed chunk bytes (v3)
 - ``<commit_hash>:<user_key>``         — blob value bytes
 
+A tag is deliberately not a key kind of its own. It is a branch head
+under a reserved name, hidden from the branch API, so that reachability
+— which every kvgit version decides by walking branch heads — keeps a
+tagged commit alive with no knowledge of tags at all. The record beside
+it holds only creation time and caller info, which nothing collects.
+
 ``__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
@@ -63,6 +71,7 @@ from .base import VersionedBase
 from .helpers import walk_history
 from .keyset import Keyset, KeysetEntry, MetaEntry
 from .merge import MergeResolution
+from .protocol import TagInfo
 
 PARENT_COMMIT = "__parent_commit__%s"
 COMMIT_ROOT = "__commit_root__%s"
@@ -70,11 +79,41 @@ COMMIT_TIME = "__commit_time__%s"
 BRANCH_HEAD = "__branch_head__%s"
 BRANCH_HEAD_PREV = "__branch_head_prev__%s"
 INFO_KEY = "__info__%s"
+TAG_INFO_KEY = "__tag_info__%s"
+
+TAG_BRANCH_PREFIX = "refs/tags/"
+"""Reserved branch-name prefix a tag's commit pointer lives under.
+
+A tag is stored as ``__branch_head__refs/tags/<name>`` — a branch head
+in every respect except that this code hides it from the branch API.
+That is what keeps a tagged commit alive across kvgit versions: reachability
+is decided by walking branch heads, so *any* version, including ones
+written before tags existed, marks a tag's commit as a root without
+being taught anything. A separate key kind would have been invisible to
+them, and no version stamp can retrofit the rule into code that already
+shipped.
+"""
 
 CHUNK_PREFIX = "kvgit:chunk:"
 
 STORAGE_VERSION_KEY = "__kvgit_version__"
 STORAGE_VERSION = 3
+"""Highest layout this code knows how to write.
+
+Tags did not raise it. They are branch heads under a reserved name, so
+every kvgit that walks branch heads already treats them correctly; a
+version bump would have locked those readers out of a store they can
+serve perfectly well, and would have protected nothing that the naming
+does not.
+"""
+
+CHUNK_STORAGE_VERSION = 3
+"""Lowest layout that can read a store containing chunks.
+
+Named separately from :data:`STORAGE_VERSION` because it is a rule about
+chunks, not about whatever the newest layout happens to be.
+"""
+
 # Lower versions accepted as input. v3 code reads v2 stores transparently
 # and only stamps the store as v3 once a chunked write actually happens.
 SUPPORTED_READ_VERSIONS = frozenset({2, 3})
@@ -108,6 +147,56 @@ def content_hash(
 logger = logging.getLogger("kvgit")
 
 
+def _assert_supported_version(store: KVStore) -> None:
+    """Raise if the store's version stamp is one this code cannot read.
+
+    Read-only, and silent on an unstamped store — it answers "may this
+    code touch what is here", not "is this store initialized". Every
+    entry point that mutates a store it did not open through
+    ``VersionedKV`` calls it first, the sweep above all: a store stamped
+    higher than this code understands may hold roots this code cannot
+    see, and sweeping it would delete live data.
+    """
+    raw = store.get(STORAGE_VERSION_KEY)
+    if raw is None:
+        return
+    version = safe_loads(raw)
+    if version not in SUPPORTED_READ_VERSIONS:
+        raise ValueError(
+            f"Store has kvgit storage version {version!r}, "
+            f"this code supports {sorted(SUPPORTED_READ_VERSIONS)}. "
+            "Use a fresh store."
+        )
+
+
+def _stamp_version_at_least(store: KVStore, version: int) -> None:
+    """Raise the store's version stamp to ``version`` if it is lower.
+
+    Called from any path that writes an artifact older layouts cannot
+    handle — currently a chunk, which needs v3.
+
+    The write is a CAS against the exact bytes the decision was made
+    from, not a plain ``set``: read-then-set lets two writers stamping
+    different versions interleave so that the *lower* one lands last,
+    leaving a store whose stamp under-describes what is in it, which is
+    precisely the state older readers are willing to open. A lost CAS
+    means someone else moved the stamp, so the loop re-reads and decides
+    again. It terminates because a stamp is only ever raised: every
+    iteration either returns or observes a strictly higher value.
+    """
+    while True:
+        raw = store.get(STORAGE_VERSION_KEY)
+        current = safe_loads(raw) if raw is not None else None
+        if (
+            isinstance(current, int)
+            and not isinstance(current, bool)
+            and current >= version
+        ):
+            return
+        if store.cas(STORAGE_VERSION_KEY, dumps(version), expected=raw):
+            return
+
+
 def _check_storage_version(store: KVStore) -> None:
     """Verify the store's kvgit version is compatible.
 
@@ -115,18 +204,12 @@ def _check_storage_version(store: KVStore) -> None:
     :data:`SUPPORTED_READ_VERSIONS`; the on-disk stamp is left
     untouched on open so that opening a v2 store with v3 code does not
     silently upgrade it to v3 (which would lock out older readers).
-    The upgrade happens lazily inside ``_create_commit`` the first
-    time a chunked write occurs.
+    The upgrade happens lazily, the first time a chunked write or a tag
+    write actually occurs.
     """
     raw = store.get(STORAGE_VERSION_KEY)
     if raw is not None:
-        version = safe_loads(raw)
-        if version not in SUPPORTED_READ_VERSIONS:
-            raise ValueError(
-                f"Store has kvgit storage version {version!r}, "
-                f"this code supports {sorted(SUPPORTED_READ_VERSIONS)}. "
-                "Use a fresh store."
-            )
+        _assert_supported_version(store)
         return
 
     # No version sentinel. Either fresh, or pre-v2.
@@ -465,12 +548,120 @@ def repair_head(
     )
 
 
+def _validate_tag_name(name: str) -> None:
+    """Reject tag names that cannot be stored, or cannot be read back.
+
+    Branch names are unvalidated, so this is deliberately close to
+    unvalidated too: any non-empty string, ``/`` included, so embedders
+    can namespace their own tags (``pub/v1``). ``%`` is the one
+    exclusion — tag keys are built with ``%``-formatting, and a name
+    carrying its own format specifier turns the key template into
+    something other than a template.
+    """
+    if not isinstance(name, str) or not name:
+        raise ValueError("Tag name must be a non-empty string")
+    if "%" in name:
+        raise ValueError(f"Tag name must not contain '%': {name!r}")
+
+
+def _tag_branch(name: str) -> str:
+    """The reserved branch name a tag's commit pointer lives under."""
+    return TAG_BRANCH_PREFIX + name
+
+
+def _reject_reserved_branch(name: str) -> None:
+    """Refuse a branch name inside the reserved tag namespace.
+
+    The branch API does not hand out names under ``refs/tags/``, because
+    a branch there would be indistinguishable from a tag: it would show
+    up in ``tags()``, and moving it would silently move the tag. Tags
+    are created, listed and deleted through the tag API instead.
+    """
+    if isinstance(name, str) and name.startswith(TAG_BRANCH_PREFIX):
+        raise ValueError(
+            f"Branch name {name!r} is reserved for tags "
+            f"(the '{TAG_BRANCH_PREFIX}' namespace). "
+            "Use tag() / tags() / delete_tag() instead."
+        )
+
+
+def _resolve_tag(store: KVStore, name: str) -> str | None:
+    """Read the commit a tag names, or None if it does not resolve.
+
+    Reads the tag's head key and nothing else. The prev-HEAD recovery
+    tiers a branch gets do not apply: a tag is written once and never
+    moved, so this code never creates a backup for one, and a backup
+    left by something that treated the tag as an ordinary branch
+    describes a move that is not ours to honour.
+    """
+    raw = store.get(BRANCH_HEAD % _tag_branch(name))
+    if raw is None:
+        return None
+    commit_hash = safe_loads(raw)
+    return commit_hash if isinstance(commit_hash, str) else None
+
+
+def tags(store: KVStore) -> dict[str, str]:
+    """Map every tag in the store to the commit it names.
+
+    Dangling tags — ones whose commit is no longer in the store — are
+    included, because leaving them out would make a damaged tag look
+    deleted. :func:`tag_info` says which is which.
+    """
+    prefix = BRANCH_HEAD % TAG_BRANCH_PREFIX
+    found: dict[str, str] = {}
+    for key in store.keys():
+        if not (isinstance(key, str) and key.startswith(prefix)):
+            continue
+        name = key[len(prefix) :]
+        if not name:
+            continue
+        raw = store.get(key)
+        if raw is None:
+            continue
+        commit_hash = safe_loads(raw)
+        if isinstance(commit_hash, str):
+            found[name] = commit_hash
+    return dict(sorted(found.items()))
+
+
+def tag_info(store: KVStore, name: str) -> TagInfo | None:
+    """Describe one tag, or None if the store has no such tag."""
+    commit_hash = _resolve_tag(store, name)
+    if commit_hash is None:
+        return None
+
+    created: float | None = None
+    info: dict | None = None
+    record_bytes = store.get(TAG_INFO_KEY % name)
+    if record_bytes is not None:
+        record = safe_loads(record_bytes)
+        if isinstance(record, dict):
+            ts = record.get("time")
+            if isinstance(ts, (int, float)) and not isinstance(ts, bool):
+                created = float(ts)
+            stored_info = record.get("info")
+            if isinstance(stored_info, dict):
+                info = stored_info
+
+    return TagInfo(
+        name=name,
+        commit=commit_hash,
+        time=created,
+        info=info,
+        dangling=store.get(COMMIT_ROOT % commit_hash) is None,
+    )
+
+
 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
     the commit metadata, blobs and HAMT nodes owned by the orphaned
-    commits and not shared with anything still reachable.
+    commits and not shared with anything still reachable. Tags need no
+    special handling: a tag is a branch head under a reserved name, so
+    it keeps its commit's whole ancestry alive by being walked with
+    everything else.
 
     Handle-independent by design: it marks from ALL live branch HEADs
     and touches nothing but ``store``, so it works with or without a
@@ -536,6 +727,13 @@ def deep_clean(store: KVStore, min_age: float = 3600) -> int:
 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")
+    # Reachability is decided from the roots this code knows about, so
+    # a store stamped above what this code reads must not be swept: its
+    # roots may be a kind that did not exist here, and everything hanging
+    # off them would look like garbage. The check belongs on this side of
+    # the call rather than only in the handle constructors, because the
+    # admin entry points sweep a raw store with no handle at all.
+    _assert_supported_version(store)
     cutoff_time = time.time() - min_age
 
     def _parent_loader(commit_hash: str) -> tuple[str, ...]:
@@ -578,6 +776,11 @@ def _sweep(store: KVStore, min_age: float, *, deep: bool) -> int:
                 reachable_chunks.update(entry.meta.chunks)
         reachable_nodes.update(new_nodes)
 
+    # Every root is a branch head, tags included: a tag is a head under
+    # the reserved ``refs/tags/`` name, so it is marked here without the
+    # sweep knowing tags exist. That is the whole compatibility
+    # property — a kvgit that predates tags runs this same loop and
+    # keeps tagged commits alive for the same reason.
     branch_prefix = BRANCH_HEAD.replace("%s", "")
     for key in store.keys():
         if not (isinstance(key, str) and key.startswith(branch_prefix)):
@@ -753,6 +956,7 @@ class VersionedKV(VersionedBase):
         if store is None:
             store = Memory()
         self.store = store
+        _reject_reserved_branch(branch)
         # Applies to every resolve this handle makes — opening, reading
         # HEAD, refreshing, switching, peeking, repairing — and is
         # inherited by the handles ``checkout`` and ``create_branch``
@@ -921,7 +1125,7 @@ class VersionedKV(VersionedBase):
         # save a roundtrip on idempotent rewrites; the dedup property
         # holds either way because the key is the hash.
         if chunks:
-            self._stamp_v3_if_needed()
+            _stamp_version_at_least(self.store, CHUNK_STORAGE_VERSION)
             for chunk_hash, chunk_bytes in chunks.items():
                 diffs[CHUNK_PREFIX + chunk_hash] = chunk_bytes
 
@@ -954,19 +1158,6 @@ class VersionedKV(VersionedBase):
 
         return new_hash
 
-    def _stamp_v3_if_needed(self) -> None:
-        """Lazily upgrade an opened v2 store to v3.
-
-        Called from any code path that writes a v3-only artifact (a
-        chunk under ``kvgit:chunk:*``). v3 stamps are sticky: once
-        upgraded, the store can no longer be opened by code that
-        only knows v2.
-        """
-        raw = self.store.get(STORAGE_VERSION_KEY)
-        current = safe_loads(raw) if raw is not None else None
-        if current != STORAGE_VERSION:
-            self.store.set(STORAGE_VERSION_KEY, dumps(STORAGE_VERSION))
-
     def _create_merge_commit(
         self,
         resolution: MergeResolution,
@@ -1170,10 +1361,32 @@ class VersionedKV(VersionedBase):
         self._load_commit(commit_hash, update_base=True)
 
     def checkout(
-        self, commit_hash: str, *, branch: str | None = None
+        self,
+        commit_hash: str | None = None,
+        *,
+        branch: str | None = None,
+        tag: str | None = None,
     ) -> "VersionedKV | None":
-        """Return a new VersionedKV at a specific commit."""
-        if self.store.get(COMMIT_ROOT % commit_hash) is None:
+        """Return a new VersionedKV at a specific commit or tag.
+
+        Name the commit positionally or name a ``tag``, not both.
+
+        The handle comes back on this handle's branch (or ``branch``),
+        not on a branch of its own — there is no read-only mode. A
+        commit made from it goes through the ordinary HEAD CAS, so it
+        fast-forwards when the branch has not moved since, and conflicts
+        exactly as any other stale handle does when it has.
+
+        Returns None when the commit, or the tag, is not in the store.
+        """
+        if (commit_hash is None) == (tag is None):
+            raise ValueError("Pass exactly one of commit_hash or tag")
+        if tag is not None:
+            tagged = _resolve_tag(self.store, tag)
+            if tagged is None or self.store.get(COMMIT_ROOT % tagged) is None:
+                return None
+            commit_hash = tagged
+        elif self.store.get(COMMIT_ROOT % commit_hash) is None:
             return None
         return VersionedKV(
             self.store,
@@ -1187,6 +1400,7 @@ class VersionedKV(VersionedBase):
 
         Returns a new VersionedKV instance on the new branch.
         """
+        _reject_reserved_branch(name)
         branch_key = BRANCH_HEAD % name
         target = at or self._current_commit
         if at is not None and self.store.get(COMMIT_ROOT % at) is None:
@@ -1212,6 +1426,7 @@ class VersionedKV(VersionedBase):
 
     def delete_branch(self, name: str) -> None:
         """Delete a branch and clean up orphaned commits."""
+        _reject_reserved_branch(name)
         if name == self._branch:
             raise ValueError("Cannot delete the current branch")
         branch_key = BRANCH_HEAD % name
@@ -1227,6 +1442,7 @@ class VersionedKV(VersionedBase):
 
     def switch_branch(self, name: str) -> None:
         """Switch this instance to a different branch in-place."""
+        _reject_reserved_branch(name)
         commit_hash = _resolve_head(
             self.store,
             name,
@@ -1239,13 +1455,32 @@ class VersionedKV(VersionedBase):
         self._branch = name
         self._load_commit(commit_hash, update_base=True)
 
-    def peek(self, key: str, *, branch: str) -> bytes | None:
-        """Read a key from another branch's HEAD without switching."""
-        commit_hash = _resolve_head(
-            self.store,
-            branch,
-            recover_from_corrupt_head=self._recover_from_corrupt_head,
-        )
+    def peek(
+        self, key: str, *, branch: str | None = None, tag: str | None = None
+    ) -> bytes | None:
+        """Read a key from another branch's HEAD, or from a tag.
+
+        Pass exactly one of ``branch`` or ``tag``. Returns None when the
+        key, the branch, or the tag is not there.
+        """
+        if (branch is None) == (tag is None):
+            raise ValueError("Pass exactly one of branch or tag")
+        commit_hash: str | None
+        if branch is not None:
+            _reject_reserved_branch(branch)
+            commit_hash = _resolve_head(
+                self.store,
+                branch,
+                recover_from_corrupt_head=self._recover_from_corrupt_head,
+            )
+        else:
+            tagged = _resolve_tag(self.store, tag or "")
+            commit_hash = (
+                tagged
+                if tagged is not None
+                and self.store.get(COMMIT_ROOT % tagged) is not None
+                else None
+            )
         if commit_hash is None:
             return None
         root = _load_root(self.store, commit_hash)
@@ -1273,13 +1508,20 @@ class VersionedKV(VersionedBase):
 
     @staticmethod
     def branches(store: KVStore) -> list[str]:
-        """List all branch names in the store."""
+        """List all branch names in the store.
+
+        Tags live under the reserved ``refs/tags/`` branch name and are
+        excluded here: callers of this list treat what it returns as
+        branches — switching to them, deleting them, showing them to a
+        user — and a tag is none of those things. :meth:`tags` lists
+        those.
+        """
         prefix = BRANCH_HEAD.replace("%s", "")
         result = []
         for key in store.keys():
             if isinstance(key, str) and key.startswith(prefix):
                 branch_name = key[len(prefix) :]
-                if branch_name:
+                if branch_name and not branch_name.startswith(TAG_BRANCH_PREFIX):
                     result.append(branch_name)
         return sorted(result)
 
@@ -1287,6 +1529,113 @@ class VersionedKV(VersionedBase):
         """List all branch names in the store."""
         return VersionedKV.branches(self.store)
 
+    # -- Tags --
+
+    def tag(self, name: str, *, at: str | None = None, info: dict | None = None) -> str:
+        """Name a commit permanently, and keep it (and its ancestry) alive.
+
+        A tag is immutable: creating one over an existing name raises,
+        and there is no move. Point a name somewhere else by deleting
+        the tag and creating it again, so that the history of the name
+        is at least visible in the calling code. Tags and branches are
+        separate namespaces — ``v1`` can be both, and they are unrelated.
+
+        The tagged commit and everything it descends from survive
+        garbage collection for as long as the tag exists, exactly as a
+        branch head's ancestry does — because a tag *is* a branch head,
+        stored under the reserved name ``refs/tags/<name>`` and hidden
+        from the branch API.
+
+        That storage choice is the compatibility contract, and it is
+        worth stating plainly. Any kvgit that walks branch heads reads a
+        tag's commit and keeps it alive, including versions written
+        before tags existed and including their anchor-free admin sweep;
+        no version stamp could have taught them a new key kind. What
+        such a version does see is a branch named ``refs/tags/<name>``.
+        It can delete that branch by name, or switch to it and commit,
+        which deletes or moves the tag — both deliberate acts naming a
+        path that says what it is.
+
+        Args:
+            at: Commit to tag. Defaults to this handle's current commit,
+                which for a ``Staged`` wrapper means the last *committed*
+                state — staged changes are not part of any commit yet and
+                are not tagged.
+            info: Optional caller metadata, stored beside the tag. Must
+                be JSON-serializable, like commit info.
+
+        Returns:
+            The commit hash the tag names.
+
+        Raises:
+            ValueError: if the name is unusable, already taken, or the
+                commit does not exist.
+
+        There is one race, and it is narrow: tagging a commit that is
+        *already* an orphan older than ``min_age`` can lose to a sweep
+        running concurrently, which was free to collect that commit
+        before the tag existed. Callers tag a commit they are holding —
+        a head, or something a head descends from — and a commit a
+        branch reaches is never a sweep candidate.
+        """
+        _validate_tag_name(name)
+        target = at or self._current_commit
+        if self.store.get(COMMIT_ROOT % target) is None:
+            raise ValueError(f"Commit '{target}' does not exist")
+        # Encoded before anything is written, so info that cannot be
+        # serialized raises without leaving a tag behind.
+        record = dumps({"time": time.time(), "info": info})
+
+        # CAS against absence: two writers racing the same name cannot
+        # both win, and an existing tag is never silently overwritten.
+        head_key = BRANCH_HEAD % _tag_branch(name)
+        if not self.store.cas(head_key, dumps(target), expected=None):
+            raise ValueError(f"Tag '{name}' already exists")
+        # A name that has just been claimed has no previous HEAD, so any
+        # backup under it is stale by definition — left by an earlier tag
+        # of the same name, or by something that moved this name as an
+        # ordinary branch. Dropped after the CAS, so a losing attempt
+        # cannot take out the winner's state.
+        self.store.remove(BRANCH_HEAD_PREV % _tag_branch(name))
+        # The record is a second write, so a crash in between leaves a
+        # tag with no time and no info. That is why the head key alone is
+        # what GC and resolution read.
+        self.store.set(TAG_INFO_KEY % name, record)
+        return target
+
+    def tags(self) -> dict[str, str]:
+        """Map every tag in the store to the commit it names."""
+        return tags(self.store)
+
+    def tag_info(self, name: str) -> TagInfo | None:
+        """Describe one tag, or None if the store has no such tag."""
+        return tag_info(self.store, name)
+
+    def delete_tag(self, name: str) -> None:
+        """Remove a tag, then sweep the commits nothing else reaches.
+
+        Three keys go — the tag's reserved head, that head's prev-HEAD
+        backup, and the info record — and then :meth:`clean_orphans`
+        runs, matching :meth:`delete_branch`. A commit the tag was the
+        last root for becomes collectable at that point, subject to the
+        sweep's ``min_age`` guard.
+
+        This code never writes a backup for a tag, since it never moves
+        one. The removal is for a backup written by something that
+        treated the tag as an ordinary branch — switching to it and
+        committing — where leaving it behind would let head resolution
+        serve the deleted tag's commit under a later branch of the same
+        reserved name.
+        """
+        _validate_tag_name(name)
+        head_key = BRANCH_HEAD % _tag_branch(name)
+        if self.store.get(head_key) is None:
+            raise ValueError(f"Tag '{name}' does not exist")
+        self.store.remove(head_key)
+        self.store.remove(BRANCH_HEAD_PREV % _tag_branch(name))
+        self.store.remove(TAG_INFO_KEY % name)
+        self.clean_orphans()
+
     def commit_info(self, commit_hash: str | None = None) -> dict | None:
         """Retrieve the info dict for a commit, or None if none was stored."""
         target = commit_hash or self._current_commit

{kvgit-0.3.4 → kvgit-0.3.5}/kvgit/versioned/protocol.py

@@ -20,6 +20,27 @@ class DiffResult:
     modified: frozenset[str]
 
 
+@dataclass(frozen=True)
+class TagInfo:
+    """What a store records about one tag.
+
+    ``time`` and ``info`` come from a record written just after the tag
+    itself, so both are ``None`` for a tag whose record is missing —
+    a crash between the two writes, or a store written by hand.
+
+    ``dangling`` means the tagged commit is not in the store. A tag
+    cannot be created for a commit that does not exist, so this is
+    damage rather than an ordinary state, and a dangling tag keeps
+    nothing alive: garbage collection marks nothing from it.
+    """
+
+    name: str
+    commit: str
+    time: float | None
+    info: dict | None
+    dangling: bool
+
+
 @dataclass(frozen=True)
 class MergeResult:
     """Result of a merge operation."""
@@ -92,7 +113,11 @@ class Versioned(Protocol):
     def refresh(self) -> None: ...
 
     def checkout(
-        self, commit_hash: str, *, branch: str | None = None
+        self,
+        commit_hash: str | None = None,
+        *,
+        branch: str | None = None,
+        tag: str | None = None,
     ) -> "Versioned | None": ...
 
     def create_branch(self, name: str, *, at: str | None = None) -> "Versioned": ...
@@ -101,7 +126,21 @@ class Versioned(Protocol):
 
     def switch_branch(self, name: str) -> None: ...
 
-    def peek(self, key: str, *, branch: str) -> bytes | None: ...
+    def peek(
+        self, key: str, *, branch: str | None = None, tag: str | None = None
+    ) -> bytes | None: ...
+
+    # -- Tags --
+
+    def tag(
+        self, name: str, *, at: str | None = None, info: dict | None = None
+    ) -> str: ...
+
+    def tags(self) -> dict[str, str]: ...
+
+    def tag_info(self, name: str) -> TagInfo | None: ...
+
+    def delete_tag(self, name: str) -> None: ...
 
     def reset_to(self, commit_hash: str) -> bool: ...
 

{kvgit-0.3.4 → kvgit-0.3.5}/kvgit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.4
+Version: 0.3.5
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT
@@ -56,6 +56,7 @@ Git-style versioning for your data. Commits, branches, and merges -- backed by a
 | **Dict interface** | `MutableMapping[str, Any]` -- reads and writes work like a dict |
 | **Commits** | Immutable, content-addressable snapshots with rollback |
 | **Branches** | Cheap forks with CAS-based optimistic concurrency |
+| **Tags** | Immutable names for commits; a tagged commit outlives every branch that reached it, in every kvgit version |
 | **Three-way merge** | Auto-merges non-overlapping changes; pluggable merge fns for conflicts |
 | **Pluggable backends** | In-memory, disk (diskcache), IndexedDB (Pyodide/browser), or bring your own `KVStore` |
 | **Chunked codecs** | Optional content-addressed dedup for large numpy arrays and pandas DataFrames -- equal buffers stored once across keys, commits, and branches |
@@ -87,6 +88,10 @@ dev.commit()
 
 print(main["score"])  # 0   (main unchanged)
 print(dev["score"])   # 999 (dev branch)
+
+# Tag a commit by name -- immutable, and safe from garbage collection
+main.tag("v1")
+print(main.peek("score", tag="v1"))  # 0
 ```
 
 ## Chunked codecs (numpy / pandas)

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

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