lorekeep 0.1.0__py3-none-any.whl

lorekeep/__init__.py

@@ -0,0 +1,3 @@
+"""Lorekeep — temporal knowledge graph for AI agents via MCP."""
+
+__version__ = "0.1.0"

lorekeep/cli.py

@@ -0,0 +1,229 @@
+"""Lorekeep CLI."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import typer
+
+from lorekeep import __version__
+from lorekeep.compile.providers import FakeProvider, LiteLLMProvider
+from lorekeep.config import load_config
+from lorekeep.pipeline import compile_graph
+from lorekeep.paths import resolve_paths
+from lorekeep.defaults import DEFAULT_CONFIG_YAML, DEFAULT_SCHEMA
+from lorekeep.schema_io import load_schema
+
+app = typer.Typer(help="Lorekeep — compile team docs into a temporal knowledge graph.")
+
+
+# Empty callback forces multi-command mode so subcommands are not auto-promoted.
+@app.callback()
+def _main() -> None:
+    """Lorekeep — compile team docs into a temporal knowledge graph."""
+
+
+
+@app.command()
+def version() -> None:
+    """Print the Lorekeep version."""
+    typer.echo(f"lorekeep {__version__}")
+
+
+@app.command()
+def compile() -> None:
+    """Compile raw/ into graph/facts.jsonl."""
+    p = resolve_paths()
+    schema = load_schema(p["schema"])
+    config = load_config(p["config"])
+
+    if os.environ.get("LOREKEEP_PROVIDER") == "fake":
+        canned = json.dumps({
+            "nodes": [
+                {"id": "svc:payments-api", "type": "service", "name": "payments-api",
+                 "props": {"lang": "go"}, "valid_from": "2024-01-15"},
+                {"id": "svc:auth", "type": "service", "name": "auth"},
+                {"id": "team:backend", "type": "team", "name": "team-backend"},
+                {"id": "dec:adr-007", "type": "decision",
+                 "props": {"title": "payments-api adopts internal signing"}},
+            ],
+            "edges": [
+                {"type": "depends_on", "from": "svc:payments-api", "to": "svc:auth",
+                 "valid_from": "2024-01-15", "valid_to": "2025-03-01"},
+                {"type": "decided_by", "from": "dec:adr-007", "to": "team:backend"},
+            ],
+            "aliases": {},
+        })
+        provider = FakeProvider(responses=[canned])
+    else:
+        api_key = None
+        if config.provider.api_key_env:
+            api_key = os.environ.get(config.provider.api_key_env)
+        if not api_key:
+            api_key = config.provider.api_key
+        if api_key is config.provider.api_key and api_key:
+            typer.echo(
+                "warning: using inline api_key from config.yaml — prefer api_key_env "
+                "(env var). config.yaml is gitignored but env is safer."
+            )
+        provider = LiteLLMProvider(
+            model=config.provider.model,
+            api_base=config.provider.api_base,
+            temperature=config.provider.temperature,
+            api_key=api_key,
+        )
+
+    manifest = compile_graph(
+        raw_root=p["raw"], out_dir=p["out"], schema=schema,
+        provider=provider, cache_path=p["cache"], chunk_lines=config.compile.chunk_lines,
+    )
+    typer.echo(f"compiled: {manifest.node_count} nodes, {manifest.edge_count} edges, "
+               f"run_id={manifest.run_id}, facts_hash={manifest.facts_hash}")
+
+
+@app.command(name="eval")
+def eval_cmd() -> None:
+    """Run Tier-1 construction-quality evaluation vs the gold corpus."""
+    p = resolve_paths()
+    gold_dir = Path(os.environ.get("LOREKEEP_GOLD", "tests/fixtures/gold"))
+    from lorekeep.eval.construction import extraction_report, structure_report
+    report = {
+        "extraction": extraction_report(p["out"], gold_dir),
+        "structure": structure_report(p["out"]),
+    }
+    results_path = Path(os.environ.get("LOREKEEP_EVAL_RESULTS",
+                                       ".lorekeep/eval/results.json"))
+    results_path.parent.mkdir(parents=True, exist_ok=True)
+    results_path.write_text(json.dumps(report, indent=2, sort_keys=True))
+    typer.echo(json.dumps(report, indent=2, sort_keys=True))
+
+
+@app.command()
+def check() -> None:
+    """Validate the compiled graph: loads, no dangling edges."""
+    p = resolve_paths()
+    from lorekeep.eval.construction import structure_report
+    struct = structure_report(p["out"])
+    if struct["dangling_edge_rate"] > 0:
+        typer.echo(f"check: FAIL — {struct['dangling_edge_rate']} dangling edges")
+        raise typer.Exit(code=1)
+    typer.echo(f"check: ok — {struct['node_count']} nodes, {struct['edge_count']} edges, 0 dangling")
+
+
+@app.command()
+def serve(
+    transport: str = typer.Option("stdio", "--transport", help="stdio (default) | http"),
+) -> None:
+    """Serve the scoped graph over MCP."""
+    p = resolve_paths()
+    raw_ns = os.environ.get("LOREKEEP_NS")
+    if raw_ns:
+        allowed = [x.strip() for x in raw_ns.split(",") if x.strip()]
+    else:
+        allowed = load_config(p["config"]).ns.default
+    from lorekeep.mcp_server import configure, mcp
+    configure(graph_dir=p["out"], allowed_ns=allowed, schema_path=p["schema"])
+    mcp.run(transport=transport)
+
+
+mcp_app = typer.Typer(help="Coding-agent integration.")
+app.add_typer(mcp_app, name="mcp")
+
+
+@mcp_app.command("add")
+def mcp_add(
+    agent: str = typer.Option(..., "--agent", help="claude | cursor | codex"),
+    scope: str = typer.Option("project", "--scope", help="project | user"),
+    ns: str = typer.Option(None, "--ns", help="namespace to scope the agent to"),
+) -> None:
+    """Write the agent's MCP config + print an agent-memory snippet."""
+    from lorekeep.integrations import claude_code, codex, cursor
+    from lorekeep.integrations.common import agent_memory_snippet, resolve_command
+
+    p = resolve_paths()
+    config = load_config(p["config"])
+    command, args = resolve_command(config.install_source)
+
+    target = Path.cwd() if scope == "project" else Path.home()
+    writers = {"claude": claude_code, "cursor": cursor, "codex": codex}
+    if agent not in writers:
+        typer.echo(f"unknown agent: {agent} (choose claude|cursor|codex)")
+        raise typer.Exit(code=1)
+    written = writers[agent].write_config(target, command, args, ns)
+    typer.echo(f"wrote {agent} config -> {written}")
+    typer.echo("\n" + agent_memory_snippet())
+
+
+@app.command()
+def doctor() -> None:
+    """Verify install: graph loads, schema valid, ns resolves, a tool responds."""
+    p = resolve_paths()
+    problems = []
+
+    facts_path = p["out"] / "facts.jsonl"
+    if not facts_path.exists():
+        typer.echo(f"FAIL: facts.jsonl not found at {facts_path}")
+        raise typer.Exit(code=1)
+
+    try:
+        from lorekeep.store.graph import GraphStore
+        store = GraphStore.from_jsonl(facts_path)
+    except Exception as exc:
+        typer.echo(f"FAIL: cannot load graph: {exc}")
+        raise typer.Exit(code=1)
+
+    if not p["schema"].exists():
+        problems.append("schema.json missing")
+    else:
+        try:
+            load_schema(p["schema"])
+        except Exception as exc:
+            problems.append(f"schema invalid: {exc}")
+
+    raw_ns = os.environ.get("LOREKEEP_NS")
+    allowed = [x.strip() for x in raw_ns.split(",")] if raw_ns else load_config(p["config"]).ns.default
+
+    try:
+        from lorekeep.mcp_server import configure, list_namespaces
+        configure(graph_dir=p["out"], allowed_ns=allowed, schema_path=p["schema"])
+        ns = list_namespaces()
+    except Exception as exc:
+        problems.append(f"mcp configure/tool failed: {exc}")
+        ns = []
+
+    if problems:
+        typer.echo("FAIL: " + "; ".join(problems))
+        raise typer.Exit(code=1)
+
+    typer.echo(
+        f"all checks passed: {len(store.node_ids())} nodes, "
+        f"{len(store.all_edges())} edges, namespaces={ns}"
+    )
+
+
+@app.command()
+def init() -> None:
+    """Bootstrap the data home: config + schema + raw/graph dirs."""
+    p = resolve_paths()
+    created = []
+    p["config"].parent.mkdir(parents=True, exist_ok=True)
+    if not p["config"].exists():
+        p["config"].write_text(DEFAULT_CONFIG_YAML)
+        created.append(str(p["config"]))
+    p["schema"].parent.mkdir(parents=True, exist_ok=True)
+    if not p["schema"].exists():
+        p["schema"].write_text(json.dumps(DEFAULT_SCHEMA, indent=2))
+        created.append(str(p["schema"]))
+    p["raw"].mkdir(parents=True, exist_ok=True)
+    p["out"].mkdir(parents=True, exist_ok=True)
+    typer.echo(f"home ready: config={p['config']}")
+    typer.echo(f"  schema={p['schema']}  raw={p['raw']}  graph={p['out']}")
+    if created:
+        typer.echo(f"  wrote defaults: {created}")
+    else:
+        typer.echo("  (existing config/schema preserved)")
+
+
+if __name__ == "__main__":
+    app()

