MESA Core · v0.9.3

Veri alımı ve hafıza yaşam döngüsü

v0.9.3 kaynak: docs/concepts-and-ingestion.md

Bu rehberin Türkçe ve İngilizce sürümleri aynı konuyu açıklar. Bu sayfayla ilgili kaynak bölümleri en altta yer alır.

Kaynaklar ve erişim alanları nasıl düzenlenir?#

Üst erişim alanı (tenant), çalışma alanlarını ve veri kümelerini içerir. Her veri kümesinin belgeleri, değiştirilemeyen sürümleri ve kaynak metin parçaları vardır. Sunucunun açtığı oturum; erişim kimliğini, üst alanı, çalışma alanını, ajanı ve izin verilen sabit veri kümesi listesini bir araya getirir. İstemcinin gönderdiği ek bilgiler kendi başına erişim yetkisi vermez.

Kabul edilmesi, tamamlandığı anlamına gelmez#

POST /v4/memory/insert için oturum ve kaynak kimlikleriyle birlikte title, source_ref ve tam content gerekir. HTTP 202 yanıtında değişiklik işleminin, aday kaydın, işleme hattının ve ham günlüğün kimlikleri döner. Sonrasında işlemin durumunu izleyin: wait_until_committed başarısız bir son durumla da dönebilir. Reddedilen iş, etkin arama kayıtları oluşturmamalıdır.

Çok parçalı sürümler ve tekrar denemeler#

Bir sürüm birden fazla parçadan oluşuyorsa her parçaya ayrı kimlik ve sıra numarası verin. Son eklemeye kadar finalize_revision=false gönderin. Son ekleme parça listesini sabitler; sürümün etkinleşmesi gereken tüm alt işlerin başarısını bekler. Tekrar denemede aynı yineleme anahtarını ve birebir aynı içeriği kullanın. Çelişen tekrar reddedilir. Düzeltme için yeni sürüm oluşturulur; kalıcı silme ve geri alma ise açık izinlerle kaynağın sahiplik bağını kaldırır.

Tam belgeler ve silme#

POST /v4/documents, sunucuda özgün metni parçalar, tekrarları ve sürüm kimliklerini yönetir. Parça başına mutasyon kimliği döndürür; kabul edilmek COMMITTED olmakla aynı değildir. Modeller kapalıyken metin saklanır ve BM25 ile aranır; isteğe bağlı vektör ve çizge adımları SKIPPED olup sonradan tamamlanabilir. Belge silme, denetim kimliklerini ve özetleri korurken sahip olunan kaynak/çıkarım metnini temizler; başka bir belgenin sahip olduğu ortak metin kalır.

Madde sınırlarını koruyan parçalama ve yeniden deneme#

MESA_CHUNKING=auto|plain varsayılan olarak auto kullanır. Satır başında en az üç Türkçe madde başlığı varsa madde sınırları korunur; uzun parçalar en fazla 512 token olur ve kaynak metin aynen saklanır. plain, yeni sürümlerde önceki planı kullanır. Mevcut ACTIVE sürümler değişmez. Yeniden deneme, sunucu yeniden başlatılsa veya ayar değişse bile kabul edilmiş metne uyan planı korur. Kabul edilmiş önek iki farklı plana da uyuyorsa yeni parça eklenmeden HTTP 409 döner.

Kuyruk kapasitesi ve belge zaman bütçesi#

Belge kabulü, queue_over_capacity durumunda aynı istek içindeki tam parça planını koruyarak geçerli parça için kısa süre yer bekler. Baskı sürerse yine 503 queue_over_capacity döner; kayıtlı sıralardan devam etmek için aynı gövdeyi yeniden gönderin. add_document(deadline=600), HTTP isteğinde kalan belge süresini kullanır. Kabul ve tamamen hazır olma ayrıdır; büyük yüklemeler dakikalar sürebilir.

