Yapısal annotation veri modeli

Yapısal annotation katmanı, canonical metni değiştirmeden metindeki bir yeri işaretler ve bu yere domain anlamı bağlar. Segment, heading ve haşiye aynı metin aralığını paylaşabilir; buna rağmen birbirinin alt türü değildir. Ortak olan yalnızca neresi seçildi sorusunun cevabıdır.

Normatif authority ayrımı annotation ER modelinde, koordinat sözleşmesi ADR-005’te, core sınırı ise ADR-001’de tanımlanır. Bu rehber mevcut fiziksel uygulamayı ve henüz materialize edilmemiş alanları birlikte, fakat açıkça ayırarak anlatır.

Zihinsel model

flowchart LR
  accTitle: Yapısal annotation veri akışı
  accDescr: Immutable core cümlesi ortak span ve selection geometrisine, bu geometri de birbirinden ayrı segment, heading ve note anlamlarına bağlanır.
  sentence[core sentence] --> span[text span]
  span --> selection[text selection]
  selection --> segment[segment assertion]
  span --> heading[heading marker]
  selection --> heading
  span --> marker[note marker]
  selection --> body[note body]
  marker --> note[note relation]
  body --> note

Model dört soruyu ayrı kayıtlarda cevaplar:

Soru	Authority	Örnek
Metnin neresi?	anchor_control	span, ordered selection
Bu seçim ne ifade ediyor?	Domain authority	segment, heading, note
Hangi sürümde yayımlandı?	Package/release	structural veya note release
Neye dayanıyor?	Contract, root ve provenance	manifest, crosswalk, evidence hash

Core; kitap, bölüm, paragraf, cümle, token occurrence, sıra, boşluk ve noktalamanın tek authority’sidir. Annotation satırı core metni kopyalayamaz, onarım amacıyla değiştiremez ve reconstruction için zorunlu hale gelemez.

Bugünkü gerçekleşme durumu

Katman	Durum	Mevcut authority
Shared span/selection	DB’de yayımlanmış	Private anchor_control şeması
Segment	DB’de yayımlanmış	16.986 immutable structural_control.segments kaydı
Segment parent graph	Doğrulanmış canonical rapor	2.610 geçerli edge; henüz DB relation değil
Heading	DB’de yayımlanabilir package	6.636 immutable structural_control.headings kaydı ve stable heading ID
Haşiye ve yıldızlı not	DB’de yayımlanmış	353 immutable note_control.notes kaydı ve bir explicit source gap
Public reader API	Heading için yayımlandı	Release-pinned api_v1.get_chapter_headings_v1; note reader private

Heading publication package’ı final domain kimliklerini ve hiyerarşiyi taşır. Accepted projection yalnız kaynak girdisidir; uygulama ve atıf katmanı final heading_id ile public RPC çıktısını tüketmelidir. Compact TOC görünürlük politikası ise bilinçli olarak sonraya bırakılmıştır.

Ortak anchor omurgası

anchor_control.text_spans, exact reconstructed tek bir cümledeki boş olmayan [start_scalar, end_scalar) aralığını tutar. Koordinat profili unicode-scalar-half-open-v1dir: Unicode scalar sayılır, normalization yapılmaz ve source text canonical cümle reconstruction’ıdır.

Bir span şu facts ile doğrulanır:

• core_release_id, core_root_sha256, text_version_id ve sentence_id aynı immutable lineage’a aittir.
• selected_scalar_count, başlangıç ve bitiş farkına eşittir.
• Exact excerpt byte uzunluğu ve SHA-256 witness’ı yeniden hesaplanır.
• Aralık occurrence body sınırlarına tam uyuyorsa ilk/son token_occurrence witness’ları taşınır. Kapsanan occurrence’ların tamamı form ise token_body_range, arada literal occurrence varsa occurrence_body_range kullanılır. Body sınırlarına tam uymayan aralık scalardır ve occurrence witness’ı taşımaz. Her span sağlayabildiği en güçlü sınıfı ilan eder.
• Aynı release, profil, cümle ve aralık tek canonical span ID’sini paylaşır.

anchor_control.text_selections, bir veya daha fazla span’ı source order ile birleştirir. Üyeler aynı core release ve text version içinde bulunur; pozisyonları 0..n-1 kesintisizdir. Duplicate ve overlap yasaktır. Aynı cümlede birbirine değen span’lar yeni selection çıkarılmadan önce coalesce edilmelidir.

Span ve selection geometri authority’sidir; segment, heading veya note gibi semantic tür taşımaz. İki domain kaydı aynı span/selection ID’sini güvenle reuse edebilir.

Kimlik ve yayın yaşam döngüsü

Her entity kind veya curated dataset, ilk public kimliğinden önce iki immutable issuance kanalından birini seçer. Canonical reproducible package içindeki package_deterministic entity UUIDv5; interactive curation_generated entity ise server-generated UUIDv7 alır. Bir entity ilk kimliğinden sonra kanal değiştirmez; sonraki package mevcut UUIDv7’yi UUIDv5 olarak yeniden basamaz.

