scriptoria 0.4.0__tar.gz → 0.5.0__tar.gz

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

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

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

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

@@ -90,6 +90,33 @@ def resolve(source_text: str, anchor: str) -> str:
     return "OK" if matches == 1 else "AMBIGUOUS"
 
 
+def span(source_text: str, anchor: str) -> tuple[str, str | None]:
+    """Return ``(status, cited_text)`` for ``anchor`` in ``source_text``.
+
+    Same verdicts as :func:`resolve`, but also returns the matched span (the
+    normalized cited text) so a caller can *read* what an anchor cites. For
+    ``AMBIGUOUS`` the window nearest the anchor's ``loc`` hint is returned; for
+    ``BROKEN`` the text is ``None``.
+    """
+    a = parse_anchor(anchor)
+    ns = normalize(source_text)
+    n, target, loc = a["len"], a["qh"], a["loc"]
+    length = len(ns)
+    if n <= 0 or n > length:
+        return "BROKEN", None
+    hits = [
+        start
+        for start in range(length - n + 1)
+        if hashlib.sha256(ns[start : start + n].encode("utf-8")).hexdigest() == target
+    ]
+    if not hits:
+        return "BROKEN", None
+    if len(hits) == 1:
+        return "OK", ns[hits[0] : hits[0] + n]
+    nearest = min(hits, key=lambda s: abs(s - loc * length))
+    return "AMBIGUOUS", ns[nearest : nearest + n]
+
+
 # --------------------------------------------------------------------------- #
 # Vault-wide verification
 # --------------------------------------------------------------------------- #

{scriptoria-0.4.0 → scriptoria-0.5.0}/src/scrip/cli.py

@@ -352,6 +352,31 @@ def _parse_source_ids(raw: str) -> list[str]:
     return ids
 
 
+def cmd_span(args: argparse.Namespace) -> int:
+    from . import anchors
+
+    root = resolve_root(args.root)
+    if args.claim:
+        from . import facts
+
+        source_id, anchor = facts.claim_source_anchor(root, args.claim)
+    else:
+        if "#" not in args.target:
+            raise errors.UsageError("target must be raw/<slug>#<anchor>")
+        source_id, anchor = args.target.split("#", 1)
+        source_id = source_id if source_id.startswith("raw/") else f"raw/{source_id}"
+        _safe_slug(source_id[len("raw/") :], "source")
+    text = anchors.source_text(root, source_id)
+    status, cited = anchors.span(text, anchor)
+    if args.json:
+        _emit({"target": f"{source_id}#{anchor}", "status": status, "text": cited})
+    else:
+        print(f"[{status}] {source_id}")
+        if cited is not None:
+            print(cited)
+    return 0 if status == "OK" else 1
+
+
 def cmd_similar(args: argparse.Namespace) -> int:
     from . import similar
 
@@ -388,7 +413,12 @@ def cmd_fact_add(args: argparse.Namespace) -> int:
         _emit(result)
     else:
         for r in result["appended"]:
-            ident = r.get("claim_id") or r.get("entity_id") or f"{r['src']} -> {r['dst']}"
+            ident = (
+                r.get("claim_id")
+                or r.get("entity_id")
+                or r.get("reconciliation_id")
+                or f"{r.get('src')} -> {r.get('dst')}"
+            )
             print(f"  appended {ident}")
         for s in result["skipped"]:
             print(f"  = record {s['index']} skipped (duplicate)")
@@ -517,7 +547,7 @@ def build_parser() -> argparse.ArgumentParser:
     pq.add_argument(
         "name",
         nargs="?",
-        choices=["claims", "entities", "edges", "contradictions"],
+        choices=["claims", "entities", "edges", "contradictions", "reconciliations"],
         help="a named query (omit when using --sql)",
     )
     pq.add_argument("--sql", help="raw DuckDB SQL (views: claims, entities, edges)")
@@ -585,6 +615,16 @@ def build_parser() -> argparse.ArgumentParser:
     pn.add_argument("--title", help="human title (default: the slug)")
     pn.set_defaults(func=cmd_new)
 
