Toplumsal sözleşmeler
Aggrega, tasarımı gereği kendi görüşü olmayan bir derleyicidir. architecture/05-invariants.md adresinde belgelenen temel değişmezlere göre derleyici YAML’ı ayrıştırır, grafları dolaşır, etiket kesişimlerini değerlendirir ve bileşenler arasında dizeleri aktarır; ancak geliştiricilerin values, parameters, infra, provides veya locals içine ne koyduğunu denetlemez; adlandırma uzlaşımlarını, port uzlaşımlarını ya da bir Architect’in icat ettiği anlamsal etiketleri zorunlu kılmaz; bileşenin amacını adından tahmin etmez. Derleyici kuralı gibi görünen pek çok disiplin aslında toplumsal sözleşmelerdir: şema veya çalışma zamanı denetimiyle değil, yazım uzlaşımıyla sürdürülen en iyi uygulamalar.
Bu tarafsızlığın nerede bittiğini açıkça söylemek gerekir, çünkü bu tek bir çizgidir ve gereğinden fazla anlam yüklemek kolaydır. Birkaç anahtar Aggrega’nın kendisine aittir; ayrılmıştır ve alabileceği değerler yayımlanan şemaya yazılmıştır. Şema bunları, bildirilen diğer her alanı denetlediği gibi denetler. Platformun kendisinin tanımladığı bir anahtarın değer kümesini bildirmek, derleyicinin sizin yazdığınıza anlam yüklemesi değildir; platformun kendi anahtarının ne anlama geldiğini söylemesidir. Kendi anahtarlarınızdan biri altında yazdığınız her şey, bu sayfanın anlattığı gibi tamamen denetimsiz kalır.
Bu sayfa, dilin toplumsal sözleşmelerinin kanonik envanteridir. Sözleşmeleri bu sayfadan öğrenen yazarlar, derleyicinin uzlaşıma göre hatalı bir derlemeyi neden kabul ettiğini (kabul eder; derleyici uzlaşımı yorumlamaz) ve ihlali yakalama sorumluluğunun nerede olduğunu (yazım disiplini, gözden geçirenin dikkati veya aggrega lint tarafından çalıştırılan bir linter eklentisi) değerlendirebilir.
Üç disiplin sınıfı
Aggrega’nın disiplinleri, disiplinin nasıl uygulatıldığına göre üç sınıfa ayrılır. Bu sınıflandırma önemlidir, çünkü disiplin ihlal edildiğinde her sınıfın farklı bir hata biçimi vardır.
Şema tarafından uygulatılan
Disiplin, yükleme sırasında JSON Schema 2020-12 doğrulamasıyla uygulatılır (varlık zarfının JSON Schema’sı ile Component ve Feature varlıklarındaki sütun düzeyindeki schema: bildirimleri). Bir ihlal, derleme ilerlemeden önce ölümcül bir durmaya yol açar; derleyici devam etmeyi reddeder. Şema tarafından uygulatılan bir disiplini ihlal etmeye çalışan yazarlar, alanı ve kısıtı gösteren açık bir doğrulama hatası görür.
Örnekler: varlık zarfının zorunlu alanları (apiVersion / kind / metadata.name / metadata.version); metadata.version üzerindeki SemVer düzenli ifadesi; ayrılmış component.aggrega.ai/type etiketindeki kapalı değer kümesi; Release şemasının values: bloklarını mekanik olarak yasaklaması (Değişmez 5 uyarınca); Release üzerinde extends ile aggregate birlikteliğinin reddedilmesi (Tek Doğruluk Kaynağı değişmezi); girdi türü bileşim sözleşmesini uygulatan Recipe biçim kuralları.
Şema tarafından uygulatılan disiplinler, dilin taşıdığı en güçlü güvencelerdir. Derleyici, bunları ihlal eden hiçbir şeyi işlemeyi reddeder.
Bir politika eklentisi tarafından uygulatılan
Disiplin, belgelenmiş soket noktalarından birinde çalışan bir Wasm eklentisiyle uygulatılır (topoloji oluşturma sırasında yönetişim label-transform rolü; statik analiz sırasında yönetişim ir-verdict rolü; bant dışı linter soketi). Bir ihlal, soketin geçit semantiğine bağlı olarak ya derlemeyi durduran bir politika hatasına (bant içi soketler) ya da tavsiye niteliğinde bir uyarıya (bant dışı soketler) yol açar.
Bir disiplin bu şekilde yalnızca onu denetleyen bir eklentinin çalıştığı yerde uygulatılır: Wasm çalışma zamanı eklentileri belgelenmiş soket noktalarında çağırır ve hiçbir eklentinin denetlemediği bir disiplin uzlaşım olarak kalır. aggrega lint komutunun çalıştırdığı yayımlama linter’ı bu sayfadaki bir uzlaşımın bir kısmını denetler — bkz. Bir linter kuralının denetlediği uzlaşımlar. Yayımlama linter’ının hiçbir kuralı hermetikliği (Sprig FuncMap, templates/sprig-functions.md sayfasındaki determinizm uyarısı uyarınca deterministik çıktıyı bozan yardımcılar sunar) veya bulut kaynağı adlandırmasını (entities/recipe.md “Cloud-resource naming discipline” uyarınca valuesMapping: çıktıları release_name / instance_id ara değerlemesi olmadan bulut kaynağı adı alanlarına başvuran Recipes) denetlemez; kendi linter eklentiniz ikisini de denetleyebilir.
Wasm eklenti sözleşmesi yüzeyi ve yerleştirme ölçütü (linter soketi ile yönetişim karar rolleri) için bkz. plugins/plugin-contract.md.
Uzlaşımla sürdürülen
Disiplin yalnızca yazım disiplini ve gözden geçirenlerin dikkatiyle sürdürülür. Derleyici uygulatmaz; hiçbir şema ihlali reddetmez; hiçbir Wasm eklentisi onu işaretlemez. Yazarlar disiplini belgelerden öğrenir, mimari biçim ona dayandığı için ona uyar ve aksaklıkları yakalamak için PR incelemesine güvenir. Bir ihlal derleme zamanında hiçbir sinyal üretmez — derleme başarılı olur, işlenen çıktı derleyicinin bildiği kadarıyla çalışır ve disiplin ihlali ancak aşağı akıştaki araçlar veya çalışma zamanı davranışı uzlaşıma dayandığında ortaya çıkar.
Uzlaşımla sürdürülen disiplinler, yazarların belgelerden öğrenmesi gereken ve yük taşıyan listedir. Derleyici bunları yorumlamaz; bunları yanlış uygulamak derlemeyi bozmaz, ancak Aggrega’nın dayandığı mimari biçimi bozar. Bu sayfanın büyük bölümü bunları belgeler.
Uzlaşımlar
Aşağıdaki toplumsal sözleşmeler uzlaşımla sürdürülür. Her girdi, disiplini, uzlaşımın belgelendiği yüzeyi ve ihlal edildiğinde ortaya çıkan hata biçimini belirtir. Her girdi nerede durursa dursun numarasını korur: ayrılmış önek disiplini olan sözleşme 3, ek açıklama anahtarları için bir linter kuralı tarafından denetlenir ve Bir linter kuralının denetlediği uzlaşımlar altında açıklanır.
1. Bileşene uyan operasyonel türü seçmek
Ayrılmış component.aggrega.ai/type etiketi, bir bileşenin ne tür bir şey olduğunu evrensel bulut temel öğelerinden oluşan kapalı bir kümeden seçerek adlandırır: server, worker, task, function, stateful-server, resource. Bu kümeye üyelik uzlaşımla sürdürülmez, şema tarafından uygulatılır. Bu anahtarı ve kabul ettiği değerleri Aggrega tanımlar, Component şeması bunları numaralandırır ve başka bir değer taşıyan bir belge yüklenirken reddedilir — E0215, yani entity-envelope-invalid koşulu, etiketi adlandırır ve kabul edeceği değerleri listeler. Bu girdinin kapsamadığı şey tam da bu reddir.
Uzlaşım olarak kalan, değerlerden hangisinin önünüzdeki bileşene uyduğudur. İlişkisel bir veritabanının server yerine stateful-server olarak etiketlendiğini ya da bir kuyruk tüketicisinin task yerine worker olduğunu hiçbir şey denetlemez; seçici, bulduğu değeri ona anlam yüklemeden değerlendirir. Bir Component yazan Architect, altyapının ona nasıl davranması gerektiğini tanımlayan değeri seçer; aşağı akıştaki seçiciler, ilke eklentileri ve Wasm işleme eklentileri bu seçimin dürüst yapılmasına dayanır.
Kendi ekseninizde sınıflandırma. Kapalı küme yalnızca bu tek ayrılmış anahtarı yönetir, başka hiçbir şeyi değil. Aggrega’nın tanımlamadığı bir sınıflandırmaya — bir katman, bir veri bölgesi, bir hizmet sınıfı ya da operasyonel temel öğelerin daha ince bir ayrımı — ihtiyaç duyan bir katalog, ayrılmış anahtarın yanına kendi etiket anahtarını ekler. Component şeması dize değerli başka herhangi bir etiket anahtarını kabul eder ve aynı seçici mekanizması onu okur; böylece acme.aggrega.ai/storage-tier: oltp, component.aggrega.ai/type: stateful-server ile yan yana durur ve bir Feature’ın appliesTo alanı ya da bir soketin selector alanı ikisinden birini hedefleyebilir. Genişletme her zaman kendi anahtarınızda yapılır, asla Aggrega’nın anahtarındaki bir değerde yapılmaz.
Belgelendiği yer: architecture/02-ecosystem-philosophy.md (operasyonel ontoloji) + labels-and-annotations.md (önek disiplini) + errors/sentinels.md (E0215).
Hata biçimi: Kümeden gelen ama bileşene uymayan bir değer, etiketi okuyan her şeyi yanıltır. server olarak etiketlenmiş bir veri deposu, stateful-server seçen bir Feature veya soket tarafından reddedilir — durma, yanlış etiketi değil seçiciyi adlandırır — ve etiketi okuyan bir politika eklentisi veya işleme eklentisi onu durumsuz bir hesaplama olarak ele alır. Onu yalnızca bu tür okuyucuların gördüğü yerde derleme başarılı olur; hata ancak işlenen yapıtlar kümeye ulaştığında ortaya çıkar.
2. Üç kovalı .context.annotations.* ayrımı
Kademeli aktarılan ek açıklamalar, her biri farklı bir amaç taşıyan üç adlandırılmış kovaya düşer: .context.annotations.release, .context.annotations.catalog, .context.annotations.aggregate. Disiplinin hedefi: release “bu bileşenin nerede çalıştığı, Ops tarafından yönetilir”; catalog “bu bileşenin ne olduğu, Architect tarafından yazılır”; aggregate ise “bu bileşenin ne yaptığı, Developer tarafından yazılır” anlamına gelir.
Derleyici kova sınırlarını uygulamaz. Üç kova düz bir string → string biçimini paylaşır; bir Recipe şablonu üçünü de okuyabilir ve hiçbir şey bir Release sınır ek açıklamasının bilişsel üst veri olarak yorumlanmasını ya da bir katalog ek açıklamasının infra: içine yönlendirilmesini engellemez. Ayrım, ek açıklamaları doğru kovaya yazan yazarlar ve kovalar arası sızıntıları yakalayan gözden geçirenler tarafından korunur.
Belgelendiği yer: labels-and-annotations.md (Üç kovalı ayrım bir Social Contract’tır).
Hata biçimi: Kova amacı ayrımına dayanan yönlendirme mantığı (örneğin .context.annotations.release.aggrega.ai/region değerini bir Terraform region alanına yönlendiren bir Recipe), yazım amacından bağımsız olarak kovada görünen ek açıklama ne ise onu sessizce tüketir. Derleme başarılı olur; işlenen çıktı anlamsal olarak yanlış değerler taşıyabilir.
4. Recipe provides: kendi kendine yeterliliği
Recipe provides: şablonları yalnızca düğümün kendi verisini kapsar: .values, .infra, .context.instance_id, düğümün provider’ı bildirdiğinde .context.rendered_name, düğümün çözümlenmiş .locals değerleri ve statik dizeler. .context.inject ve .context.uses başvuruları yasaktır, çünkü provides değerlendirmesi bu şablonları herhangi bir sırada çalıştırır; düğümler arası veri okumak, onu tasarımın bilinçli olarak kaçındığı topolojik yineleme sırasına bağlardı. .locals yüzeyin dışında değil içindedir: düğümün locals değerleri aynı aşamanın ön bölümünde, provides değerlerinden önce çözümlenir ve düğüme yereldir; bu nedenle onları okumak sıralama açısından hiçbir maliyet getirmez. Locals bloğunun bildirmediği bir anahtarı adlandırmak derlemeyi durdurur.
Bu, her biri nerede denetlendiğini belirten iki yarıdan oluşan bir kuraldır. İlkini derleyici denetler: provides değerlendirmesi her şablonu, şablon çalıştırılmadan önce bağlamının tanımladığı köklerin pozitif izin listesine göre denetler; böylece bir .context.inject / .context.uses okuması boş işlenmek yerine açık bir hatayla durur. Kural ayrıca templates/expansion-matrix.md 6. satırda belgelenmiştir. İkincisini uzlaşım sürdürür: daha geniş örüntü (provides herkese açıktır; locals özeldir) uzlaşıma dayanır.
Belgelendiği yer: templates/expansion-matrix.md 6. satır + vocabulary/data-pillars.md “provides: ve locals: — herkese açık yüz ve özel yüz”.
Hata biçimi: yasak başvurular doğrudan provides: içinde göründüğünde derleyici bunu tespit eder ve derlemeyi şablon değerlendirme anında durdurur. Daha geniş herkese açık/özel disiplini (iç durumu provides: anahtarları aracılığıyla açığa çıkarmamak) yalnızca uzlaşımdır: provides: alanını Recipe’e özgü bir ad alanı gibi kullanan yazarlar, çağıranların bağımlı hâle geldiği sözleşmeler üretir; yeniden düzenleme geriye dönük uyumu bozan bir değişikliğe dönüşür.
5. Determinizm — render yolundaki şablonlarda hermetik olmayan yardımcılar
Aggrega’nın Deterministik Çıktı Değişmezi (architecture/05-invariants.md içindeki Değişmez 8), bayt bayt aynı girdi için bayt bayt aynı çıktı gerektirir. Sprig’in tam FuncMap’i, ortam durumunu okuyan yardımcıları sunar (saat okuyucuları now / date; rastgele üreteçler randAlpha / uuidv4; ortam değişkeni okuyucuları env / expandenv; ağ çözümleyicileri getHostByName). Bu yardımcıları render edilen çıktıya katkıda bulunan bir şablondan çağıran yazarlar determinizm sözleşmesini bozar.
Derleyici, hermetik olmayan yardımcıların kullanımını algılamaz veya engellemez. Sprig FuncMap’i bunları templates/sprig-functions.md “Determinism caveat” uyarınca sunar; disiplin, render yolundaki şablonlarda bu yardımcılardan kaçınan yazarlar ve kullanımlarını PR incelemesinde yakalayan gözden geçirenler tarafından sürdürülür.
Belgelendiği yer: templates/sprig-functions.md “Determinism caveat”.
Hata biçimi: Derleme çıktısı aynı girdinin farklı çalıştırmalarında farklılık gösterir. Uyuşmazlık, GitOps diff zamanında, aşağı akıştaki araçlar (ArgoCD, Flux) commit edilmiş manifest ile küme durumu arasında beklenmeyen bir sapma gördüğünde ya da denetim zamanında aynı girdinin iki derlemesi farklı yapıtlar ürettiğinde ortaya çıkar.
Yayımlama linter’ının hiçbir kuralı şablonlarda hermetik olmayan yardımcı çağrılarını denetlemez. Yardımcının adı şablonda yazılıdır; bu nedenle kendi linter eklentiniz onu bulabilir (bkz. Bir linter kuralının denetlediği uzlaşımlar).
6. Sütun sınırları (duvar değil, yol işareti)
Sütun sınırları dil tarafından uygulanan bir kısıt değil, yazım disiplinidir. Şablon motoru, kendi kendine yeterlilik kurallarınca açıkça yasaklanmadıkça (örn. Recipe provides: ve source: içinde .context.inject / .context.uses okunması) her noktada sütunlar arası okumaya izin verir. Yazarlar şunları yapmalıdır:
- Bilişsel yük (geliştiricinin yazdığı niyet) için
.valuesokuyun. - Fiziksel boyutlandırma (Ops’un yazdığı boyutlandırma) için
.infraokuyun. - Bileşenler arası işaretçi dizeleri için
.context.uses.<alias>.provides.<key>okuyun. - Hidrasyon sonrası teslim hattı için
.context.injectokuyun.
Şablon motoru okumayı denetlemez. Bir values: alanını beslemek için .infra.replicas okuyan bir Recipe şablonu çalışır; sütunlar arası yolu hiçbir şey engellemez. Disiplinin hedefi yol işaretleridir — sınırlar çalışma zamanı kısıtlamasını değil, yazım niyetini (verinin sahibinin kim olduğunu) tanımlar.
Belgelendiği yer: vocabulary/data-pillars.md “Pillar boundaries and authoring discipline”.
Hata biçimi: Sütunlar arası sızıntı — geliştiricinin bilişsel yükü fiziksel boyutlandırma ayrıntıları içerir ya da Ops’un yazdığı boyutlandırma bilişsel meta veri içerir. Derleme başarılı olur; yazarlar sütunları kestirmeden geçtikçe dört alanlı yazım ayrımı zamanla bulanıklaşır; sütun ile veri akışı arasındaki karşılık zayıfladıkça aşağı akıştaki bakım zorlaşır.
7. Workload containers.<name>.variables çift kaynaklı anlamı
variables: haritası, Go şablon ifadeleri aracılığıyla iki ayrı veri kaynağını harmanlar: geliştirici sütunu sabitleri (.values / .infra / .locals okuyan girdiler) ve bileşenler arası hat verisi (.context.inject.env.<KEY> okuyan girdiler). Yazarlar, değerin bileşene yerel mi yoksa bileşenler arası türetilmiş mi olduğuna göre her girdi için bir kaynak seçer.
Derleyici iki kaynağı ayırt etmez; ikisi de render edilen Deployment üzerindeki aynı Kubernetes env: listesine akar. Çift kaynaklı anlam yalnızca yazım zamanına aittir — disiplin, gelecekteki bakımcıların hangi girdilerin hangi inject-hidrasyon çıktılarına bağlı olduğunu okuyabilmesi için niyeti adlandırmaktır (bu girdi bileşene yereldir; şu girdi bileşenler arası türetilmiştir).
Belgelendiği yer: entities/workload.md “Field-semantics essentials” (variables).
Hata biçimi: İki kaynağı ayırt etmeyen yazarlar “hangi girdiler hangi hedefin provides: değerlerine bağlı” izini kaybeder. Bir hedefin provides: anahtarlarını yeniden düzenlemek, inject hattı üzerinden okuyan her çağıran variables: girdisini sessizce bozar.
8. Bulut kaynağı adlandırma disiplini
Bulut kaynağı adları üreten Recipes (S3 bucket adları, RDS veritabanı tanımlayıcıları, IAM rol adları, CloudFormation stack adları — değeri bulut sağlayıcısında küresel bir ad alanını işgal eden her alan), aynı Recipe birden çok Releases veya bileşen örneği genelinde çalıştığında çakışmaları önlemek için render edilen ada {{ .metadata.release_name }} ve/veya {{ .context.instance_id }} eklemelidir.
Derleyici, valuesMapping: çıktılarını bu enterpolasyonlar olmadan bulut kaynağı adı alanları için incelemez. Disiplin, Recipe yazarları (hedef sağlayıcı için hangi alanların küresel olarak benzersiz kaynakları adlandırdığını bilenler) ve gözden geçirenler (adsız kaynak kalıplarını PR incelemesinde yakalayanlar) tarafından sürdürülür.
Belgelendiği yer: entities/recipe.md “Cloud-resource naming discipline”.
Hata biçimi: Aynı Aggregate’in iki Releases’i (prod-billing ve staging-billing) aynı küresel ada sahip bir kaynağı dağıtmaya çalışır; ikinci dağıtım çalışma zamanında bulut tarafındaki bir retle başarısız olur. Aggrega derlemesi başarılı olur; dağıtım hatası yalnızca ikinci Release uygulandığında ortaya çıkar.
Yayımlama linter’ının hiçbir kuralı bulut kaynağı adı alanlarında gerekli ara değerlemeleri denetlemez; kendi linter eklentiniz bunu yapabilir (bkz. Bir linter kuralının denetlediği uzlaşımlar).
9. Component ayrıntı düzeyi — Component başına bir tutarlı hizmet
Bir Component tek bir tutarlı hizmeti modeller — dışa açık tek bir hizmeti ya da bir hizmetin workload’larını, yalnızca dahili yardımcı workload’larıyla birlikte. Bir chart, başka bir bileşenin kendi başına anlamlı biçimde use edebileceği hizmetleri bir araya getirdiğinde — özellikle Aggrega’nın zaten kendi Component’i olarak modellediği veritabanı, önbellek veya mesaj aracısı gibi yabancı altyapıyı — standart kütüphane, ürünün tamamını tek bir opak Component olarak sarmak yerine hizmet başına Components’i bir alt aggregate Module’de (spec.aggregates + exportedComponents) birleştirir. Disiplin şudur: bir Component içinde birden çok workload olması sorun değildir; bir Component’i bir yığına bölen çizgi bağımsız kullanılabilirliktir.
Derleyici bu ayrıntı düzeyinden bağımsızdır. Şema doğrulamasından geçen her şeyi render eder — bir Component’in Recipe’inin kaç hizmeti bir araya getirdiğini ya da bunlardan birinin bağımsız kullanılabilir olup olmadığını incelemez. Beş hizmetli bir ürünü tek bir Component olarak saran bir yazar, derleyicinin kabul ettiği ve itirazsız render ettiği bir Component üretir; uzlaşım, yazım disiplini ve gözden geçirenlerin dikkatiyle sürdürülür.
Belgelendiği yer: ../../architecture/06-data-taxonomy-and-composition.md (Component başına bir tutarlı hizmet — tek workload sınırı).
Hata biçimi: Tek parça, çok hizmetli bir sarmalama başarıyla derlenir, ancak bir araya getirilen hizmetler topoloji, seçici ve politika için görünmezdir — bağımsız olarak ölçeklenemez, değiştirilemez veya bunlara bağımlı olunamaz. Tek parçayı daha sonra hizmet başına Components’e bölmek, sarılmış tek düğüme başvuran her tüketici için geriye dönük uyumsuz bir değişikliktir.
Uzlaşımlar neden var
Bu uzlaşımların her biri tasarım gereği bir yazım disiplinidir, ancak bir şema veya bir Wasm politikası bunların herhangi birini zorunlu kılabilirdi. Sözleşme türüne göre gerekçe:
Genişletilebilirlik. Ayrılmış önek disiplini (sözleşme 3), geçerli sözcük dağarcığının tamamını değil, standart kütüphanenin sözcük dağarcığını tanımlar. Kurumsal kataloglar standart kütüphaneyi genişletmek için kendi öneklerini ve etiket anahtarlarını yazar; önek uzlaşımını şema ile zorunlu kılmak “standart kütüphanenin disiplini”ni “dilin izin verilen tek biçimi”ne dönüştürürdü; bu, mimarinin bilinçli olarak kaçındığı duvardır. Operasyonel tür ekseni (sözleşme 1) aynı genişletilebilirliği farklı bir yüzeyde korur: Aggrega’nın tanımladığı ayrılmış anahtar kapalı, şema ile zorunlu kılınan bir küme taşır ve bir katalog, Aggrega’nınkinin içine bir değer eklemek yerine yanına kendine ait bir etiket anahtarı ekleyerek genişletir. Şemanın denetlediği, sahip olduğu tek bir anahtarın değer kümesidir; açık kalan ise diğer her anahtardır ve bir kataloğun kendi sözcük dağarcığı da oradadır.
AOT saflığı. Bulut kaynağı adlandırma disiplini (sözleşme 8) ve belirlenimcilik disiplini (sözleşme 5), bir alanın bulut kaynağı adı mı yoksa hermetik olmayan bir yardımcı çağrısı mı olduğunu belirlemek için şablon içeriğinin incelenmesini gerektirir. AOT saflığı (Değişmez 2), derleyicinin çalışma zamanı durumuna bağımlı olmasını engeller; statik şablon incelemesi uygulanabilirdir (bir linter eklentisi varlığın şablonlarını yazıldığı gibi okur), ancak bunu çekirdek derleyicinin içinde yapmak derleyici içi mantığı alana özgü yazım kaygılarına bağlar. Mimari bu denetimleri Değişmez 6 (Wasm ABI Sınırı) uyarınca derleyiciden çıkarıp Wasm eklentilerine taşır.
Yazım esnekliği. Sütun sınırları disiplini (sözleşme 6) ve çift kaynaklı variables semantiği (sözleşme 7), çalışma zamanı kısıtlamalarını değil yazım kalıplarını tanımlar. Aynı şablon sözdizimi disipline uyan bir kalıbı da onu ihlal eden bir kalıbı da ifade edebilir; disiplini bir çalışma zamanı denetimine dönüştürmek, derleyicinin erişemediği yazım niyetini yorumlamasını gerektirirdi. Mimari, uzlaşımı bir çalışma zamanı değişmezi olarak değil, yazarların öğrendiği bir belgeleme olarak ele alır. Component ayrıntı düzeyi (sözleşme 9) de buraya girer: kurumlar bir ürünü kataloglarının tercih ettiği herhangi bir ayrıntı düzeyinde sarmalayabilir ve Değişmez 1 uyarınca içeriğe karşı tarafsız ve kendi görüşü olmayan derleyicinin, paketlenmiş bir iş yükünün bağımsız olarak kullanılabilir olup olmadığını bilmesinin hiçbir yolu yoktur; bu yüzden tek tutarlı hizmet sınırı bir şema duvarı değil, yazım disiplini olarak kalır. Operasyonel tür seçimi (sözleşme 1) de aynı biçimdedir: şema hangi değerlerin var olduğunu belirler, ancak belirli bir bileşeni hangisinin tanımladığı, altyapının ona nasıl davranması gerektiğine dair bir modelleme yargısıdır ve bir Recipe’teki ya da bir values bloğundaki hiçbir şey derleyiciye bu yargının doğru olup olmadığını söylemez.
İki yarıda zorunluluk. Recipe provides: kendi kendine yeterliliği (sözleşme 4) kısmen derleyici tarafından zorunlu kılınır: işleme yolu provides: şablonlarındaki .context.inject / .context.uses okumalarını algılar ve durur. Daha geniş genel-özel ayrımı disiplini (iç durumu dışarı açmayın) uzlaşıma dayanır, çünkü derleyici yazım niyeti olmadan hangi dizgelerin Recipe’e içsel kalması gerektiğini belirleyemez.
Üç yol önemlidir, çünkü her biri ihlalleri yakalama sorumluluğunun nerede olduğunu gösterir. Şema tarafından uygulatılan: derleyici. Bir politika eklentisi tarafından uygulatılan: onu denetleyen eklenti, çalıştığı yerde. Uzlaşımla sürdürülen: yazarlar ve gözden geçirenler. Bu yolları içselleştiren yazarlar, derleyicinin hangi hataları yakalayacağını ve hangilerinin sessizce aşağı akıştaki araçlara ya da çalışma zamanına geçeceğini anlar.
Bir linter kuralının denetlediği uzlaşımlar
aggrega lint komutunun çalıştırdığı yayımlama linter’ı, bu sayfadaki bir uzlaşımı kısmen denetler: aşağıdaki sözleşme 3’ün ek açıklama anahtarları. Bulgusu tavsiye niteliğindedir ve uzlaşımın ulaşmadığı kısmı, yukarıdaki girdiler gibi uzlaşımla sürdürülür.
Yayımlama linter’ının hiçbir kuralı bu sayfadaki başka bir uzlaşımı denetlemez. Bunlardan ikisi bir linter kuralıyla denetlenebilir, çünkü ihlal varlıkta yazılıdır: belirlenimcilik (sözleşme 5) — hermetik olmayan bir yardımcıyı çağıran bir şablon — ve bulut kaynağı adlandırması (sözleşme 8) — release_name / instance_id ara değerlemesi olmadan bir bulut kaynağını adlandıran bir valuesMapping: çıktısı. Ayrılmış öneklerin altındaki etiket anahtarları (sözleşme 3) da öyle. Bir çalışma alanı, bunların herhangi birini denetlemek için yayımlama linter’ının yanına plugins.linter altında kendi linter eklentilerini ekleyebilir; The discipline rules yayımlama linter’ının taşıdığı kuralları listeler.
Diğer uzlaşımlar (1, 2, 4, 6, 7, 9) yazarın ne kastettiğine bağlıdır ve hiçbir kural bunu yazılandan okuyamaz. Kova ayrımı genişletilebilirlik odaklıdır (kurumsal kataloglar geçersiz kılar) — şema denetimi bu esneklikle çatışırdı. Şema değer kümesini belirledikten sonra operasyonel tür ekseninden geriye kalan — bileşene uyan temel öğeyi seçmek — yazım niyetine dayanır: derleyici iyi seçilmiş bir operasyonel türü kötü seçilmiş olandan ayırt edemez, çünkü ikisi de kabul ettiği değerlerdir. Sütun sınırları disiplini ve çift kaynaklı variables semantiği yazım niyetine dayanır — derleyici niyeti yalnızca şablon sözdiziminden belirleyemez. Recipe provides: öz-yeterliliği kısmen denetlenmektedir; daha geniş kapsamlı açık-özel disiplini, yazarın hangi anahtarları içsel tutmayı amaçladığına bağlıdır ve Recipe’te hiçbir şey bunu belirtmez. Component ayrıntı düzeyi de yazım niyetine dayanır — paketlenmiş bir iş yükünün bağımsız olarak kullanılabilir olup olmadığı, derleyicinin Recipe içeriğinden okuyamayacağı bir modelleme yargısıdır.
3. Ayrılmış önek disiplini
Ek açıklama ve etiket anahtarları <namespace>/<name> biçimini izler. Beş ayrılmış önek belirli yazım kuralları taşır: aggrega.ai/ (yalnızca platform), feature.aggrega.ai/ (resmî Feature kısayolları), component.aggrega.ai/ (Component’e içkin özellikler), aggregate.aggrega.ai/ (Aggregate modül kimliği) ve <any-other-domain>/ (kurumsal / topluluk).
Derleyici, bir katalog varlığında veya bir Release’te ayrılmış bir önek altında yazılmış bir ek açıklamayı reddetmez; derlemeyi yalnızca aggrega.ai/ altında bir anahtar talep eden bir Manifest ek açıklama bağlaması veya bir Recipe çıktı etiketi durdurur. Platformun sözcük dağarcığı dışında aggrega.ai/internal-billing-tag: "..." bildiren bir kurum, derleyicinin kabul ettiği ve kova sistemi boyunca kademeli aktardığı bir ek açıklama üretir; gerçek bir aggrega.ai/internal-billing-tag getiren sonraki platform güncellemeleri bununla sessizce çakışır.
Belgelendiği yer: labels-and-annotations.md (Önek disiplini) + providers/well-known-annotations.md.
Hata biçimi: Ayrılmış önekler altındaki özel ek açıklamalar, aynı adı taşıyan gelecekteki platform ek açıklamalarıyla çakışır; platformun beklenen davranışı, sıraya bağlı olarak kurumun yazdığı değerin üzerine sessizce yazar ya da onunla bir arada bulunur.
aggrega lint komutunun çalıştırdığı yayımlama linter’ı, bir katalog varlığının aggrega.ai/ altında olup platformun iyi bilinen ek açıklamalarından biri olmayan ek açıklama anahtarını ve Feature dışındaki bir varlıkta feature.aggrega.ai/ altındaki anahtarı tavsiye niteliğinde bir bulgu (E0277) olarak işaretler. Etiket anahtarları, diğer ayrılmış önekler ve bir varlığın metadata.annotations alanı dışındaki ek açıklamalar — örneğin bir Release’in yazdıkları — denetlenmez; bu nedenle bunlar için disiplin bir uzlaşım olarak kalır.
Çapraz başvurular
architecture/05-invariants.md— Aggrega’nın “derleyici içeriğe karşı tarafsızdır” çerçevesini temellendiren sekiz kurucu değişmez; her uzlaşım bunlardan biriyle veya birkaçıyla gerilim içindedir.architecture/02-ecosystem-philosophy.md— operasyonel ontolojinin tam tasarım gerekçesi.vocabulary/labels-and-annotations.md— toplumsal sözleşme olarak üç kovalı ayrım; ayrılmış önek disiplini.vocabulary/data-pillars.md— yol gösterici işaretler olarak sütun sınırları;provides:velocals:için genel ve özel çerçevesi.templates/sprig-functions.md— hermetik olmayan yardımcıları adlandıran determinizm uyarısı.entities/recipe.md— bulut kaynağı adlandırma disiplini + işlenmiş örnekler.entities/workload.md— Workloadvariables:çift kaynaklı semantiği.templates/expansion-matrix.md— derleyicinin zorunlu kıldığı kural olarak Recipeprovides:kendi kendine yeterliliği.plugins/plugin-contract.md— linter soketinin yerleşim ölçütü.cli/aggrega-lint.md— yayımlama linter’ının kuralları ve kendi linter’larınızı eklemek.