brainiac-cli 0.16.0__py3-none-any.whl

brain/mcp_adapter.py

@@ -0,0 +1,217 @@
+"""OPTIONAL, DELETABLE ~50-line MCP adapter for the pure Claude Desktop CHAT tab.
+
+This is the ONE surface that cannot run a shell command — so it gets a thin MCP
+bridge. Every OTHER harness (Codex, Claude Code, Gemini CLI, the Desktop Code
+tab, the Cowork VM) calls the ``brain`` CLI directly; MCP is NEVER the
+foundation. Delete this file and nothing else breaks.
+
+The bridge wraps the SAME ``BrainCore`` + the SAME deny-by-default
+``ClassificationFilter`` the CLI applies at stdout — there is no second egress
+path to keep in sync. It exposes ONLY the read verbs (``search`` / ``get`` /
+``recent``); it never exposes write/draft/host-broker commands. ``dispatch`` is
+the pure, importable, testable core; ``serve`` is the (optional) stdio transport
+glue requiring ``pip install 'brainiac-cli[mcp]'``.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from . import classification as cls
+from . import egress
+from .core import BrainCore
+
+READ_TOOLS = ("search", "get", "recent", "bases_query", "dossier")
+
+# Server-side egress ceiling (SEC-01 hardening). A caller-supplied ``max_tier``
+# was previously honored unbounded — an MCP client could simply ASK for
+# ``max_tier="MNPI"`` and receive it. That is a human-gated elevation on the
+# CLI (an explicit ``--max-tier`` flag someone typed), but the MCP transport has
+# no equivalent "a person is watching this" signal, so the adapter now clamps
+# EVERY request to a ceiling the operator configures out-of-band. A caller may
+# still request something NARROWER than the ceiling (always honored); it can
+# never request higher.
+EGRESS_CEILING_ENV_VAR = "BRAIN_MAX_EGRESS_TIER"
+DEFAULT_EGRESS_CEILING_TIER = "MNPI"  # matches cls.DEFAULT_MAX_TIER: the MCP
+# adapter is a HOST-side surface (Chat tab / Cowork MCP-on-host), so it gets
+# the same full-vault default as the host CLI (owner decision, 2026-07-10).
+# Operators who want a hard server-side cap set $BRAIN_MAX_EGRESS_TIER; the
+# clamp mechanism below is unchanged and still narrows every request to it.
+
+
+def _egress_ceiling_tier() -> str:
+    """The operator-configured hard ceiling for MCP egress. Unset or an
+    unrecognised value falls back to the conservative default — fail-closed,
+    never fail-open on a typo'd env var."""
+    raw = os.environ.get(EGRESS_CEILING_ENV_VAR, DEFAULT_EGRESS_CEILING_TIER).strip()
+    return raw if raw in cls.RANK else DEFAULT_EGRESS_CEILING_TIER
+
+
+def _clamp_max_tier(requested_tier: str) -> str:
+    """Clamp a caller-supplied ``max_tier`` to ``min(requested_rank, ceiling_rank)``.
+
+    An unrecognised ``requested_tier`` is passed through UNCHANGED so the
+    existing ``ClassificationFilter`` validation (``egress.apply_gate`` ->
+    ``cls.ClassificationFilter.__post_init__``) still raises its normal, clear
+    "unknown max_tier" error — this clamp only ever narrows a VALID request, it
+    never manufactures or swallows a validation error.
+    """
+    requested = requested_tier.strip()
+    if requested not in cls.RANK:
+        return requested_tier
+    ceiling_rank = cls.RANK[_egress_ceiling_tier()]
+    clamped_rank = min(cls.RANK[requested], ceiling_rank)
+    return cls.TIERS[clamped_rank]
+
+
+def _filtered(items: list[dict], max_tier: str) -> tuple[list[dict], dict]:
+    # Same single egress chokepoint as the CLI (SEC-01) — no second egress path.
+    return egress.apply_gate(items, max_tier)
+
+
+def dispatch(tool: str, args: dict[str, Any], *, core: BrainCore | None = None,
+             vault: str | None = None) -> dict[str, Any]:
+    """Run one read tool through the SAME egress gate as the CLI. Pure + testable.
+
+    ``max_tier`` is clamped server-side to the ``BRAIN_MAX_EGRESS_TIER`` ceiling
+    (default "Internal") BEFORE it reaches the classification filter — a caller
+    cannot self-elevate past the configured ceiling by simply asking.
+    """
+    core = core or BrainCore(vault=vault)  # host or vm; reads only either way
+    max_tier = _clamp_max_tier(str(args.get("max_tier", cls.DEFAULT_MAX_TIER)))
+    if tool in ("search", "hybrid-search"):
+        hits = [h.to_dict() for h in core.hybrid_search(str(args["query"]), k=int(args.get("k", 10)))]
+        surfaced, report = _filtered(hits, max_tier)
+        out: dict[str, Any] = {"results": surfaced, "egress": report}
+        # RET-09 freshness signal — same contract as the CLI (see
+        # cli._freshness_block): tells the agent when the vault continues
+        # past its newest hit, so "latest/current" answers don't silently
+        # ground on stale-but-coherent material.
+        dates = [h.get("date", "") for h in surfaced if h.get("date")]
+        if dates:
+            try:
+                fresh = core.source_freshness(max(dates), max_tier)
+            except Exception:  # noqa: BLE001 — freshness must never break search
+                fresh = None
+            if fresh and fresh.get("newer_count", 0) > 0:
+                fresh["hint"] = (
+                    f"{fresh['newer_count']} note(s)/source(s) are newer than your "
+                    f"newest hit ({fresh['newest_hit_date']}; vault newest "
+                    f"{fresh['vault_newest']}) — for 'latest/current' questions, "
+                    f"probe past these hits (recent, bases_query latest_only=True, "
+                    f"or a narrower search) before treating this as current.")
+            if fresh:
+                out["freshness"] = fresh
+        return out
+    if tool in ("get", "read"):
+        note = core.get(str(args["id"]))
+        surfaced, report = _filtered([note] if note else [], max_tier)
+        return {"result": surfaced[0] if surfaced else None, "egress": report}
+    if tool == "recent":
+        surfaced, report = _filtered(core.recent(limit=int(args.get("n", 10))), max_tier)
+        return {"results": surfaced, "egress": report}
+    if tool == "dossier":
+        res = core.dossier(str(args["query"]), k=int(args.get("k", 12)))
+        decisions, drep = _filtered(res["decisions"], max_tier)
+        sources, srep = _filtered(res["sources"], max_tier)
+        # Merge the two egress reports by NAMED keys — a naive comprehension
+        # KeyErrors on conditional keys (casing_mismatch_warnings appears
+        # only when a wrong-case tier exists in that half).
+        report: dict[str, Any] = {
+            k2: drep[k2] + srep[k2]
+            for k2 in ("total", "surfaced", "withheld",
+                       "withheld_unlabelled_default_deny")
+        }
+        report["max_tier"] = drep["max_tier"]
+        casing = sorted(set(drep.get("casing_mismatch_warnings", []))
+                        | set(srep.get("casing_mismatch_warnings", [])))
+        if casing:
+            report["casing_mismatch_warnings"] = casing
+        return {"query": res["query"], "decisions": decisions,
+                "sources": sources,
+                "retired_excluded": res["retired_excluded"], "egress": report}
+    if tool in ("bases-query", "bases_query"):
+        filters = dict(args.get("where") or {})
+        items = core.bases_query(
+            filters, k=int(args.get("k", 50)),
+            latest_only=bool(args.get("latest_only", False)),
+            as_of=args.get("as_of") or None)
+        surfaced, report = _filtered(items, max_tier)
+        return {"results": surfaced, "egress": report}
+    raise ValueError(f"unknown / non-read tool {tool!r}; MCP adapter exposes only {READ_TOOLS}")
+
+
+def serve(vault: str | None = None) -> None:  # pragma: no cover - transport glue
+    """Optional stdio MCP server for the Chat tab. Requires the `mcp` package."""
+    from mcp.server.fastmcp import FastMCP
+
+    core = BrainCore(vault=vault)
+    server = FastMCP("brain")
+
+    @server.tool()
+    def search(query: str, k: int = 10, max_tier: str = cls.DEFAULT_MAX_TIER) -> dict:
+        """Hybrid (BM25+dense) retrieval over the vault, egress-filtered.
+
+        Every hit carries `date` (its valid time), `is_latest_version`, and
+        `type` — the AUTHORITY signal: a `type: decision` hit IS the
+        recorded decision layer; a `type: source` hit (memos, decks,
+        drafts) is material under consideration and NEVER overturns a
+        decision on its own — if a newer source conflicts with a decision
+        note, report the tension, don't promote the proposal. READ THE
+        `freshness` BLOCK: when it reports sources newer than your newest
+        hit, the vault continues past what you just retrieved — for
+        'latest/current' questions, probe further (recent, bases_query with
+        latest_only=True, or a narrower search) before treating the result
+        as the current state. If `egress.hint` reports withheld notes,
+        re-call with a higher max_tier instead of concluding the vault is
+        empty. Curated notes (zone brain/) are synthesis; zone raw/ holds
+        the newest unprocessed sources — check both for recency-sensitive
+        questions."""
+        return dispatch("search", {"query": query, "k": k, "max_tier": max_tier}, core=core)
+
+    @server.tool()
+    def get(id: str, max_tier: str = cls.DEFAULT_MAX_TIER) -> dict:
+        """Fetch one full note by id, egress-filtered. Inspect
+        `superseded_by` / `previous_version` / `is_latest_version` on the
+        result to walk a version chain ("previous version", "what replaced
+        this")."""
+        return dispatch("get", {"id": id, "max_tier": max_tier}, core=core)
+
+    @server.tool()
+    def recent(n: int = 10, max_tier: str = cls.DEFAULT_MAX_TIER) -> dict:
+        """List the most recently created/updated notes, egress-filtered —
+        the cheapest way to see what entered the vault lately (use after a
+        search whose freshness block reported newer sources)."""
+        return dispatch("recent", {"n": n, "max_tier": max_tier}, core=core)
+
+    @server.tool()
+    def dossier(query: str, k: int = 12, max_tier: str = cls.DEFAULT_MAX_TIER) -> dict:
+        """THE ONE-CALL SWEEP for decision-state questions ("what have we
+        decided", "latest decisions", "current state of X"). Returns the
+        decision layer and the sources under consideration SEPARATED, with
+        each decision carrying a `tensions` list — newer sources that
+        post-date it (report the tension, never promote the proposal) —
+        and retired versions already excluded. Prefer this over plain
+        search for decision-state questions; fall back to search/get for
+        everything else."""
+        return dispatch("dossier", {"query": query, "k": k, "max_tier": max_tier}, core=core)
+
+    @server.tool()
+    def bases_query(where: dict | None = None, k: int = 50,
+                    latest_only: bool = False, as_of: str = "",
+                    max_tier: str = cls.DEFAULT_MAX_TIER) -> dict:
+        """Structured frontmatter query (no embedding), egress-filtered.
+        `where` filters exact frontmatter keys (e.g. {"type": "decision"}).
+        TEMPORAL ROUTING: for "what's current/latest" use latest_only=True
+        (excludes superseded notes); for "as of <date>" pass
+        as_of="YYYY-MM-DD" (point-in-time view). Prefer this over semantic
+        search when the question is really about time or note metadata."""
+        return dispatch("bases_query", {
+            "where": where or {}, "k": k, "latest_only": latest_only,
+            "as_of": as_of or None, "max_tier": max_tier}, core=core)
+
+    server.run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    serve()

