MAT-003: Shared Provenance Data Contract

• Status: Accepted
• Date: 2026-08-18
• Scope: source capture, process runs, evidence graph, publication closure and production curation control records
• Machine contract: config/governance/provenance-contract.yml

Amaç

ADR-006 bütün domainlerin tek provenance grafiğini, ADR-007 ise tek production curation protokolünü kullanmasını gerektirir. Bu belge bu iki kararın fiziksel veri sözleşmesini kesinleştirir. Corpus, compound, lügat, Osmanlıca, heading, haşiye, repetition ve multilingual pipeline’ları ayrı source/run/evidence tabloları kuramaz.

Bu sözleşme migration değildir. Tablo sınırını, alan tiplerini, anahtarları, FK’leri, canonical serialization’ı ve yayın invariant’larını kilitler. F3-019 migration ve SDK üretirken bu sözleşmeyi birebir uygular.

Provenance control evidence’dır: bir olgunun nereden geldiğini, hangi işlemden geçtiğini ve neden release’e alındığını ispatlar. Core metni, terkibin doğruluğunu, seçilmiş lügat anlamını veya current Osmanlıca rendering’i kendisi belirlemez. Curation kararları control authority’dir; domain semantic authority’sini ancak review edilmiş action ve transaction üzerinden değiştirir.

Fiziksel sınır

Sözleşme 31 relation içerir. Bir relation tek identity ve tek MAT-001 sınıfı taşır.

Source kataloğu

Relation	Kimlik	Amaç
source_system	Bir upstream koleksiyon/proje	URL’den bağımsız kaynak kökeni
source_release	Bir source system’ın immutable yakalanmış hali	Release key, artifact inventory, rights ve retention bağları
source_artifact	Release içindeki exact artifact occurrence	Logical locator, byte count ve digest
source_record	Artifact içindeki exact seçili kayıt/aralık	Versioned selector, selected bytes ve field witness root

source_system.system_key logical kökeni belirtir; homepage veya mirror değildir. source_release branch adı, latest URL, mtime veya query zamanı ile tanımlanamaz. source_record için SQLite integer ID, CSV satır numarası veya normalized key tek başına yeterli değildir. Artifact digest, selector profile/payload ve selected-byte witness birlikte bağlanır.

Process ve evidence grafiği

Relation	Sınıf	Amaç
process_contract	immutable	Versioned executable, runtime lock, schema, config, ordering ve determinism tarifi
process_run	immutable	Contract altında tek execution occurrence ve exact inventory root’ları
process_run_input	immutable	Run’ın complete, ordered ve typed input seti
derived_artifact	immutable	Başarılı bir run’ın identified output artifact occurrence’ı
process_run_output	immutable	Başarılı run ile exact derived_artifact arasındaki generating edge
provenance_assertion	immutable	Kaynak bytes olmayan exact insan/proje beyanı
provenance_endpoint	immutable	Owner kimliğini değiştirmeyen typed graph endpoint registry’si
evidence_edge	immutable	Kapalı role ve izinli kind-pair taşıyan evidence ilişkisi
validation_attestation	immutable	Exact subject/policy/validator/result bağı

process_run kimliği execution occurrence’ıdır. Aynı deterministic işlem aynı output hash’ini üretse de retry yeni run ID alır. Contract ve exact input seti aynıysa output parity ayrıca doğrulanır; iki run’ın identity’si birleştirilmez.

Bir run’ın tüm semantik inputları process_run_input içinde bulunur. Network cevabı, current DB satırları, locale, wall clock veya filesystem order gizli input olamaz. Network verisi önce source_artifact olur. Output edge ve derived_artifact yalnız terminal_status = succeeded için yayımlanabilir. Output satırı (derived_artifact_id, process_run_id, output_role, ordinal) bileşik FK’siyle artifact’ın declared generator/role/ordinal değerlerini aynen bağlar. Count, kesintisiz ordinal ve inventory-root parity zorunludur. Failed/interrupted run audit kaydı kalabilir fakat accepted output üretemez.

Closure ve publication

Relation	Amaç
coverage_binding	Büyük entity kümelerini exact profile/count/root ile temsil etmek
intake_partition	Kaynak evreninin total include/exclude bölünmesi
intake_disposition	Bir partition grubunun typed sonuç ve gerekçesi
provenance_release_manifest	Private audit ve public projection root’larını policy’lerle bağlamak
provenance_manifest_member	Manifestin ordered typed endpoint inventory’si
provenance_closure_report	Missing/unused/cycle/rights/leak blocking setlerinin exact sonucu
publication_authorization	Closure, attestation, compatibility, authority, approval ve trusted-registry accepted entry bağı