lorekeep/compile/extract.py

@@ -0,0 +1,150 @@
+"""Extract: turn a DocChunk into candidate facts via an LLM. Pure helpers first."""
+from __future__ import annotations
+
+import json
+import re
+from datetime import date
+from typing import Any
+
+from lorekeep.models import DocChunk, Edge, Node, Schema
+
+SYSTEM_PROMPT = (
+    "You are a knowledge-graph extractor. Read the document chunk and emit a JSON "
+    'object {"nodes":[...], "edges":[...], "aliases":{...}}. '
+    "Only use node_types and edge_types listed in the provided schema. "
+    "For every node give id (stable slug prefixed by type, e.g. svc:payments-api), "
+    "type, name, optional props, optional valid_from/valid_to (ISO dates, null = unknown). "
+    "For every edge give type, from (node id), to (node id), optional valid_from/valid_to. "
+    "aliases maps a canonical name to surface variants. Emit NO text outside the JSON."
+)
+
+
+def build_prompt(chunk: DocChunk, schema: Schema) -> str:
+    node_types = ", ".join(schema.node_types.keys())
+    edge_types = ", ".join(
+        f"{k}({v.from_}->{v.to})" for k, v in schema.edge_types.items()
+    )
+    return (
+        f"Allowed node_types: {node_types}\n"
+        f"Allowed edge_types: {edge_types}\n\n"
+        f"Source: {chunk.src}\n"
+        f"Namespace: {chunk.namespace}\n\n"
+        f"Document chunk:\n{chunk.text}\n"
+    )
+
+
+def _parse_date(v: Any) -> date | None:
+    if not v:
+        return None
+    return date.fromisoformat(v)
+
+
+def _extract_json(raw: str, chunk: DocChunk) -> str:
+    """Best-effort recover a JSON object from LLM output.
+
+    response_format=json_object usually yields clean JSON, but some models wrap
+    output in ```json fences or prepend prose. Strip fences, then fall back to
+    the first balanced {...} span. Raises ValueError (with chunk src) if the
+    output still can't be parsed, so the pipeline reports a clear failure.
+    """
+    s = raw.strip()
+    if s.startswith("```"):
+        s = s.strip("`")
+        brace = s.find("{")
+        if brace != -1:
+            s = s[brace:]
+    try:
+        json.loads(s)
+        return s
+    except json.JSONDecodeError:
+        m = re.search(r"\{.*\}", raw, re.DOTALL)
+        if m:
+            json.loads(m.group(0))      # validate; raises if malformed
+            return m.group(0)
+        raise ValueError(f"LLM returned non-JSON for {chunk.src}")
+
+
+def parse_response(
+    raw: str, chunk: DocChunk, schema: Schema | None = None,
+) -> tuple[list[Node], list[Edge], dict[str, list[str]]]:
+    data = json.loads(_extract_json(raw, chunk))
+    nodes: list[Node] = []
+    for n in data.get("nodes", []):
+        ntype = n.get("type")
+        if schema is not None and not schema.is_valid_node_type(ntype):
+            continue
+        props = dict(n.get("props", {}))
+        if "name" in n and "name" not in props:
+            props["name"] = n["name"]
+        nodes.append(Node(
+            id=n["id"],
+            type=ntype,
+            ns=(chunk.namespace,),
+            valid_from=_parse_date(n.get("valid_from")),
+            valid_to=_parse_date(n.get("valid_to")),
+            props=props,
+            src=(chunk.src,),
+        ))
+    edges: list[Edge] = []
+    for e in data.get("edges", []):
+        etype = e.get("type")
+        if schema is not None and not schema.is_valid_edge_type(etype):
+            continue
+        edges.append(Edge(
+            id="",                      # assigned deterministically in resolve
+            type=etype,
+            **{"from": e["from"]},
+            to=e["to"],
+            ns=(chunk.namespace,),
+            valid_from=_parse_date(e.get("valid_from")),
+            valid_to=_parse_date(e.get("valid_to")),
+            src=(chunk.src,),
+        ))
+    aliases = {k: list(v) for k, v in data.get("aliases", {}).items()}
+    return nodes, edges, aliases
+
+
+import hashlib
+from pathlib import Path
+
+from lorekeep.compile.providers import LLMProvider
+
+
+class ExtractionCache:
+    """Maps (chunk_hash, schema_version) -> raw LLM response. Local only."""
+
+    def __init__(self, path: Path) -> None:
+        self.path = Path(path)
+        self._data: dict[str, str] = {}
+        if self.path.exists():
+            self._data = json.loads(self.path.read_text(encoding="utf-8"))
+
+    def key(self, chunk: DocChunk, schema_version: int) -> str:
+        h = hashlib.sha256()
+        h.update(str(schema_version).encode("utf-8"))
+        h.update(b"\n")
+        h.update(chunk.hash.encode("utf-8"))
+        return h.hexdigest()
+
+    def get(self, key: str) -> str | None:
+        return self._data.get(key)
+
+    def set(self, key: str, raw: str) -> None:
+        self._data[key] = raw
+
+    def save(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(self._data, sort_keys=True, indent=2), encoding="utf-8"
+        )
+
+
+def extract_chunk(
+    chunk: DocChunk, schema: Schema, provider: LLMProvider, cache: ExtractionCache,
+) -> tuple[list[Node], list[Edge], dict[str, list[str]]]:
+    key = cache.key(chunk, schema.version)
+    raw = cache.get(key)
+    if raw is None:
+        raw = provider.extract_json(SYSTEM_PROMPT, build_prompt(chunk, schema))
+        cache.set(key, raw)
+    return parse_response(raw, chunk, schema)