+    psp = sub.add_parser(
+        "span",
+        parents=[common],
+        help="resolve an anchor and print the cited text (read both sides of a contradiction)",
+    )
+    span_src = psp.add_mutually_exclusive_group(required=True)
+    span_src.add_argument("target", nargs="?", metavar="raw/<slug>#<anchor>", help="anchor target")
+    span_src.add_argument("--claim", metavar="ID", help="resolve this claim's anchor instead")
+    psp.set_defaults(func=cmd_span)
+
     psim = sub.add_parser(
         "similar",
         parents=[common],
@@ -629,7 +669,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     pfa.add_argument(
         "--table",
-        choices=["claims", "entities", "edges"],
+        choices=["claims", "entities", "edges", "reconciliations"],
         default="claims",
         help="facts table to append to (default: claims)",
     )

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

@@ -36,10 +36,12 @@ _FILES = {
     "claims": "claims.ndjson",
     "entities": "entities.ndjson",
     "edges": "graph.ndjson",
+    "reconciliations": "reconciliations.ndjson",
 }
 
 # Fields scrip mints itself; proposing them is a schema error, not a finding.
 _SCRIP_OWNED = ("claim_id", "anchor", "extracted_at")
+_RECON_OWNED = ("reconciliation_id", "at")
 
 _CLAIM_REQUIRED = ("quote", "source_id", "subject", "predicate", "object", "polarity", "confidence")
 _CLAIM_ALLOWED = frozenset((*_CLAIM_REQUIRED, "claim_text", "tags"))
@@ -47,12 +49,16 @@ _ENTITY_REQUIRED = ("entity_id", "name", "kind")
 _ENTITY_ALLOWED = frozenset((*_ENTITY_REQUIRED, "tags"))
 _EDGE_REQUIRED = ("src", "dst", "kind")
 _EDGE_ALLOWED = frozenset(_EDGE_REQUIRED)
+_DECISIONS = ("supersede", "qualify", "keep-both")
+_RECON_REQUIRED = ("decision", "claim_a", "claim_b")
+_RECON_ALLOWED = frozenset((*_RECON_REQUIRED, "winner", "rationale"))
 
 # Same conservative shape ``cli._safe_slug`` enforces — no path separators,
 # '..', or leading dot — applied to source ids arriving as record *data*.
 _SLUG_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
 
 _CLAIM_ID_RE = re.compile(r"clm_(\d+)")
+_RECON_ID_RE = re.compile(r"rec_(\d+)")
 
 
 def _now() -> str:
@@ -96,12 +102,18 @@ def _check_tags(rec: dict, index: int) -> None:
         raise DataError(f"record {index}: 'tags' must be a list of strings")
 
 
-def _check_shape(rec: dict, index: int, required: tuple[str, ...], allowed: frozenset[str]) -> None:
-    owned = [k for k in _SCRIP_OWNED if k in rec]
-    if owned:
+def _check_shape(
+    rec: dict,
+    index: int,
+    required: tuple[str, ...],
+    allowed: frozenset[str],
+    owned: tuple[str, ...] = _SCRIP_OWNED,
+) -> None:
+    present = [k for k in owned if k in rec]
+    if present:
         raise DataError(
-            f"record {index}: scrip mints {', '.join(owned)} itself — propose a "
-            f"verbatim 'quote', not precomputed ids/anchors/timestamps"
+            f"record {index}: scrip mints {', '.join(present)} itself — do not "
+            f"propose precomputed ids/anchors/timestamps"
         )
     unknown = sorted(rec.keys() - allowed)
     if unknown:
@@ -136,10 +148,27 @@ def _validate(table: str, rec: dict, index: int) -> None:
         if not (eid.startswith("entity/") and _SLUG_RE.fullmatch(eid[len("entity/") :])):
             raise DataError(f"record {index}: entity_id must look like entity/<slug>")
         _check_tags(rec, index)
-    else:  # edges
+    elif table == "edges":
         _check_shape(rec, index, _EDGE_REQUIRED, _EDGE_ALLOWED)
         for key in _EDGE_REQUIRED:
             _check_str(rec, key, index)
+    else:  # reconciliations
+        _check_shape(rec, index, _RECON_REQUIRED, _RECON_ALLOWED, owned=_RECON_OWNED)
+        for key in ("decision", "claim_a", "claim_b"):
+            _check_str(rec, key, index)
+        if rec["decision"] not in _DECISIONS:
+            raise DataError(f"record {index}: decision must be one of {', '.join(_DECISIONS)}")
+        if "rationale" in rec:
+            _check_str(rec, "rationale", index, allow_blank=True)
+        # winner is required for (and only for) supersede, and must be one of the pair
+        if rec["decision"] == "supersede":
+            winner = rec.get("winner")
+            if winner not in (rec["claim_a"], rec["claim_b"]):
+                raise DataError(
+                    f"record {index}: supersede needs 'winner' = claim_a or claim_b"
+                )
+        elif "winner" in rec:
+            raise DataError(f"record {index}: 'winner' is only valid for decision 'supersede'")
 
 
 # --------------------------------------------------------------------------- #
@@ -218,6 +247,19 @@ def _read_table(path: Path) -> tuple[list[dict], str]:
     return records, text
 
 
+def claim_source_anchor(root: Path, claim_id: str) -> tuple[str, str]:
+    """Return ``(source_id, anchor)`` for a claim, for `scrip span --claim`.
+    Raises :class:`DataError` if the claim is missing or lacks the fields."""
+    records, _ = _read_table(facts_dir(root) / "claims.ndjson")
+    for rec in records:
+        if rec.get("claim_id") == claim_id:
+            sid, anchor = rec.get("source_id"), rec.get("anchor")
+            if not isinstance(sid, str) or not isinstance(anchor, str):
+                raise DataError(f"claim {claim_id} is missing source_id/anchor")
+            return sid, anchor
+    raise DataError(f"no such claim: {claim_id}")
+
+
 def _claim_key(source_id: str, qh: str, rec: dict) -> tuple:
     return (
         source_id,
@@ -251,6 +293,17 @@ def _next_claim_id(existing: list[dict]) -> tuple[int, int]:
     return highest + 1, max(4, len(str(highest)))
 
 
+def _next_recon_id(existing: list[dict]) -> tuple[int, int]:
+    """Return ``(next_number, pad_width)`` continuing the ``rec_NNNN`` sequence."""
+    numbers = [
+        int(m.group(1))
+        for rec in existing
+        if (m := _RECON_ID_RE.fullmatch(str(rec.get("reconciliation_id", ""))))
+    ]
+    highest = max(numbers, default=0)
+    return highest + 1, max(4, len(str(highest)))
+
+
 # --------------------------------------------------------------------------- #
 # facts/_meta.yaml: merge derived-from, never stamp
 # --------------------------------------------------------------------------- #
@@ -394,7 +447,7 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
                             "detail": "an entity with this id already exists with different fields",
                         }
                     )