Coverage bir mutable SQL predicate değildir. member_kind + membership_profile + member_count + membership_root ve retained membership artifact’ı ile exact üyeliğe açılabilmelidir. Intake partition’ın included ve excluded kümeleri disjoint ve toplamda declared universe’e eşit olmalıdır. unknown publish edilebilir disposition değildir.

Publication için aşağıdaki setlerin tümü boş olmalıdır:

• missing support ve unused bundled evidence;
• dangling/incompatible edge ve lineage/containment cycle;
• incomplete run veya count/root uyuşmazlığı;
• intake gap/overlap;
• unverifiable terminal source;
• rights/attribution blocker; ve
• public metadata leak.

Başarılı closure raporu tek başına publication yetkisi değildir. Önce private/public payload’ları, closure ve attestation’ı bağlayan candidate manifest oluşur. publication_authorization bu manifest ID/root’unu, candidate release endpoint’i, aynı private/public root’ları, sıfır blocking-set taşıyan closure report’u, bu report root’unu subject alan passed attestation’ı, compatibility evaluation’ı, authority epoch/snapshot’ı, approval set’i ve trusted-registry accepted-entry root’unu tek immutable authorization_root altında bağlar. Manifest authorization’a geri bağlanmadığı için hash döngüsü oluşmaz. Curation release hem aynı manifest/candidate çiftine hem aynı accepted authorization’a FK verir; compare-and-publish transaction’ı zinciri yeniden doğrular.

Curation control kayıtları

Relation	Authority	Amaç
curation_candidate	evidence	Machine/import suggestion ve score snapshot
curation_proposal	control	Immutable proposal revision ve frozen target/action/evidence seti
curation_action	control	Proposal revision içindeki ordered typed action
curation_review	control	Exact proposal bytes için actor approval/rejection
curation_decision	control	Review inventory ve authority epoch üzerinde quorum sonucu
curation_transaction	control	Accepted decision’ın atomic application occurrence’ı
curation_transaction_action	control	Her action’ın exact emitted/result kaydı
curation_release	control	Parent, ordered transaction delta ve resulting state root
curation_release_transaction	control	Release delta’sının ordered transaction üyeliği
curation_event	control	Lifecycle streamindeki append-only typed event
curation_effective_state	derived	Named curation release için rebuildable current projection

Candidate semantic kabul değildir. Proposal, candidate olmadan da oluşturulabilir; candidate’dan promotion yapılırsa immutable payload ve evidence root’ları proposal’ya bağlanır.

curation_proposal doğal anahtarı (proposal_id, revision)’dır. Her revision ayrıca tek immutable proposal_revision_id alır; endpoint owner passthrough bu UUID’yi kullanır ve iki revision’ı tek endpointte birleştiremez. Action ve event doğal bileşik anahtara, review/decision ise (proposal_id, revision, payload_root) anahtarına FK verir. Bir revision’ın action/target/evidence, expected-state, policy veya compatibility root’u değişirse reviewed bytes değiştirilemez; yeni revision ya da successor proposal gerekir.

Action hedefleri provenance_endpoint üzerinden typed owner’a gider. Text search, normalized key veya live query çalıştırılmaz. Bulk discovery sonucu proposal öncesinde ordered ID inventory/count/root olarak dondurulur.

Review; proposal ID/revision/payload root, reviewer, authority snapshot/epoch ve signed approval root’u taşır. Decision exact review inventory ve MAT-002 evaluation root’unu bağlar. Transaction yalnız accepted decision’ın exact (decision_id, decision_root, proposal_id, revision) anahtarına, aynı authority epoch’a, expected-state root’a, core witness’a ve idempotency binding’e bağlıysa uygulanabilir. Her transaction-action sonucu da reviewed action’ın (proposal_id, revision, ordinal, action_root) anahtarına FK verir; count/root parity olmadan transaction başarılı sayılamaz.

curation_event generic payload log’u değildir. Kapalı event kind her satırda tam bir typed subject ister:

Event	Subject
proposal_submitted, proposal_withdrawn, proposal_superseded	proposal ID + revision
review_recorded	review ID
decision_recorded	curation decision ID
applied, application_failed	curation transaction ID
published	curation release ID

Event payload root’u ayrıntıyı bağlar fakat typed FK’nin yerini alamaz. Stream sequence, typed predecessor event ID ve predecessor event root aynı-stream bileşik FK ve kesintisiz sequence kuralıyla append-only order sağlar. proposal_superseded ayrıca exact successor proposal ID/revision ister; diğer event kind’larında bu alanlar null olmak zorundadır. UUID veya timestamp order authority değildir.

curation_effective_state public kimlik üretmez. Projection row’u release, domain ve typed endpoint ile anahtarlanır; exact curation release zincirinden rebuild edilir ve generation root parity sağlanmadan atomic swap yapılamaz.

Endpoint sözleşmesi

Raw table_name + record_id, unchecked UUID ve runtime-created kind yasaktır. provenance_endpoint owner kaydına ikinci kimlik vermez:

endpoint_id = owner_id

Her endpoint tam olarak bir typed bridge ile owner relation’ındaki declared tek UUID candidate key’e bağlanır. Contract her kind için owner_fields anahtarını taşır ve validator bu alanın PK/unique UUID olduğunu doğrular. Local provenance/curation owner’ları kind-specific local_typed_bridge_fk kullanır. Semantic reference target’ları CAT-001 registry FK’sini kullanır. Release ve referenceable olmayan domain control hedefleri versioned kapalı kind manifestinden üretilen external_typed_bridge_fk tablolarını kullanır. Büyük setler yalnız content-addressed coverage_manifest_fk ile temsil edilir. Böylece ortak registry’nin owner_id kolonu hiçbir zaman polymorphic FK gibi kullanılmaz.

Yeni endpoint kind bir runtime data insert’i değildir. Contract değişikliği, generated bridge/FK, migration, validation fixture ve compatibility review gerektirir.

Evidence role’leri kapalıdır: direct_source, transformation_input, curation_basis, boundary_basis, validation_subject, validation_result, rights_basis, attribution_basis, fixture_basis, negative_fixture_basis ve exclusion_basis. Her role machine contract’taki exact from/to kind kümelerine uymalıdır. related_to closure kanıtı değildir.

Canonical serialization

Canonical envelope munderecat-canonical-json-sha256-v1 profilini kullanır:

• UTF-8 code point’leri korunur; örtük Unicode normalization yapılmaz;
• object key’leri lexicographic sıralanır;
• array order semantik sıra veya explicit ordinal’dır;
• yalnız integer numeric değer kullanılır;
• digest SHA-256’dır; ve
• mutable locator, operational timestamp, host, insertion/row order identity dışında kalır.

Raw source bytes hiçbir zaman JSON normalization’dan geçirilmez; exact byte digest ve encoding profile ile ayrı bağlanır. Canonical metadata içindeki optional null, boş set ve unavailable durumları profile’ın declared formuyla serialize edilir.

Authority veya inventory üreten root’lar yalnız alan adından türetilmez. root_envelopes her signing/aggregate root için versioned profile’ı, row projection alanlarını veya member relation + partition + order + member projection + count preimage’ını açıkça tanımlar. Böylece bağımsız uygulamalar aynı bytes’ı üretir; opaque upstream byte/policy witness’ları ise ilgili source/process profile’ının girdisi olarak kalır. Manifestin historical_dependency_root alanı da profile/count ve exact retained membership artifact’ının ordered_content_root değeriyle bileşik FK üzerinden bağlanır; historical traversal bir live query’ye bırakılamaz.

Private ve public projection

Private audit closure ve distributable public projection iki ayrı serialization’dır. Public form private objeden sonradan key silen serbest bir filtre değildir:

• relation/field seviyesinde explicit allowlist ve default-deny kullanır;
• private audit root veya guessable private commitment içermez;
• private/public eşleme payload dışında access-controlled tutulur;
• yalnız opaque audit-attestation reference yayımlar; ve
• selector payload, absolute path, signed URL, hostname, credential, query secret, Docker/DB object ID ve kişisel veriyi reddeder.

Public root private root’u doğrulamaya yetmez. Trusted registry iki root ve aralarındaki attested ilişkiyi private olarak bağlar. Public istemci yalnız disclosure-approved manifest/report/attestation projection’ını görür. Private audit’i bağlayan manifest_root, attestation result_root ve erişimi kısıtlı source content_root public allowlistte yer almaz; public doğrulama için ayrı public_projection_root ve public_report_root kullanılır.

Corpus release projection profile’i

munderecat-corpus-public-provenance-v1, bu genel kuralların ADR-003 corpus paketi için daraltılmış serialization profilidir. Profil yeni bir provenance authority kurmaz ve private relation satırlarını public’e kopyalamaz. Public payload yalnız:

• gerçek ve bir kez üretilmiş materialization process_run_id değerini;
• private evidence edge/path kayıtlarına karşılık gelen opaque public ID’leri;
• public closure boundary ve public manifest ID’lerini;
• sekiz coverage binding’i ve yalnız {member_kind,id} içeren membership artifact’i;
• F3-012 mapping seti için opaque attestation ve public mapping-set root’unu; ve
• disclosure policy, bilinen sınırlamalar ve public artifact digestlerini taşır.

Kaydedilmemiş eski compiler/sealer run kimlikleri geriye dönük türetilmez. Bunun yerine materialization run’ı accepted compiler manifest, sealed core, identity authority, coverage seed ve crosswalk seed hashlerini complete input inventory olarak bağlar. Public evidence path ID’lerinin bu private inputlara eşlemesi private graph’ta kalır. Böylece downstream packager gerçek olmayan geçmiş occurrence’lar icat etmeden accepted artifact lineage’ını doğrulayabilir.

