sarib 0.1.0__tar.gz

sarib-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: sarib
+Version: 0.1.0
+Summary: Reference implementation of the .sarib knowledge language: query bounded subgraphs and apply id-addressed atomic edits over plain-text knowledge.
+Author: Syed Sarib Sultan
+License: MIT
+Project-URL: Homepage, https://github.com/SyedSaribSultan/sarib-lang
+Project-URL: Repository, https://github.com/SyedSaribSultan/sarib-lang
+Project-URL: Issues, https://github.com/SyedSaribSultan/sarib-lang/issues
+Keywords: knowledge,graph,markdown,mcp,ai-agents,llm,notes,property-graph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+
+# sarib
+
+Reference implementation of the **.sarib** knowledge language — a plain-text format
+that is at once a readable document (a Markdown superset) and a labeled property graph.
+Agents query bounded subgraphs and apply id-addressed atomic edits instead of
+re-reading or regenerating whole files.
+
+```bash
+pip install sarib            # core, zero dependencies
+pip install "sarib[mcp]"     # + the MCP server for agent clients
+```
+
+## CLI
+
+```bash
+sarib validate notes.sarib
+sarib render   notes.sarib --view outline     # document | outline | board | mermaid
+sarib query    notes.sarib --spec '{"select":"none","filter":{"type":"task"}}'
+sarib apply    notes.sarib --op   '{"kind":"set-property","target":"t1","args":{"key":"status","value":"done"}}'
+sarib canon    notes.sarib                     # canonical normal form (for hash/diff)
+```
+
+## MCP server
+
+```bash
+sarib-mcp /path/to/folder-of-.sarib-files
+```
+
+Exposes `sarib_query / sarib_apply / sarib_render / sarib_validate / sarib_canon`
+to any MCP client (Claude Desktop, Claude Code, Cursor, …).
+
+## Status
+
+Research-grade **v0.1**. Spec, full design history, decision log, and benchmarks:
+<https://github.com/SyedSaribSultan/sarib-lang>. License: MIT.

sarib-0.1.0/README.md

@@ -0,0 +1,35 @@
+# sarib
+
+Reference implementation of the **.sarib** knowledge language — a plain-text format
+that is at once a readable document (a Markdown superset) and a labeled property graph.
+Agents query bounded subgraphs and apply id-addressed atomic edits instead of
+re-reading or regenerating whole files.
+
+```bash
+pip install sarib            # core, zero dependencies
+pip install "sarib[mcp]"     # + the MCP server for agent clients
+```
+
+## CLI
+
+```bash
+sarib validate notes.sarib
+sarib render   notes.sarib --view outline     # document | outline | board | mermaid
+sarib query    notes.sarib --spec '{"select":"none","filter":{"type":"task"}}'
+sarib apply    notes.sarib --op   '{"kind":"set-property","target":"t1","args":{"key":"status","value":"done"}}'
+sarib canon    notes.sarib                     # canonical normal form (for hash/diff)
+```
+
+## MCP server
+
+```bash
+sarib-mcp /path/to/folder-of-.sarib-files
+```
+
+Exposes `sarib_query / sarib_apply / sarib_render / sarib_validate / sarib_canon`
+to any MCP client (Claude Desktop, Claude Code, Cursor, …).
+
+## Status
+
+Research-grade **v0.1**. Spec, full design history, decision log, and benchmarks:
+<https://github.com/SyedSaribSultan/sarib-lang>. License: MIT.

sarib-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sarib"
+version = "0.1.0"
+description = "Reference implementation of the .sarib knowledge language: query bounded subgraphs and apply id-addressed atomic edits over plain-text knowledge."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Syed Sarib Sultan" }]
+keywords = ["knowledge", "graph", "markdown", "mcp", "ai-agents", "llm", "notes", "property-graph"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing :: Markup",
+]
+dependencies = []
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0"]
+
+[project.scripts]
+sarib = "sarib.cli:main"
+sarib-mcp = "sarib.mcp_server:main"
+
+[project.urls]
+Homepage = "https://github.com/SyedSaribSultan/sarib-lang"
+Repository = "https://github.com/SyedSaribSultan/sarib-lang"
+Issues = "https://github.com/SyedSaribSultan/sarib-lang/issues"
+
+[tool.setuptools]
+packages = ["sarib"]

