Yayımlama yüzeyi
Her Aggrega katalog YAML’ı, varlığı katalog dağıtımı için tanımlayan tek tip bir meta veri alanları kümesi taşır: onu kimin sürdürdüğü, hangi lisansla sunulduğu, kaynağının nerede bulunduğu, keşif için onu hangi anahtar sözcüklerin öne çıkardığı. Bu alanlar birlikte yayımlama yüzeyini oluşturur: katalog yayımcılarının ve araç tüketicilerinin dayandığı, labels-and-annotations.md sayfasında belgelenen içerik tarafındaki metadata.labels / metadata.annotations mekanizmasından ayrı olan meta veri sözcük dağarcığı.
Bu sayfa yayımlama yüzeyi alanlarını, külliyat genelindeki açıklama alanı envanterini (zarf, örnek ve alan düzeyindeki açıklamalar), sürdürücü alanının amaçlanan kullanımını ve doğrulanmış tüketicisini ve varlık başına zorunlu alan asimetrilerini (her varlığın bugün hangi alanları zorunlu kıldığını ve asimetrilerin nerede kasıtlı olduğunu) belgeler.
Yayımlama yüzeyi alanları
Aşağıdaki alanlar her Domain 2 (Component, Feature) ve Domain 3 (Recipe, FeatureRecipe, Plugin) varlığında, ayrıca yeniden kullanılabilir bir modül olarak Aggregate’te bulunur. Manifest ve Release’te de daraltılmış bir anlamla (katalog yayımı yerine çalışma alanı atfı) bulunurlar.
| Alan | Tür | Amaç | Tüketici |
|---|---|---|---|
description | string | Varlığın insanlar tarafından okunabilir özeti | Düzenleyici üzerine gelme kartları (aggrega serve); bir asistanın çağırdığı describe aracı (aggrega mcp); yayımlanan yapıt üzerinde aranabilir bir ek açıklama (aggrega push); aggrega inspect |
maintainers | nesne dizisi | Varlığın sahibi (ad, e-posta, url) | IR’de, Component düğümlerinde düğüm başına catalog_metadata |
license | string | Yasal uyumluluk (genellikle SPDX tanımlayıcısı) | IR’de, Component düğümlerinde düğüm başına catalog_metadata |
repository | string (URL) | Kaynağın bulunduğu Git deposu | IR’de, Component düğümlerinde düğüm başına catalog_metadata; başka hiçbir şey onu okumaz |
home | string (URL) | Belgelendirme / wiki URL’si | IR’de, Component düğümlerinde düğüm başına catalog_metadata; başka hiçbir şey onu okumaz |
keywords | string dizisi | Keşif etiketleri | IR’de, Component düğümlerinde düğüm başına catalog_metadata; hiçbir arama dizini bunları tüketmez |
Altı alanın tümü, onları taşıyan her varlıkta isteğe bağlıdır. Bu alanların tamamını atlayan bir katalog yazarı da geçerli bir YAML üretir: yayımlama yüzeyi, katalog dağıtımı amaçlanan varlıklar içindir; dahili kullanıma yönelik varlıklar onu hiçbir sonucu olmadan atlayabilir.
Tüketici sütunu bugün sunulanlar için eksiksizdir ve bunun iki sonucunu açıkça belirtmek gerekir, çünkü bunlar neyin yazmaya değer olduğunu değiştirir:
description, birden fazla okuyucusu olan tek alandır.aggrega serveonu Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest ve dört kütüphane türü (SchemaLibrary,MappingLibrary,WorkloadLibrary,ArtifactLibrary) için üzerine gelme kartına işler; Plugin veya Release için işlemez.aggrega mcp’nin sunduğudescribearacı onu her türden bir varlık için döndürür.aggrega pushonu yayımlanan yapıta aranabilir bir ek açıklama olarak damgalar.aggrega inspectonu her tür için varlığın başlığının altında yazdırır ve başka hiçbir yayımlama yüzeyi alanını yazdırmaz.repository,homevekeywordsdoğrulanır ve taşınır; IR’nin ötesinde onları hiçbir şey okumaz. Hiçbir listeleme yüzeyi, katalog sitesi veya arama dizini onları tüketmez. Bunları yazmak, varlıkla birlikte taşınan ve IR çıktısından ve bir yönetişim politikasından okunabilen köken bilgisini kaydeder; varlığı hiçbir yerde bulunabilir kılmaz.
Kullanımdan kaldırma bir yayımlama yüzeyi alanı değildir. Bir varlık, yayımdan sonra kayıt defterinde ona karşı bir işaretçi kaydedilerek kullanımdan kaldırılır: bir önem derecesi (warning, error veya retracted), bir gerekçe ve bir yedek taşıyan, çekme sırasında doğrulanan imzalı bir işaretçi. Ardından kilit dosyasını okuyan her yüzey bunu bildirir; build.halt_on_deprecated_severity yalnızca bunun bir derlemeyi de durdurup durdurmayacağına karar verir. İşaretçi hiçbir zaman varlığın kendi YAML’ında yazılmaz ve bunun nedeni yapısaldır: yayımlanan bir yapıt değiştirilemez, dolayısıyla yayım anında ona dondurulan bir bayrak daha sonra alınan bir kararı asla ifade edemezdi. aggrega inspect’in bir katalog varlığı için yazdırdığı kullanımdan kaldırma bildirimi, adıyla çözümlediği her tür için işaretçiden gelir.
IR tüketimi: düğüm başına catalog_metadata
Derleyici, yayımlama yüzeyi alanlarını her Component’ten o düğümün catalog_metadata bloğuna taşır; bu blok, bir çalıştırmanın geri verdiği IR grafiğinde görünür (aggrega inspect <release> --ir-graph). Blok maintainers, license, repository, home ve keywords alanlarını tutar; bunlar IR’nin taşıdığı beş alandır, description aralarında değildir. IR grafiği sözleşmesine göre oluşturulan araçlar, katalog YAML’ını yeniden okumak yerine meta verileri buradan okur.
Yalnızca Component düğümleri. Blok, düğümün bileşen türü katalogda bir Component olarak aranarak doldurulur; bu nedenle bir Feature’ın, Recipe’nin, FeatureRecipe’nin veya Plugin’in yayımlama yüzeyi IR’ye hiçbir zaman ulaşmaz: bu varlıklar alanları taşır ve alanlar doğrulanır, ancak onlardan hiçbir IR düğümü oluşmaz.
Kaynak Component üzerindeki her yayımlama yüzeyi alanı boş veya sıfır olduğunda catalog_metadata, IR JSON’ından tamamen çıkarılır: blok boş değerlerle yayılmak yerine atlanır. Böylece aynı girdi aynı sıkı çıktıyı üretir ve bu da IR farkını çalıştırmalar arasında kararlı tutar.
Bir yönetişim politikası bloğu okuyabilir. plugins.governance altında ir-verdict rolüyle eklenen bir plugin, her Component düğümünün catalog_metadata’sı dahil olmak üzere IR grafiğinin tamamını düğüm düğüm alır; böylece bir politika, bir düğümün license, repository, home, keywords veya maintainers alanına göre bir derlemeyi kabul edebilir ya da reddedebilir. Bu erişim yönetişim soketine özgüdür: bir sağlayıcının işleme plugin’i, catalog_metadata içermeyen sınırlı bir düğüm başına izdüşüm alır; dolayısıyla işleme plugin’leri bu alanları okuyamaz.
Üç açıklama türü
description alanı zarf üzerinde tek biçimde yer alır, ancak derlem ayrıca şema bildirimlerinin içinde (alan başına açıklamalar) ve sütun gövdelerinin içinde (örnek başına açıklamalar) açıklama tarzı dizeler de taşır. Üç ayrı açıklama türü bir arada bulunur; aşağıdaki tablo bunları birbirinden ayırır.
| Tür | Bulunduğu yer | Yazan | Amaç |
|---|---|---|---|
| Zarf açıklaması | Her varlıkta metadata.description | Katalog yayıncısı | Varlığın bütününün özeti; düzenleyici üzerine gelme kartlarında gösterilir ve yayımlanan yapıta damgalanır |
| Örnek açıklaması | Örnek başına bir bildirimin yanındaki description alanı (ör. featuresSchema.<slot>.description, usesSchema.<socket>.description) | Şema yazarı | Yuva / soket / port başına açıklama; bildirimi okuyan, onu tüketen varlıkların yazarları için |
| Alan açıklaması | schema: / featuresSchema: / usesSchema: içeriğindeki (kompakt biçim veya tam JSON Schema YAML) JSON Schema 2020-12 description: ek açıklaması | Şema yazarı | Şemayla birlikte taşınan alan başına belgeler |
Üç tür “description” sözcüğünü paylaşır, ancak yapısal olarak farklı düzeylerde bulunur. Zarf açıklaması varlığın bütününe uygulanır; örnek açıklaması bir şema yuvasının içindeki bir bildirime uygulanır; alan açıklaması ise türlendirilmiş bir şemanın içindeki belirli bir değere uygulanır. Bir Component yazan yazarlar:
- Component varlığının kendisi için
metadata.descriptionalanını bir kez ayarlar. - Component’in bildirdiği her kimlik bilgisi yuvası için
featuresSchema.admin_password.descriptionalanını bir kez ayarlar. - Component’in şemasını okuyan herkes için her alanı belgelemek üzere
schema:bloğunun içinde, kompakt biçimde (port: { type: integer, description: "..." }) veya tam JSON Schema YAML olarak, alan başınadescription:ek açıklamaları ayarlar.
Üç tür birbirine aktarılmaz ve çakışmaz; her biri farklı bir yüzeye ulaşır ya da hiçbirine ulaşmaz:
- Zarf açıklaması: yukarıdaki Tüketici sütununa göre düzenleyici üzerine gelme kartları, yayımlanan yapıtın aranabilir ek açıklamaları ve
aggrega inspect. - Alan açıklaması: bir Component’in veya bir Feature’ın üzerine gelme kartının işlediği şema alıntısında olduğu gibi görünür. Alıntı yalnızca
spec.schemaalanını kapsar ve ilk satırlarına kısaltılır; bu nedenle bloğun daha derinindeki bir açıklama ya dafeaturesSchema:veyausesSchema:içindeki bir açıklama orada görünmez. - Örnek açıklaması: bildirilir ve varlıkla birlikte taşınır; yayımlanan hiçbir yüzey onu tek başına işlemez.
aggrega inspect, bir Component’in soketlerini ve feature yuvalarını açıklamaları olmadan listeler.
Bakımcı alanının amacı
maintainers alanı, her biri name, email ve url içeren bir nesne dizisi taşır. Amacı ve doğrulanmış tüketicisi:
Amaç (bilgilendirme + IR kaynak bilgisi). Alan, katalog yayımlama için bilgilendirme amaçlıdır: mimari amaç “bu katalog varlığından kim sorumlu” sorusudur; varlıkla birlikte taşınan bir sahiplik sinyalidir. Hiçbir yüzey onu bir iletişim listesi olarak sunmaz ve hiçbir yerleşik denetim onu herhangi bir şeyle karşılaştırmaz.
Doğrulanmış tüketici (düğüm başına catalog_metadata). Derleyici, her Component’in metadata.maintainers değerini IR’de o düğümün catalog_metadata.maintainers alanına taşır; kaynak Component bir bakımcı bildirdiğinde bu, aggrega inspect <release> --ir-graph komutunun döndürdüğü grafikte görünür. Alanın tek okuyucusu budur. ir-verdict rolünde plugins.governance altına eklenen bir yönetişim politikası onu orada görür; böylece bir sahiplik kuralı (her varlık en az bir bakımcı adlandırır, bir bakımcının alan adı onaylı bir kümeyle eşleşir) katalog YAML’ı yerine IR’ye karşı ifade edilebilir. Böyle bir kural birlikte gelmez; soket, böyle bir kuralın yer alacağı yerdir.
Derleyici, bakımcı içeriğini JSON Schema’nın yapısal biçiminin (name zorunlu; email ve url isteğe bağlı, ikisi de string) ötesinde zorlamaz veya doğrulamaz. Listelenen bakımcıların varlığa gerçekten sahip olup olmadığı, e-postalarına ulaşılıp ulaşılamadığı, bir depo commit’inin içlerinden biri tarafından imzalanıp imzalanmadığı katalog yönetişimi konularıdır ve birlikte gelen hiçbir denetim bunların hiçbirini değerlendirmez. Bunlar derleyiciye değil, bir operatörün eklediği bir yönetişim politikasına aittir.
Zorunlu alan asimetrileri
Aggrega’nın varlık türleri, JSON Schema’larında birbirinden biraz farklı zorunlu alan kümeleri taşır. Asimetrilerin çoğu kasıtlıdır ve varlığın rolünü yansıtır.
Varlık başına zorunlu alanlar (her varlığın tek tip olarak zorunlu tuttuğu apiVersion / kind / metadata.name / metadata.version hariç):
| Varlık | Ek zorunlu alanlar | Gerekçe |
|---|---|---|
| Component | metadata.labels.component.aggrega.ai/type | Etiket zorunluluğu seçici eşleştirmesi için yük taşıyıcıdır: usesSchema x-aggrega-selector: ek açıklamaları hedef Components’i bu etikete göre filtreler; etiket yoksa Component yüklenirken reddedilir |
| Feature | — | Ayrılmış etiket zorunluluğu yoktur; Features ad + yayıncı ile tanımlanır |
| Recipe | spec.capability, spec.implements | Yetenek, sağlayıcıya yönlendirmeyi denetler; implements, Component bağlamayı denetler |
| FeatureRecipe | spec.capability, spec.implements | Recipe ile aynı |
| Plugin | metadata.pluginType, spec.abiVersion | Eklentinin uyguladığı soket türü (adresleme bloğunun parçasıdır ve türetilen plugin/<pluginType>/<name> koordinatının <pluginType> kesimini sağlar) ve hedeflediği ABI sürümü; .wasm konumu yazılmaz, bu kimlikten türetilir; sağlayıcı çıktısı üreten bir eklenti (pluginType: provider) ayrıca çeviri sözleşmesini spec.provider altında taşır |
| Aggregate | — | components, subsystems ve aggregates alanlarından hiçbirini bildirmeyen bir Aggregate yüklenir ve derlenir, ancak hiçbir şey işlemez |
| Manifest | spec.mappings | Eşleme katmanları, Manifest’in tek amacıdır |
| Release | spec.aggregate, spec.manifest (extends bildiren bir Release aggregate yazmaz ve manifest alanını atlayabilir); metadata.environment | İlk ikisi derlemeyi belirli bir Aggregate + Manifest’e bağlar; environment, işlenen çıktıya aggrega.ai/environment etiketi olarak damgalanır |
Component etiket zorunluluğu yük taşıyıcıdır
component.aggrega.ai/type etiketi, Aggrega’nın herhangi bir varlıkta zorunlu tuttuğu tek etikettir. Bu zorunluluk, standart kütüphanenin usesSchema mekanizmasının hedef adayları "component.aggrega.ai/type=database" gibi seçici dizeleri taşıyan x-aggrega-selector: ek açıklamalarıyla filtrelemesi nedeniyle vardır — seçici, türün soketin kabul ettiği türlerle eşleşip eşleşmediğini belirlemek için hedefin etiketlerine bakar. Component şeması bunu zorunlu kılar: etiketi atlayan bir Component yüklenirken reddedilir (E0215) ve eksik anahtar adlandırılır.
Dolayısıyla bu zorunluluk bir yayımlama yüzeyi meselesi değil (etiket katalogda keşif için değildir), bir topoloji meselesidir: katalog dağıtımını hedeflemeyen iç kullanımlı Components de dahil olmak üzere her Component bu etiketi taşır.
Release metadata.environment alanı zorunludur
Release şeması metadata.environment alanını zorunlu tutar; bu, derlemenin işlenen çıktıya aggrega.ai/environment etiketi olarak damgaladığı bir dizedir.
Diğer asimetriler
Kalan asimetriler (Recipe ile Component zorunlu alanları, Manifest’in mappings zorunluluğu) her varlığın rolünü yansıtır. Her varlık türünde tek tip bir zorunlu alan sözleşmesi isteyen yazarlar bunu bulamaz; asimetriler, role dayalı tasarım gereği kasıtlıdır.
Çapraz başvurular
labels-and-annotations.md— yayımlama yüzeyini tamamlayan, içerik tarafındaki meta veri mekanizması.entities/component.md— Component’inmetadata.labels.component.aggrega.ai/typegereksinimi veschema/usesSchema/featuresSchemabildirimleri.entities/release.md— Release’inmetadata.environmentalanı ve bu alanın zorunluluğu.10-status.md— meta veri zarfının durumu.architecture/02-ecosystem-philosophy.md— Katı API Bölümlemesi ve Kurumsal Meta Veri Paketi tasarım çerçevesi.architecture/13-catalog-and-registry.md§“Lockfile pinning and artifact immutability” + §“Catalog entity name-shape enforcement” — değişmezlik kuralının yayımlama anında neyi reddettiği ve varlık türüne göre ad biçimlerinin nerede denetlendiği: yayımlama disiplini plugin’i, bir yazaraggrega lintçalıştırdığında bunları tavsiye niteliğinde raporlar; ne derleme ne de yayımlama bunları denetler.architecture/11-governance-and-compliance.md§“Inheritance and publishing discipline” — hangi yönetişim kurallarının yayımlama disiplini plugin’ine ait olduğu ve hangilerinin bunun yerine genişleten bir Component’in kalıtımı tarafından yapısı gereği çözüldüğü.