Materialization occurrence ID’leri config girdisi değildir. Her deneme fresh process_run_id, evidence path, closure boundary, public manifest ve private mapping ID’leri üretir; yalnız staged verifier’dan geçen tek occurrence no-replace final yola taşınır. Verifier public membership satırlarını accepted identity stream’iyle ve mapping-set root’unu accepted F3-012 crosswalk stream’iyle yeniden karşılaştırır. Manifestin kendi count/root/hash alanları upstream authority yerine kullanılamaz. Passed attestation exact closure-report root’unu subject alır ve policy, validator, public projection ile sıfır blocking setini birlikte bağlar.

Public ID membership artifact’i source locator/path alanlarını düşüren deterministik bir projection’dır. Her kind’ın source stream byte hash’i accepted identity authority ile doğrulanır; ardından public root yalnız ordered UUIDv5 listesinden hesaplanır. F3-012 için public mapping-set root source sırasından bağımsızdır; accepted ordered root ve source-evidence root private closure’da bağlı kalır. Downstream packager bu artifact’leri üretmez, accepted handoff byte’larını ve kimliklerini tüketir.

Mutation ve FK kuralları

• Bütün FK’ler ON DELETE RESTRICT davranışındadır.
• FK target kolonları declared primary/unique key olmak zorundadır.
• Immutable ve control-authority historical satırlarda update/delete/truncate yoktur.
• Düzeltme yeni source release, assertion, proposal revision, decision, transaction, event, manifest veya ADR-002 successor üretir.
• Derived effective state yalnız generation staging + parity + atomic swap ile değişir.
• Parent proposal alanları ve event proposal subject alanları birlikte null veya birlikte dolu olur.
• Parent curation release nullable olabilir; parent_release_witness_root genesis null dahil canonical parent değerini identity’ye bağlar.

Makine doğrulaması

scripts/governance/provenance_contract.rb şu drift’leri fail-closed reddeder:

1. relation, endpoint kind, role, status veya action vocabulary eksilmesi/genişlemesi;
2. relation permanence/authority değişimi veya relation kimliklerinin birleştirilmesi;
3. zorunlu alan, PK, identity field, unique key ya da FK kaybı;
4. non-unique FK target, cardinality uyuşmazlığı veya cascade delete;
5. generic polymorphic alan ve unchecked endpoint;
6. proposal revision bağının veya curation event subject coverage’ının kırılması;
7. owner identity passthrough yerine ikinci endpoint kimliği üretilmesi;
8. failed run’dan output ya da unaccepted decision’dan transaction yolu açılması;
9. private root/leak koruması veya blocking closure setinin zayıflatılması; ve
10. enum alanının kapalı vocabulary bağından çıkarılması, root preimage kaybı veya canonical profile içeriğinin aynı contract altında sessizce değiştirilmesi.

Contract root, config’in canonical tamamından üretilir ve validator içindeki accepted root lock ile karşılaştırılır. Config-only alan/FK/vocabulary/allowlist eksiltmesi bu nedenle yapısal kontrollerden bağımsız olarak da fail closed olur. Bilinçli contract revision’ı config ve root lock’u aynı reviewed değişiklikte günceller. Accepted contract bytes değişirse root değişir ve migration/release authorization eski root’u kullanamaz.

Sonuçlar

Sağlananlar

• Bütün pipeline’lar aynı source/release/run/evidence kimliklerini paylaşır.
• Bir token, compound, Osmanlıca rendering veya sense kararı exact source record ve run zincirine kadar izlenebilir.
• Curation evidence ile domain authority karışmadan aynı graph closure içinde tutulur.
• Minimal source bundle ve kullanılmayan veri denetimi mekanik hale gelir.
• Private audit zenginliği public release’e bilgi sızdırmadan korunur.
• F3-019 migration ve SDK için yorum gerektirmeyen machine input oluşur.

Maliyetler

• Pipeline’lar informal log yerine complete inventory ve typed edge üretir.
• Her yeni endpoint/role/schema değişikliği reviewed contract sürümü gerektirir.
• Closure validation bütün release snapshot’ı üzerinde deterministik graph işi yapar.

Uygulama handoff’u

• F3-019 bu relation ve constraint’leri PostgreSQL migration, role grant ve generated SDK type’larına çevirir.
• F3 corpus compiler source/record/run/output kayıtlarını bu primitive’lerle yayımlar.
• F4-F7 domain pipeline’ları candidate/evidence üretir; semantic kabul için aynı curation proposal/review/decision/transaction yolunu kullanır.
• F10 trusted registry, signer/authority adapter ve public/private manifest retention sınırlarını production’da uygular.
• F2-020 bu kayıtların public API projection, error ve unavailable davranışını ayrıca tanımlar; DB row shape’i doğrudan public contract olmaz.