sarib-0.1.0/sarib/__init__.py

@@ -0,0 +1,10 @@
+"""sarib — reference implementation of the .sarib knowledge language (v0.1).
+Components per Stage 13: parser, canon(normalizer), model store, ops, query, render.
+"""
+from .parser import parse
+from .canon import canon
+from .render import fmt, VIEWS
+from .ops import apply, fold, OpRejected
+from .query import query
+
+__version__ = "0.1.0"

sarib-0.1.0/sarib/canon.py

@@ -0,0 +1,42 @@
+"""sarib.canon — the canonical normal form (Stage 9, D-041).
+Line-oriented canonical JSON: one record per line, document-order nodes,
+sorted keys, canonical scalars. Exactly one byte-string per model state.
+"""
+from __future__ import annotations
+import json
+from .model import Doc
+
+
+def _clean(d: dict) -> dict:
+    return {k: v for k, v in d.items() if v not in (None, "", {}, []) and not k.startswith("_")}
+
+
+def canon(doc: Doc) -> str:
+    out = []
+    header = {"sarib": doc.meta.get("sarib", "0.1")}
+    for k in sorted(doc.meta):
+        if k != "sarib":
+            header[k] = doc.meta[k]
+    out.append(json.dumps(header, sort_keys=True, separators=(",", ":"), ensure_ascii=False))
+    for n in doc.walk(None):                                # document order (invariant 10)
+        rec = _clean({
+            "id": n.id, "kind": "node", "type": n.type, "hint": n.kind_hint,
+            "title": n.title, "content": n.content, "slug": n.slug,
+            "props": {k: v for k, v in sorted(n.properties.items())
+                      if not k.startswith("_")
+                      and not (isinstance(v, str) and v.startswith("[[") and v.endswith("]]"))},
+            "parent": n.parent, "order": n.order,
+            "status": None if n.status == "active" else n.status,
+            "provenance": n.provenance,
+        })
+        out.append(json.dumps(rec, sort_keys=True, separators=(",", ":"), ensure_ascii=False))
+    for eid in sorted(doc.edges):                            # tie-break cascade (D-029)
+        e = doc.edges[eid]
+        rec = _clean({
+            "id": e.id, "kind": "edge", "type": e.type, "source": e.source,
+            "target": e.target, "family": None if e.family == "crossref" else e.family,
+            "props": dict(sorted(e.properties.items())) or None,
+            "status": None if e.status == "active" else e.status,
+        })
+        out.append(json.dumps(rec, sort_keys=True, separators=(",", ":"), ensure_ascii=False))
+    return "\n".join(out) + "\n"

sarib-0.1.0/sarib/cli.py