-        else:  # edges
+        elif table == "edges":
             seen_edges = {
                 (rec.get("src"), rec.get("dst"), rec.get("kind")) for rec in existing
             }
@@ -405,6 +458,43 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
                     continue
                 seen_edges.add(key)
                 appended.append({"src": rec["src"], "dst": rec["dst"], "kind": rec["kind"]})
+        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):
+                refs = [rec["claim_a"], rec["claim_b"]]
+                if rec["decision"] == "supersede":
+                    refs.append(rec["winner"])
+                missing = next((r for r in refs if r not in claim_ids), None)
+                if missing is not None:
+                    failures.append({
+                        "index": i, "status": "MISSING_CLAIM", "claim": missing,
+                        "detail": f"{missing!r} is not a claim in claims.ndjson",
+                    })
+            if failures:
+                return {"table": table, "appended": [], "skipped": [], "failures": failures}
+            seen_pairs = {frozenset((r.get("claim_a"), r.get("claim_b"))) for r in existing}
+            number, width = _next_recon_id(existing)
+            now = _now()
+            for i, rec in enumerate(proposals):
+                pair = frozenset((rec["claim_a"], rec["claim_b"]))
+                if pair in seen_pairs:
+                    skipped.append({"index": i, "reason": "duplicate", "existing_id": None})
+                    continue
+                seen_pairs.add(pair)
+                rid = f"rec_{number:0{width}d}"
+                number += 1
+                full = {
+                    "reconciliation_id": rid,
+                    "decision": rec["decision"],
+                    "claim_a": rec["claim_a"],
+                    "claim_b": rec["claim_b"],
+                }
+                if rec["decision"] == "supersede":
+                    full["winner"] = rec["winner"]
+                if rec.get("rationale"):
+                    full["rationale"] = rec["rationale"]
+                full["at"] = now
+                appended.append(full)
 
         if failures:
             return {"table": table, "appended": [], "skipped": skipped, "failures": failures}

