scriptoria 0.5.0__tar.gz → 0.5.1__tar.gz

{scriptoria-0.5.0 → scriptoria-0.5.1}/.gitignore

@@ -29,3 +29,7 @@ build/
 
 # roborev snapshots
 /.roborev/
+
+# Obsidian local state: created when you open vault/ in Obsidian (UI config,
+# sideloaded plugin copies). Local-only; the vault is valid without it.
+vault/.obsidian/

{scriptoria-0.5.0 → scriptoria-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scriptoria
-Version: 0.5.0
+Version: 0.5.1
 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.5.0 → scriptoria-0.5.1}/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.5.0"
+version = "0.5.1"
 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.5.0 → scriptoria-0.5.1}/src/scrip/__init__.py

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

{scriptoria-0.5.0 → scriptoria-0.5.1}/src/scrip/anchors.py

@@ -139,15 +139,16 @@ def source_text(root: Path, source_id: str) -> str:
 
 
 def _iter_footnote_anchors(path: Path) -> Iterator[dict]:
-    for line in path.read_text(encoding="utf-8").splitlines():
-        m = _FOOTNOTE.match(line)
-        if not m:
-            continue
-        target = m.group(2)
-        if "#" not in target:
-            continue
-        source_id, anchor = target.split("#", 1)
-        yield {"fn": m.group(1), "source_id": source_id, "anchor": anchor}
+    with path.open(encoding="utf-8") as f:
+        for line in f:
+            m = _FOOTNOTE.match(line)
+            if not m:
+                continue
+            target = m.group(2)
+            if "#" not in target:
+                continue
+            source_id, anchor = target.split("#", 1)
+            yield {"fn": m.group(1), "source_id": source_id, "anchor": anchor}
 
 
 def verify_vault(root: Path) -> dict:
@@ -179,25 +180,24 @@ def verify_vault(root: Path) -> dict:
     claims_path = facts_dir(root) / "claims.ndjson"
     if claims_path.exists():
         seen: set[str] = set()
-        for lineno, raw_line in enumerate(
-            claims_path.read_text(encoding="utf-8").splitlines(), start=1
-        ):
-            line = raw_line.strip()
-            if not line:
-                continue
-            try:
-                rec = json.loads(line)
-            except json.JSONDecodeError as e:
-                raise DataError(f"claims.ndjson:{lineno}: invalid JSON: {e}") from e
-            for key in ("claim_id", "source_id", "anchor"):
-                if key not in rec:
-                    raise DataError(f"claims.ndjson:{lineno}: missing '{key}'")
-            cid = rec["claim_id"]
-            if cid in seen:
-                raise DataError(f"duplicate claim_id: {cid}")
-            seen.add(cid)
-            text = _source_text(root, rec["source_id"], src_cache)
-            record(f"claim:{cid}", rec, resolve(text, rec["anchor"]))
+        with claims_path.open(encoding="utf-8") as f:
+            for lineno, raw_line in enumerate(f, start=1):
+                line = raw_line.strip()
+                if not line:
+                    continue
+                try:
+                    rec = json.loads(line)
+                except json.JSONDecodeError as e:
+                    raise DataError(f"claims.ndjson:{lineno}: invalid JSON: {e}") from e
+                for key in ("claim_id", "source_id", "anchor"):
+                    if key not in rec:
+                        raise DataError(f"claims.ndjson:{lineno}: missing '{key}'")
+                cid = rec["claim_id"]
+                if cid in seen:
+                    raise DataError(f"duplicate claim_id: {cid}")
+                seen.add(cid)
+                text = _source_text(root, rec["source_id"], src_cache)
+                record(f"claim:{cid}", rec, resolve(text, rec["anchor"]))
 
     wd = wiki_dir(root)
     if wd.is_dir():

{scriptoria-0.5.0 → scriptoria-0.5.1}/src/scrip/facts.py

