sarib 0.1.0__py3-none-any.whl

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/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/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/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/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()

sarib/model.py

@@ -0,0 +1,101 @@
+"""sarib.model — the core object model (Stage 4). Nodes, edges, invariants."""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class Node:
+    id: str
+    type: Optional[str] = None          # None = untyped prose (L0)
+    kind_hint: str = "prose"            # heading | item | prose | document  (surface fidelity only)
+    title: str = ""                     # heading/item line text (sans marks); "" for prose
+    content: str = ""                   # raw inline text (prose body); round-trip faithful
+    slug: Optional[str] = None
+    properties: dict = field(default_factory=dict)
+    status: str = "active"              # active | retracted   (P12)
+    provenance: Optional[str] = None    # None = asserted-by-owner (D-019)
+    parent: Optional[str] = None        # the single home containment edge (D-016)
+    order: int = 0                      # sibling order (invariant 5)
+    version: int = 0                    # bumped per op; expect-precondition target (D-038)
+
+    def name(self) -> str:
+        return self.title or (self.content[:40] if self.content else self.id)
+
+
+@dataclass
+class Edge:
+    id: str
+    type: str
+    source: str
+    target: str                         # node id, or "?unresolved:<name>" (D-024: never guessed)
+    family: str = "crossref"
+    properties: dict = field(default_factory=dict)
+    status: str = "active"
+    provenance: Optional[str] = None
+    version: int = 0
+
+
+@dataclass
+class Doc:
+    meta: dict = field(default_factory=dict)     # front matter (vocab pin, title, ...)
+    nodes: dict = field(default_factory=dict)    # id -> Node (insertion = document order)
+    edges: dict = field(default_factory=dict)    # id -> Edge
+    diagnostics: list = field(default_factory=list)
+
+    # -- containment helpers (the spanning tree, D-016) --
+    def children(self, nid: Optional[str]) -> list:
+        kids = [n for n in self.nodes.values() if n.parent == nid and n.status == "active"]
+        return sorted(kids, key=lambda n: (n.order, n.id))
+
+    def walk(self, nid: Optional[str] = None):
+        """inorder(N, E_c): DFS pre-order by sibling order — THE document (Stage 4 §6)."""
+        for c in self.children(nid):
+            yield c
+            yield from self.walk(c.id)
+
+    def node_by_slug(self, slug: str) -> Optional[Node]:
+        for n in self.nodes.values():
+            if n.slug == slug and n.status == "active":
+                return n
+        return None
+
+    # -- Tier-1 validation: the 10 invariants (Stage 4 §11) --
+    def check_invariants(self) -> list:
+        diags = []
+        seen_slugs = {}
+        for n in self.nodes.values():
+            if n.parent is not None and n.parent not in self.nodes:
+                diags.append(f"invariant2: node {n.id} has missing parent {n.parent}")
+            if n.slug:
+                if n.slug in seen_slugs:
+                    diags.append(f"duplicate-slug: #{n.slug} on {seen_slugs[n.slug]} and {n.id}")
+                seen_slugs[n.slug] = n.id
+        # cycle check on containment (must be a tree)
+        for n in self.nodes.values():
+            hops, p = 0, n.parent
+            while p is not None and hops <= len(self.nodes):
+                p = self.nodes[p].parent if p in self.nodes else None
+                hops += 1
+            if hops > len(self.nodes):
+                diags.append(f"invariant2: containment cycle at {n.id}")
+        for e in self.edges.values():
+            if e.source not in self.nodes:
+                diags.append(f"invariant3: edge {e.id} dangling source {e.source}")
+            if not e.target.startswith("?unresolved:") and e.target not in self.nodes:
+                diags.append(f"invariant3: edge {e.id} dangling target {e.target}")
+        return diags
+
+
+def anchor_owner(doc: "Doc", nid: str) -> str:
+    """Edges anchored in an untitled prose block bubble up to the nearest titled
+    ancestor for traversal/display (Stage 4 §5.3 anchor vs semantic endpoint)."""
+    n = doc.nodes.get(nid)
+    while n is not None and n.kind_hint == "prose" and n.parent:
+        n = doc.nodes.get(n.parent)
+    return n.id if n else nid
+
+
+def normalize_name(s: str) -> str:
+    import unicodedata
+    return " ".join(unicodedata.normalize("NFC", s).casefold().split())