{scriptoria-0.4.0 → scriptoria-0.5.0}/src/scrip/query.py

@@ -22,15 +22,18 @@ _VIEWS = {
     "claims": "claims.ndjson",
     "entities": "entities.ndjson",
     "edges": "graph.ndjson",
+    "reconciliations": "reconciliations.ndjson",
 }
 
 _NAMED = {
     "claims": "SELECT * FROM claims",
     "entities": "SELECT * FROM entities",
     "edges": "SELECT * FROM edges",
+    "reconciliations": "SELECT * FROM reconciliations",
     # contradiction *candidates*: same subject+predicate, opposing polarity,
-    # from different sources. Detection is deterministic; adjudication is the
-    # agent's job.
+    # from different sources, AND not yet adjudicated (no reconciliation record
+    # for the pair, either order) — so RECONCILE makes the set converge.
+    # Detection is deterministic; adjudication is the agent's job.
     "contradictions": """
         SELECT a.claim_id AS claim_a, b.claim_id AS claim_b,
                a.subject, a.predicate,
@@ -41,10 +44,15 @@ _NAMED = {
         WHERE a.polarity = 'asserts'
           AND b.polarity = 'denies'
           AND a.source_id <> b.source_id
+          AND NOT EXISTS (
+            SELECT 1 FROM reconciliations r
+            WHERE (r.claim_a = a.claim_id AND r.claim_b = b.claim_id)
+               OR (r.claim_a = b.claim_id AND r.claim_b = a.claim_id)
+          )
     """,
 }
 
-_FILTERABLE = {"claims", "entities", "edges"}
+_FILTERABLE = {"claims", "entities", "edges", "reconciliations"}
 
 
 def _connect(root: Path) -> duckdb.DuckDBPyConnection:
@@ -57,6 +65,16 @@ def _connect(root: Path) -> duckdb.DuckDBPyConnection:
                 f"CREATE VIEW {view} AS "
                 f"SELECT * FROM read_ndjson_auto('{p.as_posix()}')"
             )
+        elif view == "reconciliations":
+            # Always present (empty stub) so `contradictions` can anti-join it and
+            # raw SQL over its columns works even before any reconciliation exists.
+            con.execute(
+                "CREATE VIEW reconciliations AS SELECT "
+                "NULL::VARCHAR AS reconciliation_id, NULL::VARCHAR AS decision, "
+                "NULL::VARCHAR AS claim_a, NULL::VARCHAR AS claim_b, "
+                "NULL::VARCHAR AS winner, NULL::VARCHAR AS rationale, "
+                "NULL::VARCHAR AS at WHERE FALSE"
+            )
     return con
 
 

{scriptoria-0.4.0 → scriptoria-0.5.0}/tests/test_fact_cmd.py

@@ -48,6 +48,122 @@ def _claims_lines(kb):
     return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
 
 
