MESA Core · v0.9.3

Operasyon ve kurtarma

v0.9.3 kaynak: docs/RUNBOOK.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.

Her veri dizininin tek yazıcısı olmalı#

Her veri dizini için tek combined V4 süreci çalıştırın. Arama görünümü ve temizlik kuyruklarını, başarısız iş kuyruğunu, takılı iş sahipliklerini ve sahipsiz kayıtları izleyin. Paylaşılan çıktıların sayısının sıfır olması gerekmez. Kuyruğun büyümesi, depodaki satırları elle değiştirmek için gerekçe değildir; nedenini araştırmanız gereken bir işletim işaretidir.

Kurtarma, sahiplik kurallarını korur#

Bir işi yeniden yürütmeden önce depo veya sağlayıcı hatasını giderin. İş sahipliğini kaybeden bir çalışan, o işi tamamlayamaz. Geri alma işleminde önce kaynağın sahiplik bağı kaldırılıp silindi işareti yazılır, ardından ikincil temizlik yapılır. Başka bir etkin kaynağın hâlâ kullandığı ortak çıktı korunur. Temizliğin BLOCKED olması, başarılı olduğu anlamına gelmez.

Yeni düzene geçmeden önce yedek alın#

Aşağıdaki kaynakta yer alan, yazıcı kilidi kontrollerini içeren çevrimdışı yedekleme ve geri yükleme adımlarını izleyin. Geri dönme olanağını koruduğunuz sürece özgün veri dizinini ve yedeği saklayın. Yedeği yeni, boş bir dizine yükleyin; mevcut dizinin üzerine yazmayın veya genel bir sürüm düşürme işlemi çalıştırmayın. Yeniden oluşturma çevrimdışıdır ve veri dizininin tamamını kapsar; tek bir üst erişim alanını çevrimiçi onarmaz.

Kendi sayfasına taşınan bölümler
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.

Bu runbook v4 full-cognitive release candidate için kanonik operasyon

rehberidir. Production kararı Final MVP Certification tamamlanana kadar

NO-GOdur. V3 lexical-core uyumluluk işlemleri ayrıca belirtilir.

1. Desteklenen v4 topology#

V4 aynı storage root’a yazan tek bir combined process ile çalışır. API

admission, durable consumer, validation ve SQLite/LanceDB/Kùzu projection

işleri bu process’tedir.

bash
export MESA_RUNTIME_PROFILE=combined
export MESA_STORAGE_ROOT=/srv/mesa/v4-data
export MESA_LOAD_DOTENV=false
# Provision credentials and reviewed model/provider settings before startup.
.venv/bin/python -m mesa_memory.runtime_entrypoint

Bu komut tek başına V4 provider kurulumu değildir. Canonical insert için

MESA_MODEL_ENABLED=true, kullanılabilir extraction/embedding ve seçili

validation policy gerekir; kurulum ve

yapılandırma ön koşullarını tamamlayın.

Aynı storage root’u ikinci API, worker veya combined process’e yazılabilir

olarak mount etmeyin. Yatay ölçekleme öncesi storage ownership protokolü

gerekir. V3 ile v4 farklı fiziksel storage root kullanmalıdır.

2. İlk credential ve ACL kurulumu#

Uygulama durdurulmuşken veya policy DB’yi kullanan tek operator olarak:

bash
export MESA_STORAGE_ROOT=/srv/mesa/v4-data
mesa-v4-admin issue-key --principal service-api
mesa-v4-admin grant-role --principal service-api \
  --tenant tenant-a --role OWNER
mesa-v4-admin grant-agent --principal service-api \
  --agent agent-a --permission SESSION_CREATE

İlk komut credential’ı yalnız bir kez stdout’a yazar. Secret manager’a aktarın;

log, shell history veya dokümana koymayın. Rotate edilen eski key aynı işlemde

revoke edilir:

bash
mesa-v4-admin rotate-key --key-id KEY_ID
mesa-v4-admin revoke-key --key-id KEY_ID

Purge/rollback rol ile örtük gelmez:

bash
mesa-v4-admin grant-dataset-permission --principal service-api \
  --tenant tenant-a --dataset dataset-a --permission ROLLBACK

3. Projection backlog ve DLQ#

Önce /health ile status, maintenance, rebuild_state özeti ve

/health/init ile readiness kontrol edilir. /health HTTP 200 dönse de

status degraded olabilir. Aşağıdaki ayrıntılı sayaçlar /metrics üzerinden

izlenir; public /health yanıtında ayrı alanlar değildir:

  • mesa_v4_projection_backlog
  • mesa_v4_projection_dead_letter
  • mesa_v4_projection_stuck_leases
  • mesa_v4_cleanup_backlog
  • mesa_v4_cleanup_blocked
  • mesa_v4_orphan_registry
  • mesa_v4_shared_artifacts

Backlog artıyorsa process loglarında mutation/pipeline run ID, failure class ve

lane aranır. İçerik, credential veya claim token loglanmamalıdır. Geçici hata

bounded retry ile ilerler; permanent/poison hata DLQ’ya gider.

Replay’den önce kök neden giderilir ve mutation’ın aynı tenant/dataset

kapsamında olduğu doğrulanır. Yetkili API çağrısı:

bash
curl --fail -X POST \
  -H "X-API-Key: $MESA_API_KEY" \
  "http://127.0.0.1:8000/v4/mutations/$MUTATION_ID/replay"

Fenced lease nedeniyle claim token’ı kaybetmiş worker sonucu finalize edemez.

Lease’e elle müdahale etmek yerine process’i yeniden başlatın ve reconciler’ın

expired claim’i almasını bekleyin.

4. Rollback ve BLOCKED#

Commit edilmemiş başarısız run rollback’i önce SQLite retrieval tombstone’u,

sonra vector/graph cleanup outbox’ı oluşturur. Yalnız ilgili

artifact_sources sahipliği kaldırılır. Başka aktif sahibi olan ortak artifact

silinmez.

Cleanup tamamlanamazsa run BLOCKED olur; bunu başarılı saymayın. Store

erişimini düzeltin, health parity’yi kontrol edin ve idempotent cleanup/replay

akışını yeniden çalıştırın. Fiziksel store’da manuel silme yapmayın; ledger ile

store daha fazla ayrışır.

5. Reconciliation#

Reconciliation tenant ve dataset sınırında iki yönlüdür:

  • ledger’da olup store’da olmayan artifact yeniden project edilir;
  • store’da olup ledger/owner kaydı olmayan artifact karantinaya alınır ve

cleanup kuyruğuna taşınır.

Release veya cutover öncesi projection backlog, blocked cleanup ve ownerless

orphan sıfır olmalıdır. Shared artifact sayısının sıfır olması gerekmez; ortak

sahiplik beklenen bir durumdur.

6. Backup, restore ve v4 rebuild#

Uygulamayı durdurun ve kaynak storage’ı offline hale getirin:

bash
mesa-recovery --trusted-root /srv/mesa backup \
  --source-root /srv/mesa/v4-data \
  --backup-root /srv/mesa/backups/v4-2026-07-23 \
  --stores-stopped
mesa-recovery --trusted-root /srv/mesa validate \
  --backup-root /srv/mesa/backups/v4-2026-07-23
mesa-recovery --trusted-root /srv/mesa restore \
  --backup-root /srv/mesa/backups/v4-2026-07-23 \
  --restore-root /srv/mesa/restore-v4-test

--stores-stopped geriye dönük uyumluluk için açık bir operator

precondition'ıdır; tek başına consistency kanıtı değildir. Backup

implementation'ı ayrıca storage-root writer lock'ını doğrular/alır, her SQLite

dosyasını SQLite'ın online backup primitive'iyle ayrı bir tutarlı snapshot