sarib/ops.py

@@ -0,0 +1,110 @@
+"""sarib.ops — the operation vocabulary (Stage 8, D-035..D-039).
+Ops are data; targets are ids (never positions); expect = optimistic concurrency;
+fold(op-set) is order-independent (ops sorted by Lamport ts -> LWW/grow-set semantics).
+"""
+from __future__ import annotations
+from .model import Doc, Node, Edge
+
+PRIMITIVES = {"create-node", "retract-node", "set-content", "set-property",
+              "unset-property", "add-edge", "retract-edge", "move"}
+COMPOSITES = {"merge", "tag"}
+
+
+class OpRejected(Exception):
+    pass
+
+
+def _check_expect(doc: Doc, op: dict):
+    exp = op.get("expect")
+    if not exp:
+        return
+    for tid, cond in exp.items():
+        obj = doc.nodes.get(tid) or doc.edges.get(tid)
+        if obj is None:
+            raise OpRejected(f"expect: target {tid} not found")
+        if "version" in cond and obj.version != cond["version"]:
+            raise OpRejected(f"expect: {tid} at version {obj.version}, expected {cond['version']}")
+        for k, v in cond.get("props", {}).items():
+            if (obj.properties if hasattr(obj, "properties") else {}).get(k) != v:
+                raise OpRejected(f"expect: {tid}.{k} != {v!r}")
+
+
+def apply(doc: Doc, op: dict) -> Doc:
+    """Apply one op, preserving the 10 invariants (D-035). Mutates and returns doc."""
+    _check_expect(doc, op)
+    kind, t, a = op["kind"], op.get("target"), op.get("args", {})
+
+    if kind == "create-node":
+        nid = a.get("id") or f"n{len(doc.nodes) + 1}x"
+        if nid in doc.nodes:
+            raise OpRejected(f"create-node: id {nid} exists")
+        parent = a.get("parent")
+        if parent is not None and parent not in doc.nodes:
+            raise OpRejected(f"create-node: parent {parent} missing")   # invariant 2
+        n = Node(id=nid, type=a.get("type"), kind_hint=a.get("hint", "item"),
+                 title=a.get("title", ""), content=a.get("content", ""),
+                 properties=dict(a.get("props", {})), parent=parent,
+                 order=a.get("order", len(doc.children(parent))),
+                 provenance=op.get("provenance"))
+        doc.nodes[nid] = n
+    elif kind == "retract-node":
+        doc.nodes[t].status = "retracted"                               # P12: never destroy
+    elif kind == "set-content":
+        doc.nodes[t].content = a["content"]
+    elif kind == "set-property":
+        obj = doc.nodes.get(t) or doc.edges[t]
+        obj.properties[a["key"]] = a["value"]
+    elif kind == "unset-property":
+        obj = doc.nodes.get(t) or doc.edges[t]
+        obj.properties.pop(a["key"], None)
+    elif kind == "add-edge":
+        eid = a.get("id") or f"e{len(doc.edges) + 1}x"
+        if a.get("family") == "containment":
+            raise OpRejected("containment is edited only via create-node/move (D-035)")
+        for end in (a["source"], a["target"]):
+            if end not in doc.nodes:
+                raise OpRejected(f"add-edge: endpoint {end} missing")   # invariant 3
+        doc.edges[eid] = Edge(id=eid, type=a["type"], source=a["source"],
+                              target=a["target"], properties=dict(a.get("props", {})),
+                              provenance=op.get("provenance"))
+    elif kind == "retract-edge":
+        doc.edges[t].status = "retracted"
+    elif kind == "move":
+        if a["parent"] not in doc.nodes:
+            raise OpRejected(f"move: parent {a['parent']} missing")
+        p = a["parent"]                                                  # cycle guard (invariant 2)
+        while p is not None:
+            if p == t:
+                raise OpRejected("move: would create containment cycle")
+            p = doc.nodes[p].parent
+        doc.nodes[t].parent = a["parent"]
+        doc.nodes[t].order = a.get("order", len(doc.children(a["parent"])))
+    elif kind == "merge":                                                # composite (D-035)
+        loser, winner = t, a["into"]
+        doc.nodes[loser].status = "retracted"
+        doc.edges[f"e-merge-{loser}"] = Edge(id=f"e-merge-{loser}", type="merged-into",
+                                             source=loser, target=winner)
+        for e in doc.edges.values():
+            if e.target == loser and e.type != "merged-into":
+                e.target = winner
+    elif kind == "tag":
+        return apply(doc, {**op, "kind": "add-edge",
+                           "args": {"type": "tag", "source": t, "target": a["concept"]}})
+    else:
+        raise OpRejected(f"unknown op kind {kind}")
+
+    obj = doc.nodes.get(t) or doc.edges.get(t) if t else None
+    if obj is not None:
+        obj.version += 1
+    diags = doc.check_invariants()
+    if diags:
+        raise OpRejected(f"op would break invariants: {diags}")          # RM14: closed op set
+    return doc
+
+
+def fold(doc: Doc, ops: list) -> Doc:
+    """State = fold(op-set), order-independent: sort by Lamport ts (counter, replica) then apply.
+    Any permutation of `ops` yields the same state (D-037/D-039)."""
+    for op in sorted(ops, key=lambda o: (o.get("ts", [0, 0])[1], o.get("ts", [0, 0])[0], o.get("id", ""))):
+        apply(doc, op)
+    return doc

