MAT-002: Compatibility Impact And Approval

• Status: Accepted
• Date: 2026-08-18
• Decision owners: architecture, identity, release and security maintainers
• Scope: stable/public identity, observable contracts, accepted semantics, migrations and release approval

Amaç ve sınır

Bu matris bir değişikliğin doğru olup olmadığına tek başına karar vermez. Önce domain, schema, corpus, API veya güvenlik kontrolü değişikliğin gerçek etkisini kanıtlar; bu matris o kanıtlanmış olguların en yüksek compatibility sınıfını ve gereken bağımsız onay tabanını hesaplar.

Sınıflandırma migration adı, commit mesajı, semver etiketi veya yazar niyeti üzerinden yapılmaz. Exact candidate/root, kapalı olgu kümesi ve etkilenen yüzeyler üzerinden yapılır. Aynı candidate içindeki en ağır olgu bütün candidate’ın alt sınırıdır.

Makine anahtarları, sayılar ve capability kümeleri config/governance/compatibility-policy.yml içinde versioned olarak tutulur. Bu belge anahtarların semantik anlamının canonical kaydıdır. Evaluator canonical policy içeriğinden policy_root üretir; ID ve root birlikte release’e bağlanır. Accepted policy içeriği aynı ID altında sessizce değiştirilemez, yeni sürüm yeni policy identity/root üretir. Belge, config ve bound root arasında fark varsa authorization üretilmez.

Dört kapalı sınıf

Şiddet sırası değişmez:

none < compatible < superseding < breaking

Sınıf	Anlam	Korunması gerekenler	Tipik sonuç
none	Stable/public kimlik, kabul edilmiş anlam ve gözlemlenebilir sözleşme değişmez	Bütün eski ID, byte/anlam ve davranış iddiaları aynıdır	Aynı contract/major içinde normal release
compatible	Yeni yetenek veya kayıt eklenir; mevcut tüketici ve referansların anlamı değişmez	Eski ID, exact lookup, gerekli alanlar, hata ve yetki davranışı korunur	Additive release
superseding	Kabul edilmiş current/recommended çözüm veya identity-bearing anlam typed lifecycle olayıyla değişir	Eski ID, historical exact lookup ve event geçmişi korunur; replacement/split/merge/restructure successor taşır, retirement taşımaz	Successor, retirement veya recommendation transition release’i
breaking	Mevcut kabul edilmiş kimlik veya davranış yeni sözleşme altında korunamaz	Eski history yine değiştirilmez; geçiş yeni major, namespace veya support boundary ile açıkça yapılır	Breaking release veya authorization blokajı

superseding, compatible ile breaking arasında belirsiz bir ara etiket değildir. Eski referent doğru biçimde yaşamaya devam eder, fakat current/recommended çözüm typed bir lifecycle olayıyla değişir. Identity-bearing anlam değiştiyse yeni referent ve successor gerekir. Yalnız recommendation/status değişiminde ID korunur; retirement olayının successor kümesi boş olabilir. Eski ID’yi yeni anlama vermek ise supersession değil, yasaklanmış yeniden kullanımdır.

breaking değişiklik otomatik olarak yasak demek değildir. Örneğin destek süresi tamamlanmış bir API major’ını yeni major ile değiştirmek breaking olabilir ve doğru geçiş kanıtlarıyla yayımlanabilir. Buna karşılık accepted ID’yi yeniden atamak veya curated history’yi yerinde değiştirmek hem breaking olarak görünür hem de temel ADR ihlalidir; yeterli oy bunu meşru kılamaz.

Sınıflandırma olguları

Machine policy kapalı olgu anahtarlarını sınıflara bağlar. Ana gruplar şöyledir:

None

• Yalnız dokümantasyon veya non-semantic metadata değişmiştir.
• Implementation refactor gözlemlenebilir davranışı değiştirmemiştir.
• Derived/cache rebuild aynı authority root’larını üretmiştir.
• Evidence yeniden çalıştırılmış, accepted state değişmemiştir.

none iddiası negatif kanıt ister. Public response, current resolution, identity preimage, accepted data/curation root veya yetki davranışındaki açıklanamayan fark bu sınıfı geçersiz kılar.

Compatible