Shared anchor registry bu genel kuralın kendi yaşam döngüsünü uygular. Her core release için tek deterministic bootstrap penceresinde yeni canonical anchor’lar UUIDv5 alır. Bootstrap kapandıktan sonra yeni anchor UUIDv7 alır; fakat aynı canonical geometry daha önce kayıtlıysa mevcut ID ve issuance kanalı her zaman reuse edilir. Bir package kimliğini rastgele UUID ile veya metin aramasıyla yeniden üretmek yasaktır.

Her domain yayını exact dataset contract’ına, core release/root’a, coordinate profile’a, shared anchor identity release’e ve ordered inventory root’larına bağlanır. Publisher bu facts’i PostgreSQL içinde tekrar hesaplamadan görünür release oluşturmaz. Yayımlanan anchor, segment ve note satırları update/delete/ truncate rejection trigger’larıyla immutable’dır.

Kimliği koruyan ve değiştiren düzeltmeler ayrılmalıdır. Provenance, review evidence, confidence, lifecycle state ve temsil edilen değeri değiştirmeyen display label düzeltmeleri aynı ID’yi korur ve append-only curation/control event’i ekler. Core release, selected span, parent, ordered members veya domain kaydının neyi ifade ettiği gibi identity-bearing facts değişirse yeni successor entity/occurrence ve typed supersession gerekir; eski ID çözülebilir kalır. Bir domain düzeltmesi, başka annotation’ların da kullandığı geçerli shared span’ı global olarak supersede etmez; anchor lifecycle ancak geometrinin kendi identity-bearing facts’inde kusur varsa değişir. Böylece annotation’a verilen atıflar sessizce başka anlama kaymaz.

Segmentler

Bir segment, bir exact text_selection üzerinde duran yapısal assertion’dır. structural_control.segments domain kimliğini, kind’ı, selection’ı ve structural release’i bağlar; source metnini tekrar saklamaz.

Bugünkü accepted package’ta:

• 16.986 segment assertion’ı vardır.
• Bunlar 16.718 distinct span/selection geometrisini paylaşır.
• Aynı sınırdaki 225 duplicate grup silinmez; geometry ortak olsa da source assertion kimlikleri ayrıdır.
• Her legacy token sınırı typed sentence/token crosswalk ile canonical occurrence’a bağlanmıştır; normalized text veya first-match kullanılmaz.
• 2.610 parent edge’in tamamı parent containment, aynı cümle ve cycle kurallarını geçmiştir. Bu graph şimdilik doğrulanmış canonical rapordur, DB relation değildir.

legacy_segment_crosswalk migration bridge ve provenance evidence’ıdır. Yeni uygulama kodu legacy ID’yi domain kimliği gibi kullanmamalıdır.

Headingler

Heading pipeline’ı marker gözlemi, hierarchy evidence ve semantic kabulü ayrı tutar. 6.782 gözlemden 6.636’sı semantic heading olarak kabul edilmiştir. Exact formal haşiye etiketleri olan 146 kayıt silinmemiş, note pipeline’ına yönlendirilmiştir.

Accepted heading projection her satır için marker span’ını, accepted parent’ı, depth’i ve coverage boundary’yi taşır. Parent en yakın önceki daha düşük yapısal seviyedir; coverage ilk sonraki aynı veya daha yüksek rank marker’ında, yoksa chapter sonunda biter. Rejected marker’lar çıkarıldıktan sonra parent ve coverage yeniden hesaplanmıştır; observational forest doğrudan filtrelenmemiştir.

publication-v1 her accepted satıra deterministic UUIDv5 heading_id verir. Kimlik; dataset identity key’i, source_marker türü ve exact shared marker_span_id üzerinden türetilir; gösterim metni, audit evidence veya array sırası kimliği belirlemez. Package aynı DB’ye tekrar uygulandığında idempotenttir, aynı kimlikte farklı içerik görürse başarısız olur.

DB’de heading_releases exact core/shared-anchor/projection root’larını, headings ise marker span, parent, coverage boundary, chapter order, level ve depth’i tutar. Exact başlık metni ikinci kez saklanmaz; reader canonical cümleden [start_scalar, end_scalar) aralığını reconstruct eder. Yayımlanmış kayıtlar immutable’dır.

Public chapter projection’ı şöyledir:

select api_v1.get_chapter_headings_v1(
  jsonb_build_object('chapter_id', :chapter_id),
  :api_deployment_id
);

Yanıt exact deployment içindeki core ve heading release’lerine pinlenir; stable ID, parent, level, depth, sentence/span koordinatı ve source order döndürür. Reader bu listeyi hiyerarşik içindekiler olarak gösterir ve mevcut cümlenin başına sıfır genişlikli bir fragment anchor koyar. Chapter metni heading’lerden reconstruct edilmez ve Latin/Osmanlıca çıktı değişmez. Heading API kullanılamazsa yalnız TOC kapanır; canonical metin okuyucusu çalışmaya devam eder.

Haşiye ve yıldızlı notlar