sarib/parser.py

@@ -0,0 +1,202 @@
+"""sarib.parser — Candidate-A surface -> model. Tier-0 TOTAL parse (D-049):
+every byte string yields a model; unrecognized lines become L0 prose nodes.
+Local, line-shaped, no backtracking (D-045). Deterministic ids in document order.
+"""
+from __future__ import annotations
+import re
+from .model import Doc, Node, Edge, normalize_name
+
+H_RE = re.compile(r"^(#{1,6})\s+(.*)$")
+LI_RE = re.compile(r"^(\s*)[-*]\s+(.*)$")
+FIELD_RE = re.compile(r"^([A-Za-z][\w-]*)::\s*(.*)$")
+ATTR_RE = re.compile(r"\s*\{([^{}]*)\}\s*$")
+BID_RE = re.compile(r"\s*\^([\w-]+)\s*$")
+TYPED_REF_RE = re.compile(r"\[([A-Za-z][\w-]*)::\s*\[\[([^\[\]]+)\]\]\]")
+WIKI_RE = re.compile(r"\[\[([^\[\]]+)\]\]")
+COOKIE_RE = re.compile(r"\s*\[\d+/\d+[^\]]*\]\s*$")  # derived cue: ignored on parse (D-051)
+
+
+def _strip_marks(text: str):
+    """Peel trailing ^id, {attrs}, and derived [k/n] cookies off a title line."""
+    nid = slug = ntype = None
+    props = {}
+    changed = True
+    while changed:                      # peel trailing marks in any order until fixed-point
+        changed = False
+        m = COOKIE_RE.search(text)
+        if m:
+            text, changed = text[: m.start()], True
+            continue
+        m = BID_RE.search(text)
+        if m:
+            nid, text, changed = m.group(1), text[: m.start()], True
+            continue
+        m = ATTR_RE.search(text)
+        if m:
+            for tok in m.group(1).split():
+                if tok.startswith("."):
+                    ntype = tok[1:]
+                elif tok.startswith("#"):
+                    slug = tok[1:]
+                elif "=" in tok:
+                    k, v = tok.split("=", 1)
+                    props[k] = v.strip('"')
+            text, changed = text[: m.start()], True
+    return text.strip(), nid, slug, ntype, props
+
+
+def parse(src: str) -> Doc:
+    doc = Doc()
+    counter = [0]
+
+    def make_id(explicit):
+        if explicit:
+            return explicit
+        counter[0] += 1
+        return f"n{counter[0]}"
+
+    lines = src.splitlines()
+    i = 0
+    # -- front matter --
+    if lines and lines[0].strip() == "---":
+        j = 1
+        while j < len(lines) and lines[j].strip() != "---":
+            if ":" in lines[j]:
+                k, v = lines[j].split(":", 1)
+                doc.meta[k.strip()] = v.strip()
+            j += 1
+        i = j + 1
+
+    stack = []          # [(heading_level, node_id)]
+    current = None      # node fields attach to (last heading/item)
+    para: list = []
+    pending_edges = []  # (source_id, rel, target_name)
+
+    def container():
+        return stack[-1][1] if stack else None
+
+    def scan_inline(source_id: str, text: str):
+        for m in TYPED_REF_RE.finditer(text):
+            pending_edges.append((source_id, m.group(1), m.group(2)))
+        stripped = TYPED_REF_RE.sub("", text)
+        for m in WIKI_RE.finditer(stripped):
+            pending_edges.append((source_id, "relates-to", m.group(1)))
+
+    def flush_para():
+        nonlocal para
+        if not para:
+            return
+        text = "\n".join(para).strip()
+        para = []
+        if not text or text.startswith("<!--"):
+            return
+        n = Node(id=make_id(None), kind_hint="prose", content=text,
+                 parent=container(), order=len(doc.children(container())))
+        doc.nodes[n.id] = n
+        scan_inline(n.id, text)
+
+    while i < len(lines):
+        line = lines[i]
+        # multi-line HTML comments: skip wholesale
+        if line.lstrip().startswith("<!--"):
+            while i < len(lines) and "-->" not in lines[i]:
+                i += 1
+            i += 1
+            continue
+        if not line.strip():
+            flush_para()
+            i += 1
+            continue
+
+        m = H_RE.match(line)
+        if m:
+            flush_para()
+            level = len(m.group(1))
+            text, nid, slug, ntype, props = _strip_marks(m.group(2))
+            while stack and stack[-1][0] >= level:
+                stack.pop()
+            n = Node(id=make_id(nid), kind_hint="heading", title=text, type=ntype,
+                     slug=slug, properties=props, parent=container(),
+                     order=len(doc.children(container())))
+            n.properties["_level"] = level
+            doc.nodes[n.id] = n
+            scan_inline(n.id, text)
+            stack.append((level, n.id))
+            current = n
+            i += 1
+            continue
+
+        m = LI_RE.match(line)
+        if m:
+            flush_para()
+            text, nid, slug, ntype, props = _strip_marks(m.group(2))
+            n = Node(id=make_id(nid), kind_hint="item", title=text, type=ntype,
+                     slug=slug, properties=props, parent=container(),
+                     order=len(doc.children(container())))
+            doc.nodes[n.id] = n
+            scan_inline(n.id, text)
+            current = n
+            i += 1
+            continue
+
+        m = FIELD_RE.match(line)
+        if m and current is not None:
+            key, val = m.group(1), m.group(2).strip()
+            wl = WIKI_RE.fullmatch(val)
+            if wl:  # field whose value is a wikilink = a typed edge (owner:: [[Alice]])
+                pending_edges.append((current.id, key, wl.group(1)))
+                current.properties[key] = val   # keep raw for surface round-trip (D-051);
+                                                # canon skips wikilink-valued props (edge-represented)
+            else:
+                current.properties[key] = val
+            i += 1
+            continue
+
+        para.append(line)
+        i += 1
+    flush_para()
+
+    # -- reference resolution (D-024: explicit slug -> nearest-in-containment -> global -> unresolved) --
+    by_name: dict = {}
+    for n in doc.nodes.values():
+        if n.title:
+            by_name.setdefault(normalize_name(n.title), []).append(n.id)
+
+    def resolve(source_id: str, name: str):
+        if name.startswith("#"):
+            hit = doc.node_by_slug(name[1:])
+            return hit.id if hit else None
+        cands = by_name.get(normalize_name(name), [])
+        if len(cands) == 1:
+            return cands[0]
+        if len(cands) > 1:  # nearest-in-containment: walk up source ancestors
+            anc, p = [], doc.nodes.get(source_id)
+            while p is not None:
+                anc.append(p.id)
+                p = doc.nodes.get(p.parent) if p.parent else None
+            def dist(cid):
+                q, d = doc.nodes.get(cid), 0
+                while q is not None:
+                    if q.id in anc:
+                        return d + anc.index(q.id)
+                    q = doc.nodes.get(q.parent) if q.parent else None
+                    d += 1
+                return 10 ** 6
+            ranked = sorted(cands, key=lambda c: (dist(c), c))
+            if dist(ranked[0]) < dist(ranked[1]):
+                return ranked[0]
+            doc.diagnostics.append(f"ambiguous-reference: '{name}' from {source_id}")
+            return None
+        return None
+
+    ec = 0
+    for src_id, rel, name in pending_edges:
+        tid = resolve(src_id, name)
+        ec += 1
+        if tid is None:
+            doc.diagnostics.append(f"unresolved-reference: '{name}' from {src_id}")
+            tid = f"?unresolved:{name}"
+        doc.edges[f"e{ec}"] = Edge(id=f"e{ec}", type=rel, source=src_id, target=tid)
+
+    doc.diagnostics.extend(doc.check_invariants())
+    return doc

