Reference resolution

Munderecat’ta bir entity kimligi yayimlandiktan sonra baska bir kimlikle degistirilmez. Bir terkip, lexeme veya occurrence duzeltildiginde eski UUID tarihsel kayitlarda ve atiflarda kalir; degisiklik typed supersession olayi olarak eklenir. Bu sayfa, reference_control katmaninin bu olaylardan nasil exact ve current okumalar urettigini aciklar.

Normatif kurallar ADR-002 ve ADR-007 icindedir. Fiziksel uygulama db/supabase/migrations/20260826110000_f9_003_reference_resolution.sql migration’idir.

Neden iki okuma var?

get_entity_exact_v1 istenen UUID’yi asla yonlendirmez. Kaynak bir atif eski bir terkibe yazilmissa exact okuma o terkibin kendi projeksiyonunu ve secilen release’teki yasam dongusu durumunu verir.

resolve_entity_current_v1 ise acik bir resolution policy ve release ister. Etkin supersession grafini sinirli olarak izler ve guncel hedef kumesini verir. Bu ayrim, tarihsel dogruluk ile kullaniciya guncel kaydi gostermeyi birbirine karistirmaz.

Ornek:

Atifta saklanan ID: A
Eski olay:           A -> B       invalidated
Duzeltilmis olay:    A -> C       effective

exact(A)   => entity_id=A, lifecycle=superseded, successor_ids=[C]
current(A) => target_entity_ids=[C], path=[A->B invalidated, A->C effective]

Atif satiri yine A tutar. B veya C atif kaydina yazilarak tarih yeniden yazilmaz.

Katmanlar

Global registry

reference_control.referenceable_entities, F9-002’nin ayni UUID’li typed owner bridge’leriyle birlikte cozumlenebilen kimliklerin kapisidir. Bir supersession katilimcisi registry’de yoksa veya olayla ayni kind’a sahip degilse resolution release yayimlanamaz.

Registry entity verisini kopyalamaz. compound_entry, lexeme ve diger sahip tablolardaki UUID’yi kaydeder ve typed FK ile gercek owner satirina baglar.

Domain supersession ledgers

F9-003 yeni compound veya lexeme olayi uretmez. Su append-only kaynaklari projekte eder:

• lexical_control.compound_supersession_events
• lexical_control.compound_supersession_participants
• lexical_control.lexeme_supersession_events
• lexical_control.lexeme_supersession_participants
• provenance_control.lexical_curation_compensation_events

Compound olaylari replacement, split, merge, restructure ve retirement olabilir. Mevcut lexeme ledger’i replacement ve retirement uretir. Yeni bir domain kendiliginden bu sisteme dahil olmaz; yeni typed source bridge ve ayri inceleme gerekir.

Policy ve release

resolution_policies, traversal davranisini isimlendirir ve max_hops sinirini tutar. Ilk policy identity-preserving-current-v1dir.

resolution_releases, belirli bir anda hangi olaylarin etkin oldugunu degismez ve tam bir envanter olarak yayimlar. Child release, parent’in sirali curation kaynaklarini prefix olarak korur. Baglanan curation transaction’larinin desteklenen butun supersession olaylari release’te yer almak zorundadir; bir olayi listeden cikarmak onu sessizce tekrar etkin hale getiremez. Bir release su tablolara sahiptir:

Tablo	Gorev
resolution_release_curation_sources	Kabul edilmis curation release kaynaklarini sirali baglar.
resolution_release_events	Olayi effective veya invalidated olarak secer.
resolution_compound_event_sources	Generic kaydi gercek compound olayina typed FK ile baglar.
resolution_lexeme_event_sources	Generic kaydi gercek lexeme olayina typed FK ile baglar.

Her release curation envanteri, tum olay envanteri ve etkin grafik icin ayri SHA-256 root tutar. Root’lar kimlik uretmek icin degil, yayimlanan envanterin sonradan degismedigini kanitlamak icindir.

Compensation davranisi

Curation olaylari silinmez veya guncellenmez. Yanlis A -> B olayi duzeltildiginde A -> C olayi ve iki transaction arasinda compensation kaydi eklenir. Resolution release eski olayi invalidated, yenisini effective secer. Compensation transaction’i release’e bagli oldugu halde eski olay effective secilemez. Bir retirement geri alindiysa eski retirement, replacement event uydurulmadan terminal invalidated kaydi olarak tutulur ve current resolver entity’nin kendisini yeniden canli hedef olarak dondurur.

Eski domain modelindeki global outgoing/incoming unique indeksleri bu iki immutable olayin ayni anda saklanmasini engelliyordu. F9-003 bu indeksleri lookup indekslerine cevirir ve ayni kurali ertelenmis effective graph constraint’i olarak uygular:

• uncompensated olaylar arasinda entity basina en fazla bir outgoing event vardir;
• uncompensated olaylar arasinda entity basina en fazla bir incoming event vardir;
• etkin grafik dongusuzdur;
• normal ikinci supersession reddedilir;
• yalniz acikca onceki transaction’i compensate eden islem eski olayin yaninda duzeltilmis olayi ekleyebilir.

Dolayisiyla kural gevsetilmez. Tekillik, tarihceyi yok eden fiziksel satir seviyesinden release-effective grafik seviyesine tasinir.

Bir duzeltme tekrar duzeltilirse zincir korunur:

A -> B  invalidated, replaced by event 2
A -> C  invalidated, replaced by event 3
A -> D  effective