olarak kopyalar ve ancak staging doğrulamasından sonra atomik publish yapar.

SQL authoritative/canonical truth'tür. LanceDB vector ve Kùzu graph

projection'ları rebuildable derived state'tir ve yalnız exclusive writer-lock

boundary altında kopyalanır.

Restore mevcut hedefi ezmemelidir. Backup'ı yeni boş root'a, uyumlu kod ve

config ile geri yükleyip doğrulayın. V3 verisini V4'e taşımak ayrı kaynak/catalog

eşleme ve V4 ingestion çalışmasıdır; projection runner V3→V4 dönüştürücüsü

değildir. Migration rehberi V4 yükseltmesini açıklar.

Backup rollback süresi boyunca korunur.

V4 projection rebuild'inin submit → drain → stop → offline

run/resume → restart → status → automatic rollback akışı, exit code'ları ve

retained generation kuralları

`v4-rebuild-runbook.md` içinde kanonik olarak

belgelenir. Dataset/tenant-scoped rebuild veya online runner desteklenmez.

Alembic migration'ları forward-only'dir. Bir migration başarısız olursa

alembic downgrade çalıştırmayın: release'i durdurun, doğrulanmış backup'ı

yeni boş bir storage root'a restore edin, parity kontrolünü yeniden çalıştırın

ve ancak ardından cutover yapın.

Single-writer kapasite sınırı#

V4 bir storage root için yalnız bir aktif combined owner kullanır.

Worker başlangıcı aynı hostta advisory lock ile ikinci writer'ı reddeder;

çoklu host/NFS için bu bir koordinasyon mekanizması değildir. API ve

MCP process-local cache'leri yalnız performans optimizasyonudur; doğruluk

durumu SQLite ledger ve fenced lease'lerdedir. Yatay writer ölçekleme ancak

paylaşımlı lease/koordinasyon servisi tasarlanıp doğrulandıktan sonra açılır.

7. Model/provider olayı#

MESA_MODEL_ENABLED ve MESA_EXTERNAL_PROVIDER_ENABLED açıkça ayarlanır.

Provider timeout/rate-limit hatası retryable; bozuk şema permanent; sürekli

aynı toksik payload poison olarak sınıflanır. Seçili validation policy

tamamlanmadan SQL/vector/graph projection başlamaz. Provider’ı atlamak için mutation’ı doğrudan VALIDATED

duruma çekmeyin.

8. PageRank#

V4 PageRank çıktısı yalnız telemetridir. Düşük merkezilik bir memory,

assertion, vector veya source’u karantinaya alamaz. PageRank temelli

hallucination/delete davranışı görülürse deploy durdurulmalı; bu v4

sözleşmesine aykırıdır.

9. Session finalization#

Session end durable finalization kaydı oluşturur. Restart sonrası pending işler

combined consumer tarafından alınır. Uzun süre pending kalırsa session,

finalization ID, lease ve DLQ durumu kontrol edilir; FastAPI process içi

BackgroundTasks çalışmasına güvenilmez.

10. Logging ve olay kanıtı#

Production varsayılanı MESA_LOG_LEVEL=INFO ve MESA_LOG_FORMAT=json’dır.

Loglarda request/operation/mutation/pipeline run kimlikleri bulunabilir;

query, source content, payload, credential, raw model output ve claim token

bulunamaz. Docker local driver 10 MB × 5 dosya sınırı kullanır.

Incident kanıtı olarak maskelenmiş log, mutation status, health/metrics anlık

görüntüsü, image digest ve storage manifesti saklanır.

12. Release durumu#

Unit/integration/contract testlerinin geçmesi production GO değildir. Gerçek

provider ve production-benzeri store ile backup→restore→rebuild→cutover,

queue saturation, worker crash, cross-tenant concurrency ve 24 saat soak

kanıtları tamamlanana kadar karar NO-GO kalır.