sarib/query.py

@@ -0,0 +1,99 @@
+"""sarib.query — the 7-axis parameterized walk (Stage 6/7, D-026..D-034).
+spec = {start, select, direction, order, filter, bound, derivation, projection}
+Returns a bounded result subgraph carrying stable ids (D-032). Cycle-safe (D-027).
+"""
+from __future__ import annotations
+from .model import Doc, anchor_owner
+
+
+def _match(doc: Doc, n, flt) -> bool:
+    if not flt:
+        return True
+    if "type" in flt and (n.type or "") != flt["type"] and not (n.type or "").endswith(":" + flt["type"]):
+        return False
+    if "status" in flt and n.properties.get("status", n.status) != flt["status"]:
+        return False
+    for key, op, val in flt.get("prop", []):
+        have = n.properties.get(key)
+        if op == "=" and str(have) != str(val):
+            return False
+        if op == "!=" and str(have) == str(val):
+            return False
+        if op == "exists" and have is None:
+            return False
+    return True
+
+
+def query(doc: Doc, spec: dict) -> dict:
+    start = spec.get("start", "all")
+    select = spec.get("select", "none")
+    direction = spec.get("direction", "forward")
+    order = spec.get("order", "document")
+    flt = spec.get("filter", {})
+    bound = spec.get("bound", {"max_nodes": 500})
+    proj = spec.get("projection", ["id", "type", "title", "props"])
+    maxn = bound.get("max_nodes", 500)
+    maxd = bound.get("max_depth", 50)
+
+    result_ids, result_edges, cursor = [], [], None
+
+    if select == "none":                       # pure selection (priority/chronological case)
+        pool = [n for n in doc.walk(None) if _match(doc, n, flt)]
+        if order.startswith("by-"):
+            key = order[3:]
+            pool.sort(key=lambda n: (str(n.properties.get(key, "~")), n.id))
+        result_ids = [n.id for n in pool[:maxn]]
+        cursor = pool[maxn].id if len(pool) > maxn else None
+    else:                                      # graph walk
+        seeds = [s for s in ([start] if isinstance(start, str) else start) if s in doc.nodes]
+        seen, frontier, depth = set(), list(seeds), 0
+        while frontier and len(result_ids) < maxn and depth <= maxd:
+            nxt = []
+            for nid in frontier:
+                if nid in seen:                # cycle-safe: emit-once (D-027)
+                    continue
+                seen.add(nid)
+                n = doc.nodes[nid]
+                if _match(doc, n, flt):
+                    result_ids.append(nid)
+                if select in ("contains", "any"):
+                    for c in doc.children(nid):
+                        nxt.append(c.id)
+                if select != "contains":
+                    for eid in sorted(doc.edges):        # tie-break cascade (D-029)
+                        e = doc.edges[eid]
+                        if e.status != "active" or e.target.startswith("?unresolved:"):
+                            continue
+                        etypes = select if isinstance(select, list) else [select]
+                        if select != "any" and e.type not in etypes:
+                            continue
+                        esrc = anchor_owner(doc, e.source)
+                        etgt = anchor_owner(doc, e.target)
+                        if direction in ("forward", "both") and esrc == nid:
+                            nxt.append(etgt); result_edges.append(eid)
+                        if direction in ("backward", "both") and etgt == nid:
+                            nxt.append(esrc); result_edges.append(eid)
+            frontier = nxt
+            depth += 1
+        if frontier:
+            cursor = frontier[0]
+
+    def project(nid):
+        n = doc.nodes[nid]
+        rec = {}
+        for f in proj:
+            if f == "props":
+                rec["props"] = {k: v for k, v in n.properties.items() if not k.startswith("_")}
+            elif f == "title":
+                rec["title"] = n.name()
+            else:
+                rec[f] = getattr(n, f, None)
+        return rec
+
+    return {"nodes": [project(i) for i in result_ids],
+            "edges": [{"id": e, "type": doc.edges[e].type,
+                       "source": anchor_owner(doc, doc.edges[e].source),
+                       "target": anchor_owner(doc, doc.edges[e].target)}
+                      for e in dict.fromkeys(result_edges)],
+            "cursor": cursor,
+            "diagnostics": doc.diagnostics}