• Yeni public entity/kind eklenmiş, mevcut kind ve ID anlamları korunmuştur.
• Optional contract davranışı eklenmiş, eski istemci ve required alanlar korunmuştur.
• Yeni release eski kimlikleri ve kabul edilmiş semantiği aynı biçimde taşımıştır.
• Provenance veya translation eklenmiş, current resolution değişmemiştir.

Yeni bir alanın optional görünmesi yeterli değildir. Varsayılan, cardinality, error, authorization, ordering veya pagination anlamını değiştiriyorsa additive sayılmaz.

Superseding

• Identity-bearing olgu değişmiş ve ADR-002 successor olayı oluşturulmuştur.
• Current resolution explicit lifecycle/supersession olayıyla değiştirilmiştir.
• Recommendation/status identity-bearing referent değişmeden güncellenmiştir.
• Referent, ADR-002 retirement olayıyla successor olmadan current çözümden çekilmiştir.
• Entity split, merge veya restructure tam crosswalk ile yayımlanmıştır.
• Accepted semantik düzeltme history’yi koruyan curation/successor olayıdır.
• Desteklenen davranış historical resolution korunarak deprecate edilmiştir.

Identity-changing supersession; predecessor/successor kümelerini, relation kind’ını, reason/evidence’i, effective release’i ve ambiguity durumunu bağlamadan tamamlanmış sayılmaz. Retirement aynı sözleşmeyi zero-successor olarak uygular. Recommendation veya status transition’ı ise referent’ı değiştirmeyen typed curation/lifecycle event’ini ve önceki/yeni selection durumunu bağlar; sahte successor üretmez.

Breaking

• Identity namespace veya identity-name schema değişmiştir.
• Required public davranış, hata, cardinality, authorization veya yorum kaldırılmış ya da uyumsuz biçimde değiştirilmiştir.
• Yeni release eski desteklenen tuple’ı successor/major sınırı olmadan geçersiz kılmıştır.
• Migration’ın partial/destructive hali kabul edilmiş execution modelinde temsil edilemiyordur.
• Etki bilinmiyor veya yeterince kanıtlanmamıştır.

Belirsizlik için impact_unknown_or_unproved olgusu kullanılır. Bu olgu breaking hesaplanır fakat authorization alamaz; gerekli diff/fixture üretilip kapalı bir olguya dönüşene kadar candidate bloklanır.

Yasak olgular

Aşağıdaki durumlar sınıflandırılır fakat approval evaluator tarafından her zaman reddedilir:

• accepted immutable/curated history’yi yerinde yeniden yazmak;
• accepted public ID’yi yeniden kullanmak veya başka referent’a atamak;
• historical exact resolution’ı kaldırmak ya da yanlış göstermek;
• bilinmeyen/kanıtlanmamış etki;
• temsil edilemeyen partial/destructive migration;
• successor veya major boundary olmadan desteklenen release tuple’ını geçersiz kılmak.

Düzeltme, olgu anahtarını gizlemek değildir. Candidate; successor, yeni major, representable migration veya eksik kanıt ile yeniden kurulmalıdır.

Etkilenen yüzeyler

Impact class ne olduğunun, surface ise nerede olduğunun cevabıdır. Bir candidate birden fazla surface taşır.

Surface	En az bağımsız onay	Zorunlu capability kapsamı
internal_only	1	independent_verification
annotation_or_relation	1	domain_review
stable_identity	2	domain_review, identity_lifecycle
public_contract	2	api_contract, security_review
authorization_or_disclosure	2	domain_review, security_review
production_migration	2	database_schema, release_security
immutable_core	2	corpus_review, identity_lifecycle
curated_semantics	2	curation_review, domain_review
multilingual_or_repetition	2	domain_review, identity_lifecycle

Surface seçimi write path’e bakılarak tahmin edilmez. Bir SQL dosyası API contract’ını, bir data curation current resolution’ı, bir TypeScript değişikliği authorization davranışını etkileyebilir. Diff ve fixture hangi yüzeylerin gerçekten etkilendiğini kanıtlar.

Onay matrisi

Sınıf tabanı şöyledir:

Sınıf	En az bağımsız approver	Sınıf capability kapsamı
none	1	independent_verification
compatible	1	domain_review
superseding	2	domain_review, identity_lifecycle
breaking	3	domain_review, identity_lifecycle, release_security

Nihai minimum, sınıf minimumu ile bütün surface minimumlarının en büyüğüdür. Zorunlu capability kümesi sınıf ve bütün surface kümelerinin birleşimidir. Bir kişi birden fazla kanıtlanmış capability taşıyabilir; ancak reviewer kimliği yalnız bir oy sayılır.