@@ -0,0 +1,81 @@
+"""sarib CLI (Stage 13 D-057): parse | validate | canon | fmt | query | apply | render"""
+from __future__ import annotations
+import argparse, json, sys, pathlib
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
+from sarib import parse, canon, fmt, VIEWS, apply as apply_op, query as run_query
+from sarib.ops import OpRejected
+from sarib.importer import build as import_build, DEFAULT_VOCAB
+
+
+def _load(path):
+    return parse(pathlib.Path(path).read_text(encoding="utf-8"))
+
+
+def main(argv=None):
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")  # piped output on Windows defaults to cp1252
+    ap = argparse.ArgumentParser(prog="sarib", description=".sarib reference CLI v0.1")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    for c in ("parse", "validate", "canon", "fmt"):
+        sub.add_parser(c).add_argument("file")
+    q = sub.add_parser("query"); q.add_argument("file"); q.add_argument("--spec", required=True)
+    a = sub.add_parser("apply"); a.add_argument("file"); a.add_argument("--op", required=True); a.add_argument("--write", action="store_true")
+    r = sub.add_parser("render"); r.add_argument("file"); r.add_argument("--view", default="outline", choices=list(VIEWS))
+    im = sub.add_parser("import", help="markdown/prose -> a .sarib knowledge graph")
+    im.add_argument("inputs", nargs="+")
+    im.add_argument("-o", "--out")
+    im.add_argument("--title", default=None, help="graph title; defaults to the source's own front-matter title")
+    im.add_argument("--extract-edges", action="store_true", help="add constrained+verified LLM edges")
+    im.add_argument("--model", default="qwen2.5:7b")
+    im.add_argument("--endpoint", default="http://localhost:11434/api/chat")
+    im.add_argument("--vocab", default=",".join(DEFAULT_VOCAB), help="closed edge-type list, comma-separated")
+    ns = ap.parse_args(argv)
+
+    if ns.cmd == "import":
+        inputs = [(pathlib.Path(p).stem, pathlib.Path(p).read_text(encoding="utf-8")) for p in ns.inputs]
+        text, stats, diags = import_build(
+            inputs, title=ns.title, extract=ns.extract_edges, model=ns.model,
+            endpoint=ns.endpoint, vocab=[v.strip() for v in ns.vocab.split(",") if v.strip()])
+        if ns.out:
+            pathlib.Path(ns.out).write_text(text, encoding="utf-8")
+            print(f"wrote {ns.out}")
+            print("stats: " + json.dumps(stats))
+            hard = [d for d in diags if not d.startswith(("unresolved-reference", "ambiguous-reference"))]
+            for d in hard:
+                print(f"WARN: {d}")
+        else:
+            print(text, end="")
+        return
+
+    doc = _load(ns.file)
+    if ns.cmd == "parse":
+        print(canon(doc), end="")
+    elif ns.cmd == "canon":
+        print(canon(doc), end="")
+    elif ns.cmd == "validate":
+        for d in doc.diagnostics:
+            print(f"lint: {d}")
+        print(f"OK: {len(doc.nodes)} nodes, {len(doc.edges)} edges, "
+              f"{len(doc.diagnostics)} diagnostics (non-fatal, D-049)")
+    elif ns.cmd == "fmt":
+        print(fmt(doc), end="")
+    elif ns.cmd == "query":
+        print(json.dumps(run_query(doc, json.loads(ns.spec)), indent=1, ensure_ascii=False))
+    elif ns.cmd == "apply":
+        try:
+            apply_op(doc, json.loads(ns.op))
+        except OpRejected as e:
+            print(f"REJECTED: {e}"); sys.exit(1)
+        out = fmt(doc)
+        if ns.write:
+            pathlib.Path(ns.file).write_text(out, encoding="utf-8")
+            print(f"applied + written to {ns.file}")
+        else:
+            print(out, end="")
+    elif ns.cmd == "render":
+        print(VIEWS[ns.view](doc), end="")
+
+
+if __name__ == "__main__":
+    main()

sarib-0.1.0/sarib/importer.py