sarib/render.py

@@ -0,0 +1,99 @@
+"""sarib.render — projections (Stage 12, D-052): view = query + template.
+document (= fmt, the live canonical surface), outline (+spatial cues, D-047),
+board (terminal), mermaid (terminal, D-053).
+"""
+from __future__ import annotations
+from .model import Doc, anchor_owner
+
+
+def fmt(doc: Doc) -> str:
+    """Model -> Candidate-A surface. The document projection; idempotent (D-051)."""
+    out = []
+    if doc.meta:
+        out.append("---")
+        for k, v in doc.meta.items():
+            out.append(f"{k}: {v}")
+        out.append("---\n")
+    for n in doc.walk(None):
+        if n.kind_hint == "heading":
+            level = int(n.properties.get("_level", _depth(doc, n) + 1))
+            marks = ""
+            attrs = []
+            if n.type:
+                attrs.append(f".{n.type}")
+            if n.slug:
+                attrs.append(f"#{n.slug}")
+            if attrs:
+                marks += " {" + " ".join(attrs) + "}"
+            if not n.id.startswith("n") or not n.id[1:].isdigit():
+                marks += f" ^{n.id}"
+            out.append(f"{'#' * level} {n.title}{marks}")
+            for k, v in n.properties.items():
+                if not k.startswith("_"):
+                    out.append(f"{k}:: {v}")
+            out.append("")
+        elif n.kind_hint == "item":
+            t = f"- {n.title}"
+            if n.type:
+                t += f" {{.{n.type}}}"
+            out.append(t)
+        else:
+            out.append(n.content + "\n")
+    return "\n".join(out).rstrip() + "\n"
+
+
+def _depth(doc: Doc, n) -> int:
+    d, p = 0, n.parent
+    while p is not None:
+        d, p = d + 1, doc.nodes[p].parent
+    return d
+
+
+def outline(doc: Doc) -> str:
+    """Outline view with spatial cues: depth indent, [k/n] task cookies, subtree size (D-047)."""
+    out = []
+    for n in doc.walk(None):
+        if n.kind_hint == "prose":
+            continue
+        d = _depth(doc, n)
+        sub = list(doc.walk(n.id))
+        tasks = [m for m in sub if m.type and m.type.endswith("task")]
+        cue = ""
+        if tasks:
+            done = sum(1 for t in tasks if t.properties.get("status") == "done")
+            cue = f" [{done}/{len(tasks)}]"
+        size = f" ({len(sub)})" if sub else ""
+        typ = f" ·{n.type}" if n.type else ""
+        out.append(f"{'  ' * d}- {n.title}{typ}{cue}{size}")
+    return "\n".join(out) + "\n"
+
+
+def board(doc: Doc) -> str:
+    """Kanban projection of tasks by status (terminal export)."""
+    cols: dict = {}
+    for n in doc.walk(None):
+        if n.type and n.type.endswith("task"):
+            cols.setdefault(n.properties.get("status", "todo"), []).append(n)
+    out = []
+    for status in sorted(cols):
+        out.append(f"== {status.upper()} ({len(cols[status])}) ==")
+        for n in cols[status]:
+            due = f"  (due {n.properties['due']})" if "due" in n.properties else ""
+            out.append(f"  • {n.title}{due}   [{n.id}]")
+    return "\n".join(out) + "\n"
+
+
+def mermaid(doc: Doc) -> str:
+    """Dependency-graph projection -> Mermaid (terminal export, D-053: self-declared read-only)."""
+    out = ["%% terminal export — edits do not flow back (D-053)", "flowchart TD"]
+    for e in doc.edges.values():
+        if e.status != "active" or e.target.startswith("?unresolved:"):
+            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.id != t.id:
+            out.append(f'  {s.id}["{s.name()}"] -->|{e.type}| {t.id}["{t.name()}"]')
+    return "\n".join(out) + "\n"
+
+
+VIEWS = {"document": fmt, "outline": outline, "board": board, "mermaid": mermaid}