Bu nedenle none ve compatible için bir approver mümkün olsa da yazar oy veremez: yazar ile approver birlikte iki-person control tabanını oluşturur. superseding en az iki, breaking en az üç ayrı approver ister. Production migration gibi bir surface, sınıf daha düşük olsa bile en az iki approver’a yükseltir.

Ek ayrım kuralları:

• reviewer ID’leri unique olmalıdır;
• author approval set’inde bulunamaz;
• release operator tek approver olamaz;
• fact/surface kümesi candidate beyanından değil exact evidence root’unu doğrulayan trusted impact resolver sonucundan gelir;
• author/operator kimliği, reviewer yetkisi, capability ve revocation durumu candidate alanından değil bound authority snapshot/epoch üzerinden trusted resolver ile gelir;
• approval kaydı capability beyanı taşımaz; reviewer ID ve exact signed approval root’u taşır;
• capability kapsamı yalnız sayı tamamlandı diye sağlanmış sayılmaz;
• approval exact subject/target ve policy root’una aittir, başka candidate’a taşınamaz;
• domain correctness gate’i compatibility approval ile ikame edilemez.

Deterministik hesap

Evaluator şu sırayı izler:

1. Manifest alanlarını, array biçimlerini, policy ID’yi ve exact policy_root’u doğrular.
2. Trusted impact resolver; subject/target ve impact_evidence_root üzerinden complete fact/surface kümesini doğrular. Candidate beyanı bu sonuçla exact değilse reddedilir.
3. Boş, scalar, duplicate veya vocabulary dışında fact/surface değerini reddeder ve maksimum severity sınıfını hesaplar.
4. Declared class exact hesapla aynı değilse downgrade/overstatement dahil reddeder.
5. Sınıf ve surface minimum/capability birleşimini üretir; non-authorizable fact varsa quorum’a bakmadan reddeder.
6. Policy, subject/target, evidence, class, authority snapshot/epoch ve actor alanlarından canonical approval_subject_sha256 üretir.
7. Trusted authority resolver her approval root’unun bu subject’i onayladığını; reviewer yetkisini, current capability/revocation durumunu ve gerçek author/operator kimliğini bound snapshot üzerinden doğrular.
8. Distinct reviewer, author/operator ayrımı, sayı ve trusted capability kapsamını doğrular; canonical binding ve evaluation_sha256 üretir.

Evaluator’a trusted resolver verilmezse değerlendirme fail closed olur. Repository CLI yalnız policy yapısını kontrol eder; caller-supplied JSON, kendi başına release veya curation authorization üretemez.

Overstatement da reddedilir; çünkü yanlış breaking etiketi gereksiz major/supersession işlemlerine ve hatalı public metadata’ya yol açabilir. Belirsizlik özel breaking olgusu ile açıkça kaydedilir.

Binding şu anlam alanlarını taşır:

policy_id + policy_root + subject_kind + subject_root + target_root
+ impact_evidence_root + facts + surfaces + declared_class
+ authority_snapshot_root + authority_epoch + author_id + release_operator_id
+ approval_subject_sha256 + canonical reviewer_id/approval_root set

ADR-012 migration authorization ve final attestation bu evaluation root’unu candidate manifest/evidence closure üzerinden bağlar. Subject, target, fact, surface, policy içeriği, authority epoch veya approval değişirse root değişir ve eski onay kullanılamaz.

Örnekler

Dokümantasyon yazım düzeltmesi

documentation_or_nonsemantic_metadata_only + internal_only sonucu none, en az bir author-excluded approver ve independent_verification capability’sidir.

Additive public alan

Mevcut istemci davranışını değiştirmeyen optional alan additive_optional_contract_behavior + public_contract ile compatible olur. Surface nedeniyle en az iki approver gerekir; approval set domain_review, api_contract ve security_review capability’lerini birlikte kapsar.

Curated terkip düzeltmesi

Eski compound occurrence’ı silmeden yeni referent ve typed successor yayımlayan düzeltme, accepted_semantic_correction_preserves_history ile superseding olur. stable_identity + curated_semantics yüzeylerinde en az iki reviewer; domain, identity ve curation capability kapsamı gerekir.

Davranış değiştirmeyen index migration’ı

