scriptoria 0.7.0__tar.gz → 0.8.0__tar.gz

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

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

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

{scriptoria-0.7.0 → scriptoria-0.8.0}/src/scrip/anchors.py

@@ -199,6 +199,27 @@ def verify_vault(root: Path) -> dict:
                 text = _source_text(root, rec["source_id"], src_cache)
                 record(f"claim:{cid}", rec, resolve(text, rec["anchor"]))
 
+    # cited edges (graph.ndjson): an edge that carries an anchor is verified like
+    # a claim; a bare {src,dst,kind} edge has no citation to resolve and is skipped.
+    edges_path = facts_dir(root) / "graph.ndjson"
+    if edges_path.exists():
+        with edges_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"graph.ndjson:{lineno}: invalid JSON: {e}") from e
+                if "anchor" not in rec:
+                    continue
+                if "source_id" not in rec:
+                    raise DataError(f"graph.ndjson:{lineno}: cited edge missing 'source_id'")
+                text = _source_text(root, rec["source_id"], src_cache)
+                where = f"edge:{rec.get('src')}->{rec.get('dst')} ({rec.get('kind')})"
+                record(where, rec, resolve(text, rec["anchor"]))
+
     wd = wiki_dir(root)
     if wd.is_dir():
         for path in sorted(wd.rglob("*.md")):

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

@@ -53,7 +53,10 @@ _CLAIM_ALLOWED = frozenset((*_CLAIM_REQUIRED, "claim_text", "tags"))
 _ENTITY_REQUIRED = ("entity_id", "name", "kind")
 _ENTITY_ALLOWED = frozenset((*_ENTITY_REQUIRED, "tags"))
 _EDGE_REQUIRED = ("src", "dst", "kind")
-_EDGE_ALLOWED = frozenset(_EDGE_REQUIRED)
+# An edge may optionally be *cited*: a verbatim ``quote`` + ``source_id`` whose
+# ``anchor`` scrip mints+verifies exactly as for a claim. Bare edges stay
+# structural. ``anchor`` remains scrip-owned (proposing it is a schema error).
+_EDGE_ALLOWED = frozenset((*_EDGE_REQUIRED, "quote", "source_id"))
 _DECISIONS = ("supersede", "qualify", "keep-both")
 _RECON_REQUIRED = ("decision", "claim_a", "claim_b")
 _RECON_ALLOWED = frozenset((*_RECON_REQUIRED, "winner", "rationale"))
@@ -161,6 +164,17 @@ def _validate(table: str, rec: dict, index: int) -> None:
         _check_shape(rec, index, _EDGE_REQUIRED, _EDGE_ALLOWED)
         for key in _EDGE_REQUIRED:
             _check_str(rec, key, index)
+        if "quote" in rec or "source_id" in rec:
+            # both or neither: a quote needs a source to anchor against
+            missing = [k for k in ("quote", "source_id") if k not in rec]
+            if missing:
+                raise DataError(
+                    f"record {index}: a cited edge needs both 'quote' and 'source_id' "
+                    f"(missing: {', '.join(missing)})"
+                )
+            _check_str(rec, "source_id", index)
+            # quote emptiness is a per-record finding (EMPTY_QUOTE), not a schema error
+            _check_str(rec, "quote", index, allow_blank=True)
     else:  # reconciliations
         _check_shape(rec, index, _RECON_REQUIRED, _RECON_ALLOWED, owned=_RECON_OWNED)
         for key in ("decision", "claim_a", "claim_b"):
@@ -390,13 +404,16 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
     resolved: list[dict | None] = [None] * len(proposals)
     path = facts_dir(root) / _FILES[table]
     with lock.write_lock(root):
-        if table == "claims":
-            # Resolve quotes INSIDE the lock: raw/ only changes via a *locked*
-            # `ingest --reingest`, so holding the lock from verification through
-            # append closes the window where a re-ingest could land between the
-            # two and silently break the just-minted anchors.
+        # Resolve quotes INSIDE the lock: raw/ only changes via a *locked*
+        # `ingest --reingest`, so holding the lock from verification through
+        # append closes the window where a re-ingest could land between the
+        # two and silently break the just-minted anchors. Claims always carry a
+        # quote; an edge does only when it is *cited*.
+        if table == "claims" or table == "edges":
             src_cache: dict[str, str | None] = {}
             for i, rec in enumerate(proposals):