sarib-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+sarib/__init__.py,sha256=irzBkLDEZmAmO6RpDzziyeP489DTSIHxLjT6AJJgXTM,339
+sarib/canon.py,sha256=WDKu6d4mmhffdUhtdiKZCv6gRnImul5NM4udvoR0UEA,2000
+sarib/cli.py,sha256=qIc3tS9w44269R9xrwZCdgWRblOzC_EwEiKWZ_IB1UM,3717
+sarib/importer.py,sha256=aM2SJx0R9ogNdJV7zfdxQvqToUQ4nH8RgaQw323h9Us,14156
+sarib/mcp_server.py,sha256=t7fWdTb5IHE-rMW_kPWYFJ2hjTOXYE7uXZr2kLZJUyE,2933
+sarib/model.py,sha256=2Rfe9NqpuM4EGzBohYOlVD35VPdQjPuKnZZMxK9QGcI,4297
+sarib/ops.py,sha256=J4aoHv1zz7l6Q7N5LVVEe9xCQs3SebFJLiNYXCvK8R8,5080
+sarib/parser.py,sha256=7gOrB6pWTjsOT5ITlLjp_h65xIbD0XVqIqM8FptplVc,7345
+sarib/query.py,sha256=Ogjt6_LyV_9NgRom3FcpKEfTVs_UjciVlmmjuV4ynrQ,4331
+sarib/render.py,sha256=smOo4MFN8DBZJQTdt9z06oafzTCpxi0s3rS9-r6OcjY,3639
+sarib-0.1.0.dist-info/METADATA,sha256=nOXweifPyyvhVbADo_IfSOyhbqIBkHVpgXazB5jCWzw,2108
+sarib-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+sarib-0.1.0.dist-info/entry_points.txt,sha256=_FOva6SOVbeLRd3zLr34XlsXyEKQaj5ToojxvWsUKRc,75
+sarib-0.1.0.dist-info/top_level.txt,sha256=CMi2JK_rrBycJIg-N6SrBPfiX8_9nhOXCftH6DgG2EU,6
+sarib-0.1.0.dist-info/RECORD,,

sarib-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sarib-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+sarib = sarib.cli:main
+sarib-mcp = sarib.mcp_server:main

sarib-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sarib