MESA Core · v0.9.3

Architecture decisions

v0.9.3 source: docs/adr/README.md

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.

Verified sources
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#

ADRWhat it protects
0009 — Ledger and single ownerSQLite authority, ordered projections and one V4 storage writer
0010 — RRF and PageRankRank fusion; PageRank cannot quarantine evidence
0011 — Tenant/dataset authorizationServer-authored scope and explicit permissions
0012 — DAO repository boundariesImplemented catalog boundary; future extractions remain proposals
0013 — Production dependenciesOne-way imports and explicit composition roots
0014 — Rebuild closureOffline full-root rebuild and reversible cutover; historical roadmap separated
0015 — Adaptive query planningOpt-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.