@@ -0,0 +1,305 @@
+"""sarib.importer — prose/markdown -> a .sarib knowledge graph. The adoption on-ramp.
+
+A CONSUMER of the model (like tools/preview.py and the MCP server); it lives OUTSIDE the
+<=1000 LOC parser core (G4), so it does not affect that budget.
+
+Two layers, both emitting valid, round-trippable .sarib:
+
+  skeleton (default)   deterministic. Markdown headings/list-items/paragraphs -> nodes with
+                       stable slug ids + the containment tree; existing [[wikilinks]] and
+                       [rel:: [[x]]] refs are preserved by the parser. No LLM, no network.
+
+  --extract-edges      constrained + verified edge extraction (market/importer-extraction-
+                       research.md). Boxed so a model can only SELECT, never invent:
+                         L1 closed vocab + existing-slug targets   (JSON-schema enum)
+                         L2 constrained decoding                    (Ollama `format`=schema)
+                         L3 span-grounding                          (quote must be verbatim)
+                         L4 entailment verify                       (independent yes/no per edge)
+                         L5 abstain                                 (unsupported/ambiguous dropped)
+                       Kept edges are written to the surface as `[rel:: [[#slug]]]` with an
+                       `inferred` provenance comment (D-019); resolution never guesses (D-024).
+
+Known limitations (documented, not bugs): edges are read from a node's own paragraph text, so
+relationships stated only inside sub-bullets or deeper sub-sections are missed (conservative:
+fewer edges, never wrong). Obsidian-style block ids (`^id`) on a heading are not preserved
+(surface refs use slugs). Import each file singly for maximum fidelity.
+"""
+from __future__ import annotations
+import json, re, urllib.request
+from .parser import parse
+from .model import anchor_owner
+
+DEFAULT_VOCAB = ["depends-on", "refines", "supersedes", "cites", "part-of"]
+VOCAB_DEF = {
+    "depends-on": "the source cannot proceed / is blocked until the target.",
+    "refines": "the source clarifies, extends, or amends the target.",
+    "supersedes": "the source replaces or overrides the target.",
+    "cites": "the source references the target as evidence, basis, or grounding.",
+    "part-of": "the source is a component or sub-part of the target.",
+}
+PHRASE = {
+    "depends-on": "depends on (is blocked until) ",
+    "refines": "refines or amends ",
+    "supersedes": "replaces or supersedes ",
+    "cites": "cites as evidence ",
+    "part-of": "is part of ",
+}
+_TYPE_RE = re.compile(r"^[A-Za-z][\w-]*$")   # a rel type must survive the parser's TYPED_REF_RE
+OLLAMA = "http://localhost:11434/api/chat"
+
+
+# ---------- deterministic skeleton ----------
+
+def _slug_base(title):
+    s = re.sub(r"[^a-z0-9]+", "-", (title or "").lower()).strip("-") or "node"
+    return s[:48].rstrip("-") or "node"
+
+
+def _dedup(base, used):
+    s, i = base, 2
+    while s in used:
+        s = f"{base}-{i}"; i += 1
+    used.add(s)
+    return s
+
+
+def _strip_front_matter(text):
+    lines = text.splitlines()
+    if lines and lines[0].strip() == "---":
+        j = 1
+        while j < len(lines) and lines[j].strip() != "---":
+            j += 1
+        return "\n".join(lines[j + 1:]).lstrip("\n")
+    return text
+
+
+def _bump_headings(text):
+    return re.sub(r"(?m)^(#{1,5})(\s)", r"#\1\2", text)
+
+
+def _combine(inputs):
+    """One file -> as-is (parser lifts its front matter). Many -> each nested under a file
+    heading, with its own front matter stripped (else it would become body prose)."""
+    if len(inputs) == 1:
+        return inputs[0][1]
+    return "\n\n".join(f"# {name}\n\n" + _bump_headings(_strip_front_matter(text))
+                       for name, text in inputs)
+
+
+def _assign_slugs(doc):
+    """Every titled node gets a UNIQUE slug. Explicit slugs (from `{#id}`) are de-duped too
+    (bug fix: a document-authored slug could otherwise collide with an auto one)."""
+    used, slug_of = set(), {}
+    for n in doc.walk(None):
+        if n.title:
+            n.slug = _dedup(n.slug or _slug_base(n.title), used)
+            slug_of[n.id] = n.slug
+    return slug_of
+
+
+def _section_text(doc, node):
+    """The node's own prose (its title + direct prose children) — what edges are read from."""
+    body = [c.content for c in doc.children(node.id) if c.kind_hint == "prose"]
+    return (node.title + "\n" + "\n".join(body)).strip()
+
+
+# ---------- constrained + verified extraction ----------
+
+def _ollama(endpoint, model, system, user, schema, timeout=120):
+    body = json.dumps({
+        "model": model,
+        "messages": [{"role": "system", "content": system}, {"role": "user", "content": user}],
+        "stream": False, "format": schema, "options": {"temperature": 0, "seed": 42},
+    }).encode()
+    req = urllib.request.Request(endpoint, data=body, headers={"Content-Type": "application/json"})
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.loads(json.load(r)["message"]["content"])
+
+
+def _norm(s):
+    return re.sub(r"\s+", " ", s or "").strip().lower()
+
+
+def _extract_schema(vocab, slugs):
+    return {"type": "object", "properties": {"edges": {"type": "array", "items": {
+        "type": "object",
+        "properties": {"type": {"type": "string", "enum": vocab},
+                       "target": {"type": "string", "enum": slugs},
+                       "span": {"type": "string"}},
+        "required": ["type", "target", "span"]}}}, "required": ["edges"]}
+
+
+_VERIFY_SCHEMA = {"type": "object",
+                  "properties": {"answer": {"type": "string", "enum": ["yes", "no"]}},
+                  "required": ["answer"]}
+
+
+def _existing_edges(doc):
+    """(src-slug, type, tgt-slug) already present from the surface — for de-dup (#8)."""
+    seen = set()
+    for e in doc.edges.values():
+        if e.status != "active" or e.target.startswith("?"):
+            continue
+        s = doc.nodes.get(anchor_owner(doc, e.source))
+        t = doc.nodes.get(anchor_owner(doc, e.target))
+        if s and t and s.slug and t.slug:
+            seen.add((s.slug, e.type, t.slug))
+    return seen
+
+
+def _propose(doc, model, endpoint, vocab):
+    """One constrained call per titled heading node. Returns (kept, stats). kept: src_id->[edge]."""
+    titled = [n for n in doc.walk(None) if n.title and n.kind_hint == "heading"]
+    id_of = {n.slug: n.id for n in titled}
+    slugs = [n.slug for n in titled]
+    already = _existing_edges(doc)
+    vdef = "\n".join(f"- {k}: {v}" for k, v in VOCAB_DEF.items() if k in vocab)
+    directory = "\n".join(f"{n.slug}: {n.title}" for n in titled)
+    system = (
+        "You are a STRICT relationship extractor. Output ONLY relationships EXPLICITLY stated "
+        "in the given text. Do NOT infer, guess, or use outside knowledge. When in doubt, leave "
+        "it out.\n\nAllowed types (use EXACTLY one):\n" + vdef + "\n\n'target' must be the slug "
+        "of the OTHER node being referred to. 'span' MUST be the exact verbatim substring of the "
+        "text that states the relationship. If the text states no relationship to another node, "
+        "return an empty list.")
+    stats = {"proposed": 0, "reject_target": 0, "reject_span": 0, "verify_no": 0, "dup": 0, "kept": 0}
+    kept = {}
+    for n in titled:
+        text = _section_text(doc, n)
+        others = [s for s in slugs if s != n.slug]
+        if not others:
+            continue
+        user = (f"Current node: {n.slug} — {n.title}\n\nDirectory of other nodes (slug: title):\n"
+                f"{directory}\n\nText of the current node:\n{text}\n\n"
+                "Return JSON {\"edges\":[{\"type\":..,\"target\":\"<slug>\",\"span\":\"..\"}]}.")
+        try:
+            res = _ollama(endpoint, model, system, user, _extract_schema(vocab, others))
+        except Exception:
+            stats["errors"] = stats.get("errors", 0) + 1
+            continue
+        for e in res.get("edges", []):
+            stats["proposed"] += 1
+            rel, tgt, span = e.get("type"), e.get("target"), e.get("span", "")
+            if rel not in vocab or tgt not in id_of or tgt == n.slug:
+                stats["reject_target"] += 1; continue
+            if _norm(span) not in _norm(text):                              # L3 span grounding
+                stats["reject_span"] += 1; continue
+            if (n.slug, rel, tgt) in already:                              # #8 de-dup vs surface
+                stats["dup"] += 1; continue
+            if not _verify(model, endpoint, n.title, rel, doc.nodes[id_of[tgt]].title, span):  # L4
+                stats["verify_no"] += 1; continue
+            kept.setdefault(n.id, []).append({"type": rel, "target_slug": tgt, "span": span})
+            already.add((n.slug, rel, tgt))                               # de-dup within run too
+            stats["kept"] += 1
+    return kept, stats
+
+
+def _verify(model, endpoint, src_title, rel, tgt_title, span):
+    """L4: independent entailment check. Few-shot + natural-language claim so a weak model
+    actually discriminates (a terse yes/no enum degenerates to 'no' on everything)."""
+    system = (
+        "Decide whether the SPAN supports the CLAIM. Reply yes if the span states or clearly "
+        "implies the claim (in that direction); reply no otherwise.\n"
+        "Example 1 SPAN: \"A is blocked until we finish B.\" CLAIM: A depends on B. -> yes\n"
+        "Example 2 SPAN: \"B was amended by A.\" CLAIM: A refines B. -> yes\n"
+        "Example 3 SPAN: \"B was amended by A.\" CLAIM: A supersedes B. -> no\n"
+        "Example 4 SPAN: \"We should water the plants.\" CLAIM: A depends on B. -> no")
+    user = (f"SPAN: \"{span}\"\nCLAIM: {src_title} {PHRASE.get(rel, rel + ' ')}{tgt_title}.\n"
+            "Answer yes or no.")
+    try:
+        return _ollama(endpoint, model, system, user, _VERIFY_SCHEMA).get("answer") == "yes"
+    except Exception:
+        return False
+
+
+# ---------- emit ----------
+
+def _emit(doc, kept, title, extra_meta):
+    out = ["---", "sarib: 0.1", "vocab: std@0.1", f"title: {title}"]
+    for k, v in extra_meta.items():                     # #1: carry source front matter through
+        out.append(f"{k}: {v}")
+    out += ["---",
+            "<!-- generated by `sarib import`; edges marked `inferred` were auto-extracted "
+            "and verified (see provenance comments). -->", ""]
+    for n in doc.walk(None):
+        if n.kind_hint == "heading":
+            level = int(n.properties.get("_level", 1))
+            attrs = ([f".{n.type}"] if n.type else []) + ([f"#{n.slug}"] if n.slug else [])
+            mark = (" {" + " ".join(attrs) + "}") if attrs else ""
+            out.append(f"{'#' * level} {n.title}{mark}")
+            for k, v in n.properties.items():
+                if not k.startswith("_"):
+                    out.append(f"{k}:: {v}")
+            for e in kept.get(n.id, []):
+                out.append(f"<!-- inferred: \"{e['span'][:80].strip()}\" -->")
+                out.append(f"[{e['type']}:: [[#{e['target_slug']}]]]")
+            out.append("")
+        elif n.kind_hint == "item":
+            attrs = ([f".{n.type}"] if n.type else []) + ([f"#{n.slug}"] if n.slug else [])
+            mark = (" {" + " ".join(attrs) + "}") if attrs else ""
+            out.append(f"- {n.title}{mark}")
+        else:
+            out.append(n.content + "\n")
+    return "\n".join(out).rstrip() + "\n"
+
+
+# ---------- structural round-trip verification (#4) ----------
+
+def _pmap(d):
+    """slug -> parent-slug (or None), over titled nodes: the containment shape."""
+    m = {}
+    for n in d.walk(None):
+        if n.title:
+            p = d.nodes.get(n.parent) if n.parent else None
+            m[n.slug] = p.slug if (p and p.title) else None
+    return m
+
+
+# ---------- entry point ----------
+
+def build(inputs, title=None, extract=False,
+          model="qwen2.5:7b", endpoint=OLLAMA, vocab=None):
+    """inputs: [(name, text)]. Returns (sarib_text, stats, diagnostics)."""
+    vocab = vocab or list(DEFAULT_VOCAB)
+    warns = [f"ignored invalid edge-type '{v}' (must match {_TYPE_RE.pattern})"
+             for v in vocab if not _TYPE_RE.match(v)]                       # #7 vocab guard
+    vocab = [v for v in vocab if _TYPE_RE.match(v)]
+
+    if len(inputs) > 1:                                                     # #3 level-6 warning
+        for name, txt in inputs:
+            if re.search(r"(?m)^######\s", _strip_front_matter(txt)):
+                warns.append(f"multi-file: '{name}' has level-6 headings; deep nesting may "
+                             "flatten — import it singly for full fidelity")
+
+    doc = parse(_combine(inputs))
+    _assign_slugs(doc)
+    # #1: prefer an explicit --title, else the source doc's own title, else a default
+    eff_title = title or doc.meta.get("title") or "Imported knowledge"
+    extra_meta = {k: v for k, v in doc.meta.items() if k not in ("sarib", "vocab", "title")}
+
+    kept, stats = ({}, {})
+    if extract:
+        if not vocab:
+            warns.append("no valid edge types; skipping extraction")
+        else:
+            kept, stats = _propose(doc, model, endpoint, vocab)
+
+    text = _emit(doc, kept, eff_title, extra_meta)
+
+    check = parse(text)                                                     # #4 structural check
+    problems = list(warns)
+    di, ci = _pmap(doc), _pmap(check)
+    if set(di) != set(ci):
+        problems.append(f"structure-drift: {len(di)} titled nodes intended, {len(ci)} after round-trip")
+    elif di != ci:
+        problems.append("structure-drift: nesting changed on round-trip")
+    live_slugs = {n.slug for n in check.walk(None) if n.title}
+    for lst in kept.values():
+        for e in lst:
+            if e["target_slug"] not in live_slugs:
+                problems.append(f"inferred edge target #{e['target_slug']} did not resolve")
+    unresolved = [d for d in check.diagnostics if d.startswith("unresolved-reference")]
+    stats.update(nodes=len([n for n in doc.nodes.values() if n.title]),
+                 edges=sum(len(v) for v in kept.values()),
+                 unresolved=len(unresolved), problems=len(problems))
+    return text, stats, problems + check.diagnostics