+def _recs_lines(kb):
+    p = kb.root / "vault" / "facts" / "reconciliations.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)
+    kb.add_claim("clm_0001", "s", "The quick brown fox jumps over the lazy dog.",
+                 subject="chunking", predicate="discards", polarity="asserts")
+    kb.add_claim("clm_0002", "s", "Caching answers beats recomputing them.",
+                 subject="chunking", predicate="discards", polarity="denies")
+
+
+def _recon(decision, **kw):
+    rec = {"decision": decision, "claim_a": "clm_0001", "claim_b": "clm_0002"}
+    rec.update(kw)
+    return rec
+
+
+# --------------------------------------------------------------------------- #
+# Reconciliations table
+# --------------------------------------------------------------------------- #
+def test_fact_add_reconciliation_supersede(kb, capsys):
+    _two_claims(kb)
+    rc = _run_add(
+        kb,
+        _ndjson(_recon("supersede", winner="clm_0001", rationale="newer source wins")),
+        "--table", "reconciliations", "--json",
+    )
+    assert rc == 0
+    [rec] = _recs_lines(kb)
+    assert rec["reconciliation_id"] == "rec_0001"
+    assert rec["decision"] == "supersede"
+    assert rec["winner"] == "clm_0001"
+    assert rec["claim_a"] == "clm_0001" and rec["claim_b"] == "clm_0002"
+    assert rec["rationale"] == "newer source wins"
+    assert ISO_Z.fullmatch(rec["at"])
+    assert json.loads(capsys.readouterr().out)["appended"][0]["reconciliation_id"] == "rec_0001"
+
+
+def test_fact_add_reconciliation_qualify_and_keep_both(kb):
+    _two_claims(kb)
+    kb.add_claim("clm_0003", "s", "Caching answers beats recomputing them.", subject="x")
+    assert _run_add(kb, _ndjson(_recon("qualify")), "--table", "reconciliations") == 0
+    # a *different* pair so dedup doesn't skip it
+    assert _run_add(kb, _ndjson(_recon("keep-both", claim_b="clm_0003")),
+                    "--table", "reconciliations") == 0
+    recs = _recs_lines(kb)
+    assert [r["decision"] for r in recs] == ["qualify", "keep-both"]
+    assert [r["reconciliation_id"] for r in recs] == ["rec_0001", "rec_0002"]
+    assert all("winner" not in r for r in recs)  # winner only for supersede
+
+
+def test_fact_add_reconciliation_supersede_requires_valid_winner(kb):
+    _two_claims(kb)
+    assert _run_add(kb, _ndjson(_recon("supersede")), "--table", "reconciliations") == 3  # no winner
+    assert _run_add(kb, _ndjson(_recon("supersede", winner="clm_9999")),
+                    "--table", "reconciliations") == 3  # winner not in pair
+
+
+def test_fact_add_reconciliation_winner_forbidden_unless_supersede(kb):
+    _two_claims(kb)
+    assert _run_add(kb, _ndjson(_recon("qualify", winner="clm_0001")),
+                    "--table", "reconciliations") == 3
+
+
+def test_fact_add_reconciliation_bad_decision_is_data_error(kb):
+    _two_claims(kb)
+    assert _run_add(kb, _ndjson(_recon("ignore-it")), "--table", "reconciliations") == 3
+
+
+def test_fact_add_reconciliation_rejects_minted_fields(kb):
+    _two_claims(kb)
+    assert _run_add(kb, _ndjson(_recon("qualify", reconciliation_id="rec_0001")),
+                    "--table", "reconciliations") == 3
+    assert _run_add(kb, _ndjson(_recon("qualify", at="2026-01-01T00:00:00Z")),
+                    "--table", "reconciliations") == 3
+
+
+def test_fact_add_reconciliation_missing_claim_fails(kb, capsys):
+    _two_claims(kb)
+    rc = _run_add(kb, _ndjson(_recon("qualify", claim_b="clm_9999")),
+                  "--table", "reconciliations", "--json")
+    assert rc == 1
+    assert _recs_lines(kb) == []
+    [failure] = json.loads(capsys.readouterr().out)["failures"]
+    assert failure["status"] == "MISSING_CLAIM"
+
+
+def test_fact_add_reconciliation_dedups_unordered_pair(kb, capsys):
+    _two_claims(kb)
+    assert _run_add(kb, _ndjson(_recon("qualify")), "--table", "reconciliations") == 0
+    capsys.readouterr()
+    # same pair, reversed order → already adjudicated → skipped, not re-appended
+    rc = _run_add(
+        kb,
+        _ndjson({"decision": "supersede", "claim_a": "clm_0002", "claim_b": "clm_0001", "winner": "clm_0002"}),
+        "--table", "reconciliations", "--json",
+    )
+    assert rc == 0
+    assert len(_recs_lines(kb)) == 1
+    assert json.loads(capsys.readouterr().out)["skipped"][0]["reason"] == "duplicate"
+
+
+def test_fact_add_reconciliation_id_sequencing(kb):
+    _two_claims(kb)
+    kb.add_claim("clm_0003", "s", "The quick brown fox jumps over the lazy dog.", subject="x")
+    assert _run_add(kb, _ndjson(_recon("qualify")), "--table", "reconciliations") == 0
+    assert _run_add(kb, _ndjson(_recon("keep-both", claim_a="clm_0001", claim_b="clm_0003")),
+                    "--table", "reconciliations") == 0
+    assert [r["reconciliation_id"] for r in _recs_lines(kb)] == ["rec_0001", "rec_0002"]
+
+
 # --------------------------------------------------------------------------- #
 # Happy path
 # --------------------------------------------------------------------------- #