@@ -228,23 +228,35 @@ def _resolve_claim(
 # --------------------------------------------------------------------------- #
 # Existing-table reads & keys
 # --------------------------------------------------------------------------- #
-def _read_table(path: Path) -> tuple[list[dict], str]:
-    """Read an NDJSON table, returning ``(records, raw_text)``. Malformed lines
-    are a :class:`DataError` — the vault on disk violates the contract."""
+def _ends_with_newline(path: Path) -> bool:
+    """Whether the file's final byte is a newline (an empty/absent file counts as
+    terminated, so no separator is prepended before the next append)."""
+    if not path.exists() or path.stat().st_size == 0:
+        return True
+    with path.open("rb") as f:
+        f.seek(-1, 2)
+        return f.read(1) == b"\n"
+
+
+def _read_table(path: Path) -> tuple[list[dict], bool]:
+    """Read an NDJSON table, returning ``(records, ends_with_newline)``. Streams the
+    file line-by-line rather than loading it whole. Malformed lines are a
+    :class:`DataError` — the vault on disk violates the contract."""
     if not path.exists():
-        return [], ""
-    text = path.read_text(encoding="utf-8")
+        return [], True
+    ends_newline = _ends_with_newline(path)
     records: list[dict] = []
-    for lineno, raw_line in enumerate(text.splitlines(), start=1):
-        line = raw_line.strip()
-        if not line:
-            continue
-        try:
-            rec = json.loads(line)
-        except json.JSONDecodeError as e:
-            raise DataError(f"{path.name}:{lineno}: invalid JSON: {e}") from e
-        records.append(rec)
-    return records, text
+    with path.open(encoding="utf-8") as f:
+        for lineno, raw_line in enumerate(f, start=1):
+            line = raw_line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError as e:
+                raise DataError(f"{path.name}:{lineno}: invalid JSON: {e}") from e
+            records.append(rec)
+    return records, ends_newline
 
 
 def claim_source_anchor(root: Path, claim_id: str) -> tuple[str, str]:
@@ -384,7 +396,7 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
             if failures:
                 return {"table": table, "appended": [], "skipped": [], "failures": failures}
 
-        existing, existing_text = _read_table(path)
+        existing, ends_with_newline = _read_table(path)
         meta = _load_meta(root)  # parse before appending: fail whole, not half
         appended: list[dict] = []
         skipped: list[dict] = []
@@ -503,7 +515,7 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
             path.parent.mkdir(parents=True, exist_ok=True)
             payload = "".join(json.dumps(r, ensure_ascii=False) + "\n" for r in appended)
             with open(path, "a", encoding="utf-8") as f:
-                if existing_text and not existing_text.endswith("\n"):
+                if not ends_with_newline:
                     f.write("\n")
                 f.write(payload)
             new_sources: list[str] = []

{scriptoria-0.5.0 → scriptoria-0.5.1}/src/scrip/frontmatter.py

@@ -60,3 +60,30 @@ def require(meta: dict, keys: Iterable[str], where: str = "frontmatter") -> None
     missing = [k for k in keys if k not in meta]
     if missing:
         raise DataError(f"{where}: missing required key(s): {', '.join(missing)}")
+
+
+def as_str(meta: dict, key: str, where: str = "frontmatter") -> str | None:
+    """Return ``meta[key]`` as a string, or ``None`` if absent/null. Raise
+    :class:`DataError` (naming ``where``) if present but not a string."""
+    value = meta.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise DataError(
+            f"{where}: '{key}' must be a string, got {type(value).__name__}"
+        )
+    return value
+
+
+def as_str_list(meta: dict, key: str, where: str = "frontmatter") -> list[str]:
+    """Return ``meta[key]`` as a list of strings, or ``[]`` if absent/null. Raise
+    :class:`DataError` (naming ``where``) if present but not a list of strings.
+
+    This is what stops a hand-edited bare string (``derived-from: raw/x``) from
+    silently char-splitting into per-character dependency ids downstream."""
+    value = meta.get(key)
+    if value is None:
+        return []
+    if not isinstance(value, list) or not all(isinstance(x, str) for x in value):
+        raise DataError(f"{where}: '{key}' must be a list of strings")
+    return value

{scriptoria-0.5.0 → scriptoria-0.5.1}/src/scrip/graph.py

@@ -80,28 +80,35 @@ def scan_derived(root: Path) -> dict:
             meta, _ = frontmatter.load(path)
             if not meta or "derived-from" not in meta:
                 continue  # index.md, log.md, hand notes: not tracked artifacts
-            did = meta.get("id") or str(path.relative_to(root))
+            where = str(path.relative_to(root))
+            did = frontmatter.as_str(meta, "id", where) or where
             out[did] = {
-                "path": str(path.relative_to(root)),
-                "type": meta.get("type", "wiki"),
-                "derived_from": list(meta.get("derived-from") or []),
-                "input_hash": meta.get("input-hash"),
-                "last_compiled": meta.get("last-compiled"),
+                "path": where,
+                "type": frontmatter.as_str(meta, "type", where) or "wiki",
+                "derived_from": frontmatter.as_str_list(meta, "derived-from", where),
+                "input_hash": frontmatter.as_str(meta, "input-hash", where),
+                "last_compiled": frontmatter.as_str(meta, "last-compiled", where),
             }
     fmeta = facts_dir(root) / "_meta.yaml"
     if fmeta.exists():
         try:
-            data = yaml.safe_load(fmeta.read_text(encoding="utf-8")) or {}
+            data = yaml.safe_load(fmeta.read_text(encoding="utf-8"))
         except yaml.YAMLError as e:
             raise DataError(f"invalid facts/_meta.yaml: {e}") from e
-        if isinstance(data, dict) and "derived-from" in data:
-            did = data.get("id") or "facts/core"
+        if data is None:
+            data = {}  # empty / null file: legitimately "no facts set"
+        elif not isinstance(data, dict):
+            # don't let `or {}` mask falsey non-mappings ([], false, 0, '')
+            raise DataError("facts/_meta.yaml must be a YAML mapping")
+        if "derived-from" in data:
+            where = str(fmeta.relative_to(root))
+            did = frontmatter.as_str(data, "id", where) or "facts/core"
             out[did] = {
-                "path": str(fmeta.relative_to(root)),
-                "type": data.get("type", "facts.set"),
-                "derived_from": list(data.get("derived-from") or []),
-                "input_hash": data.get("input-hash"),
-                "last_compiled": data.get("last-compiled"),
+                "path": where,
+                "type": frontmatter.as_str(data, "type", where) or "facts.set",
+                "derived_from": frontmatter.as_str_list(data, "derived-from", where),
+                "input_hash": frontmatter.as_str(data, "input-hash", where),
+                "last_compiled": frontmatter.as_str(data, "last-compiled", where),
             }
     return out
 
@@ -114,10 +121,10 @@ def _dep_hash(dep_id: str, raw: dict) -> str | None:
         r = raw.get(base)
         if not r:
             return None
-        for b in r["blocks"]:
-            if b["block_id"] == block_id:
-                return b["hash"]
-        return None
+        # ⚡ Bolt: Replace O(n) loop with O(1) hash map lookup for blocks
+        if "_blocks_map" not in r:
+            r["_blocks_map"] = {b["block_id"]: b["hash"] for b in r["blocks"]}
+        return r["_blocks_map"].get(block_id)
     r = raw.get(dep_id)
     return r["content_hash"] if r else None
 

{scriptoria-0.5.0 → scriptoria-0.5.1}/src/scrip/hashing.py

@@ -7,13 +7,10 @@ self-describing in the manifest and frontmatter.
 from __future__ import annotations
 
 import hashlib
-import re
 import unicodedata
 from collections.abc import Mapping
 from pathlib import Path
 
-_WS = re.compile(r"\s+")
-
 
 def normalize(text: str) -> str:
     """Canonical text normalization shared by provenance anchors and block ids.
@@ -23,8 +20,8 @@ def normalize(text: str) -> str:
     ``blocks`` import) means anchor identity and block identity can never drift.
     """
     t = unicodedata.normalize("NFC", text)
-    t = _WS.sub(" ", t).strip()
-    return t.lower()
+    # Using split() and join() is significantly faster than regex for whitespace normalization
+    return " ".join(t.split()).lower()
 
 
 def _digest(data: bytes) -> str:

{scriptoria-0.5.0 → scriptoria-0.5.1}/src/scrip/similar.py

@@ -56,25 +56,26 @@ def _source_tags(root: Path) -> dict[str, set[str]]:
     p = facts_dir(root) / "claims.ndjson"
     if not p.exists():
         return out
-    for lineno, raw_line in enumerate(p.read_text(encoding="utf-8").splitlines(), start=1):
-        line = raw_line.strip()
-        if not line:
-            continue
-        try:
-            rec = json.loads(line)
-        except json.JSONDecodeError as e:
-            raise DataError(f"claims.ndjson:{lineno}: invalid JSON: {e}") from e
-        if not isinstance(rec, dict):
-            raise DataError(f"claims.ndjson:{lineno}: expected a JSON object")
-        sid = rec.get("source_id")
-        if not isinstance(sid, str):
-            raise DataError(f"claims.ndjson:{lineno}: 'source_id' must be a string")
-        tags = rec.get("tags")
-        if tags is None:
-            continue
-        if not isinstance(tags, list) or any(not isinstance(t, str) for t in tags):
-            raise DataError(f"claims.ndjson:{lineno}: 'tags' must be a list of strings")
-        out.setdefault(sid, set()).update(tags)
+    with p.open(encoding="utf-8") as f:
+        for lineno, raw_line in enumerate(f, start=1):
+            line = raw_line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError as e:
+                raise DataError(f"claims.ndjson:{lineno}: invalid JSON: {e}") from e
+            if not isinstance(rec, dict):
+                raise DataError(f"claims.ndjson:{lineno}: expected a JSON object")
+            sid = rec.get("source_id")
+            if not isinstance(sid, str):
+                raise DataError(f"claims.ndjson:{lineno}: 'source_id' must be a string")
+            tags = rec.get("tags")
+            if tags is None:
+                continue
+            if not isinstance(tags, list) or any(not isinstance(t, str) for t in tags):
+                raise DataError(f"claims.ndjson:{lineno}: 'tags' must be a list of strings")
+            out.setdefault(sid, set()).update(tags)
     return out
 
 

scriptoria-0.5.1/tests/test_frontmatter.py

@@ -0,0 +1,97 @@
+import pytest
+from scrip.errors import DataError
+
+from scrip import frontmatter
+
+
+# --- parse ----------------------------------------------------------------
+def test_parse_no_frontmatter_returns_whole_text():
+    meta, body = frontmatter.parse("just a body\n")
+    assert meta == {}
+    assert body == "just a body\n"
+
+
+def test_parse_valid_mapping():
+    meta, body = frontmatter.parse("---\nid: concept/x\nn: 3\n---\nBody.\n")
+    assert meta == {"id": "concept/x", "n": 3}
+    assert body == "Body.\n"
+
+
+def test_parse_empty_frontmatter_is_empty_dict():
+    meta, body = frontmatter.parse("---\n---\nbody\n")
+    assert meta == {}
+    assert body == "body\n"
+
+
+def test_parse_invalid_yaml_raises():
+    with pytest.raises(DataError):
+        frontmatter.parse("---\nfoo: [unclosed\n---\nbody\n")
+
+
+def test_parse_non_mapping_raises():
+    with pytest.raises(DataError):
+        frontmatter.parse("---\n- a\n- b\n---\nbody\n")  # a list, not a mapping
+
+
+def test_parse_unterminated_raises():
+    with pytest.raises(DataError):
+        frontmatter.parse("---\nid: x\nno closing fence here\n")
+
+
+# --- load / dump ----------------------------------------------------------
+def test_load_missing_file_raises(tmp_path):
+    with pytest.raises(DataError):
+        frontmatter.load(tmp_path / "nope.md")
+
+
+def test_dump_roundtrips_and_preserves_insertion_order():
+    meta = {"id": "concept/x", "type": "wiki.concept", "derived-from": ["raw/a"]}
+    text = frontmatter.dump(meta, "Body.\n")
+    meta2, body2 = frontmatter.parse(text)
+    assert meta2 == meta
+    assert body2 == "Body.\n"
+    assert text.index("id:") < text.index("type:") < text.index("derived-from:")
+
+
+# --- require --------------------------------------------------------------
+def test_require_raises_on_missing():
+    with pytest.raises(DataError):
+        frontmatter.require({"a": 1}, ["a", "b"], where="page")
+
+
+def test_require_passes_when_present():
+    frontmatter.require({"a": 1, "b": 2}, ["a", "b"])  # no raise
+
+
+# --- typed accessors (new) ------------------------------------------------
+def test_as_str_returns_value_or_none():
+    assert frontmatter.as_str({"k": "v"}, "k") == "v"
+    assert frontmatter.as_str({}, "k") is None
+    assert frontmatter.as_str({"k": None}, "k") is None
+
+
+def test_as_str_rejects_non_string():
+    with pytest.raises(DataError):
+        frontmatter.as_str({"k": 3}, "k")
+    with pytest.raises(DataError):
+        frontmatter.as_str({"k": ["a"]}, "k")
+
+
+def test_as_str_list_returns_list_or_empty():
+    assert frontmatter.as_str_list({"k": ["a", "b"]}, "k") == ["a", "b"]
+    assert frontmatter.as_str_list({}, "k") == []
+    assert frontmatter.as_str_list({"k": None}, "k") == []
+
+
+def test_as_str_list_rejects_bare_string_and_non_string_items():
+    with pytest.raises(DataError):
+        frontmatter.as_str_list({"k": "raw/a"}, "k")  # bare string would char-split
+    with pytest.raises(DataError):
+        frontmatter.as_str_list({"k": [1, 2]}, "k")
+
+
+def test_accessor_error_names_the_location():
+    with pytest.raises(DataError) as ei:
+        frontmatter.as_str_list({"derived-from": "raw/a"}, "derived-from", where="wiki/x.md")
+    assert "wiki/x.md" in str(ei.value)
+    assert "derived-from" in str(ei.value)

{scriptoria-0.5.0 → scriptoria-0.5.1}/tests/test_graph_status.py

@@ -1,6 +1,83 @@
 import os
 
-from scrip import cli, graph
+import pytest
+from scrip.errors import DataError
+
+from scrip import cli, frontmatter, graph
+
+
+def _write_wiki(kb, slug, meta, body="Body.\n"):
+    """Write a wiki page with arbitrary (possibly malformed) frontmatter."""
+    p = kb.root / "vault" / "wiki" / "concepts" / f"{slug}.md"
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(frontmatter.dump(meta, body), encoding="utf-8")
+
+
+def test_derived_from_as_string_raises_not_silent_stale(kb):
+    """A bare string derived-from would char-split into per-character dep ids and
+    silently mark the page STALE; it must raise a clear, file-named error."""
+    kb.add_raw("a", "# A\n\nAlpha.\n")
+    _write_wiki(kb, "x", {
+        "id": "concept/x",
+        "type": "wiki.concept",
+        "derived-from": "raw/a",  # STRING, not a list
+        "input-hash": "sha256:dead",
+        "last-compiled": "2026-01-01T00:00:00Z",
+    })
+    with pytest.raises(DataError) as ei:
+        graph.compute_status(kb.root, use_cache=False)
+    assert "x.md" in str(ei.value)
+
+
+def test_wrong_typed_id_raises(kb):
+    kb.add_raw("a", "# A\n\nAlpha.\n")
+    _write_wiki(kb, "x", {
+        "id": ["concept/x"],  # non-string id
+        "derived-from": ["raw/a"],
+        "input-hash": "sha256:dead",
+        "last-compiled": "2026-01-01T00:00:00Z",
+    })
+    with pytest.raises(DataError):
+        graph.compute_status(kb.root, use_cache=False)
+
+
+def test_facts_meta_derived_from_as_string_raises(kb):
+    kb.add_raw("a", "# A\n\nAlpha.\n")
+    (kb.root / "vault" / "facts" / "_meta.yaml").write_text(
+        "id: facts/core\nderived-from: raw/a\n", encoding="utf-8",
+    )
+    with pytest.raises(DataError):
+        graph.compute_status(kb.root, use_cache=False)
+
+
+def test_facts_meta_non_mapping_raises(kb):
+    """A facts/_meta.yaml that parses to a non-mapping must fail loudly, not
+    silently drop the facts set from the graph (roborev 1251)."""
+    kb.add_raw("a", "# A\n\nAlpha.\n")
+    (kb.root / "vault" / "facts" / "_meta.yaml").write_text(
+        "- not\n- a\n- mapping\n", encoding="utf-8",
+    )
+    with pytest.raises(DataError):
+        graph.compute_status(kb.root, use_cache=False)
+
+
+def test_facts_meta_falsey_non_mapping_raises(kb):
+    """`[]`/`false`/`''` are falsey, so `safe_load(...) or {}` used to mask them as
+    an empty mapping and silently drop the facts set (roborev 1253)."""
+    kb.add_raw("a", "# A\n\nAlpha.\n")
+    (kb.root / "vault" / "facts" / "_meta.yaml").write_text("[]\n", encoding="utf-8")
+    with pytest.raises(DataError):
+        graph.compute_status(kb.root, use_cache=False)
+
+
+def test_facts_meta_empty_is_not_an_error(kb):
+    """An empty / null facts/_meta.yaml is legitimately 'no facts set' — None must
+    still map to {} and not raise (guards against over-correcting)."""
+    kb.add_raw("a", "# A\n\nAlpha.\n")
+    kb.add_wiki("x", ["raw/a"])
+    (kb.root / "vault" / "facts" / "_meta.yaml").write_text("", encoding="utf-8")
+    res = graph.compute_status(kb.root, use_cache=False)
+    assert res["stale"] == []
 
 
 def test_fresh_vault_all_ok(kb):

{scriptoria-0.5.0 → scriptoria-0.5.1}/uv.lock

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