MESA Core · v0.9.3
Architecture decisions
This guide has equivalent English and Turkish versions. The source sections behind this page are at the bottom.
Architecture decisions#
This maintained decision records design rationale at v0.9.3. Current architecture and runtime contracts define implemented behavior; retired decisions remain historical context.
Read the maintained reference#
The source below includes status, rationale and consequences. Start with the decision index and architecture.
Source reference for this page
The sections of the upstream file that back this page, unchanged. Source section links open the appendix automatically.
ADRs record why a design was selected. Use current architecture
for implemented behavior and the operations guide for procedures.
A historical claim or roadmap is not current capability or release evidence.
Current decisions#
| ADR | What it protects |
|---|---|
| 0009 — Ledger and single owner | SQLite authority, ordered projections and one V4 storage writer |
| 0010 — RRF and PageRank | Rank fusion; PageRank cannot quarantine evidence |
| 0011 — Tenant/dataset authorization | Server-authored scope and explicit permissions |
| 0012 — DAO repository boundaries | Implemented catalog boundary; future extractions remain proposals |
| 0013 — Production dependencies | One-way imports and explicit composition roots |
| 0014 — Rebuild closure | Offline full-root rebuild and reversible cutover; historical roadmap separated |
| 0015 — Adaptive query planning | Opt-in bounded reformulation with fixed scope and one context-packing pass |
Retired decisions#
The original files are retained in Git history. These summaries preserve the
reason for the transition; they do not remove the supported V3 compatibility code.
Retired numbers are not reused.
0001 — SQLite WAL and LanceDB#
V3 replaced an in-memory graph/synchronous façade with SQLite WAL/FTS and
LanceDB behind an async DAO. Mandatory agent partitioning was its isolation
mechanism. V4 now uses SQLite as canonical authority plus derived vector/graph
stores (0009); tenant/dataset
scope replaces agent identity as the security boundary
(0011).
0002 — Alpha reranking#
The historical score-blending design was superseded for V4 by
0010. Its old performance claims are
not current measurements or a guarantee over a vector-only baseline.
0003 — Adaptive validation routing#
Automatic small-model/dual-model selection was superseded by explicit validation
modes 0/1/2. Routing cannot weaken the chosen assurance level; see
ingestion. This is distinct from query planning.
0004 — Background tasks instead of Celery#
The old coroutine/background-task rationale and mock benchmark do not define
V4 durability. 0009 owns the durable
ledger/outbox and single-owner decision. Historical throughput is not release proof.
0005 — PageRank quarantine#
Superseded in full by 0010: centrality
is observational and cannot remove or quarantine retrieval artifacts.
0006 — Spreading activation#
The historical design damped activation through high-degree nodes to limit
fan-out and irrelevant context. Current V4 uses bounded path retrieval with
canonical evidence checks; retrieval defines its
limits, without promising exhaustive spreading activation.
0007 — WAL queue and phantom writes#
V3 used a durable SQLite lancedb_wal queue to recover writes that reached only
one store. That rationale does not create a shared ACID transaction. V4 ordered
projection, fencing and ownership are defined by
0009.
0008 — Comparative benchmark architecture#
Comparative retrieval/Full-QA methodology belongs to the external mesa_benchmark
project. See ecosystem ownership. Core's
deterministic retrieval tests do not replace independent model-quality evidence.
Maintaining decisions#
New decisions record status, scope, rationale, consequences and recovery
implications. Link superseded decisions here and update the current guide;
do not silently turn a historical result or unimplemented proposal into a guarantee.