Yeni kabul edilen parçalarda hukuk kuralları varsayılan açık; model tabanlı SPO çıkarımı modeller açık olsa da varsayılan kapalıdır. Hukuki öğeler özgün parça konumlarını korur ve SPO kayıtlarından ayrı kalır. Mevcut kimlikler devam sırasında değişmez.

Şemalar

UML · Sıralı etkileşim şemasıYazma yolu: hemen kabul, arka planda işleme, sonucu sorgulama
«actor»Uygulamanız«boundary»API«entity»SQLite günlüğü«control»İşçi«external»Model«entity»LanceDB · Kùzu insert(kaynak parça) hukuki öğe + değişiklik + iş mutation_id 202 · mutation_id 202 = kabul edildi, işlenmedi.İşleme aşağıda sürer. işi sahiplen (süreli) kaynak parça SPO ayrıca açıksa 0..N bilgi doğrula (mod 0–2) kabul / ret alt[kabul] bilgiler · SQL_APPLIED VECTOR_APPLIED / SKIPPED GRAPH_APPLIED / SKIPPED state = COMMITTED [ret] state = REJECTED loop[son duruma kadar 2 sn’de bir] GET /v4/mutations/{id} durumu oku state son durum

Kabul, hukuki öğeleri SPO kayıtlarından ayrı saklar. Hukuk kuralları varsayılan açık, model tabanlı SPO çıkarımı kapalıdır. Etkin depolar sırayla yazılır; yeniden denemeler aynı kimlikleri kullanır. Mutation sorgusu 2 sn, sürüm etkinleşmesi 1 sn aralıklıdır.

UML · Durum makinesiBir değişikliğin QUEUED’dan son duruma yolu
QUEUEDRUNNINGEXTRACTEDVALIDATEDPROJECTINGCOMMITTEDDLQRETRY_PENDINGREJECTEDBLOCKEDROLLED_BACK işçi alırbilgi veya kaynakkontrol geçtiSQL yazıldıadımlar tamam geçici hata (herhangi adım) [doğrulama reddeder] yeniden dene deneme hakkı bitti yeniden kuyruk geri alma[temizlik bitti] geri alma [temizlik bitmedi] REJECTED denetim kaynağını tutar, arama verisi oluşturmaz.

COMMITTED, gerekli adımların tamamlandığını gösterir; kapalı vektör/çizge adımları SKIPPED olabilir. Yeniden denemeler sınırlıdır; sonuçlanmayan iş, biri yeniden kuyruğa alana kadar hata kuyruğunda (DLQ) bekler. Hata gizlenmez, görünür kalır.

Tüm şemalar ve gerekçeleri: Mimari →

Kaynak belgedeki ilgili bölümler

Bu bölüm, kaynak belgenin bu sayfayla ilgili kısımlarını değiştirmeden gösterir. Kaynak içindeki bir bölüme giden bağlantıyı açtığınızda metin otomatik olarak görünür.

Identity and scope#

ConceptImplemented meaning
PrincipalServer-authenticated identity owning keys and ACL grants
TenantV4 authorization boundary
WorkspaceTenant-owned grouping of datasets
DatasetSource collection inside a workspace; session-bound access
AgentCompute/persona context; not a tenant credential
SessionServer-generated principal/scope binding with immutable dataset set
DocumentDataset-owned source identity with a current revision head
RevisionImmutable source version with a frozen chunk manifest
Source chunkExact source content, ordinal, source reference and content hash
AssertionCanonical subject/predicate/entity-or-literal fact with source evidence
MutationDurable admitted work and its state, separate from pipeline aggregate
ProjectionDerived SQL/vector/graph artifact work with fenced claim and receipt
EvidenceLinked assertion/chunk/source span; not independently verified truth

Catalog public IDs resolve inside the tenant. Physical storage keys are opaque;

passing a physical key as an external ID does not grant access. Agent and dataset

authorization are resolved from the session, never caller metadata.

Admission and completion#

POST /v4/memory/insert requires session, dataset, document, revision, chunk,

title, source_ref and exact content. See API for bounds.