+                if table == "edges" and "quote" not in rec:
+                    continue  # bare edge: nothing to anchor
                 fail, res = _resolve_claim(root, rec, i, src_cache)
                 if fail:
                     failures.append(fail)
@@ -478,7 +495,12 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
                     skipped.append({"index": i, "reason": "duplicate", "existing_id": None})
                     continue
                 seen_edges.add(key)
-                appended.append({"src": rec["src"], "dst": rec["dst"], "kind": rec["kind"]})
+                full = {"src": rec["src"], "dst": rec["dst"], "kind": rec["kind"]}
+                res = resolved[i]
+                if res is not None:  # cited edge: carry the minted provenance
+                    full["source_id"] = res["source_id"]
+                    full["anchor"] = res["anchor"]
+                appended.append(full)
         else:  # reconciliations
             claim_ids = {c.get("claim_id") for c in _read_table(facts_dir(root) / "claims.ndjson")[0]}
             for i, rec in enumerate(proposals):
@@ -528,10 +550,11 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
                     f.write("\n")
                 f.write(payload)
             new_sources: list[str] = []
-            if table == "claims":
+            if table in ("claims", "edges"):
                 for rec in appended:
-                    if rec["source_id"] not in new_sources:
-                        new_sources.append(rec["source_id"])
+                    sid = rec.get("source_id")  # cited edges carry one; bare edges don't
+                    if sid and sid not in new_sources:
+                        new_sources.append(sid)
             _write_meta(root, meta, new_sources)
 
     return {"table": table, "appended": appended, "skipped": skipped, "failures": []}

{scriptoria-0.7.0 → scriptoria-0.8.0}/tests/test_fact_cmd.py

@@ -31,6 +31,12 @@ def _claim(quote, source="raw/s", **kw):
     return rec
 
 
+def _edge(src="entity/a", dst="entity/b", kind="relates-to", **kw):
+    rec = {"src": src, "dst": dst, "kind": kind}
+    rec.update(kw)
+    return rec
+
+
 def _ndjson(*recs):
     return "".join(json.dumps(r, ensure_ascii=False) + "\n" for r in recs)
 
@@ -55,6 +61,13 @@ def _recs_lines(kb):
     return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
 
 
+def _graph_lines(kb):
+    p = kb.root / "vault" / "facts" / "graph.ndjson"
+    if not p.exists():
+        return []
+    return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
+
+
 def _two_claims(kb):
     """Seed a contradiction pair to reconcile."""
     kb.add_raw("s", SRC)
@@ -476,3 +489,63 @@ def test_fact_add_edges_appends_and_skips_duplicates(kb):
     assert _run_add(kb, _ndjson(edge), "--table", "edges") == 0
     lines = (kb.root / "vault" / "facts" / "graph.ndjson").read_text(encoding="utf-8")
     assert len(lines.splitlines()) == 1
