scriptoria 0.8.1__tar.gz → 0.10.0__tar.gz

{scriptoria-0.8.1 → scriptoria-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: scriptoria
-Version: 0.8.1
+Version: 0.10.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
@@ -51,9 +51,11 @@ uv run --project scrip scrip --help
 
 | Command | What it does |
 |---|---|
+| `scrip init [DIR]` | Create the root skeleton — `vault/{raw,facts,wiki}/` plus the `.kb/` cache and its manifest — in `DIR` (default: the current directory). Idempotent in an existing root; refuses to nest a new instance inside one. |
 | `scrip status` | Report `STALE` / `OK` / `UNCOMPILED` artifacts from the dependency graph. `--no-cache` recomputes from files; `--rebuild-manifest` regenerates the cache. |
 | `scrip verify` | Check every provenance anchor still resolves to text in its source; check referenced sources exist and `claim_id`s are unique. Fails on `BROKEN` and `AMBIGUOUS` by default; `--allow-ambiguous` downgrades `AMBIGUOUS` to a warning. |
 | `scrip query [claims\|entities\|edges\|contradictions\|reconciliations]` | Structured query over `vault/facts/*.ndjson` via DuckDB. `--sql "<duckdb>"`, `--where`, `--limit`. |
+| `scrip ontology` | Validate and summarize optional `vault/ontology.yaml` vocabulary for fact predicates, entity kinds, and edge kinds. |
 | `scrip ingest <url\|file>` | Fetch/read a source and write canonical `vault/raw/<slug>.md` plus sidecar metadata. HTML/PDF need the optional `[ingest]` extra. |
 | `scrip new concept\|entity <slug> --from raw/...` | Scaffold a derived wiki page for the agent to fill. |
 | `scrip anchor "<quote>" --source raw/<slug>` | Mint a content-anchored footnote for a verbatim source quote. |
@@ -66,7 +68,8 @@ uv run --project scrip scrip --help
 | `scrip pageindex search "<question>" [--source raw/<slug>]` | Search cached PageIndex sections, returning only snippets mapped back to canonical `vault/raw/` text. |
 | `scrip watch` / `scrip unlock` | Watch vault health in a poll loop; clear a stale advisory write lock. |
 
-Every command accepts `--root DIR` and `--json`.
+Every command accepts `--root DIR` and `--json` (`init` takes its target as a
+positional path instead of `--root`).
 
 The optional `scrip-harness` package adds the model-bearing commands, including
 `scrip-harness answer "<question>"`, which gathers evidence with these primitives

{scriptoria-0.8.1 → scriptoria-0.10.0}/README.md

@@ -20,9 +20,11 @@ uv run --project scrip scrip --help
 
 | Command | What it does |
 |---|---|
+| `scrip init [DIR]` | Create the root skeleton — `vault/{raw,facts,wiki}/` plus the `.kb/` cache and its manifest — in `DIR` (default: the current directory). Idempotent in an existing root; refuses to nest a new instance inside one. |
 | `scrip status` | Report `STALE` / `OK` / `UNCOMPILED` artifacts from the dependency graph. `--no-cache` recomputes from files; `--rebuild-manifest` regenerates the cache. |
 | `scrip verify` | Check every provenance anchor still resolves to text in its source; check referenced sources exist and `claim_id`s are unique. Fails on `BROKEN` and `AMBIGUOUS` by default; `--allow-ambiguous` downgrades `AMBIGUOUS` to a warning. |
 | `scrip query [claims\|entities\|edges\|contradictions\|reconciliations]` | Structured query over `vault/facts/*.ndjson` via DuckDB. `--sql "<duckdb>"`, `--where`, `--limit`. |
+| `scrip ontology` | Validate and summarize optional `vault/ontology.yaml` vocabulary for fact predicates, entity kinds, and edge kinds. |
 | `scrip ingest <url\|file>` | Fetch/read a source and write canonical `vault/raw/<slug>.md` plus sidecar metadata. HTML/PDF need the optional `[ingest]` extra. |
 | `scrip new concept\|entity <slug> --from raw/...` | Scaffold a derived wiki page for the agent to fill. |
 | `scrip anchor "<quote>" --source raw/<slug>` | Mint a content-anchored footnote for a verbatim source quote. |
@@ -35,7 +37,8 @@ uv run --project scrip scrip --help
 | `scrip pageindex search "<question>" [--source raw/<slug>]` | Search cached PageIndex sections, returning only snippets mapped back to canonical `vault/raw/` text. |
 | `scrip watch` / `scrip unlock` | Watch vault health in a poll loop; clear a stale advisory write lock. |
 
-Every command accepts `--root DIR` and `--json`.
+Every command accepts `--root DIR` and `--json` (`init` takes its target as a
+positional path instead of `--root`).
 
 The optional `scrip-harness` package adds the model-bearing commands, including
 `scrip-harness answer "<question>"`, which gathers evidence with these primitives

{scriptoria-0.8.1 → scriptoria-0.10.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.8.1"
+version = "0.10.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.8.1 → scriptoria-0.10.0}/src/scrip/__init__.py

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

{scriptoria-0.8.1 → scriptoria-0.10.0}/src/scrip/blocks.py

@@ -38,43 +38,45 @@ def split_blocks(text: str) -> list[dict]:
     # 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
+    # Emit blocks in a single pass: a running [cur_start, cur_end] paragraph is
+    # flushed at each boundary, so no intermediate `ranges` list is allocated.
+    out: list[dict] = []
+    seen: dict[str, int] = {}
+
+    def emit(s: int, e: int) -> None:
+        slice_text = text[s:e]
+        out.append(
+            {
+                "block_id": _block_id(slice_text, seen),
+                "span": [s, e],
+                "hash": hashing.sha256_text(slice_text),
+            }
+        )
+
+    cur_start: int | None = None
+    cur_end = 0
     start = 0
 
     for line in text.splitlines(keepends=True):
         end = start + len(line)
         if _is_blank(line):
-            if cur is not None:
-                ranges.append(cur)
-                cur = None
+            if cur_start is not None:
+                emit(cur_start, cur_end)
+                cur_start = None
         elif _is_heading(line):
-            if cur is not None:
-                ranges.append(cur)
-                cur = None
-            ranges.append([start, end])  # a heading is its own block
+            if cur_start is not None:
+                emit(cur_start, cur_end)
+                cur_start = None
+            emit(start, end)  # a heading is its own block
         else:
-            if cur is None:
-                cur = [start, end]
-            else:
-                cur[1] = end
+            if cur_start is None:
+                cur_start = start
+            cur_end = end
         start = end
 
-    if cur is not None:
-        ranges.append(cur)
+    if cur_start is not None:
+        emit(cur_start, cur_end)
 
-    out: list[dict] = []
-    seen: dict[str, int] = {}
-    for s, e in ranges:
-        slice_text = text[s:e]
-        block_id = _block_id(slice_text, seen)
-        out.append(
-            {
-                "block_id": block_id,
-                "span": [s, e],
-                "hash": hashing.sha256_text(slice_text),
-            }
-        )
     return out
 
 

{scriptoria-0.8.1 → scriptoria-0.10.0}/src/scrip/cli.py

@@ -35,12 +35,20 @@ def _safe_slug(slug: str, what: str = "slug") -> str:
 # --------------------------------------------------------------------------- #
 # Root resolution
 # --------------------------------------------------------------------------- #
+def _looks_like_root(cand: Path) -> bool:
+    """True if ``cand`` looks like a scriptorium instance root: a directory
+    containing ``vault/`` plus either ``SPEC.md`` or ``.kb/``."""
+    return (cand / "vault").is_dir() and (
+        (cand / "SPEC.md").exists() or (cand / ".kb").is_dir()
+    )
+
+
 def resolve_root(root_arg: str | None) -> Path:
     """Return the scriptorium root.
 
     With ``--root`` the path is used verbatim (must be a directory). Otherwise we
-    walk up from the cwd for the nearest ancestor that looks like an instance: a
-    directory containing ``vault/`` plus either ``SPEC.md`` or ``.kb/``.
+    walk up from the cwd for the nearest ancestor that looks like an instance
+    (see :func:`_looks_like_root`).
     """
     if root_arg:
         root = Path(root_arg).expanduser().resolve()
@@ -50,13 +58,12 @@ def resolve_root(root_arg: str | None) -> Path:
 
     cur = Path.cwd().resolve()
     for cand in (cur, *cur.parents):
-        if (cand / "vault").is_dir() and (
-            (cand / "SPEC.md").exists() or (cand / ".kb").is_dir()
-        ):
+        if _looks_like_root(cand):
             return cand
     raise errors.UsageError(
         "could not locate a scriptorium root (looked for a parent with vault/ and "
-        "SPEC.md or .kb/). Pass --root explicitly."
+        "SPEC.md or .kb/). Run `scrip init` to start one here, or pass --root "
+        "explicitly."
     )
 
 
@@ -68,6 +75,58 @@ def _emit(payload: dict) -> None:
 # --------------------------------------------------------------------------- #
 # Subcommand handlers  ->  return an int exit code
 # --------------------------------------------------------------------------- #
+def cmd_init(args: argparse.Namespace) -> int:
+    from . import graph, manifest_path
+
+    target = Path(args.path or ".").expanduser().resolve()
+    if target.exists() and not target.is_dir():
+        raise errors.UsageError(f"init target is not a directory: {target}")
+    if _looks_like_root(target):
+        if args.json:
+            _emit({"root": str(target), "status": "exists", "created": []})
+        else:
+            print(f"already a scriptorium root: {target} (nothing to do)")
+        return 0
+    # Refuse to create a nested instance: an inner vault/ would shadow the outer
+    # root for every command run beneath it (resolve_root stops at the nearest
+    # ancestor).
+    for cand in target.parents:
+        if _looks_like_root(cand):
+            raise errors.UsageError(
+                f"refusing to create a nested scriptorium: {target} is inside the "
+                f"root at {cand}. Run `scrip init` at that root, or pick a "
+                f"directory outside it."
+            )
+
+    created: list[str] = []
+    for rel in ("vault/raw", "vault/facts", "vault/wiki", ".kb"):
+        d = target / rel
+        if d.is_dir():
+            continue
+        if d.exists():
+            raise errors.UsageError(
+                f"cannot create {rel}/: a file already exists at {d}"
+            )
+        d.mkdir(parents=True, exist_ok=True)
+        created.append(rel + "/")
+    # Same as `scrip status --rebuild-manifest`: scan the (empty) vault and write
+    # the .kb/manifest.json cache, so the instance starts warm and detectable.
+    graph.compute_status(target, rebuild=True)
+    created.append(str(manifest_path(target).relative_to(target)))
+
+    if args.json:
+        _emit({"root": str(target), "status": "initialized", "created": created})
+    else:
+        print(f"initialized scriptorium root at {target}")
+        for c in created:
+            print(f"  + {c}")
+        print(
+            "  next: add a source (`scrip ingest <url|file>`), compile a page "
+            "(`scrip new` + `scrip anchor` + `scrip stamp`), then `scrip verify`"
+        )
+    return 0
+
+
 def cmd_status(args: argparse.Namespace) -> int:
     from . import graph
 
@@ -493,6 +552,25 @@ def cmd_fact_add(args: argparse.Namespace) -> int:
     return 1 if result["failures"] else 0
 
 
+def cmd_ontology(args: argparse.Namespace) -> int:
+    from . import ontology
+
+    root = resolve_root(args.root)
+    ont = ontology.load(root)
+    result = {"path": str(ontology.ontology_path(root).relative_to(root)), **ont.summary()}
+    if args.json:
+        _emit(result)
+    else:
+        state = "active" if ont.active else "not present or empty"
+        print(f"ontology: {state}")
+        if ont.active:
+            print(f"  entity kinds: {', '.join(result['entity_kinds']) or '(none)'}")
+            print(f"  edge kinds: {', '.join(result['edge_kinds']) or '(none)'}")
+            print(f"  claim predicates: {', '.join(result['claim_predicates']) or '(none)'}")
+            print(f"  predicate aliases: {len(result['predicate_aliases'])}")
+    return 0
+
+
 def cmd_ingest(args: argparse.Namespace) -> int:
     from . import ingest, lock
 
@@ -536,6 +614,21 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--version", action="version", version=f"scrip {__version__}")
     sub = p.add_subparsers(dest="command", required=True, metavar="<command>")
 
+    pinit = sub.add_parser(
+        "init",
+        help="create the root skeleton (vault/{raw,facts,wiki}/ + .kb/ cache) and its manifest",
+    )
+    pinit.add_argument(
+        "path",
+        nargs="?",
+        metavar="DIR",
+        help="directory to initialize (default: current directory; created if absent)",
+    )
+    pinit.add_argument(
+        "--json", action="store_true", help="machine-readable JSON output"
+    )
+    pinit.set_defaults(func=cmd_init)
+
     ps = sub.add_parser(
         "status",
         parents=[common],
@@ -764,6 +857,13 @@ def build_parser() -> argparse.ArgumentParser:
     )
     pfa.set_defaults(func=cmd_fact_add)
 
+    po = sub.add_parser(
+        "ontology",
+        parents=[common],
+        help="validate and summarize optional vault/ontology.yaml vocabulary",
+    )
+    po.set_defaults(func=cmd_ontology)
+
     pin = sub.add_parser(
         "ingest",
         parents=[common],

{scriptoria-0.8.1 → scriptoria-0.10.0}/src/scrip/facts.py

@@ -34,6 +34,8 @@ except ImportError:
 
 from . import anchors, facts_dir, lock
 from .errors import DataError, UsageError
+from .ontology import Ontology
+from .ontology import load as load_ontology
 
 _POLARITIES = ("asserts", "denies", "qualifies")
 
@@ -52,7 +54,7 @@ _RECON_OWNED = ("reconciliation_id", "at")
 _CLAIM_REQUIRED = ("quote", "source_id", "subject", "predicate", "object", "polarity", "confidence")
 _CLAIM_ALLOWED = frozenset((*_CLAIM_REQUIRED, "claim_text", "tags"))
 _ENTITY_REQUIRED = ("entity_id", "name", "kind")
-_ENTITY_ALLOWED = frozenset((*_ENTITY_REQUIRED, "tags"))
+_ENTITY_ALLOWED = frozenset((*_ENTITY_REQUIRED, "tags", "uri", "same_as", "external_ids"))
 _EDGE_REQUIRED = ("src", "dst", "kind")
 # An edge may optionally be *cited*: a verbatim ``quote`` + ``source_id`` whose
 # ``anchor`` scrip mints+verifies exactly as for a claim. Bare edges stay
@@ -127,6 +129,26 @@ def _check_tags(rec: dict, index: int) -> None:
         raise DataError(f"record {index}: 'tags' must be a list of strings")
 
 
+def _check_string_list(rec: dict, key: str, index: int) -> None:
+    values = rec.get(key)
+    if values is None:
+        return
+    if not isinstance(values, list) or any(not isinstance(v, str) or not v.strip() for v in values):
+        raise DataError(f"record {index}: '{key}' must be a list of non-empty strings")
+
+
+def _check_string_map(rec: dict, key: str, index: int) -> None:
+    values = rec.get(key)
+    if values is None:
+        return
+    if (
+        not isinstance(values, dict)
+        or any(not isinstance(k, str) or not k.strip() for k in values)
+        or any(not isinstance(v, str) or not v.strip() for v in values.values())
+    ):
+        raise DataError(f"record {index}: '{key}' must be a mapping of strings to strings")
+
+
 def _check_shape(
     rec: dict,
     index: int,
@@ -148,13 +170,14 @@ def _check_shape(
         raise DataError(f"record {index}: missing required field(s): {', '.join(missing)}")
 
 
-def _validate(table: str, rec: dict, index: int) -> None:
+def _validate(table: str, rec: dict, index: int, ont: Ontology) -> None:
     if table == "claims":
         _check_shape(rec, index, _CLAIM_REQUIRED, _CLAIM_ALLOWED)
         # the quote's *emptiness* is a per-record finding, not a schema error
         _check_str(rec, "quote", index, allow_blank=True)
         for key in ("source_id", "subject", "predicate", "object"):
             _check_str(rec, key, index)
+        rec["predicate"] = ont.canonical_claim_predicate(rec["predicate"], index)
         if "claim_text" in rec:
             _check_str(rec, "claim_text", index, allow_blank=True)
         if rec["polarity"] not in _POLARITIES:
@@ -169,14 +192,20 @@ def _validate(table: str, rec: dict, index: int) -> None:
         _check_shape(rec, index, _ENTITY_REQUIRED, _ENTITY_ALLOWED)
         for key in _ENTITY_REQUIRED:
             _check_str(rec, key, index)
+        ont.validate_entity_kind(rec["kind"], index)
         eid = rec["entity_id"]
         if not (eid.startswith("entity/") and _SLUG_RE.fullmatch(eid[len("entity/") :])):
             raise DataError(f"record {index}: entity_id must look like entity/<slug>")
+        if "uri" in rec:
+            _check_str(rec, "uri", index)
+        _check_string_list(rec, "same_as", index)
+        _check_string_map(rec, "external_ids", index)
         _check_tags(rec, index)
     elif table == "edges":
         _check_shape(rec, index, _EDGE_REQUIRED, _EDGE_ALLOWED)
         for key in _EDGE_REQUIRED:
             _check_str(rec, key, index)
+        ont.validate_edge_kind(rec["kind"], 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]
@@ -383,10 +412,7 @@ def _load_meta(root: Path) -> dict:
 
 def _write_meta(root: Path, data: dict, new_sources: list[str]) -> None:
     derived = list(data.get("derived-from") or [])
-    for sid in new_sources:
-        if sid not in derived:
-            derived.append(sid)
-    data["derived-from"] = derived
+    data["derived-from"] = list(dict.fromkeys(derived + new_sources))
     # Drop the stamp on EVERY append: with an unchanged derived-from the
     # recomputed input-hash would still match the stored one, and status would
     # report OK over facts nobody has blessed. Removing input-hash forces STALE
@@ -410,8 +436,9 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
     """
     if table not in _FILES:
         raise UsageError(f"unknown facts table: {table}")
+    ont = load_ontology(root)
     for i, rec in enumerate(proposals):
-        _validate(table, rec, i)
+        _validate(table, rec, i, ont)
 
     failures: list[dict] = []
     resolved: list[dict | None] = [None] * len(proposals)
@@ -470,12 +497,16 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
                 appended.append(full)
         elif table == "entities":
             def canon(rec: dict) -> dict:
-                return {
+                out = {
                     "entity_id": rec["entity_id"],
                     "name": rec["name"],
                     "kind": rec["kind"],
                     "tags": rec.get("tags") or [],
                 }
+                for key in ("uri", "same_as", "external_ids"):
+                    if key in rec:
+                        out[key] = rec[key]
+                return out
 
             byid = {rec.get("entity_id"): canon(rec) for rec in existing if "entity_id" in rec
                     and isinstance(rec.get("name"), str) and isinstance(rec.get("kind"), str)}
@@ -562,12 +593,12 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
                 if not ends_with_newline:
                     f.write("\n")
                 f.write(payload)
-            new_sources: list[str] = []
+            new_sources_dict: dict[str, None] = {}
             if table in ("claims", "edges"):
                 for rec in appended:
                     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)
+                    if sid:
+                        new_sources_dict[sid] = None
+            _write_meta(root, meta, list(new_sources_dict.keys()))
 
     return {"table": table, "appended": appended, "skipped": skipped, "failures": []}

scriptoria-0.10.0/src/scrip/ontology.py

@@ -0,0 +1,162 @@
+"""Optional semantic vocabulary for the facts layer.
+
+The ontology is deliberately small and file-native. If ``vault/ontology.yaml`` is
+absent, facts behave exactly as before. If present, it constrains selected free
+text fields and can canonicalize claim predicates via aliases.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .errors import DataError
+
+try:
+    from yaml import CSafeLoader as SafeLoader
+except ImportError:
+    from yaml import SafeLoader
+
+_ONTOLOGY_KEYS = frozenset(
+    ("entity_kinds", "edge_kinds", "claim_predicates", "predicate_aliases")
+)
+
+
+@dataclass(frozen=True)
+class Ontology:
+    entity_kinds: frozenset[str] = frozenset()
+    edge_kinds: frozenset[str] = frozenset()
+    claim_predicates: frozenset[str] = frozenset()
+    predicate_aliases: dict[str, str] | None = None
+
+    @property
+    def active(self) -> bool:
+        return bool(
+            self.entity_kinds
+            or self.edge_kinds
+            or self.claim_predicates
+            or self.predicate_aliases
+        )
+
+    def canonical_claim_predicate(self, predicate: str, index: int) -> str:
+        aliases = self.predicate_aliases or {}
+        canonical = aliases.get(predicate, predicate)
+        if self.claim_predicates and canonical not in self.claim_predicates:
+            raise DataError(
+                f"record {index}: predicate {predicate!r} is not in "
+                f"vault/ontology.yaml claim_predicates"
+            )
+        return canonical
+
+    def validate_entity_kind(self, kind: str, index: int) -> None:
+        if self.entity_kinds and kind not in self.entity_kinds:
+            raise DataError(
+                f"record {index}: entity kind {kind!r} is not in "
+                f"vault/ontology.yaml entity_kinds"
+            )
+
+    def validate_edge_kind(self, kind: str, index: int) -> None:
+        if self.edge_kinds and kind not in self.edge_kinds:
+            raise DataError(
+                f"record {index}: edge kind {kind!r} is not in "
+                f"vault/ontology.yaml edge_kinds"
+            )
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "active": self.active,
+            "entity_kinds": sorted(self.entity_kinds),
+            "edge_kinds": sorted(self.edge_kinds),
+            "claim_predicates": sorted(self.claim_predicates),
+            "predicate_aliases": dict(sorted((self.predicate_aliases or {}).items())),
+        }
+
+
+def ontology_path(root: Path) -> Path:
+    return root / "vault" / "ontology.yaml"
+
+
+def load(root: Path) -> Ontology:
+    path = ontology_path(root)
+    if not path.exists():
+        return Ontology()
+    try:
+        data = yaml.load(path.read_text(encoding="utf-8"), Loader=SafeLoader)
+    except yaml.YAMLError as e:
+        raise DataError(f"invalid vault/ontology.yaml: {e}") from e
+    if data is None:
+        return Ontology()
+    if not isinstance(data, dict):
+        raise DataError("invalid vault/ontology.yaml: expected a mapping")
+    _check_known_keys(data)
+
+    entity_kinds = _string_set(data, "entity_kinds")
+    edge_kinds = _string_set(data, "edge_kinds")
+    claim_predicates = _string_set(data, "claim_predicates")
+    predicate_aliases = _string_map(data, "predicate_aliases")
+    if claim_predicates:
+        for alias, target in predicate_aliases.items():
+            if target not in claim_predicates:
+                raise DataError(
+                    "invalid vault/ontology.yaml: predicate_aliases target "
+                    f"{target!r} for {alias!r} is not in claim_predicates"
+                )
+
+    return Ontology(
+        entity_kinds=frozenset(entity_kinds),
+        edge_kinds=frozenset(edge_kinds),
+        claim_predicates=frozenset(claim_predicates),
+        predicate_aliases=predicate_aliases,
+    )
+
+
+def _check_known_keys(data: dict) -> None:
+    unknown = [key for key in data if not isinstance(key, str) or key not in _ONTOLOGY_KEYS]
+    if unknown:
+        rendered = ", ".join(repr(key) for key in unknown)
+        expected = ", ".join(sorted(_ONTOLOGY_KEYS))
+        raise DataError(
+            f"invalid vault/ontology.yaml: unknown key(s): {rendered}; expected one of: "
+            f"{expected}"
+        )
+
+
+def _string_set(data: dict, key: str) -> set[str]:
+    value = data.get(key, [])
+    if value is None:
+        return set()
+    if not isinstance(value, list):
+        raise DataError(f"invalid vault/ontology.yaml: {key} must be a list of strings")
+    out: set[str] = set()
+    for i, item in enumerate(value):
+        if not isinstance(item, str) or not item.strip():
+            raise DataError(
+                f"invalid vault/ontology.yaml: {key}[{i}] must be a non-empty string"
+            )
+        out.add(item.strip())
+    return out
+
+
+def _string_map(data: dict, key: str) -> dict[str, str]:
+    value = data.get(key, {})
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise DataError(
+            f"invalid vault/ontology.yaml: {key} must be a mapping of strings to strings"
+        )
+    out: dict[str, str] = {}
+    for raw_k, raw_v in value.items():
+        if not isinstance(raw_k, str) or not raw_k.strip():
+            raise DataError(
+                f"invalid vault/ontology.yaml: {key} keys must be non-empty strings"
+            )
+        if not isinstance(raw_v, str) or not raw_v.strip():
+            raise DataError(
+                f"invalid vault/ontology.yaml: {key}.{raw_k} must be a non-empty string"
+            )
+        out[raw_k.strip()] = raw_v.strip()
+    return out

{scriptoria-0.8.1 → scriptoria-0.10.0}/tests/test_fact_cmd.py

@@ -68,6 +68,17 @@ def _graph_lines(kb):
     return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
 
 
+def _entities_lines(kb):
+    p = kb.root / "vault" / "facts" / "entities.ndjson"
+    if not p.exists():
+        return []
+    return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
+
+
+def _write_ontology(kb, text):
+    (kb.root / "vault" / "ontology.yaml").write_text(text, encoding="utf-8")
+
+
 def _two_claims(kb):
     """Seed a contradiction pair to reconcile."""
     kb.add_raw("s", SRC)
@@ -244,6 +255,38 @@ def test_fact_add_json_reports_appended_records(kb, capsys):
     assert rec["anchor"].startswith("qh:")
 
 
+def test_fact_add_ontology_canonicalizes_claim_predicate_aliases(kb):
+    kb.add_raw("s", SRC)
+    _write_ontology(
+        kb,
+        """
+claim_predicates:
+  - caches
+predicate_aliases:
+  p: caches
+""",
+    )
+    rc = _run_add(
+        kb,
+        _ndjson(_claim("Caching answers beats recomputing them.", predicate="p")),
+    )
+    assert rc == 0
+    assert _claims_lines(kb)[0]["predicate"] == "caches"
+
+
+def test_fact_add_ontology_rejects_unknown_claim_predicate(kb):
+    kb.add_raw("s", SRC)
+    _write_ontology(kb, "claim_predicates:\n  - caches\n")
+
+    rc = _run_add(
+        kb,
+        _ndjson(_claim("Caching answers beats recomputing them.", predicate="p")),
+    )
+
+    assert rc == 3
+    assert _claims_lines(kb) == []
+
+
 # --------------------------------------------------------------------------- #
 # All-or-nothing batch + per-record failures (exit 1)
 # --------------------------------------------------------------------------- #
@@ -483,6 +526,93 @@ def test_fact_add_entities_appends_and_conflicts(kb, capsys):
     assert len(lines.splitlines()) == 1  # nothing else was appended
 
 
+def test_fact_add_entities_accept_optional_uri_metadata(kb):
+    ent = {
+        "entity_id": "entity/duckdb",
+        "name": "DuckDB",
+        "kind": "tool",
+        "uri": "https://duckdb.org/",
+        "same_as": ["https://www.wikidata.org/wiki/Q118533698"],
+        "external_ids": {"wikidata": "Q118533698"},
+    }
+
+    assert _run_add(kb, _ndjson(ent), "--table", "entities") == 0
+
+    [stored] = _entities_lines(kb)
+    assert stored["uri"] == "https://duckdb.org/"
+    assert stored["same_as"] == ["https://www.wikidata.org/wiki/Q118533698"]
+    assert stored["external_ids"] == {"wikidata": "Q118533698"}
+
+
+def test_fact_add_ontology_rejects_unknown_entity_kind_and_edge_kind(kb):
+    _write_ontology(
+        kb,
+        """
+entity_kinds:
+  - tool
+edge_kinds:
+  - depends-on
+""",
+    )
+
+    assert (
+        _run_add(
+            kb,
+            _ndjson({"entity_id": "entity/a", "name": "A", "kind": "concept"}),
+            "--table",
+            "entities",
+        )
+        == 3
+    )
+    assert _run_add(kb, _ndjson(_edge(kind="relates-to")), "--table", "edges") == 3
+    assert _run_add(kb, _ndjson(_edge(kind="depends-on")), "--table", "edges") == 0
+
+
+def test_ontology_command_reports_optional_vocabulary(kb, capsys):
+    _write_ontology(
+        kb,
+        """
+entity_kinds:
+  - tool
+edge_kinds:
+  - depends-on
+claim_predicates:
+  - caches
+predicate_aliases:
+  p: caches
+""",
+    )
+
+    assert cli.main(["ontology", "--json", "--root", str(kb.root)]) == 0
+
+    data = json.loads(capsys.readouterr().out)
+    assert data["active"] is True
+    assert data["entity_kinds"] == ["tool"]
+    assert data["edge_kinds"] == ["depends-on"]
+    assert data["claim_predicates"] == ["caches"]
+    assert data["predicate_aliases"] == {"p": "caches"}
+
+
+def test_ontology_rejects_alias_to_unknown_predicate(kb):
+    _write_ontology(
+        kb,
+        """
+claim_predicates:
+  - caches
+predicate_aliases:
+  p: stores
+""",
+    )
+
+    assert cli.main(["ontology", "--root", str(kb.root)]) == 3
+
+
+def test_ontology_rejects_unknown_top_level_key(kb):
+    _write_ontology(kb, "claim_predicate:\n  - caches\n")
+
+    assert cli.main(["ontology", "--root", str(kb.root)]) == 3
+
+
 def test_fact_add_edges_appends_and_skips_duplicates(kb):
     edge = {"src": "entity/duckdb", "dst": "entity/motherduck", "kind": "made-by"}
     assert _run_add(kb, _ndjson(edge), "--table", "edges") == 0

scriptoria-0.10.0/tests/test_init_cmd.py

@@ -0,0 +1,102 @@
+"""`scrip init` — create the root skeleton (vault/ layers + .kb/ cache) so a new
+instance starts detectable and green. Idempotent in an existing root; refuses to
+nest a new instance inside an existing one."""
+
+import json
+
+from scrip import cli, manifest_path
+
+
+def test_init_creates_skeleton_and_manifest(tmp_path, capsys):
+    root = tmp_path / "kb"
+    assert cli.main(["init", str(root)]) == 0
+    for rel in ("vault/raw", "vault/facts", "vault/wiki", ".kb"):
+        assert (root / rel).is_dir()
+    # same effect as `scrip status --rebuild-manifest`: the cache exists
+    assert manifest_path(root).exists()
+    out = capsys.readouterr().out
+    assert f"initialized scriptorium root at {root}" in out
+    assert "scrip ingest" in out  # next-steps hint: ingest -> compile -> verify
+    assert "scrip verify" in out
+
+
+def test_init_defaults_to_cwd(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    assert cli.main(["init"]) == 0
+    assert (tmp_path / "vault" / "raw").is_dir()
+    assert (tmp_path / ".kb").is_dir()
+
+
+def test_init_then_commands_resolve_root_without_flags(tmp_path, monkeypatch):
+    """The dogfooding gap this command closes: after init, `scrip status` and
+    `scrip verify` run green from inside the new root with no --root."""
+    root = tmp_path / "kb"
+    assert cli.main(["init", str(root)]) == 0
+    monkeypatch.chdir(root)
+    assert cli.main(["status"]) == 0
+    assert cli.main(["verify"]) == 0
+
+
+def test_init_existing_root_is_noop(tmp_path, capsys):
+    root = tmp_path / "kb"
+    assert cli.main(["init", str(root)]) == 0
+    manifest_before = manifest_path(root).read_text(encoding="utf-8")
+    capsys.readouterr()
+    assert cli.main(["init", str(root)]) == 0
+    out = capsys.readouterr().out
+    assert f"already a scriptorium root: {root}" in out
+    # a true no-op: the manifest was not rewritten
+    assert manifest_path(root).read_text(encoding="utf-8") == manifest_before
+
+
+def test_init_detects_spec_marker_root_as_existing(kb, capsys):
+    """A root marked by SPEC.md (no .kb/ needed) counts as already initialized."""
+    assert cli.main(["init", str(kb.root)]) == 0
+    assert "already a scriptorium root" in capsys.readouterr().out
+
+
+def test_init_inside_existing_root_refused_exit_2(tmp_path):
+    root = tmp_path / "kb"
+    assert cli.main(["init", str(root)]) == 0
+    nested = root / "vault" / "raw" / "sub"
+    assert cli.main(["init", str(nested)]) == 2
+    # nothing was created for the refused nested instance
+    assert not nested.exists()
+
+
+def test_init_target_is_a_file_exit_2(tmp_path):
+    f = tmp_path / "notes.md"
+    f.write_text("hi\n", encoding="utf-8")
+    assert cli.main(["init", str(f)]) == 2
+
+
+def test_init_fills_in_missing_layers(tmp_path):
+    """A partial layout (vault/ alone is not a detectable root) is completed
+    rather than refused."""
+    root = tmp_path / "kb"
+    (root / "vault" / "raw").mkdir(parents=True)
+    assert cli.main(["init", str(root)]) == 0
+    for rel in ("vault/facts", "vault/wiki", ".kb"):
+        assert (root / rel).is_dir()
+
+
+def test_init_layer_path_is_a_file_refused_exit_2(tmp_path):
+    """A file squatting a layer path is refused cleanly (exit 2), not an
+    uncaught FileExistsError mapped to the internal-error exit code."""
+    root = tmp_path / "kb"
+    (root / "vault").mkdir(parents=True)
+    (root / "vault" / "facts").write_text("oops\n", encoding="utf-8")
+    assert cli.main(["init", str(root)]) == 2
+
+
+def test_init_json_shape(tmp_path, capsys):
+    root = tmp_path / "kb"
+    assert cli.main(["init", "--json", str(root)]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert set(data) == {"root", "status", "created"}
+    assert data["status"] == "initialized"
+    assert ".kb/manifest.json" in data["created"]
+    assert cli.main(["init", "--json", str(root)]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert data["status"] == "exists"
+    assert data["created"] == []

{scriptoria-0.8.1 → scriptoria-0.10.0}/uv.lock

@@ -249,7 +249,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -1141,7 +1141,7 @@ wheels = [
 
 [[package]]
 name = "scriptoria"
-version = "0.8.1"
+version = "0.10.0"
 source = { editable = "." }
 dependencies = [
     { name = "duckdb" },