brain/multihop.py

@@ -0,0 +1,232 @@
+"""Graph-augmented multi-hop retrieval (RET-06).
+
+Flat top-k retrieval answers "which single note is most similar to this query".
+A *multi-hop* question — "how does Alex Silva's exit connect to the org-transition
+programme", "Contoso runs S/4HANA while Northwind runs a different SAP estate, what
+does the JV do" — asks about a RELATIONSHIP between two or more named entities.
+The relevant evidence is often spread across several notes linked by
+``[[wikilinks]]``; no single note is top-k-similar to the whole question, so
+flat dense/lexical retrieval misses the corroborating notes in the tail.
+
+This module adds a *gated* graph-expansion step on top of ``hybrid_search``:
+
+  1. **Gate (query-intrinsic).** Detect whether the query is "multi-hop-shaped"
+     — it names **>= 2 distinct entities** (people / companies / decisions /
+     projects / concepts) that exist as notes. A ubiquitous hub entity
+     (``contoso`` — mentioned by almost every query in this corpus) does NOT count
+     toward the threshold, though it may still seed the walk. Single-hop
+     queries fail the gate and are returned by flat ``hybrid_search`` UNCHANGED
+     — so single-hop latency and quality can never regress (the graph code is
+     never even reached).
+
+  2. **Seed.** Seeds = the entity notes named in the query, UNION the top few
+     flat hits (the notes flat retrieval already judged relevant).
+
+  3. **Expand.** Wikilink-BFS + Personalized-PageRank from the seeds
+     (``brain.graph``) — DISCOVERY-ONLY (RET-03): the derived graph is never
+     authoritative, it only nominates candidate note ids.
+
+  4. **Re-rank (flat-dominant weighted RRF).** Fuse the flat ranking with the
+     graph ranking. The flat list carries weight 1.0; the graph list a smaller
+     ``graph_weight`` (<= 1). This is deliberately conservative: the top flat
+     hit can never be displaced by a discovery-only candidate, and a graph-only
+     note (one flat never retrieved) lands in the tail — but a note that flat
+     retrieved *weakly* (rank 11-30) AND the graph corroborates gets promoted
+     into the top-k. That promotion of a graph-corroborated flat-tail note is
+     the multi-hop recall/nDCG mechanism.
+
+The graph and the entity lexicon are built once and cached on the owning index
+(both are derived from the immutable ``notes`` table), so the per-query cost of
+the multi-hop path is a walk over an in-memory graph, and the per-query cost of
+the single-hop path is one cheap regex scan over ~250 entity surface forms.
+"""
+from __future__ import annotations
+
+import re
+import sqlite3
+import unicodedata
+from dataclasses import dataclass
+
+from .graph import (
+    LinkGraph,
+    personalized_pagerank,
+    wikilink_bfs,
+)
+
+# Entity-typed notes whose titles are the multi-hop "hop" vocabulary. These are
+# the ``type:`` frontmatter values the projection assigns to People / Companies
+# / Decisions / Projects / Concepts notes.
+ENTITY_TYPES: tuple[str, ...] = ("person", "company", "decision", "project", "concept")
+
+# Ubiquitous hub entities: mentioned by nearly every query in this corpus, so
+# they are not DISCRIMINATING evidence of multi-hop intent. They may still seed
+# the graph walk, but they do not count toward the >= 2 gate.
+HUB_STOPLIST: frozenset[str] = frozenset({"contoso"})
+
+# Minimum surface-form length — avoids matching 2-3 char acronyms that collide
+# with common substrings (word-boundary anchored, but still noisy when short).
+_MIN_FORM_LEN = 4
+
+# Generic single-word concept titles that are too common to be entity evidence.
+_GENERIC_FORMS: frozenset[str] = frozenset(
+    {"governance", "legal", "budget", "roadmap", "strategy", "security",
+     "compliance", "risk", "data", "cloud", "digital"}
+)
+
+
+def _norm(s: str | None) -> str:
+    return unicodedata.normalize("NFC", (s or "")).lower().strip()
+
+
+@dataclass(frozen=True)
+class EntityMention:
+    note_id: str
+    surface: str
+    etype: str
+    is_hub: bool
+
+
+class EntityLexicon:
+    """Query -> entity-note mentions, built from the entity-typed notes.
+
+    Cheap to query (regex scan over the compiled surface forms), built once."""
+
+    __slots__ = ("_forms",)
+
+    def __init__(self, forms: list[tuple[re.Pattern[str], str, str, str, bool]]):
+        self._forms = forms
+
+    @classmethod
+    def build(cls, conn: sqlite3.Connection) -> "EntityLexicon":
+        placeholders = ",".join("?" * len(ENTITY_TYPES))
+        rows = conn.execute(
+            f"SELECT id, title, type FROM notes WHERE type IN ({placeholders})",
+            ENTITY_TYPES,
+        ).fetchall()
+        forms: list[tuple[re.Pattern[str], str, str, str, bool]] = []
+        for nid, title, etype in rows:
+            surface = _norm(title)
+            if len(surface) < _MIN_FORM_LEN or surface in _GENERIC_FORMS:
+                continue
+            pat = re.compile(r"(?<!\w)" + re.escape(surface) + r"(?!\w)")
+            forms.append((pat, nid, surface, etype, surface in HUB_STOPLIST))
+        # Longest surface first so a specific "s/4hana" is preferred over a bare
+        # substring when both would match (mentions() de-dups by note id anyway).
+        forms.sort(key=lambda t: -len(t[2]))
+        return cls(forms)
+
+    def mentions(self, query: str) -> list[EntityMention]:
+        """Distinct entity notes whose surface form appears in the query."""
+        q = _norm(query)
+        seen: dict[str, EntityMention] = {}
+        for pat, nid, surface, etype, is_hub in self._forms:
+            if nid in seen:
+                continue
+            if pat.search(q):
+                seen[nid] = EntityMention(nid, surface, etype, is_hub)
+        return list(seen.values())
+
+
+def is_multihop_shaped(mentions: list[EntityMention]) -> bool:
+    """True iff the query names >= 2 distinct NON-HUB entity notes.
+
+    This is the deployable, query-intrinsic gate: a multi-hop question is one
+    that references at least two specific entities whose relationship the graph
+    can traverse. Hub entities (``contoso``) are excluded from the count so that
+    "<hub> + one incidental entity" single-hop queries do not trip the gate."""
+    non_hub = {m.note_id for m in mentions if not m.is_hub}
+    return len(non_hub) >= 2
+
+
+def rank_graph_candidates(
+    graph: LinkGraph,
+    seeds: list[str],
+    *,
+    depth: int = 2,
+    limit: int = 30,
+) -> list[str]:
+    """Ordered discovery-only candidate note ids from a PREBUILT graph.
+
+    Mirrors ``graph.graph_expand`` but takes an already-built graph so the eval
+    harness can reuse one graph across every query. Ranks by
+    ``(ppr desc, hops asc, id)`` and drops the seeds themselves."""
+    known = [s for s in dict.fromkeys(seeds) if s in graph.nodes]
+    if not known:
+        return []
+    bfs = wikilink_bfs(graph, known, depth=depth)
+    hops = {d["id"]: d["hops"] for d in bfs}
+    ppr = personalized_pagerank(graph, known)
+    seed_set = set(known)
+    cands = (set(hops) | {n for n, s in ppr.items() if s > 0.0}) - seed_set
+    ranked = sorted(cands, key=lambda n: (-ppr.get(n, 0.0), hops.get(n, 99), n))
+    return ranked[:limit]
+
+
+def fuse_flat_and_graph(
+    flat_ids: list[str],
+    graph_ids: list[str],
+    *,
+    rrf_k: int = 60,
+    graph_weight: float = 0.5,
+) -> list[tuple[str, float]]:
+    """Flat-dominant weighted Reciprocal Rank Fusion.
+
+    ``score(id) = 1/(rrf_k + rank_flat) + graph_weight * 1/(rrf_k + rank_graph)``
+
+    With ``graph_weight <= 1`` the flat list dominates: the flat rank-1 note
+    (contribution ``1/(rrf_k+1)``) can never be overtaken by a graph-ONLY note
+    (max contribution ``graph_weight/(rrf_k+1)``). A note present in BOTH lists
+    accumulates from both and is promoted. Returns ``[(id, score)]`` descending;
+    ties broken by flat order (stable)."""
+    scores: dict[str, float] = {}
+    order: dict[str, int] = {}
+    for rank, nid in enumerate(flat_ids, start=1):
+        scores[nid] = scores.get(nid, 0.0) + 1.0 / (rrf_k + rank)
+        order.setdefault(nid, rank)
+    for rank, nid in enumerate(graph_ids, start=1):
+        scores[nid] = scores.get(nid, 0.0) + graph_weight * (1.0 / (rrf_k + rank))
+        order.setdefault(nid, 10_000 + rank)
+    return sorted(scores.items(), key=lambda kv: (-kv[1], order[kv[0]]))
+
+
+def graph_augmented_ranking(
+    query: str,
+    flat_ids: list[str],
+    lexicon: EntityLexicon,
+    graph: LinkGraph,
+    *,
+    depth: int = 2,
+    graph_weight: float = 0.5,
+    rrf_k: int = 60,
+    seed_flat_top: int = 3,
+    candidate_limit: int = 30,
+) -> tuple[bool, list[str], dict]:
+    """Return ``(fired, ranked_ids, trace)``.
+
+    ``fired`` is False for single-hop queries — then ``ranked_ids == flat_ids``
+    unchanged. When fired, seeds = named entities UNION the top ``seed_flat_top``
+    flat hits; graph candidates are fused into the flat ranking (flat-dominant)."""
+    mentions = lexicon.mentions(query)
+    fired = is_multihop_shaped(mentions)
+    trace: dict = {
+        "fired": fired,
+        "entities": [m.surface for m in mentions],
+        "non_hub_entities": [m.surface for m in mentions if not m.is_hub],
+    }
+    if not fired:
+        return False, list(flat_ids), trace
+
+    entity_seeds = [m.note_id for m in mentions]
+    seeds = list(dict.fromkeys(entity_seeds + flat_ids[:seed_flat_top]))
+    graph_ids = rank_graph_candidates(
+        graph, seeds, depth=depth, limit=candidate_limit
+    )
+    trace["seeds"] = seeds
+    trace["graph_candidates"] = graph_ids
+    if not graph_ids:
+        # No reachable neighbourhood — nothing to fuse; flat order stands.
+        return True, list(flat_ids), trace
+    fused = fuse_flat_and_graph(
+        flat_ids, graph_ids, rrf_k=rrf_k, graph_weight=graph_weight
+    )
+    return True, [nid for nid, _ in fused], trace