scriptoria-0.5.0/tests/test_query.py

@@ -0,0 +1,109 @@
+import pytest
+from scrip.errors import UsageError
+
+from scrip import cli, query
+
+
+def test_named_claims_query(kb):
+    kb.add_raw("a", "# A\n\nThe sky is blue.\n")
+    kb.add_claim("clm_1", "a", "the sky is blue", subject="sky", tags=["color"])
+    cols, rows = query.run(kb.root, name="claims")
+    assert "subject" in cols
+    assert any(r["claim_id"] == "clm_1" for r in rows)
+
+
+def test_raw_sql_aggregate(kb):
+    kb.add_raw("a", "# A\n\nThe sky is blue.\n")
+    kb.add_claim("clm_1", "a", "the sky is blue")
+    kb.add_claim("clm_2", "a", "the sky is blue")
+    cols, rows = query.run(kb.root, sql="SELECT count(*) AS n FROM claims")
+    assert rows[0]["n"] == 2
+
+
+def test_contradictions_detected(kb):
+    kb.add_raw("a", "# A\n\nThe sky is blue.\n")
+    kb.add_raw("b", "# B\n\nThe sky is not blue.\n")
+    kb.add_claim(
+        "clm_1", "a", "the sky is blue", subject="sky", predicate="color",
+        polarity="asserts",
+    )
+    kb.add_claim(
+        "clm_2", "b", "the sky is not blue", subject="sky", predicate="color",
+        polarity="denies",
+    )
+    cols, rows = query.run(kb.root, name="contradictions")
+    assert len(rows) == 1
+    assert rows[0]["subject"] == "sky"
+    assert {rows[0]["source_a"], rows[0]["source_b"]} == {"raw/a", "raw/b"}
+
+
+def _contradiction_pair(kb):
+    kb.add_raw("a", "# A\n\nThe sky is blue.\n")
+    kb.add_raw("b", "# B\n\nThe sky is not blue.\n")
+    kb.add_claim("clm_1", "a", "the sky is blue", subject="sky", predicate="color", polarity="asserts")
+    kb.add_claim("clm_2", "b", "the sky is not blue", subject="sky", predicate="color", polarity="denies")
+
+
+def test_contradictions_excludes_reconciled_pairs(kb):
+    _contradiction_pair(kb)
+    assert len(query.run(kb.root, name="contradictions")[1]) == 1
+    # record a reconciliation for that pair (reversed order, to test symmetry)
+    (kb.root / "vault" / "facts" / "reconciliations.ndjson").write_text(
+        '{"reconciliation_id":"rec_0001","decision":"supersede","claim_a":"clm_2",'
+        '"claim_b":"clm_1","winner":"clm_2","at":"2026-01-01T00:00:00Z"}\n',
+        encoding="utf-8",
+    )
+    assert query.run(kb.root, name="contradictions")[1] == []  # adjudicated → gone
+
+
+def test_reconciliations_named_query(kb):
+    _contradiction_pair(kb)
+    (kb.root / "vault" / "facts" / "reconciliations.ndjson").write_text(
+        '{"reconciliation_id":"rec_0001","decision":"keep-both","claim_a":"clm_1",'
+        '"claim_b":"clm_2","at":"2026-01-01T00:00:00Z"}\n',
+        encoding="utf-8",
+    )
+    cols, rows = query.run(kb.root, name="reconciliations")
+    assert rows[0]["reconciliation_id"] == "rec_0001"
+    assert rows[0]["decision"] == "keep-both"
+
+
+def test_contradictions_works_without_reconciliations_file(kb):
+    # the reconciliations view is an empty stub when the file is absent
+    _contradiction_pair(kb)
+    assert len(query.run(kb.root, name="contradictions")[1]) == 1
+
+
+def test_query_reconciliations_cli_choice(kb):
+    # the named query must be a valid CLI `query` choice, not just in query.run
+    _contradiction_pair(kb)
+    assert cli.main(["query", "reconciliations", "--json", "--root", str(kb.root)]) == 0
+
+
+def test_reconciliations_stub_exposes_full_schema(kb):
+    # before the file exists, raw SQL over the stub's columns must still work
+    _contradiction_pair(kb)
+    cols, rows = query.run(kb.root, sql="SELECT decision, winner, reconciliation_id FROM reconciliations")
+    assert rows == []
+    assert "decision" in cols
+
+
+def test_where_and_limit(kb):
+    kb.add_raw("a", "# A\n\nThe sky is blue.\n")
+    kb.add_claim("clm_1", "a", "the sky is blue")
+    kb.add_claim("clm_2", "a", "the sky is blue")
+    cols, rows = query.run(kb.root, name="claims", where="claim_id = 'clm_1'", limit=10)
+    assert len(rows) == 1
+    assert rows[0]["claim_id"] == "clm_1"
+
+
+def test_where_rejects_statement_chaining(kb):
+    kb.add_raw("a", "# A\n\nThe sky is blue.\n")
+    kb.add_claim("clm_1", "a", "the sky is blue")
+    with pytest.raises(UsageError):
+        query.run(kb.root, name="claims", where="1=1; DROP TABLE claims")
+
+
+def test_unknown_named_query_is_usage_error(kb):
+    with pytest.raises(UsageError):
+        query.run(kb.root, name="bogus")