Current resolver path’i bu uc adimi eski kayittan etkin kayda dogru sirayla dondurur. Compensation zinciri de policy hop siniriyla sinirlidir.

Release dogrulamalari

publish_resolution_release_v1 yalniz immutable envanteri yayimlar. Deferred closure asagidaki hatalarda transaction’i reddeder:

• kaynak event veya typed bridge eksikse;
• event bagli curation release icinde degilse;
• predecessor/successor registry’de degilse ya da kind farkliysa;
• event kind ile katilimci sayisi uyusmuyorsa;
• invalidated event gercek compensation zincirine bagli degilse;
• duzeltme farkli predecessor kumesini sessizce hedefliyorsa;
• etkin outgoing veya incoming olaylar rekabet ediyorsa;
• grafik dongulu veya policy sinirindan uzunsa;
• saklanan inventory root’lardan biri yeniden hesaplanan degerden farkliysa.

Overlap veya “en son eklenen kazanir” davranisi yoktur. Belirsizlik hata ya da acikca set-valued sonuc olarak gorunur.

Resolver sonuclari

Current resolution dort durumdan birini verir:

Durum	Anlam
exact	Kaynak entity’nin etkin outgoing olayi yoktur; hedef kendisidir.
current	Traversal sonunda tek canli hedef vardir.
ambiguous	Split/restructure sonunda birden cok canli hedef vardir.
retired	Canli hedef yoktur ve yol retirement ile sonlanmistir.

target_entity_ids her zaman kume semantigindedir. Split, merge veya restructure sessizce tek UUID’ye indirgenmez. Bir split kolu sonradan retire olsa ve tek canli hedef kalsa sonuc current olabilir; tam path retirement kolunu yine tasir.

Her current cevap sunlari icerir:

• source_entity_id
• resolution_state
• target_entity_ids
• resolution_policy_id
• resolution_release_id
• sirali path (source_kind ile event ID birlikte olay kimligini belirtir)
• kaynak entity icin lifecycle

Path adiminda event ID, event kind, disposition, predecessor ve successor kumeleri ile reason code bulunur.

Public API

Public RPC’ler:

api_v1.get_entity_exact_v1(entity_kind, entity_id, deployment_id)
api_v1.resolve_entity_current_v1(
  entity_kind, entity_id, resolution_policy_id, deployment_id
)

API deployment’i reference_resolution_release_bindings araciligiyla tam bir policy ve resolution release’e pinlenir. Uygulama rolleri reference_control, lexical_control veya provenance_control tablolarina dogrudan erisemez; yalniz security-definer RPC’yi cagirir.

Yanlis veya deployment’ta bulunmayan policy resolution_policy_unavailable verir. Registry’de olmayan entity unavailable olur. Integrity hatalari tahmini bir hedef dondurmek yerine kapali hata durumuna gider.

API contract release v1.9, EntityResolution tipine policy ID, resolution release ID ve typed supersession path alanlarini ekler. Exact ve current endpointleri ayri operation revision’laridir.

Yayim akisi

Production akisi su sirayi izler:

1. Domain curation transaction’i yeni supersession olayini append eder.
2. Gerekliyse onceki transaction icin immutable compensation kaydi eklenir.
3. Kabul edilen transaction’lar bir curation release’e yayimlanir.
4. publish_resolution_release_v1 etkin ve invalidated olay envanterini kapatir.
5. prepare_reference_resolution_release_v1 mevcut API deployment’ini yeni resolution release ile v1.9 manifestine tasir. Ayni kaynak ve release ile retry ayni manifest kimligini dondurur; farkli icerik ayni kimlikle kabul edilmez.
6. activate_reference_resolution_deployment_v1 compare-and-swap ile deployment’i etkinlestirir.

Release veya deployment satirlari sonradan duzenlenmez. Yeni karar yeni release ve yeni deployment olarak yayimlanir.

Degisiklik yaparken

• Authored reference ID’lerini current hedefle overwrite etmeyin.
• Current lookup’u policy ID olmadan cagirmayin.
• Registry’ye kayitli olmayan katilimciyi resolution envanterine eklemeyin.
• Split/merge sonuclarini ilk elemana indirgemeyin.
• Compensation icin eski event’i silmeyin veya update etmeyin.
• Yeni kaynak domain’i generic JSON ile eklemeyin; typed FK bridge olusturun.

Odakli kontroller:

ruby scripts/api/generate_contracts.rb --check
ruby scripts/db/verify_reference_resolution.rb
MUNDERECAT_REFERENCE_RESOLUTION_LIVE=1 ruby tests/db/reference_resolution_test.rb

Canli fixture temiz PostgreSQL 17’ye migration’lari bir kez uygular. Corpus veya reader verisi yuklemeden exact, corrected replacement, retirement/restoration, split, wrong policy, eksik release tarihcesi, compensate edilmis eventi yeniden etkinlestirme, missing registry participant ve cycle davranislarini sentetik UUID’lerle dogrular.

Sonraki katmanlar

Bu model reference edge veya atif tablosu degildir. Sonraki F9 adimlari authored edge’in tarihsel target ID’sini saklayacak; okuma aninda kullanici tercihiyle exact veya current projection kullanacaktir. Occurrence traversal, cross-language gorunum ve frontend etkilesimleri ayni resolver sonucunu tuketebilir, fakat kimlik sahipligini veya bu release sinirini atlayamaz.