brain/notes.py

@@ -0,0 +1,195 @@
+"""Note model + vault scanning. Markdown files are the single source of truth."""
+from __future__ import annotations
+
+import hashlib
+import re
+import unicodedata
+import warnings
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterator
+
+from . import frontmatter
+
+
+def sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+# TMP-02: bitemporal frontmatter (ADR-0003 Ruling 2) — mirrors the id-resolution
+# tools/validate.py already does (link_id) so a "[[id]]"/"[[id|alias]]" wikilink
+# value indexes the same as a bare id.
+_WIKILINK = re.compile(r"^\[\[([^\]|]+)(?:\|[^\]]*)?\]\]$")
+
+
+def _bitemporal_link(val: object) -> str:
+    if not isinstance(val, str) or not val.strip():
+        return ""
+    m = _WIKILINK.match(val.strip())
+    return m.group(1).strip() if m else val.strip()
+
+
+def _bitemporal_bool(val: object) -> str:
+    """Normalize a raw frontmatter bool to "true"/"false"/"" (unset) for the
+    index column — never a Python bool, so SQL equality stays trivial."""
+    if isinstance(val, bool):
+        return "true" if val else "false"
+    if isinstance(val, str):
+        v = val.strip().lower()
+        if v in ("true", "yes"):
+            return "true"
+        if v in ("false", "no"):
+            return "false"
+    return ""
+
+
+# Bare-slug charset for note ids that become filesystem paths (kebab slugs like
+# `arctic-embed-choice`, `2026-06-27-arctic-benchmark`, `draft-ab12cd34ef56`).
+# No separators, no leading dot, and '..' is rejected explicitly below.
+_SLUG_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*")
+
+
+def safe_slug(ident: object) -> str:
+    """Validate an (untrusted) note id as a bare, path-safe slug — fail closed.
+
+    Trust-boundary guard (C-1/C-2): an id from --id or untrusted YAML
+    frontmatter becomes ``<dir>/<id>.md``, so anything but a bare slug
+    (separators, '..', absolute paths, control chars, empty) is a traversal
+    vector and is REFUSED with ValueError — never silently renamed.
+
+    The id is NFC-normalized BEFORE validation so a decomposed variant cannot
+    reconstitute '..' or '/' after the check (fullwidth forms are not in the
+    allowed charset, so they are rejected outright).
+    """
+    s = unicodedata.normalize("NFC", str(ident))
+    if not s or ".." in s or _SLUG_RE.fullmatch(s) is None:
+        raise ValueError(
+            f"unsafe note id {ident!r}: must be a bare slug "
+            "([A-Za-z0-9._-], no leading '.', no '/', no '..')"
+        )
+    return s
+
+
+@dataclass
+class Note:
+    id: str
+    title: str
+    type: str
+    classification: str  # RAW frontmatter value (may be missing -> "" ; filter applies default-deny)
+    zone: str            # "raw" | "brain"
+    path: Path
+    body: str
+    meta: dict[str, Any] = field(default_factory=dict)
+    created: str = ""
+    updated: str = ""
+    sha256: str = ""
+    content_hash: str = ""  # sha256 of the FULL on-disk file text (change detection)
+    # TMP-02 bitemporal keys (ADR-0003 Ruling 2) — all optional, "" when absent.
+    document_date: str = ""
+    effective_date: str = ""
+    superseded_date: str = ""
+    is_latest_version: str = ""   # "true" | "false" | "" (unset -> treated as current)
+    superseded_by: str = ""
+    previous_version: str = ""    # previous_version, falling back to `replaces`
+
+    def to_row(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "type": self.type,
+            "classification": self.classification,
+            "zone": self.zone,
+            "path": self.path.as_posix(),
+            "created": self.created,
+            "updated": self.updated,
+            "sha256": self.sha256,
+            "content_hash": self.content_hash,
+            "body": self.body,
+            "document_date": self.document_date,
+            "effective_date": self.effective_date,
+            "superseded_date": self.superseded_date,
+            "is_latest_version": self.is_latest_version,
+            "superseded_by": self.superseded_by,
+            "previous_version": self.previous_version,
+        }
+
+
+def _zone_of(path: Path, vault: Path) -> str:
+    try:
+        rel = path.relative_to(vault)
+    except ValueError:
+        return "brain"
+    return rel.parts[0] if rel.parts else "brain"
+
+
+def load_note(path: Path, vault: Path) -> Note | None:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (UnicodeDecodeError, OSError) as exc:
+        # H-3: a single bad-encoding (or unreadable) file must not abort a
+        # whole-vault rebuild/sync. Skip it with a warning rather than
+        # silently mangling its content (no errors="replace") — an excluded
+        # note is honest; a mojibake-indexed one is not.
+        warnings.warn(f"skipping unreadable note {path}: {exc}", stacklevel=2)
+        return None
+    meta, body = frontmatter.parse_text(text)
+    if not meta:
+        return None
+    zone = _zone_of(path, vault)
+    nid = str(meta.get("id") or path.stem)
+    return Note(
+        content_hash=sha256_text(text),
+        id=nid,
+        title=str(meta.get("title") or nid),
+        type=str(meta.get("type") or ("source" if zone == "raw" else "note")),
+        classification=str(meta.get("classification") or ""),
+        zone=zone,
+        path=path,
+        body=body,
+        meta=meta,
+        created=str(meta.get("created") or meta.get("captured") or ""),
+        updated=str(meta.get("updated") or meta.get("captured") or ""),
+        sha256=str(meta.get("sha256") or sha256_text(body)),
+        document_date=str(meta.get("document_date") or ""),
+        effective_date=str(meta.get("effective_date") or ""),
+        superseded_date=str(meta.get("superseded_date") or ""),
+        is_latest_version=_bitemporal_bool(meta.get("is_latest_version")),
+        superseded_by=_bitemporal_link(meta.get("superseded_by")),
+        previous_version=(_bitemporal_link(meta.get("previous_version"))
+                          or _bitemporal_link(meta.get("replaces"))),
+    )
+
+
+def scan_vault(vault: Path) -> Iterator[Note]:
+    """Yield every note under vault/, skipping the .brain/ runtime cache, the
+    top-level inbox/ drop zone, archived ingestion originals under
+    raw/originals/, and the generated backlinks.md."""
+    for p in sorted(vault.rglob("*.md")):
+        sp = p.as_posix()
+        if "/.brain/" in sp:
+            continue
+        try:
+            rel_parts = p.relative_to(vault).parts
+        except ValueError:
+            rel_parts = ()
+        # ADR-0003 Ruling 1: the ingestion drop zone is a visible top-level dir
+        # (not hidden like .brain/), but is never indexed — only the
+        # extracted raw/ source a handler promotes is a real note.
+        # C4: anchored to the vault-relative TOP-LEVEL path segment only — a
+        # prior unanchored "/inbox/" substring match wrongly excluded any note
+        # under a directory named "inbox" at ANY depth (e.g.
+        # brain/resources/inbox/reading-list.md), silently dropping it from
+        # the index.
+        if rel_parts and rel_parts[0] == "inbox":
+            continue
+        # C5: raw/originals/ holds the archived, immutable ORIGINAL file a
+        # handler claimed during ingestion (e.g. a promoted .md's own source
+        # copy) — it is evidence, never a real note, and must not be
+        # double-indexed alongside the promoted raw/<slug>.md note.
+        if rel_parts[:2] == ("raw", "originals"):
+            continue
+        if p.name == "backlinks.md":
+            continue
+        note = load_note(p, vault)
+        if note is not None:
+            yield note