scriptoria-0.5.0/tests/test_span_cmd.py

@@ -0,0 +1,86 @@
+"""`scrip span` — resolve an anchor and print the cited text. Read-only; lets an
+agent read both sides of a contradiction (RECONCILE) without re-implementing
+anchor resolution."""
+
+import json
+
+import pytest
+
+from scrip import anchors, cli
+
+SRC = "# H\n\nThe quick brown fox jumps over the lazy dog.\n\nalpha beta. alpha beta.\n"
+
+
+def test_span_prints_cited_text(kb, capsys):
+    kb.add_raw("s", SRC)
+    anchor = anchors.make_anchor(SRC, "The quick brown fox jumps over the lazy dog.")
+    rc = cli.main(["span", f"raw/s#{anchor}", "--root", str(kb.root)])
+    assert rc == 0
+    # the cited span is shown (normalized: lowercased, whitespace-collapsed)
+    assert "the quick brown fox jumps over the lazy dog." in capsys.readouterr().out.lower()
+
+
+def test_span_json_shape(kb, capsys):
+    kb.add_raw("s", SRC)
+    anchor = anchors.make_anchor(SRC, "The quick brown fox jumps over the lazy dog.")
+    rc = cli.main(["span", f"raw/s#{anchor}", "--json", "--root", str(kb.root)])
+    assert rc == 0
+    data = json.loads(capsys.readouterr().out)
+    assert set(data) == {"target", "status", "text"}
+    assert data["status"] == "OK"
+    assert "quick brown fox" in data["text"]
+
+
+def test_span_by_claim_id(kb, capsys):
+    kb.add_raw("s", SRC)
+    kb.add_claim("clm_0001", "s", "The quick brown fox jumps over the lazy dog.")
+    rc = cli.main(["span", "--claim", "clm_0001", "--json", "--root", str(kb.root)])
+    assert rc == 0
+    data = json.loads(capsys.readouterr().out)
+    assert data["status"] == "OK"
+    assert "quick brown fox" in data["text"]
+
+
+def test_span_ambiguous_exits_1(kb, capsys):
+    kb.add_raw("s", SRC)
+    anchor = anchors.make_anchor(SRC, "alpha beta.")  # appears twice
+    rc = cli.main(["span", f"raw/s#{anchor}", "--json", "--root", str(kb.root)])
+    assert rc == 1
+    assert json.loads(capsys.readouterr().out)["status"] == "AMBIGUOUS"
+
+
+def test_span_broken_exits_1(kb, capsys):
+    kb.add_raw("s", SRC)
+    # a well-formed anchor whose quote is absent from the source
+    anchor = anchors.make_anchor("a totally different document about cats", "totally different")
+    rc = cli.main(["span", f"raw/s#{anchor}", "--json", "--root", str(kb.root)])
+    assert rc == 1
+    assert json.loads(capsys.readouterr().out)["status"] == "BROKEN"
+
+
+def test_span_unsafe_source_is_usage_error(kb):
+    kb.add_raw("s", SRC)
+    anchor = anchors.make_anchor(SRC, "The quick brown fox jumps over the lazy dog.")
+    assert cli.main(["span", f"../../etc/passwd#{anchor}", "--root", str(kb.root)]) == 2
+
+
+def test_span_missing_source_is_data_error(kb):
+    kb.add_raw("s", SRC)
+    anchor = anchors.make_anchor(SRC, "The quick brown fox jumps over the lazy dog.")
+    assert cli.main(["span", f"raw/absent#{anchor}", "--root", str(kb.root)]) == 3
+
+
+def test_span_unknown_claim_is_data_error(kb):
+    kb.add_raw("s", SRC)
+    assert cli.main(["span", "--claim", "clm_9999", "--root", str(kb.root)]) == 3
+
+
+def test_span_requires_a_target(kb):
+    with pytest.raises(SystemExit) as e:
+        cli.main(["span", "--root", str(kb.root)])
+    assert e.value.code == 2
+
+
+def test_span_target_without_anchor_is_usage_error(kb):
+    kb.add_raw("s", SRC)
+    assert cli.main(["span", "raw/s", "--root", str(kb.root)]) == 2  # no '#<anchor>'

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

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

