scriptoria 0.6.4__tar.gz → 0.7.0__tar.gz

{scriptoria-0.6.4 → scriptoria-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scriptoria
-Version: 0.6.4
+Version: 0.7.0
 Summary: Deterministic scriptorium-keeper (the `scrip` CLI): staleness, provenance integrity, and fact queries for an agent-compiled knowledge base
 Project-URL: Homepage, https://github.com/coredipper/scriptorium
 Project-URL: Changelog, https://github.com/coredipper/scriptorium/blob/main/CHANGELOG.md

{scriptoria-0.6.4 → scriptoria-0.7.0}/pyproject.toml

@@ -2,7 +2,7 @@
 # Distribution name on PyPI is `scriptoria` (scrip/scriptorium were taken); the
 # CLI command and the import package both remain `scrip`.
 name = "scriptoria"
-version = "0.6.4"
+version = "0.7.0"
 description = "Deterministic scriptorium-keeper (the `scrip` CLI): staleness, provenance integrity, and fact queries for an agent-compiled knowledge base"
 readme = "README.md"
 requires-python = ">=3.10"

{scriptoria-0.6.4 → scriptoria-0.7.0}/src/scrip/__init__.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 from pathlib import Path
 
-__version__ = "0.6.4"
+__version__ = "0.7.0"
 
 # --- canonical vault layout ------------------------------------------------
 # ``root`` is the repo/instance root: the directory containing ``vault/``.

{scriptoria-0.6.4 → scriptoria-0.7.0}/src/scrip/lock.py

@@ -8,14 +8,18 @@ writers don't interleave stamps and edits. Reads (``status``, ``verify``,
 
 The lock is a small JSON file created atomically with ``O_CREAT|O_EXCL`` holding
 ``{pid, host, acquired_at}``. A lock whose holder is a dead process *on this
-host* is **stale** and is reclaimed automatically on acquire; a lock that looks
-live fails fast (exit 2) and points the user at ``scrip unlock``. A lock from
-another host is treated as live (we can't prove the process dead).
+host* is **stale** and is reclaimed automatically on acquire. A lock that looks
+live is **waited on**: ``acquire`` polls (with backoff) up to a timeout —
+``SCRIP_LOCK_TIMEOUT`` seconds, default 10 — so two agents serialize cooperatively
+rather than one failing immediately. If the lock is still held when the wait
+elapses it fails (exit 2) and points the user at ``scrip unlock``; ``timeout=0``
+keeps the old fail-fast behavior. A lock from another host is treated as live (we
+can't prove the process dead), so it is waited on but never reclaimed.
 
 It is advisory, not a kernel mutex: a tiny TOCTOU window remains when reclaiming
-a stale lock. That is acceptable for the single-machine, single-agent workflow
-this guards; it is a guardrail against accidental concurrent writes, not a
-distributed lock manager.
+a stale lock, and waiting is best-effort polling, not a fair queue. That is
+acceptable for the single-machine workflow this guards; it is a guardrail against
+accidental concurrent writes, not a distributed lock manager.
 """
 
 from __future__ import annotations
@@ -24,6 +28,7 @@ import json
 import os
 import socket
 import tempfile
+import time
 from contextlib import contextmanager
 from datetime import datetime, timezone
 from pathlib import Path
@@ -31,6 +36,31 @@ from pathlib import Path
 from . import lock_path
 from .errors import LockError, UsageError
 
+# How long ``acquire`` waits for a busy lock before giving up (seconds). The default
+# is cooperative: concurrent writers serialize rather than failing fast. ``0`` keeps
+# the old fail-fast behavior; ``SCRIP_LOCK_TIMEOUT`` overrides it. The poll interval
+# backs off from _POLL_MIN to _POLL_MAX so a freed lock is taken promptly without
+# busy-spinning.
+_DEFAULT_LOCK_TIMEOUT = 10.0
+_POLL_MIN = 0.025
+_POLL_MAX = 0.25
+
+
+def _lock_timeout(explicit: float | None) -> float:
+    """Seconds ``acquire`` should wait for a busy lock. An explicit argument wins;
+    otherwise read ``SCRIP_LOCK_TIMEOUT`` (default :data:`_DEFAULT_LOCK_TIMEOUT`). A
+    missing or unparseable env value falls back to the default; negatives clamp to 0
+    (fail fast)."""
+    if explicit is not None:
+        return max(0.0, explicit)
+    raw = os.environ.get("SCRIP_LOCK_TIMEOUT")
+    if raw is None or not raw.strip():
+        return _DEFAULT_LOCK_TIMEOUT
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return _DEFAULT_LOCK_TIMEOUT
+
 
 def _now() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -129,45 +159,68 @@ def _create(path: Path, payload: bytes) -> None:
             pass
 
 
-def acquire(root: Path) -> dict:
+def acquire(root: Path, *, timeout: float | None = None) -> dict:
     """Take the lock, returning the holder info. Reclaims a *provably-dead* lock
-    once; raises :class:`LockError` (exit 2) if the lock looks live or is being
-    created by another writer."""
+    immediately. If the lock looks live (or is mid-creation by another writer),
+    *waits* — polling with backoff — up to ``timeout`` seconds for it to free, then
+    raises :class:`LockError` (exit 2) if it is still held. ``timeout`` defaults to
+    ``SCRIP_LOCK_TIMEOUT`` (``10`` s); ``timeout=0`` fails fast (the old behavior).
+    A holder that dies *during* the wait is reclaimed on the next poll."""
     p = lock_path(root)
     p.parent.mkdir(parents=True, exist_ok=True)
     info = _holder_info()
     payload = (json.dumps(info, ensure_ascii=False) + "\n").encode("utf-8")
-    try:
-        _create(p, payload)
-        return info
-    except FileExistsError:
-        pass
+    wait = _lock_timeout(timeout)
+    deadline = time.monotonic() + wait
+    poll = _POLL_MIN
 
-    existing = _read(p)
-    if not _reclaimable(existing):
-        if existing is None:
-            raise LockError(
-                ".kb/lock is held but not yet readable (another writer may be "
-                "acquiring it). Retry; run `scrip unlock --force` if it is stuck."
-            ) from None
-        raise LockError(
-            f"vault is locked by another writer ({_describe(existing)}). Wait for "
-            f"it to finish, or run `scrip unlock --force` if it is stuck."
-        ) from None
+    def _try_take() -> bool:
+        """One acquisition attempt: True if we now hold the lock. A provably-dead
+        lock on this host is reclaimed and retried once; otherwise we don't hold it."""
+        try:
+            _create(p, payload)
+            return True
+        except FileExistsError:
+            pass
+        if _reclaimable(_read(p)):
+            try:
+                p.unlink()
+            except FileNotFoundError:
+                pass
+            try:
+                _create(p, payload)
+                return True
+            except FileExistsError:
+                pass  # raced with another writer; fall through to wait/retry
+        return False
 
-    # Reclaim a clearly-dead lock and retry once.
-    try:
-        p.unlink()
-    except FileNotFoundError:
-        pass
-    try:
-        _create(p, payload)
-    except FileExistsError:
+    # Always attempt once (so a free lock is taken even at timeout=0), then poll —
+    # re-checking the deadline both before sleeping and again after, so we never
+    # retry (and grab) a lock that freed only once the budget was already spent.
+    if _try_take():
+        return info
+    while True:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            break
+        time.sleep(min(poll, remaining))  # remaining > 0 here, so never negative
+        poll = min(poll * 2, _POLL_MAX)
+        if time.monotonic() >= deadline:
+            break
+        if _try_take():
+            return info
+
+    existing = _read(p)  # who holds it now, for the diagnostic
+    waited = f" after waiting {wait:g}s" if wait else ""
+    if existing is None:
         raise LockError(
-            "could not acquire .kb/lock (raced with another writer); retry, or "
-            "`scrip unlock` if it is stuck."
+            ".kb/lock is held but not yet readable (another writer may be "
+            f"acquiring it){waited}. Retry; run `scrip unlock --force` if it is stuck."
         ) from None
-    return info
+    raise LockError(
+        f"vault is locked by another writer ({_describe(existing)}){waited}. "
+        f"Wait for it to finish, or run `scrip unlock --force` if it is stuck."
+    ) from None
 
 
 def release(root: Path, info: dict | None = None) -> None:
@@ -187,8 +240,8 @@ def release(root: Path, info: dict | None = None) -> None:
 
 
 @contextmanager
-def write_lock(root: Path):
-    info = acquire(root)
+def write_lock(root: Path, *, timeout: float | None = None):
+    info = acquire(root, timeout=timeout)
     try:
         yield info
     finally:

{scriptoria-0.6.4 → scriptoria-0.7.0}/tests/conftest.py

@@ -16,6 +16,16 @@ import pytest
 from scrip import anchors, blocks, frontmatter, hashing
 
 
+@pytest.fixture(autouse=True)
+def _fail_fast_lock(monkeypatch):
+    """Keep the hermetic suite fast: the write lock now *waits* for a busy lock
+    (``SCRIP_LOCK_TIMEOUT``, default 10s). Pin it to 0 (fail-fast) for tests so the
+    lock-blocked cases return immediately instead of sitting through the wait. Tests
+    of the waiting path pass an explicit ``timeout=`` to :func:`scrip.lock.acquire`,
+    which overrides this env default."""
+    monkeypatch.setenv("SCRIP_LOCK_TIMEOUT", "0")
+
+
 class KB:
     def __init__(self, root: Path):
         self.root = root

{scriptoria-0.6.4 → scriptoria-0.7.0}/tests/test_lock.py

@@ -6,6 +6,8 @@ import os
 import socket
 import stat
 import subprocess
+import threading
+import time
 
 import pytest
 
@@ -85,6 +87,91 @@ def test_release_only_removes_our_own_lock(tmp_path):
     lock_path(tmp_path).unlink()
 
 
+# --- waiting (cooperative blocking acquire) ---------------------------------
+def test_acquire_timeout_zero_fails_fast_on_live_lock(tmp_path):
+    info = lock.acquire(tmp_path, timeout=0)
+    try:
+        start = time.monotonic()
+        with pytest.raises(errors.LockError) as ei:
+            lock.acquire(tmp_path, timeout=0)
+        assert ei.value.exit_code == 2
+        assert time.monotonic() - start < 0.2  # immediate — no wait at timeout=0
+    finally:
+        lock.release(tmp_path, info)
+
+
+def test_acquire_waits_for_a_busy_lock_then_succeeds(tmp_path):
+    # a writer holds the lock briefly; a waiting acquire grabs it once it frees,
+    # rather than failing fast.
+    info = lock.acquire(tmp_path, timeout=0)
+
+    def _release_after():
+        time.sleep(0.2)
+        lock.release(tmp_path, info)
+
+    t = threading.Thread(target=_release_after)
+    t.start()
+    try:
+        start = time.monotonic()
+        info2 = lock.acquire(tmp_path, timeout=5)  # blocks ~0.2s, then acquires
+        waited = time.monotonic() - start
+        assert waited >= 0.15  # it actually waited for the release
+        assert json.loads(lock_path(tmp_path).read_text())["pid"] == os.getpid()
+        lock.release(tmp_path, info2)
+    finally:
+        t.join()
+
+
+def test_acquire_times_out_while_lock_stays_held(tmp_path):
+    info = lock.acquire(tmp_path, timeout=0)
+    try:
+        start = time.monotonic()
+        with pytest.raises(errors.LockError) as ei:
+            lock.acquire(tmp_path, timeout=0.3)
+        waited = time.monotonic() - start
+        assert ei.value.exit_code == 2
+        assert 0.25 <= waited < 3.0  # waited ~the timeout, then gave up (not forever)
+    finally:
+        lock.release(tmp_path, info)
+
+
+def test_acquire_does_not_grab_a_lock_freed_after_the_deadline(tmp_path, monkeypatch):
+    # A writer releases only once the timeout has elapsed. acquire must time out
+    # (exit 2), not wake from its last sleep, retry, and grab the just-freed lock —
+    # which would silently extend the budget past SCRIP_LOCK_TIMEOUT. Driven by a
+    # mocked clock so the boundary is deterministic (real-time races are not).
+    info = lock.acquire(tmp_path, timeout=0)  # our live pid holds it
+    clock = {"t": 100.0}
+    sleeps: list[float] = []
+    monkeypatch.setattr(lock.time, "monotonic", lambda: clock["t"])
+
+    def fake_sleep(d):
+        sleeps.append(d)
+        clock["t"] += d
+        if clock["t"] >= 100.3 and lock_path(tmp_path).exists():
+            lock.release(tmp_path, info)  # freed, but only at/after the deadline
+
+    monkeypatch.setattr(lock.time, "sleep", fake_sleep)
+    try:
+        with pytest.raises(errors.LockError) as ei:
+            lock.acquire(tmp_path, timeout=0.3)  # deadline = 100.0 + 0.3
+        assert ei.value.exit_code == 2
+        assert all(d >= 0 for d in sleeps)  # never a negative sleep duration
+    finally:
+        if lock_path(tmp_path).exists():
+            lock.release(tmp_path, info)
+
+
+def test_lock_timeout_resolution(monkeypatch):
+    monkeypatch.delenv("SCRIP_LOCK_TIMEOUT", raising=False)
+    assert lock._lock_timeout(None) == 10.0  # default when unset
+    monkeypatch.setenv("SCRIP_LOCK_TIMEOUT", "3.5")
+    assert lock._lock_timeout(None) == 3.5  # env configures the default
+    assert lock._lock_timeout(0) == 0.0  # an explicit timeout wins over the env
+    monkeypatch.setenv("SCRIP_LOCK_TIMEOUT", "nonsense")
+    assert lock._lock_timeout(None) == 10.0  # a bad env value falls back to default
+
+
 # --- staleness --------------------------------------------------------------
 def test_leftover_temp_from_recycled_pid_does_not_block_acquire(tmp_path, monkeypatch):
     """A temp file left by a crashed process must not be mistaken for a held lock

{scriptoria-0.6.4 → scriptoria-0.7.0}/uv.lock

@@ -1141,7 +1141,7 @@ wheels = [
 
 [[package]]
 name = "scriptoria"
-version = "0.6.4"
+version = "0.7.0"
 source = { editable = "." }
 dependencies = [
     { name = "duckdb" },