MESA Core · v0.9.3
Veri alımı ve hafıza yaşam döngüsü
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
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.
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#
| Concept | Implemented meaning |
|---|---|
| Principal | Server-authenticated identity owning keys and ACL grants |
| Tenant | V4 authorization boundary |
| Workspace | Tenant-owned grouping of datasets |
| Dataset | Source collection inside a workspace; session-bound access |
| Agent | Compute/persona context; not a tenant credential |
| Session | Server-generated principal/scope binding with immutable dataset set |
| Document | Dataset-owned source identity with a current revision head |
| Revision | Immutable source version with a frozen chunk manifest |
| Source chunk | Exact source content, ordinal, source reference and content hash |
| Assertion | Canonical subject/predicate/entity-or-literal fact with source evidence |
| Mutation | Durable admitted work and its state, separate from pipeline aggregate |
| Projection | Derived SQL/vector/graph artifact work with fenced claim and receipt |
| Evidence | Linked 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.
stateDiagram-v2
[*] --> RECEIVED
RECEIVED --> EXTRACTED
EXTRACTED --> VALIDATED
EXTRACTED --> REJECTED
VALIDATED --> SQL_APPLIED
SQL_APPLIED --> VECTOR_APPLIED
VECTOR_APPLIED --> GRAPH_APPLIED
GRAPH_APPLIED --> COMMITTEDThe 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.