scriptoria-0.4.0/tests/test_query.py

@@ -1,58 +0,0 @@
-import pytest
-from scrip.errors import UsageError
-
-from scrip import query
-
-
-def test_named_claims_query(kb):
-    kb.add_raw("a", "# A\n\nThe sky is blue.\n")
-    kb.add_claim("clm_1", "a", "the sky is blue", subject="sky", tags=["color"])
-    cols, rows = query.run(kb.root, name="claims")
-    assert "subject" in cols
-    assert any(r["claim_id"] == "clm_1" for r in rows)
-
-
-def test_raw_sql_aggregate(kb):
-    kb.add_raw("a", "# A\n\nThe sky is blue.\n")
-    kb.add_claim("clm_1", "a", "the sky is blue")
-    kb.add_claim("clm_2", "a", "the sky is blue")
-    cols, rows = query.run(kb.root, sql="SELECT count(*) AS n FROM claims")
-    assert rows[0]["n"] == 2
-
-
-def test_contradictions_detected(kb):
-    kb.add_raw("a", "# A\n\nThe sky is blue.\n")
-    kb.add_raw("b", "# B\n\nThe sky is not blue.\n")
-    kb.add_claim(
-        "clm_1", "a", "the sky is blue", subject="sky", predicate="color",
-        polarity="asserts",
-    )
-    kb.add_claim(
-        "clm_2", "b", "the sky is not blue", subject="sky", predicate="color",
-        polarity="denies",
-    )
-    cols, rows = query.run(kb.root, name="contradictions")
-    assert len(rows) == 1
-    assert rows[0]["subject"] == "sky"
-    assert {rows[0]["source_a"], rows[0]["source_b"]} == {"raw/a", "raw/b"}
-
-
-def test_where_and_limit(kb):
-    kb.add_raw("a", "# A\n\nThe sky is blue.\n")
-    kb.add_claim("clm_1", "a", "the sky is blue")
-    kb.add_claim("clm_2", "a", "the sky is blue")
-    cols, rows = query.run(kb.root, name="claims", where="claim_id = 'clm_1'", limit=10)
-    assert len(rows) == 1
-    assert rows[0]["claim_id"] == "clm_1"
-
-
-def test_where_rejects_statement_chaining(kb):
-    kb.add_raw("a", "# A\n\nThe sky is blue.\n")
-    kb.add_claim("clm_1", "a", "the sky is blue")
-    with pytest.raises(UsageError):
-        query.run(kb.root, name="claims", where="1=1; DROP TABLE claims")
-
-
-def test_unknown_named_query_is_usage_error(kb):
-    with pytest.raises(UsageError):
-        query.run(kb.root, name="bogus")