scriptoria 0.6.3__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scriptoria
-Version: 0.6.3
+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.3 → 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.3"
+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.3 → scriptoria-0.7.0}/src/scrip/__init__.py

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

{scriptoria-0.6.3 → scriptoria-0.7.0}/src/scrip/blocks.py

@@ -35,7 +35,9 @@ def _is_blank(line: str) -> bool:
 
 def split_blocks(text: str) -> list[dict]:
     """Return a list of ``{"block_id", "span": [start, end], "hash"}``."""
-    # ⚡ Bolt: Single pass block segmentation to avoid intermediate O(N) allocation
+    # Use splitlines(keepends=True): its boundary set (form feed, NEL, U+2028/9,
+    # …) is part of the deterministic segmentation contract — io.StringIO only
+    # splits on \r/\n and would re-hash existing blocks that contain those chars.
     ranges: list[list[int]] = []  # [start, end] per block
     cur: list[int] | None = None
     start = 0

{scriptoria-0.6.3 → scriptoria-0.7.0}/src/scrip/facts.py

@@ -77,7 +77,11 @@ def parse_ndjson(text: str) -> list[dict]:
     """Parse proposed records (one JSON object per line). Malformed input is a
     :class:`DataError` with its line number; an empty input is a usage error."""
     records: list[dict] = []
-    for lineno, raw_line in enumerate(text.splitlines(), start=1):
+    # Split on "\n" only, not str.splitlines(): NDJSON records are newline-
+    # delimited and may legally contain U+2028/U+2029/NEL inside a JSON string,
+    # which splitlines() would wrongly treat as record breaks. trailing \r (from
+    # \r\n) and the trailing empty element from a final newline are dropped below.
+    for lineno, raw_line in enumerate(text.split("\n"), start=1):
         line = raw_line.strip()
         if not line:
             continue

{scriptoria-0.6.3 → 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.3 → 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.3 → scriptoria-0.7.0}/tests/test_blocks.py

@@ -151,3 +151,14 @@ def test_blank_runs_are_boundaries_not_blocks():
     assert len(bs) == 1
     s, e = bs[0]["span"]
     assert "only paragraph" in "\n\nonly paragraph\n\n"[s:e]
+
+
+def test_form_feed_is_a_line_boundary():
+    """Segmentation uses str.splitlines()'s full boundary set (form feed here,
+    also NEL/U+2028/U+2029). Splitting only on \\r/\\n — e.g. via io.StringIO —
+    would merge these into one block and change every affected block's id/hash,
+    breaking the deterministic-segmentation contract (SPEC §7.2)."""
+    text = "# Heading\x0c## Sub\n"
+    spans = [tuple(b["span"]) for b in blocks.split_blocks(text)]
+    # two separate heading blocks, split at the form feed
+    assert spans == [(0, 10), (10, 17)]

scriptoria-0.7.0/tests/test_facts.py

@@ -0,0 +1,34 @@
+import pytest
+from scrip.errors import DataError, UsageError
+
+from scrip import facts
+
+
+def test_parse_ndjson_basic():
+    text = '{"a": 1}\n{"b": 2}\n'
+    assert facts.parse_ndjson(text) == [{"a": 1}, {"b": 2}]
+
+
+def test_parse_ndjson_skips_blank_lines_and_strips_crlf():
+    text = '{"a": 1}\r\n\r\n{"b": 2}\r\n'
+    assert facts.parse_ndjson(text) == [{"a": 1}, {"b": 2}]
+
+
+def test_parse_ndjson_keeps_u2028_inside_json_string():
+    # U+2028 / U+2029 are legal *inside* a JSON string value. str.splitlines()
+    # treats them as line breaks and would split this record into invalid
+    # fragments; splitting on "\n" only keeps the record intact.
+    text = '{"a": "x
y
z"}\n{"b": 2}\n'
+    assert facts.parse_ndjson(text) == [{"a": "x
y
z"}, {"b": 2}]
+
+
+def test_parse_ndjson_reports_line_number_on_bad_json():
+    text = '{"a": 1}\nnot json\n'
+    with pytest.raises(DataError) as exc:
+        facts.parse_ndjson(text)
+    assert "line 2" in str(exc.value)
+
+
+def test_parse_ndjson_empty_is_usage_error():
+    with pytest.raises(UsageError):
+        facts.parse_ndjson("  \n  \n")

{scriptoria-0.6.3 → 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.3 → scriptoria-0.7.0}/uv.lock

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