Referenceable Entity Catalog

Bu belge gelecekteki atıf ağının doğrudan source veya target endpoint’i olabilecek entity kind’lerini kapalı bir katalog olarak tanımlar. Katalog ADR-002’deki public kimliği, ER-001’deki core sahipliğini ve ER-002’deki annotation sahipliğini değiştirmez.

Referenceable burada “generic semantic reference edge’inin endpoint’i olabilir” demektir. Bir kaydın UUID taşıması, typed API’de addressable olması, aramada bulunması, metin olarak embed edilmesi veya provenance assertion’ına target olması tek başına referenceable olduğu anlamına gelmez.

Karar özeti

Münderecat kapalı bir reference_kind allowlist’i ve downstream REFERENCEABLE_ENTITY registry’si kullanacaktır. Registry yeni kimlik üretmez: entity_id, authoritative owner kaydının mevcut globally unique public UUID’sidir. Her aktif kind’in ayrı typed bridge’i registry kimliğini gerçek owner tablosuna FK ile kanıtlar. Declared fakat henüz owner’ı yayımlanmamış kind registry satırı veya bridge alamaz. Core ve annotation owner tabloları registry’ye geri FK taşımaz.

Bu desen gelecekte tek REFERENCE_EDGE(source_entity_id, target_entity_id) üzerinde gerçek endpoint FK’leri kurulmasına izin verir; fakat serbest table_name + record_id, unchecked UUID veya runtime kind eklenmesine izin vermez. Relation vocabulary ve kind-pair matrisi F9’da ayrıca kapatılacaktır.

Capability ayrımı

Capability	Anlamı	Bu katalogla ilişkisi
Exact addressability	Typed route ile tarihsel ID’yi çözmek	Referenceable olmayan accepted claim/release’lerde de olabilir
Semantic referenceability	Future reference edge source/target’ı olmak	Yalnız aşağıdaki 28 declared kind; registry üyeliği yalnız active owner’larda
Searchability	Query/index sonucu olarak bulunmak	Derived index policy’sidir; kimlik veya authority değildir
Embeddability	Exact metin/rendering sunabilmek	Core/anchor join ve API policy gerektirir; her endpoint için geçerli değildir
Provenance targetability	Typed evidence/assertion target’ı olmak	ADR-006/F2-019 catalog’u semantic catalog’dan daha geniş olabilir
Public visibility	İstek yapan role ve release’e göre açıklanmak	Registry üyeliğinden ayrıca fail-closed hesaplanır

Bir UI bu capability’ler arasında fallback yapamaz. Örneğin addressable bir FORM_ANALYSIS, v1 semantic reference endpoint’i değildir; bir TOKEN_OCCURRENCE search sonucu olması da onun current lexeme analizini identity fact yapmaz.

Endpoint modeli