note_control iki closed note type yayımlar: formal_hasiye ve starred_note. Bir note bir veya daha fazla ordered marker span’ına ve bir veya daha fazla ordered body selection’ına bağlanabilir:

• notes: note occurrence ve pairing rule,
• note_markers: ordered marker span’ları,
• note_bodies: ordered body selection’ları,
• note_coverage_gaps: metinde marker bulunup kaynakta body bulunmayan explicit istisnalar.

Accepted package 353 note relation, 354 marker observation ve 353 body observation içerir. Tek unmatched marker source_gap olarak kayıtlıdır; sahte body veya note ID üretilmemiştir. Body birden fazla cümleye yayılabilir ve ordered selection olarak tutulur. Prose note tablosuna kopyalanmaz; private reader metni canonical core ile shared anchor’lardan reconstruct eder.

Chapter düzeyindeki authority-içi okuma yüzeyi:

select * from note_control.list_chapter_notes_v2(
  :note_release_id,
  :chapter_id
);

Bu fonksiyon public değildir ve yalnız API owner tarafından çağrılır. Public API v1.6 yüzeyi şöyledir:

select api_v1.get_chapter_notes_v1(:chapter_id, :api_deployment_id);

Deployment aynı core, Osmanlıca, lexical, heading ve note release tuple’ını birlikte pinler. Public yanıt stable note ID, note type/status, ordered marker koordinatları ve ordered body selection/span metinlerini döndürür. Source path, satır numarası, evidence key ve row hash private kalır. source_gap satırında note ID ve body yoktur.

Reader marker aralıklarını canonical cümlenin Unicode-scalar koordinatlarıyla tekrar doğrular. Latin marker exact scalar slice olarak ayrılır. Osmanlıca gösterimde marker bir dönüşmüş render unit’ini yalnız tam sınırlarıyla kapsayabilir; birimin içinden kesmeye çalışan release aktivasyon sırasında reddedilir. Marker bir term hover ile çakışırsa note interaction o kaynak biriminin tek sahibi olur; nested button veya iki ayrı popup üretilmez. Render parçaları oluşturulduktan sonra Latin ve Osmanlıca concatenation yeniden validated reconstruction ile eşitlenir. Note API veya association başarısız olursa yalnız note etkileşimi kapanır, canonical chapter reader çalışır.

Güvenli geliştirme akışı

1. Önce semantic domain kaydını belirleyin; span’a domain anlamı eklemeyin.
2. Exact reconstructed cümlede Unicode-scalar aralığını çıkarın.
3. Mevcut canonical geometry varsa aynı anchor’ı reuse edin; yoksa yalnız yetkili issuance fonksiyonunu kullanın.
4. Çok parçalı ifadeyi ordered selection olarak kurun ve touching üyeleri coalesce edin.
5. Domain assertion’ını typed FK ile span/selection’a bağlayın.
6. Exact contract, root ve provenance closure doğrulanmadan release yayımlamayın.
7. Core fingerprint değişirse annotation importunu başarısız sayın; core’u annotation sonucuna uydurmayın.

Bir geliştirici değişiklikten sonra yalnız etkilediği yüzeyi doğrulamalıdır:

make text-anchor-schema-check
make structural-segments-check
make note-reader-check
make note-panel-check
make annotation-core-equality-check

İlk üç komut ilgili statik/sample sözleşmeleri sınar. Son komut retained eşitlik sertifikasını ve verifier sözleşmesini statik olarak kontrol eder; 1,9 milyon satırlık full disposable importu tekrar çalıştırmaz. Full corpus doğrulaması ancak core importer, immutable relation seti veya annotation publication contract’ı değişirse yeniden gereklidir.

Heading publication ve reader için focused kontroller şöyledir:

make heading-publication-check
make heading-reader-check
MUNDERECAT_HEADING_READER_LIVE=1 ruby -w tests/db/heading_reader_test.rb

İlk komut 6.636 satırlık package’ın deterministic kimlik/root sözleşmesini, ikinci komut migration ve importer yüzeyini kontrol eder. Son komut küçük disposable DB fixture’ında public RPC, release pinning ve core/Osmanlıca/hover değişmezliğini doğrular. Full runtime importu MUNDERECAT_HEADING_READER_CONTAINER ile yalnız yeni Münderecat runtime DB’sine uygulanır; legacy/source DB hedef değildir.

Public note release binding için focused canlı fixture:

MUNDERECAT_NOTE_PANEL_LIVE=1 ruby -w tests/db/note_panel_test.rb

Bu fixture iki exact marker ile mapped note/source-gap davranışını, yedi operasyonlu API deployment’ını, private alan izolasyonunu ve mevcut occurrence reader’ın v1.6’da çalışmayı sürdürdüğünü sınar. Accepted 353 ilişkiyi yeniden parse veya import etmez.

Bir failure’da metni veya accepted ID’leri elle düzeltmeyin. Hatanın geometry, domain assertion, package authority, source evidence ya da reader projection katmanlarından hangisinde olduğunu ayırın; düzeltmeyi o authority’nin yeni release/curation akışında yapın.