sarib-0.1.0/sarib/mcp_server.py

@@ -0,0 +1,82 @@
+"""sarib MCP server (Stage 13 §4, D-057) — the day-one consumer.
+Exposes .sarib files to any MCP-speaking agent: bounded queries (never whole-file dumps),
+id-addressed atomic ops (never regeneration), projections, and validation.
+
+Run:  python -m sarib.mcp_server /path/to/knowledge/dir
+Claude Desktop / Cowork config:
+  { "mcpServers": { "sarib": { "command": "python",
+      "args": ["-m", "sarib.mcp_server", "<dir>"], "cwd": "<repo>/impl" } } }
+"""
+from __future__ import annotations
+import json, pathlib, sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
+from mcp.server.fastmcp import FastMCP
+from sarib import parse, canon, fmt, query as run_query
+from sarib.ops import apply as apply_op, OpRejected
+from sarib.render import VIEWS
+
+ROOT = pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+mcp = FastMCP("sarib")
+
+
+def _doc(file: str):
+    p = (ROOT / file).resolve()
+    assert str(p).startswith(str(ROOT)), "path escape"
+    return p, parse(p.read_text(encoding="utf-8"))
+
+
+@mcp.tool()
+def sarib_query(file: str, spec: str) -> str:
+    """Run a bounded 7-axis query over a .sarib file. spec is JSON:
+    {start, select, direction, order, filter:{type,status,prop:[[k,op,v]]},
+     bound:{max_nodes,max_depth}, projection:[...]}. Returns a result subgraph
+    carrying stable ids — use those ids as op targets (the read/write bridge)."""
+    _, doc = _doc(file)
+    return json.dumps(run_query(doc, json.loads(spec)), ensure_ascii=False)
+
+
+@mcp.tool()
+def sarib_apply(file: str, op: str) -> str:
+    """Apply one atomic operation (JSON: {kind, target, args, expect?}) addressed
+    by node/edge id. Guarded ops (expect:{id:{version:v}}) are rejected if stale.
+    Writes the updated surface back to the file. Costs a delta, not a regeneration."""
+    p, doc = _doc(file)
+    try:
+        apply_op(doc, json.loads(op))
+    except OpRejected as e:
+        return f"REJECTED: {e}"
+    p.write_text(fmt(doc), encoding="utf-8")
+    return "applied"
+
+
+@mcp.tool()
+def sarib_render(file: str, view: str = "outline") -> str:
+    """Project a .sarib file into a view: document | outline (spatial cues) |
+    board (tasks by status) | mermaid (dependency graph, terminal export)."""
+    _, doc = _doc(file)
+    return VIEWS[view](doc)
+
+
+@mcp.tool()
+def sarib_validate(file: str) -> str:
+    """Three-tier validation (D-049): parse is total; returns non-fatal diagnostics."""
+    _, doc = _doc(file)
+    return json.dumps({"nodes": len(doc.nodes), "edges": len(doc.edges),
+                       "diagnostics": doc.diagnostics}, ensure_ascii=False)
+
+
+@mcp.tool()
+def sarib_canon(file: str) -> str:
+    """Canonical normal form (D-041): one byte-string per state; for hashing/diff."""
+    _, doc = _doc(file)
+    return canon(doc)
+
+
+def main():
+    """Console-script entry point (`sarib-mcp <folder>`); folder read from argv at import."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()