lorekeep/compile/ingest.py

@@ -0,0 +1,55 @@
+"""Ingest: raw markdown files -> DocChunks with provenance."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from lorekeep.models import DocChunk
+
+
+def namespace_for(raw_root: Path, path: Path) -> str:
+    rel = path.relative_to(raw_root)
+    parts = rel.parts
+    if len(parts) >= 2:          # <dir>/<file> -> ns is the first directory
+        return parts[0]
+    return "public"
+
+
+def ingest_file(raw_root: Path, path: Path, chunk_lines: int) -> list[DocChunk]:
+    ns = namespace_for(raw_root, path)
+    rel = str(path.relative_to(raw_root))
+    lines = path.read_text(encoding="utf-8").splitlines()
+    chunks: list[DocChunk] = []
+    for start in range(0, len(lines), chunk_lines):
+        block = lines[start:start + chunk_lines]
+        if not any(line.strip() for line in block):
+            continue
+        chunks.append(DocChunk(
+            path=rel,
+            start_line=start + 1,
+            end_line=start + len(block),
+            text="\n".join(block),
+            namespace=ns,
+        ))
+    return chunks
+
+
+def ingest(raw_root: Path, glob: str = "**/*.md", chunk_lines: int = 60) -> list[DocChunk]:
+    """Ingest files under raw_root into DocChunks.
+
+    Any path whose resolved target escapes raw_root is skipped with a stderr
+    warning. Everything under raw/ is sent to the LLM provider at compile, so a
+    planted symlink (e.g. raw/x/leak.md -> ~/.ssh/id_rsa) must not exfiltrate
+    files outside raw_root — fail closed.
+    """
+    root = raw_root.resolve()
+    chunks: list[DocChunk] = []
+    for p in sorted(raw_root.glob(glob)):
+        if not p.is_file():
+            continue
+        if not p.resolve().is_relative_to(root):
+            print(f"lorekeep: skip path outside raw_root (possible symlink): {p}",
+                  file=sys.stderr)
+            continue
+        chunks.extend(ingest_file(raw_root, p, chunk_lines))
+    return chunks

lorekeep/compile/providers.py

@@ -0,0 +1,49 @@
+"""LLM provider abstraction. litellm is the only hard dependency on a vendor."""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class LLMProvider(Protocol):
+    def extract_json(self, system: str, user: str) -> str: ...
+
+
+class FakeProvider:
+    """Returns canned responses in order. Used by tests; never hits a network."""
+
+    def __init__(self, responses: list[str]) -> None:
+        self._responses = list(responses)
+        self.calls: list[tuple[str, str]] = []
+
+    def extract_json(self, system: str, user: str) -> str:
+        self.calls.append((system, user))
+        if not self._responses:
+            raise RuntimeError("FakeProvider: no canned response left")
+        return self._responses.pop(0)
+
+
+class LiteLLMProvider:
+    """Real provider backed by litellm. Supports openai/anthropic/ollama."""
+
+    def __init__(self, model: str, api_base: str | None = None,
+                 temperature: float = 0.0, api_key: str | None = None) -> None:
+        self.model = model
+        self.api_base = api_base
+        self.temperature = temperature
+        self.api_key = api_key
+
+    def extract_json(self, system: str, user: str) -> str:
+        import litellm  # imported lazily so tests need not install it
+        resp = litellm.completion(
+            model=self.model,
+            api_base=self.api_base,
+            api_key=self.api_key,
+            temperature=self.temperature,
+            messages=[
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            response_format={"type": "json_object"},
+        )
+        return resp.choices[0].message.content

lorekeep/compile/resolve.py

@@ -0,0 +1,111 @@
+"""Resolve: dedup entities, validate edges, enforce ns, quarantine bad facts.
+
+Extraction may emit the same entity under several ids (aliases). This stage
+collapses them onto one canonical id, rewrites edge endpoints, drops edges whose
+endpoints disappeared, and quarantines malformed facts for review.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from lorekeep.models import Edge, Node
+
+
+@dataclass
+class ResolveResult:
+    nodes: list[Node] = field(default_factory=list)
+    edges: list[Edge] = field(default_factory=list)
+    aliases: dict[str, str] = field(default_factory=dict)      # alias_id -> canonical_id
+    quarantined: list[tuple[dict, str]] = field(default_factory=list)
+
+
+def _build_alias_map(
+    nodes: list[Node],
+    name_aliases: dict[str, list[str]] | None,
+    explicit_map: dict[str, str] | None,
+) -> dict[str, str]:
+    """Return alias_id -> canonical_id. Canonical = first node id seen for a name."""
+    alias_map: dict[str, str] = {}
+    # 1) by name: group nodes whose props.name matches an alias group's canonical
+    if name_aliases:
+        name_to_canonical: dict[str, str] = {}
+        for nd in nodes:
+            nm = nd.props.get("name")
+            if not nm:
+                continue
+            for canonical_name, variants in name_aliases.items():
+                if nm in variants:
+                    canon = name_to_canonical.setdefault(canonical_name, nd.id)
+                    if nd.id != canon:
+                        alias_map[nd.id] = canon
+    # 2) explicit id->id overrides win
+    if explicit_map:
+        alias_map.update(explicit_map)
+    return alias_map
+
+
+def _canonical(node_id: str, alias_map: dict[str, str]) -> str:
+    seen: set[str] = set()
+    cur = node_id
+    while cur in alias_map and cur not in seen:
+        seen.add(cur)
+        cur = alias_map[cur]
+    return cur
+
+
+def resolve(
+    nodes: list[Node],
+    edges: list[Edge],
+    name_aliases: dict[str, list[str]] | None = None,
+    aliases_map: dict[str, str] | None = None,
+) -> ResolveResult:
+    alias_map = _build_alias_map(nodes, name_aliases, aliases_map)
+
+    # collapse nodes
+    canon_nodes: dict[str, Node] = {}
+    for nd in nodes:
+        cid = _canonical(nd.id, alias_map)
+        if cid in canon_nodes:
+            base = canon_nodes[cid]
+            merged_props = {**base.props, **nd.props}
+            merged_src = tuple(dict.fromkeys(base.src + nd.src))
+            merged_ns = tuple(dict.fromkeys(base.ns + nd.ns))
+            canon_nodes[cid] = base.model_copy(
+                update={"props": merged_props, "src": merged_src, "ns": merged_ns}
+            )
+        else:
+            # normalize stored node id to the canonical key so node identity and
+            # dict key can never diverge (covers explicit_map to a non-node id)
+            canon_nodes[cid] = nd if nd.id == cid else nd.model_copy(update={"id": cid})
+
+    out_nodes = list(canon_nodes.values())
+    node_ids = set(canon_nodes.keys())
+
+    # rewrite + validate edges
+    out_edges: list[Edge] = []
+    quarantined: list[tuple[dict, str]] = []
+    counter = 0
+    for ed in edges:
+        f = _canonical(ed.from_, alias_map)
+        t = _canonical(ed.to, alias_map)
+        if f not in node_ids or t not in node_ids:
+            quarantined.append((ed.model_dump(mode="json", by_alias=True),
+                                f"dangling endpoint ({f}->{t})"))
+            continue
+        if f == t:
+            quarantined.append((ed.model_dump(mode="json", by_alias=True),
+                                "self-loop"))
+            continue
+        counter += 1
+        out_edges.append(ed.model_copy(update={
+            "id": f"e_{ed.type}_{counter:04d}",
+            **{"from_": f},
+            "to": t,
+        }))
+
+    return ResolveResult(
+        nodes=out_nodes,
+        edges=out_edges,
+        aliases=alias_map,
+        quarantined=quarantined,
+    )