Exact schema/API/data semantiğini değiştirmeyen bir index düzenlemesi none olabilir; ancak production_migration surface’i nedeniyle en az iki approver ve database/release security kapsamı gerekir. Düşük impact sınıfı operasyonel riski silmez.

Required API alanını kaldırmak

required_public_contract_behavior_removed_or_reinterpreted + public_contract breaking üretir. En az üç approver, breaking class capability’leri ve API/security capability kapsamı gerekir; ADR-010 major ve support-window kuralları ayrıca geçer.

Public ID’yi başka kayda vermek

accepted_public_id_reused_or_reassigned breaking hesaplanır fakat non-authorizable olduğu için üç veya daha fazla oyla dahi yayımlanamaz. Doğru çözüm yeni ID ve gerekiyorsa typed supersession’dır.

Diğer kararlarla ilişki

• ADR-002 hangi olguların identity-bearing olduğunu ve successor’ın neyi koruduğunu belirler; bu matris onları yeniden tanımlamaz.
• ADR-007 proposal/action byte’larını, reviewer authority’sini ve accepted curation transaction’ını sağlar.
• ADR-010 public contract major/minor davranışını ve compatible deployment tuple’ını belirler. Bu matris bir migration veya code diff’inin tek başına API compatibility ilan etmesine izin vermez.
• ADR-012 classification, policy, signer ve evidence root’larını migration authorization/release attestation zincirine bağlar.
• CAT-001 yeni kind ve identity path değişikliklerinin stable identity surface’ini işaretlemesini gerektirir.
• MAT-001 permanence sınıfı mutation’ın teknik olarak rebuild/edit/successor olup olamayacağını belirler; approval yasak mutation’ı serbest bırakmaz.

Zorunlu doğrulamalar

F3-F10 uygulamaları en az şu fixture’ları sağlamalıdır:

1. Kapalı vocabulary, severity sırası ve policy drift kontrolü.
2. Birden fazla fact için order-independent maksimum severity sonucu.
3. Boş, duplicate ve bilinmeyen fact/surface reddi.
4. Scalar fact/surface, candidate olgu eksiltmesi ve trusted-impact mismatch reddi.
5. none -> compatible -> superseding -> breaking downgrade ve overstatement reddi.
6. Trusted authority olmadan değerlendirme; uydurma reviewer/capability, duplicate reviewer, author self-review ve sole-operator reddi.
7. Sayı yeterli olsa da eksik capability; capability yeterli görünse de eksik distinct reviewer reddi.
8. Non-authorizable breaking fact’in quorum’dan bağımsız bloklanması.
9. Subject/target/evidence/fact/surface/policy bytes/authority epoch/approval değişince evaluation root’unun değişmesi.
10. Recommendation-only transition ile zero-successor retirement’ın identity-changing successor üretmeden superseding hesaplanması.
11. Identity, API, migration, core ve curation örneklerinin beklenen overlay sonucunu üretmesi.
12. Release authorization’ın exact evaluation root dışında yeniden kullanılamaması.

Sonuçlar

Kazanımlar

• Identity, API, migration ve curation aynı risk dilini kullanır.
• “Bug fix”, “yalnız SQL” veya “additive” etiketiyle sınıf düşürme engellenir.
• Reviewer sayısı sabit aşırı süreç yerine gerçek class/surface etkisine göre artar.
• Supersession ile breaking ayrımı historical reference doğruluğunu korur.
• Release imzası yorum metnine değil deterministik evaluation root’una bağlanabilir.

Maliyetler

• Her candidate kapalı fact ve surface iddiası ile complete impact evidence root’u üretmelidir; trusted resolver iddiayı yeniden doğrular.
• Yeni etki türü policy vocabulary güncellemesi ve bağımsız review gerektirir.
• Multi-surface candidate’larda reviewer capability koordinasyonu gerekir.

Ertelenen kararlar

• F2-019 source/run/evidence/curation event fiziksel alanlarını bu binding’e bağlar.
• F2-020 public API diff ve generated-contract çıktılarının concrete fact üretimini tanımlar.
• F3-F9 domain pipeline’ları fact/surface manifestlerini ve negatif fixture’ları üretir.
• F10 trusted impact/authority resolver’larını, signature threshold/key/provider uygulamasını ve hosted branch protection’ı uygular; bu matristeki minimumu düşüremez.