+
+
+# --------------------------------------------------------------------------- #
+# Cited edges: an edge may carry a verbatim quote + source_id; scrip mints and
+# verifies an anchor for it exactly as it does for a claim. Bare edges still work.
+# --------------------------------------------------------------------------- #
+def test_fact_add_bare_edge_carries_no_provenance(kb):
+    # additivity guard: an edge with no quote stays purely structural
+    assert _run_add(kb, _ndjson(_edge()), "--table", "edges") == 0
+    [edge] = _graph_lines(kb)
+    assert set(edge) == {"src", "dst", "kind"}
+
+
+def test_fact_add_cited_edge_mints_and_verifies_anchor(kb):
+    kb.add_raw("s", SRC)
+    rc = _run_add(
+        kb,
+        _ndjson(_edge(quote="Caching answers beats recomputing them.", source_id="raw/s")),
+        "--table", "edges",
+    )
+    assert rc == 0
+    [edge] = _graph_lines(kb)
+    assert (edge["src"], edge["dst"], edge["kind"]) == ("entity/a", "entity/b", "relates-to")
+    assert edge["source_id"] == "raw/s"
+    # the minted anchor resolves uniquely in the source, and scrip verify confirms it
+    assert anchors.resolve(SRC, edge["anchor"]) == "OK"
+    assert cli.main(["verify", "--root", str(kb.root)]) == 0
+
+
+def test_fact_add_cited_edge_broken_quote_fails_batch(kb, capsys):
+    kb.add_raw("s", SRC)
+    rc = _run_add(
+        kb,
+        _ndjson(_edge(quote="this sentence is absent from the source", source_id="raw/s")),
+        "--table", "edges", "--json",
+    )
+    assert rc == 1
+    assert _graph_lines(kb) == []  # all-or-nothing: nothing written
+    [failure] = json.loads(capsys.readouterr().out)["failures"]
+    assert failure["status"] == "BROKEN"
+
+
+def test_fact_add_cited_edge_requires_both_quote_and_source_id(kb):
+    kb.add_raw("s", SRC)
+    # a quote needs a source to anchor against, and vice versa — both or neither
+    assert _run_add(kb, _ndjson(_edge(quote="Caching answers beats recomputing them.")),
+                    "--table", "edges") == 3
+    assert _run_add(kb, _ndjson(_edge(source_id="raw/s")), "--table", "edges") == 3
+    assert _graph_lines(kb) == []
+
+
+def test_fact_add_cited_edge_dedups_on_triple(kb, capsys):
+    kb.add_raw("s", SRC)
+    cited = _ndjson(_edge(quote="Caching answers beats recomputing them.", source_id="raw/s"))
+    assert _run_add(kb, cited, "--table", "edges") == 0
+    capsys.readouterr()
+    # same (src,dst,kind) again — even bare — is the same relation, so it's skipped
+    assert _run_add(kb, _ndjson(_edge()), "--table", "edges", "--json") == 0
+    assert len(_graph_lines(kb)) == 1
+    assert json.loads(capsys.readouterr().out)["skipped"][0]["reason"] == "duplicate"

{scriptoria-0.7.0 → scriptoria-0.8.0}/tests/test_verify.py

@@ -1,9 +1,17 @@
+import json
+
 import pytest
 from scrip.errors import DataError
 
 from scrip import anchors, cli
 
 
+def _write_edge(kb, rec):
+    p = kb.root / "vault" / "facts" / "graph.ndjson"
+    with open(p, "a", encoding="utf-8") as f:
+        f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+
+
 def test_cli_verify_fails_on_ambiguous_by_default(kb):
     # a quote that occurs twice in the source -> AMBIGUOUS
     kb.add_raw("a", "# A\n\nalpha beta gamma. alpha beta gamma.\n")
@@ -62,3 +70,33 @@ def test_verify_wiki_footnote_anchor(kb):
     res = anchors.verify_vault(kb.root)
     assert res["ok"] == 1
     assert res["broken"] == []
+
+
+def test_verify_cited_edge_anchor_resolves(kb):
+    src = "# A\n\nThe sky is blue today over the hills.\n"
+    kb.add_raw("a", src)
+    anchor = anchors.make_anchor(src, "the sky is blue today")
+    _write_edge(kb, {"src": "entity/sky", "dst": "entity/color", "kind": "is",
+                     "source_id": "raw/a", "anchor": anchor})
+    res = anchors.verify_vault(kb.root)
+    assert res["ok"] == 1
+    assert res["broken"] == []
+
+
+def test_verify_broken_cited_edge_anchor_is_listed(kb):
+    kb.add_raw("a", "# A\n\nThe sky is blue.\n")
+    bogus = "qh:" + ("0" * 64) + "|loc:0.0|len:10"
+    _write_edge(kb, {"src": "entity/a", "dst": "entity/b", "kind": "rel",
+                     "source_id": "raw/a", "anchor": bogus})
+    res = anchors.verify_vault(kb.root)
+    assert len(res["broken"]) == 1
+    assert res["broken"][0]["where"].startswith("edge:")
+
+
+def test_verify_bare_edge_is_not_checked(kb):
+    # an uncited edge has nothing to resolve, so verify ignores it (additive)
+    kb.add_raw("a", "# A\n\nThe sky is blue.\n")
+    _write_edge(kb, {"src": "entity/a", "dst": "entity/b", "kind": "rel"})
+    res = anchors.verify_vault(kb.root)
+    assert res["checked"] == 0
+    assert res["broken"] == []

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

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