release: 1.0.0

first stable release. pre-1.0.0 verification complete: all surviving MED regressions and
gaps resolved and independently re-fired, tree audited clean across the suite.

Signed-off-by: disqualifier <dev@disqualifier.me>

.gitignore

@@ -1,5 +1,5 @@
 # claude
-CLAUDE.md
+.claude/
 
 # python
 __pycache__/

README.md

@@ -12,17 +12,19 @@ you `delete` or `clear` them.
 `requirements.txt`:
 
 ```
-aiokv @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiokv.git@v0.1.0
+aiokv @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiokv.git@v1.0.0
 ```
 
 Direct:
 
 ```bash
-pip install "aiokv @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiokv.git@v0.1.0"
+pip install "aiokv @ git+ssh://git@git.rethinkstudios.io/rethink-public/aiokv.git@v1.0.0"
 ```
 
 Requires `aiofiles` (pulled transitively).
 
+Drop the `@v1.0.0` suffix from the line above to install the latest unpinned.
+
 ## Usage
 
 ```python
@@ -60,11 +62,21 @@ Prefer `AioKV` in new code.
 ## Durability
 
 Writes are **atomic**: data is written to a temp file in the same directory and
-`os.replace()`d over the target (atomic on POSIX). A crash mid-write leaves the
-previous good file intact, and a reader never observes a partial file. A single
-`asyncio.Lock` guards every read and write, so concurrent operations on one instance
-are consistent and no update is lost. All blocking filesystem calls run via
-`asyncio.to_thread`, so nothing stalls the event loop.
+`os.replace()`d over the target's realpath — symlink-safe, so a symlinked store file is
+written through rather than clobbered. A **process** crash mid-write leaves the previous
+good file intact, and a reader never observes a partial file. (This is process-crash
+safety, not power-loss durability — there's no `fsync`, so an OS/power failure could
+still lose the last write; fine for reconstructible single-process state.) `clear()` is
+symlink-safe the same way: it removes the realpath'd target, not the symlink itself, so
+a symlinked store is genuinely erased rather than just having its symlink unlinked.
+Orphaned `.<pid>.tmp` files left by a hard crash of a *different, dead* process are swept
+on the next save; the sweep matches only the exact `<realpath basename>.<pid>.tmp` shape
+it creates, so a differently-shaped neighbor file is never touched and a store filename
+containing glob-like characters (e.g. `state[prod].json`) doesn't miss its own orphans or
+cross-match another store's. A single `asyncio.Lock` guards every read and write, so
+concurrent operations on one instance are consistent and no update is lost. All blocking
+filesystem calls and JSON (de)serialization run via `asyncio.to_thread`, so nothing stalls
+the event loop.
 
 ## Scope — read this
 
@@ -77,10 +89,15 @@ are consistent and no update is lost. All blocking filesystem calls run via
 
 ## Error contract
 
-- `get` / `set` / `get_all` raise on unexpected I/O (and `_load` raises on a
-  truncated/corrupt file) so a real failure is visible rather than silently masked.
+- Keys must be `str` — `get` / `set` raise `ValueError` on a non-str key (JSON object
+  keys are always strings, so a non-str key would silently never round-trip).
+- `get` / `set` / `get_all` raise on unexpected I/O. `_load` raises `JSONDecodeError`
+  on a truncated/corrupt file, and `ValueError` when the file holds valid JSON that
+  isn't an object (a bare list/number/string/null) — so corruption or a wrong-shaped
+  file is visible rather than silently masked. Non-finite floats (`NaN`/`Infinity`)
+  raise `ValueError` on `set` rather than persisting invalid JSON.
 - `delete` / `clear` log the exception and return `False` on error, `True` otherwise.
 
 ## Versioning
 
-Tagged `vX.Y.Z`. Pin the tag in `requirements.txt`.
+Releases are tagged `vX.Y.Z`. The install line above pins a release; drop the `@vX.Y.Z` suffix to install the latest unpinned. Pin deliberately for reproducible installs.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "aiokv"
-version = "0.1.0"
+version = "1.0.0"
 description = "Async file-backed key-value store for single-process local state — atomic writes, no TTL, config-free, installable."
 requires-python = ">=3.10"
 dependencies = [

src/aiokv/__init__.py

@@ -1,3 +1,10 @@
+from importlib.metadata import version, PackageNotFoundError
+
 from .aiokv import AioKV, aiocache
 
+try:
+    __version__ = version("aiokv")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
 __all__ = ["AioKV", "aiocache"]

src/aiokv/aiokv.py

@@ -1,34 +1,23 @@
 """
 async file-backed key-value store for single-process local state
 
-a persist-forever KV store (last-used-command, rate-limit timestamps, seen-ids,
-simple bot state) backed by a JSON file. NOT a cache: no TTL, no expiry, no
-eviction — values live until you delete or clear them.
+a persist-forever KV store backed by a JSON file, not a cache (no TTL/expiry/eviction).
+see README for usage and the full API.
 
     from aiokv import AioKV
 
     kv = AioKV("state.json")
     await kv.set("last_seen", 12345)
-    await kv.set("ran_cleanup")              # value omitted -> stores int(time.time())
-    when = await kv.get("ran_cleanup")
-    await kv.delete("last_seen")
+    when = await kv.get("last_seen")
 
-durability: writes are atomic — data is written to a temp file in the same
-directory and os.replace()d over the target, so a crash mid-write never corrupts
-the store and readers never see a partial file. a single asyncio.Lock guards every
-read and write, so concurrent operations on one instance are consistent.
-
-scope: SINGLE-PROCESS, single-instance local state only. the lock is per-instance —
-two AioKV instances (or two processes) pointing at the same file are NOT safe and
-will clobber each other. for shared cross-process/cross-bot state, use a database
-(e.g. mongo), not this.
-
-config-free: the file path is passed at construction; nothing is read from a global
-config. errors in delete/clear are logged and swallowed (returning False); get/set
-raise on unexpected i/o so a real failure is visible.
+atomic writes are process-crash safe (temp file + os.replace) but NOT power-loss safe
+(no fsync). the lock is per-instance only - two AioKV instances or processes on the
+same file will clobber each other; this is single-process local state, not shared
+cross-process storage.
 """
 
 import os
+import re
 import json
 import time
 import asyncio
@@ -53,10 +42,8 @@ class AioKV:
         self.lock = asyncio.Lock()
 
     async def set(self, key: str, value: Any = None) -> None:
-        """set a value; if value is omitted or None, stores int(time.time())
-
-        the timestamp default exists for "mark that i saw/did X at time T" usage.
-        """
+        """set a value; if value is omitted or None, stores int(time.time())"""
+        self._check_key(key)
         async with self.lock:
             cache = await self._load()
             cache[key] = value if value is not None else int(time.time())
@@ -64,6 +51,7 @@ class AioKV:
 
     async def get(self, key: str, default: Any = None) -> Any:
         """return the value for key, or default if absent"""
+        self._check_key(key)
         async with self.lock:
             cache = await self._load()
             return cache.get(key, default)
@@ -71,6 +59,7 @@ class AioKV:
     async def delete(self, key: str) -> bool:
         """delete a key; returns True if removed or absent, False on error"""
         try:
+            self._check_key(key)
             async with self.lock:
                 cache = await self._load()
                 if key in cache:
@@ -82,11 +71,17 @@ class AioKV:
             return False
 
     async def clear(self) -> bool:
-        """remove the backing file entirely; returns True on success, False on error"""
+        """remove the backing file entirely; True on success or if already absent, False on error
+
+        symlink-safe: removes the realpath'd target rather than the symlink itself, mirroring
+        _save()'s symlink-safe writes - a symlinked store's real data file is what gets erased"""
         try:
             async with self.lock:
-                if await asyncio.to_thread(os.path.exists, self.file):
-                    await asyncio.to_thread(os.remove, self.file)
+                target = await asyncio.to_thread(os.path.realpath, self.file)
+                try:
+                    await asyncio.to_thread(os.remove, target)
+                except FileNotFoundError:
+                    pass
             return True
         except Exception:
             log.exception("aiokv.clear() failed")
@@ -97,40 +92,43 @@ class AioKV:
         async with self.lock:
             return await self._load()
 
-    async def _load(self) -> Dict[str, Any]:
-        """load the store from disk, returning {} if the file is absent or empty
+    @staticmethod
+    def _check_key(key: str) -> None:
+        """raise ValueError if key is not str"""
+        if not isinstance(key, str):
+            raise ValueError(f"aiokv keys must be str, got {type(key).__name__}")
 
-        a truncated/corrupt file raises JSONDecodeError, and a file holding valid
-        JSON that is not an object (e.g. a bare list, number, or null) raises
-        ValueError — both surfaced to the caller rather than silently masking a
-        real corruption or returning a non-dict that breaks every other method.
-        """
-        if not await asyncio.to_thread(os.path.exists, self.file):
+    async def _load(self) -> Dict[str, Any]:
+        """load the store, returning {} if absent or blank; raises JSONDecodeError on
+        corrupt content and ValueError on valid-but-non-object JSON rather than masking it"""
+        try:
+            async with aiofiles.open(self.file, mode="r", encoding="utf-8") as f:
+                data = await f.read()
+        except FileNotFoundError:
             return {}
-        async with aiofiles.open(self.file, mode="r") as f:
-            data = await f.read()
-        if not data:
+        if not data.strip():
             return {}
-        loaded = json.loads(data)
+        loaded = await asyncio.to_thread(json.loads, data)
         if not isinstance(loaded, dict):
             raise ValueError(f"store file {self.file} does not hold a JSON object")
         return loaded
 
     async def _save(self, cache: Dict[str, Any]) -> None:
-        """write the store atomically: temp file in the same dir, then os.replace
-
-        os.replace is atomic on POSIX, so a reader never sees a partial file and a
-        crash mid-write leaves the previous good file intact.
-        """
-        directory = os.path.dirname(self.file) or "."
+        """write atomically: temp file in the same dir, then os.replace over the realpath'd
+        target (symlink-safe). process-crash safe (a crash mid-write leaves the prior good
+        file intact), NOT power-loss safe - no fsync, so an OS/power failure can still lose
+        the last write (acceptable: reconstructible single-process state, not a db)"""
+        target = await asyncio.to_thread(os.path.realpath, self.file)
+        directory = os.path.dirname(target) or "."
         await asyncio.to_thread(os.makedirs, directory, exist_ok=True)
+        await self._sweep_stale_tmp(directory, os.path.basename(target))
 
-        payload = json.dumps(cache)
-        tmp = f"{self.file}.{os.getpid()}.tmp"
+        payload = await asyncio.to_thread(json.dumps, cache, allow_nan=False)
+        tmp = f"{target}.{os.getpid()}.tmp"
         try:
-            async with aiofiles.open(tmp, mode="w") as f:
+            async with aiofiles.open(tmp, mode="w", encoding="utf-8") as f:
                 await f.write(payload)
-            await asyncio.to_thread(os.replace, tmp, self.file)
+            await asyncio.to_thread(os.replace, tmp, target)
         except Exception:
             if await asyncio.to_thread(os.path.exists, tmp):
                 try:
@@ -139,7 +137,46 @@ class AioKV:
                     log.exception("aiokv: failed to clean up temp file %s", tmp)
             raise
 
+    async def _sweep_stale_tmp(self, directory: str, base: str) -> None:
+        """remove orphaned .<pid>.tmp files left by a hard crash of a different, dead process
 
-# back-compat: this lib was originally named aiocache; legacy call sites using
-# `aiocache(...)` keep working via this alias. prefer AioKV in new code.
+        matches only the exact shape _save() creates (<realpath basename>.<pid>.tmp), via a
+        re.escape'd regex over a directory listing rather than a raw glob - a glob pattern
+        both crosses unrelated dots (matching non-aiokv neighbors like foo.backup.999.tmp) and
+        mistreats glob metacharacters in the store's own filename (e.g. state[prod].json).
+        `base` is the realpath'd basename _save() already resolved - passed in rather than
+        re-resolved here so a save does one realpath call, not two."""
+        candidate = re.compile(rf"^{re.escape(base)}\.(\d+)\.tmp$")
+        names = await asyncio.to_thread(os.listdir, directory)
+        for name in names:
+            match = candidate.match(name)
+            if not match:
+                continue
+            pid = int(match.group(1))
+            if pid == os.getpid():
+                continue
+            if await asyncio.to_thread(self._pid_alive, pid):
+                continue
+            path = os.path.join(directory, name)
+            try:
+                await asyncio.to_thread(os.remove, path)
+            except FileNotFoundError:
+                pass
+            except Exception:
+                log.exception("aiokv: failed to sweep stale temp file %s", path)
+
+    @staticmethod
+    def _pid_alive(pid: int) -> bool:
+        """check whether pid refers to a live process, without permission to signal counting as alive"""
+        try:
+            os.kill(pid, 0)
+        except (ProcessLookupError, OverflowError):
+            # OverflowError: a pid too large for a C int can't name a live process
+            return False
+        except PermissionError:
+            return True
+        return True
+
+
+# back-compat: originally named aiocache; prefer AioKV in new code.
 aiocache = AioKV