Admission returns 202 with candidate, mutation, pipeline-run and raw-log IDs.

This is durable admission, not visibility in every store.

mermaid
stateDiagram-v2
    [*] --> RECEIVED
    RECEIVED --> EXTRACTED
    EXTRACTED --> VALIDATED
    EXTRACTED --> REJECTED
    VALIDATED --> SQL_APPLIED
    SQL_APPLIED --> VECTOR_APPLIED
    VECTOR_APPLIED --> GRAPH_APPLIED
    GRAPH_APPLIED --> COMMITTED

The pipeline aggregate uses `QUEUED → RUNNING → EXTRACTED → VALIDATED →

PROJECTING → COMMITTED`. Technical recovery states include retry, dead-letter,

rollback and blocked cleanup. The SDK terminal set is COMMITTED, REJECTED,

DEAD_LETTER, ROLLED_BACK, BLOCKED; check status, not just method name.

Internal outbox/pipeline records may use DLQ; inspect each object's state.

Canonical FactExtractionService preserves zero-to-many extracted facts.

Validation mode 0 checks deterministically, mode 1 uses validator A, and mode 2

requires distinct A/B provider-model pairs. The runtime-selected policy is

snapshotted into admitted work; reserved _mesa_* metadata cannot downgrade it.

Rejected work may retain audit source but creates no active retrieval artifact.

Projection order is SQL → vector → graph. Separate stores do not share an ACID

transaction: fenced leases, receipts, ownership and reconciliation provide

idempotent convergence. A lost lease cannot finalize another owner's work.

Backpressure yields explicit admission errors; do not retry without bounds.

Revision finalization and retries#

For a multi-chunk revision set finalize_revision=false on all but the final

insert, with distinct chunk IDs and ordinals. The last insert freezes the

manifest. No new chunks may then enter that revision; the revision activates

only after every required child mutation succeeds. One document has one active

head. Create a new revision to change source content.

Use an insert idempotency_key (body field, <=128 characters) with the exact

same payload on retries. Conflicting payloads are rejected. Rebuild uses the

separate Idempotency-Key HTTP header. The SDK avoids unsafe automatic POST

retry after ambiguous failures; application recovery must inspect durable IDs.

declared_content_hash is the caller's whole-revision hash, manifest_hash

identifies frozen chunk membership, and a chunk content_hash identifies only

that chunk. Direct insertion does not establish a whole-revision hash.

Correction, purge and rollback#

Supersession retains historical assertions. A time-qualified query can include

eligible superseded evidence, which requires explicit producer validity dates (valid_from / valid_to); without them, superseded evidence is not returned. An unqualified query uses active evidence.

Rollback removes source ownership; shared artifacts remain while another active

source owns them. Tombstones precede secondary cleanup; failure stays BLOCKED.

Purge requires dataset OWNER plus explicit PURGE; replay/rollback require

the originating scope and explicit ROLLBACK. Semantic rejection cannot be

reopened through generic replay (409 NON_REPLAYABLE). Non-head historical

rollback is a conflict. Do not edit store rows or leases manually.

Producer contract#

Core consumes exact content and identity; MESA_Data owns source

acquisition, chunking and verified source metadata. HTTP insertion supports a

typed legal_identity; the current SDK insert signature does not expose it.

Use the HTTP contract for that field. Bare “MADDE 1” text is insufficient to

prove law identity. Producer metadata accuracy remains an external responsibility.

Canonical V4 insertion requires the combined processing consumer. A combined

runtime without models stores documents and finds them with BM25; vector search

starts when embedding is enabled (degraded_sources shows vector until then);

503 canonical_processing_unavailable happens only on a non-combined profile.

Document ingestion briefly waits for queue capacity for the current chunk,

keeping its chunk plan within the request. Persistent pressure still returns

503 queue_over_capacity; retry the exact payload to resume stored ordinals.

SDK add_document(deadline=600) uses the remaining document budget for this

HTTP request, allowing a large upload to wait for capacity.