lorekeep/compile/writer.py

@@ -0,0 +1,63 @@
+"""Writer: emit deterministic facts.jsonl + manifest.json.
+
+Determinism = facts sorted by (kind, type, id), JSON keys sorted, stable
+separators. Re-compiling unchanged input yields byte-identical output.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from lorekeep.models import DocChunk, Edge, Manifest, Node
+
+
+def _sort_key(fact: Node | Edge) -> tuple[str, str, str]:
+    return (fact.kind, fact.type, fact.id)
+
+
+def _atomic_write(path: Path, data: str) -> None:
+    """Write data to path atomically: stage a temp file then os.replace onto it.
+
+    Prevents a torn read when the MCP server lazy-reloads facts.jsonl mid-write
+    (compile truncating the file while a query reads it). os.replace is atomic
+    when src and dst share a filesystem, which holds for a sibling temp file.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=path.name + ".", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(data)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def write_graph(
+    out_dir: Path, nodes: list[Node], edges: list[Edge], manifest: Manifest,
+) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    facts = sorted(nodes + edges, key=_sort_key)
+    lines = [f.to_json_line() for f in facts]
+    text = "\n".join(lines) + ("\n" if lines else "")
+    _atomic_write(out_dir / "facts.jsonl", text)
+    _atomic_write(out_dir / "manifest.json", manifest.to_json())
+
+
+def run_id(chunks: list[DocChunk], schema_version: int) -> str:
+    h = hashlib.sha256()
+    h.update(str(schema_version).encode("utf-8"))
+    for c in sorted(chunks, key=lambda c: (c.path, c.start_line)):
+        h.update(c.hash.encode("utf-8"))
+    return h.hexdigest()[:16]
+
+
+def facts_hash(out_dir: Path) -> str:
+    raw = (out_dir / "facts.jsonl").read_bytes()
+    return hashlib.sha256(raw).hexdigest()[:16]