erDiagram
  accTitle: Closed referenceable entity registry
  accDescr: Existing public entity UUID is registered once. A kind-specific bridge proves the authoritative owner with a real foreign key. Future edges point only to the closed registry.

  REFERENCE_KIND_SPEC ||--o{ REFERENCEABLE_ENTITY : classifies
  REFERENCEABLE_ENTITY ||--|| TYPED_OWNER_BRIDGE : proven_by_exactly_one
  AUTHORITATIVE_OWNER ||--|| TYPED_OWNER_BRIDGE : owns_same_uuid
  REFERENCEABLE_ENTITY ||--o{ REFERENCE_EDGE : source
  REFERENCEABLE_ENTITY ||--o{ REFERENCE_EDGE : target

  REFERENCEABLE_ENTITY {
    uuid entity_id PK
    text kind_key
    text identity_profile
    uuid registration_transaction_id
  }

  TYPED_OWNER_BRIDGE {
    uuid entity_id PK, FK
    uuid owner_id UK, FK
  }

  REFERENCE_EDGE {
    uuid id PK
    uuid source_entity_id FK
    uuid target_entity_id FK
    text relation_kind
  }

TYPED_OWNER_BRIDGE tek polymorphic tablo değildir; diyagram her active kind için ayrı bridge tablosunun mantıksal kısaltmasıdır. Güncel migration katalogunda bu sayı 27’dir; reserved repeat_family owner kazanmadan bridge alamaz. İsim kuralı reference_<kind_key>(entity_id) olur. Tek kolon hem REFERENCEABLE_ENTITY.entity_id hem ilgili authoritative owner id kolonuna FK olur; bu nedenle entity_id = owner_id yapısaldır ve ikinci public UUID yoktur.

REFERENCE_KIND_SPEC runtime-editable authority tablosu değildir. Aşağıdaki kapalı setten migration sırasında üretilen enum/check ve generated code manifestidir. Yeni kind eklemek katalog değişikliği, reviewed migration, bridge, API type ve policy fixture’ı gerektirir. Production kullanıcısı registry, kind spec veya bridge’e doğrudan INSERT yapamaz.

Bir registry satırı ancak tam bir typed bridge’e sahipse geçerlidir; aynı UUID başka bridge’de bulunamaz. Deferred publication gate, yeni veya değişen registry satırları için tam olarak bir bridge ve bridge’in declared kind ile eşleşmesini doğrular. Future edge’in iki endpoint’i de registry FK’si taşır; relation kind’in izin verdiği source/target kind çifti ayrıca kapalı F9 matrisiyle kontrol edilir.

Doğrudan referenceable kind’ler

Kimlik profilleri: C yalnız accepted core package UUIDv5; A bootstrap anchor UUIDv5 veya bootstrap sonrasında registry UUIDv7; D version-controlled domain package UUIDv5 veya sonradan curation UUIDv7. Bir entity ilk issuance channel’ını ömür boyu korur.

Endpoint rolü both, kind’in generic edge’in iki ucunda da teknik olarak yer alabileceğini söyler. Belirli relation kind’lerin daha dar yön ve kind-pair kuralları F9’da zorunludur.

Machine-readable fiziksel bağ config/referenceable-entity-catalog.yml dosyasındadır. Bu manifest 28 declared kind’i korur; 27 active owner relation’ını ve bir reserved_unpublished kind’i migration kataloğuna bağlar. Her active kind ayrıca owner’dan yayın otoritesine giden ordered kolon/FK profilini taşır. F9-002 relation, üyelik yolu, yayın anahtarı veya satır eligibility koşulunu isim kuralından, information_schema içeriğinden ya da runtime satırlarından tahmin edemez.

kind_key	Authoritative owner	Sınıf	ID	Endpoint	Yayın kapısı
work	WORK	logical corpus	C	both	accepted core inventory
text_version	TEXT_VERSION	immutable text snapshot	C	both	accepted core membership ve closure
book	BOOK	core occurrence	C	both	accepted core release
chapter	CHAPTER	core occurrence	C	both	accepted core release
paragraph	PARAGRAPH	core occurrence	C	both	accepted core release
sentence_occurrence	SENTENCE	core occurrence	C	both	accepted core release
token_form	TOKEN_FORM	exact scoped value	C	both	accepted core release ve used-form closure
token_occurrence	TOKEN_OCCURRENCE	core occurrence	C	both	accepted core release
text_span	TEXT_SPAN	geometry anchor	A	both	accepted anchor/core binding
text_selection	TEXT_SELECTION	ordered geometry anchor	A	both	accepted anchor/core binding
heading	HEADING	structural occurrence	D	both	structural component release
segment	SEGMENT	structural occurrence	D	both	structural component release
note	NOTE	structural occurrence	D	both	structural component release
compound_entry	COMPOUND_ENTRY	semantic definition	D	both	lexical authority release
compound_variant	COMPOUND_VARIANT	semantic surface variant	D	both	lexical authority release
compound_occurrence	COMPOUND_OCCURRENCE	occurrence assertion	D	both	lexical occurrence release
lexeme	LEXEME	semantic definition	D	both	lexical authority release
lexeme_form	LEXEME_FORM	linguistic surface form	D	both	lexical authority release
lexical_root	LEXICAL_ROOT	linguistic authority	D	both	lexical authority release
dictionary_entry	DICTIONARY_ENTRY	dictionary authority	D	both	lexical/dictionary authority release
dictionary_sense	DICTIONARY_SENSE	sense authority	D	both	lexical/dictionary authority release
orthographic_form	ORTHOGRAPHIC_FORM	Ottoman form authority	D	both	Ottoman authority release
rendering_occurrence	PUBLISHED_READER_OCCURRENCE	rendering assertion	D	both	compact Ottoman reader release
passage_occurrence	PASSAGE_OCCURRENCE	repetition occurrence	D	both	repetition release
exact_class	EXACT_CLASS	certified exact group	D	both	repetition release
repeat_family	reserved; owner yok	reviewed semantic group	D	both	unpublished; registry/edge yasak
alignment_unit	ALIGNMENT_UNIT	language-side occurrence	D	both	alignment release ve scope coverage
alignment_group	ALIGNMENT_GROUP	bipartite correspondence	D	both	alignment release ve complete coverage

Bu tablo declared kind seti için exhaustive’dir. repeat_family wire vocabulary ve gelecek semantic model için ayrılmıştır; accepted owner/publication tablosu olmadığı için bugün referenceable entity kaydı değildir. Kalan 27 kind active’dir. Bir fiziksel tablo veya logical entity adı burada yoksa v1 generic semantic reference endpoint’i değildir. Benzer bir yeni entity mevcut kind key’iyle kaydedilemez; katalog ve kind-pair sözleşmesi successor migration ile genişletilir.

Production Ottoman reader’ın authoritative occurrence kimliği ottoman_control.published_reader_occurrences.id değeridir. Eski ottoman_control.rendering_occurrences generic fixture/shared-span yaşam döngüsünü korur; compact production reader authority’sinin yerine geçmez ve F9 bridge’i alamaz. Bu owner içindeki yalnız reader_status = 'canonical' ve pattern_output_id is not null koşullarını birlikte sağlayan satırlar rendering_occurrence eligibility profile’ını sağlar. machine_fallback, passthrough, unmapped ve source-Arabic reader satırları bu semantic kind altında kaydedilmez. Benzer şekilde repetition_control.repeat_candidates, reviewed family owner’ı gibi yorumlanamaz.

Compact publication migration’ı bu owner UUID’sini semantic katalogdan önce ottoman_published_reader_occurrence identity discriminator’ıyla basmıştır. Katalog bunu yeni bir UUID üretmeden rendering_occurrence semantic kind’ine projekte eder: typed bridge aynı owner id değerini taşır ve manifestte identity_projection = preserve_owner_uuid_v1 açıkça kayıtlıdır. Bu istisna discriminator’ı geriye dönük değiştirmenin veya ikinci bir public kimlik basmanın gerekçesi değildir.

Kimlik path profilleri

Her UUIDv5 payload’ı ADR-002’nin exact {identity_schema, kind, path} envelope’unu kullanır. Yeni issuance’larda kind yukarıdaki machine key’dir ve path içinde tekrar edilmez. Yukarıda kaydedilen compact Ottoman projection’ı mevcut owner discriminator’ını ve UUID’sini koruyan tek v1 istisnasıdır. Bütün stringler NFC, UUID’ler lowercase canonical text ve integer’lar safe non-negative JSON integer’dır.

Profil	Package UUIDv5 path şeması	İlave kural
C-work-v1	[identity_release_key, source_work_locator]	Locator source manifestte unique ve immutable’dır
C-version-v1	[identity_release_key, work_id, source_version_locator]	Dil/edisyon locator’ın versioned sözleşmesindedir
C-child-v1	[identity_release_key, parent_id, source_position]	Book, chapter, paragraph ve sentence için parent/position identity fact’tir
C-token-occurrence-v1	[identity_release_key, sentence_id, source_position]	Boundary/body closure permanent claim ile bağlanır
C-token-form-v1	[identity_release_key, text_version_id, first_source_sentence_id, first_source_position]	Display text veya legacy token ID path input’u değildir
A-span-v1	[identity_release_key, coordinate_profile_id, core_release_id, sentence_id, start_scalar, end_scalar]	ADR-005 canonical coordinate key’idir
A-selection-v1	[identity_release_key, coordinate_profile_id, core_release_id, "members", member_span_id...]	Exact ordered canonical member setidir
D-record-v1	[identity_release_key, domain_dataset_key, record_coordinate]	Definition, variant, form, sense ve group record coordinate’i pre-publication manifestte kalıcıdır
D-occurrence-v1	[identity_release_key, domain_dataset_key, occurrence_coordinate]	Bound owner/anchor/member facts ayrıca permanent row claim ile doğrulanır

C-child-v1 katalogda book, chapter, paragraph ve sentence_occurrence; D-record-v1 domain definition/value/group kind’leri; D-occurrence-v1 heading, segment, note, compound/rendering/passage occurrence ve alignment unit/group kayıtları için kullanılır. Exact per-kind path profile ID ve manifest root package contract’ında yazılır.

Package dışı accepted curation entity’si UUIDv7 alır. UUIDv7 value’su yeniden hesaplanmaz; aynı entity sonradan package’a girerse stored ID korunur. Registry hangi channel’ın kullanıldığını owner’ın permanent identity claim’inden doğrular, UUID versiyonuna bakarak authority tahmin etmez.

Referenceable olmayan closed sınıflar

Aşağıdaki sınıflar ER-001 ve ER-002’de kalan logical entity’leri exhaustive olarak kapsar. Bunlar gerektiğinde typed API veya provenance üzerinden addressable olabilir; generic semantic registry’ye girmez.

Release ve publication context

CORE_RELEASE, ANNOTATION_RELEASE, STRUCTURAL_RELEASE, LEXICAL_RELEASE, OTTOMAN_RELEASE, REPETITION_RELEASE, ALIGNMENT_RELEASE ve CURATION_RELEASE exact context olarak addressable olabilir. Bunlar semantic metin veya kavram değildir; future edge endpoint’i yerine ilgili referansın release binding ve policy alanında taşınır.

Membership, order ve composition

RELEASE_TEXT_VERSION, TEXT_SELECTION_MEMBER, CORE_RELEASE_BINDING, CURATION_RELEASE_TRANSACTION, NOTE_MARKER, NOTE_BODY, COMPOUND_MEMBER_ROLE, COMPOUND_CHILD, EXACT_CLASS_MEMBER, FAMILY_OCCURRENCE_MEMBER, FAMILY_EXACT_CLASS_MEMBER, SCOPE_ATOM, SCOPE_ATOM_UNIT, SCOPE_UNIT, GROUP_SOURCE_MEMBER, GROUP_TARGET_MEMBER, ALIGNMENT_ORDER, ALIGNMENT_ORDER_MEMBER ve PATTERN_EVIDENCE owner kapanımının parçalarıdır. Bağımsız referent gibi kullanılırlarsa parent/member invariant’ı atlanır. Endpoint olarak parent authority veya member entity seçilir.

Contract, type, profile ve policy

TOKENIZATION_PROFILE, coordinate profile, HEADING_KIND, SEGMENT_KIND, NOTE_TYPE, DICTIONARY_SOURCE, DISPLAY_STYLE_RULE, REPETITION_PROFILE, ALIGNMENT_PROFILE ve PROPAGATION_POLICY versioned contract/config authority’dir. Contract API’sinde addressable olabilir; semantic graph entity’si değildir.

Accepted claim ve relation kayıtları

SEGMENT_RELATION, LEXEME_ROOT_ASSERTION, FORM_ANALYSIS, LEXEME_SENSE_LINK, COMPOUND_SENSE_LINK, TOKEN_SENSE_SELECTION, COMPOUND_SENSE_SELECTION, MAPPING_PATTERN, PATTERN_OUTPUT, QUOTATION_RELATION, EXACT_CLASS_CHOICE, REPEAT_FAMILY_CHOICE, ALIGNMENT_SCOPE ve PASSAGE_DIFF typed domain claim/evidence olarak exact ID ile addressable olabilir. V1 graph edge’inin başka bir edge/claim’i endpoint yapması yasaktır; relation’ın participant entity’leri doğrudan referenceable’dır. Bir claim’i semantic endpoint yapma ihtiyacı kanıtlanırsa kind katalog migration’ıyla açıkça promote edilir.

Curation, candidate ve provenance control

CURATION_PROPOSAL, CURATION_ACTION, CURATION_REVIEW, CURATION_DECISION, CURATION_TRANSACTION, domain candidate envelope/detail kayıtları, PROVENANCE_MANIFEST, PROVENANCE_ASSERTION ve ADR-006 source/artifact/record/run node’ları semantic endpoint değildir. Bunların typed audit ve provenance graph’ı ayrıdır; erişim hakları semantic public allowlist’ten türetilmez.

Projection ve cache

EFFECTIVE_SPAN_RENDERING, derived span/token member tabloları, current resolver projection’ları, search documents, frequency/group indexes ve hover/read caches hiçbir zaman public identity veya reference endpoint taşımaz. Rebuild aynı semantic edge’i başka cache satırına yönlendiremez.

Publication ve lifecycle

1. Active authoritative entity ve identity claim önce kendi sealed domain kurallarıyla doğrulanır. Reserved kind owner ve accepted publication kazanmadan registry’ye giremez.
2. Aynı publication transaction’ı statik kind’i, typed owner bridge FK’sini, owner ID ile registry ID eşitliğini ve accepted release görünürlüğünü doğrular.
3. Registry satırı, bridge ve public visibility birbirinden kopuk kısmi durumda yayımlanamaz. Domain publication olmuş fakat registration başarısızsa entity semantic API allowlist’inde görünmez ve release gate başarısız sayılır.
4. Bir kez public olmuş registry satırı silinmez, kind’i veya entity ID’si değiştirilmez. Supersession eski endpoint’i rewrite etmez.
5. Pre-publication rejected candidate registry’ye girmez. Daha önce public olmuş ve sonra retired/superseded/invalidated edilen endpoint historical exact lookup ve eski edge’ler için kalır; yeni edge authoring policy’si onu fail-closed reddedebilir.
6. Exact-ID resolution client’ın verdiği (kind_key, entity_id, release/policy) bağını kontrol eder. Kind mismatch, unavailable ve unauthorized sonuçları ADR-010 disclosure policy’sine göre ayrılır; server kind’i UUID’den tahmin etmez.
7. Current resolution yalnız typed same-kind supersession graph’ını explicit policy ile izler. Alignment, repeat canonical choice, lexeme/root veya translation ilişkisi reference target’ı sessizce değiştiremez.

Registry core reconstruction girdisi değildir. Registry, bridge ve bütün future reference tabloları silindiğinde ER-001 byte reconstruction ve root’ları aynı kalmalıdır. Owner correction registry satırını update etmek yerine ADR-002 successor entity ve gerektiğinde ayrı edge migration proposal’ı üretir.

Capability uygulama kuralları

• kind_key + entity_id public wire identity’sidir; URL veya API yalnız UUID’den tablo/kind keşfetmez.
• referenceable olmak public görünürlük vermez. API contract version, accepted release pin, request role, RLS ve policy sonucu ayrıca geçmelidir.
• Search index yalnız registry’de görünür entity ID’lerini taşıyabilir, fakat ranking, normalized key veya document ID reference authority olamaz.
• Embedding exact core/anchor text istiyorsa bound core release üzerinden reconstruct eder. Domain label’i kaynak excerpt yerine geçmez.
• Provenance assertions semantic registry ID’sini typed target olarak kullanabilir; registry dışındaki control hedefleri ADR-006/F2-019’un ayrı typed endpoint catalog’unda kalır.
• Same-form, same-lexeme, same-root, compound membership, repeat ve alignment sorguları ayrı typed ilişkiler kullanır; generic reference edge bu ilişkileri kendiliğinden üretmez.

Zorunlu enforcement kapıları

F3/F9 uygulaması aşağıdakileri executable fixture ve migration kontrolleriyle kanıtlamalıdır:

1. Catalog enum/set’i yukarıdaki 28 machine key ile exact eşleşir; 27 active ve bir reserved_unpublished readiness durumu korunur. Unknown/runtime-created kind ile reserved kind için registry satırı reddedilir.
2. Registry UUID’si owner UUID’siyle aynıdır ve globally unique’dir; bridge ikinci public identity üretemez.
3. Her registry satırının tam bir declared typed bridge’i, her bridge’in gerçek owner FK’si vardır; zero, duplicate veya wrong-kind bridge publication’ı durdurur.
4. Owner tablolarında registry/reference FK’si yoktur ve registry olmadan core reconstruction aynı digest’i verir.
5. Yalnız accepted, release-bound entity atomik registration alır; partial owner/bridge/registry/visibility state görünmez.
6. Registry ve bridge accepted publication sonrasında update/delete/truncate edilemez; historical endpoint supersession sonrasında çözülür.
7. Future edge source/target kolonları registry FK’si taşır; kind-pair validator relation vocabulary’deki closed matrix dışında fail eder.
8. Exact lookup kind mismatch, retired, superseded, unavailable, unauthorized ve integrity error durumlarını birbirine veya not found sonucuna sessizce çevirmez.
9. Package UUIDv5 fixture’ları profile path’lerini iki fresh build’de exact üretir; curation UUIDv7 ve preserved imported ID kanalları karışmaz.
10. Her excluded ER entity’si ya yukarıdaki closed sınıflardan birine düşer ya da katalog değişikliği olmadan schema gate’ini geçemez.

Reddedilen alternatifler

Serbest table name ve record ID

FK, kind allowlist’i, RLS planı ve migration rename güvenliği sağlamaz. ADR-002 ve ADR-006 ile doğrudan çelişir.

Owner tablolarının generic registry’ye FK vermesi

Core’u downstream reference katmanına bağımlı yapar ve annotation/reference yokken reconstruction şartını bozar.

Her relation kind için bütün entity-pair tabloları

Endpoint güvenliği güçlü olsa da kind sayısı büyüdükçe fiziksel tablo patlaması yaratır. Seçilen model endpoint’i typed bridge ile kanıtlar; relation-specific kind-pair kurallarını kapalı validator/generate edilmiş constraint ile korur.

UUID global olduğu için kind’i kaldırmak

Client’ın semantic type’ı tahmin etmesine, wrong-kind lookup’a ve policy bypass’a yol açar. Public işlemler UUID ile birlikte machine kind ister ve kind’i response’ta döndürür.

Sonraki işler

• F2-014 bu katalogdaki owner, bridge, registry ve future edge tablolarına permanence sınıfı atar.
• F2-015 katalog ve iki ER belgesini docs navigation’da yayımlar.
• F2-016 machine kind’lerle kullanıcı/geliştirici terimlerini canonical glossary’de eşler.
• F2-018 kind ekleme veya identity/path değişikliğinin compatibility sınıfını ve iki-kisi onayını makinece tanımlar.
• F2-019 provenance için semantic catalog’dan ayrı typed control endpoint setini tamamlar.
• F9 relation vocabulary, allowed kind-pair/direction matrisi, edge identity, traversal ve curation akışını bu registry üzerine kurar.