--- title: "Architecture" url: "https://nsta1.github.io/Orleans.Lattice/docs/lattice.api.mcp.repocontext/architecture.html" source: "https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/docs/lattice.api.mcp.repocontext/architecture.md" package: "Orleans.Lattice.Api.Mcp.RepoContext" status: "unreleased" documents: "Orleans.Lattice 9.9.0 (release line 9.9)" built: "2026-10-04" all-pages: "https://nsta1.github.io/Orleans.Lattice/llms.txt" bundle: "https://nsta1.github.io/Orleans.Lattice/docs/lattice.api.mcp.repocontext/llms-full.txt" --- # Architecture Part of the [Api.Mcp.RepoContext documentation](README.md). A map of the module's constituent parts and how a request or a file moves through them. The reference pages describe each plane in depth; this page exists so you can find the right one, and so the shape of the whole is visible from one place. Read it alongside the [record model](record-model.md), which is the authoritative layout contract for the trees and keys named here. ## The parts ```mermaid flowchart LR agent["AI coding agent
(MCP client)"] subgraph surface["Tool surface"] gate["Permission-aware discovery
fail-closed authorization gate
workspace guard, path containment"] handlers["repocontext_* tool group
capture, retrieval, graph,
claims, workspace"] gate --> handlers end subgraph retrieve["Retrieval plane"] search["Search service
reports which path answered"] ann["Approximate index
the default path"] exact["Exact kNN scan
corpus bound, fault breaker"] kw["Keyword BM25"] graphsvc["Graph service
outline, related, changed"] bundle["Bundle service
packer, session reuse,
token counter"] search --> ann --> exact --> kw end subgraph grains["Orchestration"] self["Self-index grain, per repository
keep-alive, paged gap sweep,
periodic reconcile, git refresh"] job["Index job grain
one durable pass,
resumed after a restart"] annb["ANN build coordinator
one per repository
and embedding space"] sweep["Build sweep service"] self --> job self --> annb sweep --> annb end subgraph ingest["Ingest plane"] srcgate["Index-source gate
per repository, mutually exclusive"] mount["Mounted workspace, the default
walk and digest, mtime pruning"] git["Git source, opt-in and hub-only
fetch ref, diff commit"] boot["Bootstrap pass
walk, reconcile, apply, vectorise"] rec["Reconcilers
structural, content,
symbol, cross-reference"] ving["Vector ingestor
file windows, symbols,
memory entries"] srcgate --> mount & git --> boot --> rec --> ving end subgraph store["Record store"] sor["Store of record
structural, symbol, memory"] proj["Rebuildable projections
content, cross-reference, session,
vector membership, payload, metadata"] local["Local-derived, never replicated
approximate index,
vector-coverage digest"] end claims["Claims
leased and fenced,
over the distributed lock"] embed["Embedding provider
HTTP companion"] healer["Vector-plane re-deriver
fail-closed allow-list"] lattice[("Lattice CRDT B+ trees
WAL, TTL, tombstone compaction")] repl["Replication companion
enrols the replicated trees"] agent --> gate handlers --> search handlers --> graphsvc handlers --> bundle handlers --> claims handlers --> self job --> boot annb --> local ving <-->|embed| embed rec --> sor rec --> proj ving --> proj search --> sor ann --> local exact --> proj kw --> proj graphsvc --> sor bundle --> proj claims --> sor healer -.-> proj sor <--> lattice proj <--> lattice local <--> lattice repl -.-> lattice ``` ## The flows that matter **Ingest.** A repository's content arrives from one of two mutually exclusive sources: a read-only mounted workspace (the default, and the only one that sees uncommitted work) or a configured git remote (opt-in, hub-only, anchored to a commit). From there a single idempotent pass walks or diffs, reconciles the structural records, projects file content, extracts symbols, maintains the reverse cross-reference edges, and embeds. Each stage records its own *processed marker* - on the file node for content, symbols, and cross-references, and as an add-wins presence flag in vector membership for embeddings - so each has an idempotent back-fill and a repository indexed before a stage existed heals itself with no client call. See [Index source strategies](container/index-source-strategies.md). **Retrieval.** A query is answered by the best plane available and always says which one that was. The approximate index serves by default; it falls back to a bounded exact scan, and to deterministic keyword ranking over the content projection when no vector plane can serve. Hits hydrate from the store of record, never from the index. See [Semantic search](semantic-search.md) for the `retrievalPath` vocabulary, and [Retrieval and token economics](retrieval-economics.md) for the graph verbs and the budgeted bundle. **Convergence.** No client call is on the critical path for freshness. A per-repository self-index grain owns the standing "reach and stay indexed" guarantee, the job grain owns the durability of one pass, and a build coordinator owns the approximate index. All three are anchored by Orleans reminders, so a process death resumes the work rather than abandoning it. See [Staying fully indexed](tools.md#staying-fully-indexed-the-self-index-grain). ## The idea the design rests on Every tree is classified as either **store of record** or **rebuildable projection**, and that classification is enforced by name rather than inferred. Store-of-record trees hold the primary records: the structural nodes, the symbol records, and agent memory. Projections hold data derived from them: the content projection, the reverse cross-reference index, session reuse bookkeeping, and the whole vector plane. A projection can be dropped and rebuilt. Of the store-of-record trees, the structural and symbol trees can be re-created only by re-ingesting the working files, and agent memory exists nowhere else, so it cannot be re-created at all. That single distinction is what makes several otherwise-awkward behaviours safe and predictable: - `repocontext_reset_index` drops the code index and every derived plane while preserving agent memory, so a wedged index is repairable without discarding notes, decisions, and gotchas. - The self-healing re-derivation may reset one of two rebuildable vector trees - vector metadata or vector membership - when it falls terminally off its write-ahead log (a membership reset also drops the coverage digest that mirrors it), and refuses every other tree outright, so a heal can never become data loss. - A terminally stale content tree degrades body-text ranking without failing ingest or retrieval, because the reconcile knows that content can be re-projected later. - Replication enrols the store-of-record and shareable projection trees, while the approximate index and the vector-coverage digest stay local: each cluster derives its own far more cheaply than it could ship one. Each classification is a fail-closed allow-list checked against local constants, so an unrecognised tree name is refused rather than defaulted into a bucket. ## Where to go next - [Record model](record-model.md) - the named trees, the key grammar, and the CRDT store-of-record model. - [Tools](tools.md) - the tool catalogue, the indexing lifecycle, and the self-index grain. - [Semantic search](semantic-search.md) - the embedding seam, the index planes, and fail-closed degradation. - [Retrieval and token economics](retrieval-economics.md) - explainable search, graph navigation, and the budgeted bundle. - [Memory and TTL](memory-and-ttl.md) - topics, entries, and per-repository expiry policy. - [The agent-operated backlog](backlog.md) - leased, fenced claims over memory records. - [Container quickstart](container.md) - running the module as a single durable local container.