İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

Katalog ve kayıt

Bu bölüm, platformun Open Container Initiative (OCI) Kataloğu aracılığıyla kurum genelinde nasıl ölçeklendiğini tanımlar: kataloğun nasıl düzenlendiğini, bir referansın nasıl çözümlendiğini, bir varlığın nasıl yayımlanıp sabitlendiğini ve katalog varlıklarının izlediği ad biçimlerini.

Aggrega kataloğu: kayıt taksonomisi ve çözümleme

Aggrega derleyicisi, soyut geliştirici niyetini (Alan 1) somut Ops gerçekliğine (Alan 3) çözümlemek için kesin olarak türlendirilmiş, OAM’den esinlenen bir kayda dayanır. Kesintisiz bir geliştirici deneyimini korurken açık, dağıtık bir ekosistemi desteklemek için tüm şemalar, altyapı bağlamaları, programlanabilir politikalar ve bağdaştırıcı eklentileri standartlaştırılmış bir Open Container Initiative (OCI) URI taksonomisini izler. Her katalog varlığı URI ile adreslenebildiğinden, aggrega pull bir Release’in ihtiyaç duyduklarını önbelleğe getirir ve kilit dosyasında sabitler; bir derleme de onları oradan okur. Geliştiricinin yerel çalışma alanı kataloğun bir kopyasını değil, yalnızca kendi Aggregate ve Release dosyalarını içerir.

1. Çekirdek dizin yapısı (katalog)

Standart kütüphanenin aggrega-catalog klasörü (ve uyumlu her üçüncü taraf kataloğu), sorumlulukların ayrılmasını fiziksel olarak uygulayacak şekilde düzenlenir. Yapı, soyut arayüzleri somut altyapı uygulamalarından açıkça ayırır.

Components ve Features için URI segmentleri dosya sistemi yol segmentleriyle 1:1 eşlenir. Components, kategori segmentinin kapalı bir bilişsel kategoriler kümesinden birini taşıdığı üç segmentli bir URI ({publisher}/{category}/{name}) kullanır — bileşenin component.aggrega.ai/category etiketiyle aynı sözcük (yayımlama linter’ının category-matches-directory kuralıyla denetlenen 1:1 dizin aynası). Features düz kalır ({publisher}/{name}) — küçük, yavaş büyüyen bir küme. Operasyonel ontolojik sınıflandırma (stateful-server, server vb.) dizin yapısında değil, her zaman component.aggrega.ai/type etiketinde bulunur; bilişsel yetenek etiketleri (datastore.aggrega.ai/engine, agent.aggrega.ai/autonomy, …) bunun üzerine davranışsal alt kümeler ekler. Hub web arayüzü filtreleme ve arama için etiketleri kullanır; kategoriler hem dosya sisteminde gezinmeye hem de kataloğun göz atma eksenine hizmet eder.

Aşağıdaki ağaç içeriği bakımından örnek niteliğinde, biçimi bakımından kesindir. Bir varlığın tamamen çizildiği yerde yaprak dosyasına kadar iner, böylece diyagramdan gerçek bir yolun tamamı okunabilir: hangi dizin düzeyinin hangi URI segmentini taşıdığı, zorunlu sürüm segmentinin nerede bulunduğu ve her varlık türünün yaprakta hangi dosya adını kullandığı. Kataloğun tüm içeriği yerine düzey başına bir avuç girdi gösterir — ... bir atlamayı işaretler ve yanına yazılan adlar aynı düzeydeki diğer girdilerdir.

aggrega-catalog/
│
├── schemalibrary/ # TIER 3: Reusable JSON Schema 2020-12 definitions
│ │ # Shared shapes (BaseComponentParameter,
│ │ # BaseDatastoreParameter) consumed from a Component or
│ │ # Feature schema via $ref: <Library>#/schemas/<name>
│ │ # Path: {name}/{version}/library.yaml
│ │
│ ├── ai-datastores/
│ │ └── 1.0.0/
│ │ └── library.yaml
│ └── base-components/
│ └── 1.0.0/
│ └── library.yaml
│
├── workloadlibrary/ # TIER 3: Reusable Workload template fragments
│ │ # Shared bodies (StatelessService) consumed from a
│ │ # Recipe via workload: { $import: <Library>#/workloads/<name> }
│ │ # Path: {name}/{version}/library.yaml
│ │
│ └── base-workloads/
│ └── 1.0.0/
│ └── library.yaml
│
├── component/ # DOMAIN 2: Abstract Interfaces
│ │ # URI: {publisher}/{category}/{name}
│ │ # Path: {publisher}/{category}/{name}/{version}/component.yaml
│ │ # type: core/datastore/mariadb:1.0.0
│ │ # → component/core/datastore/mariadb/1.0.0/component.yaml
│ │
│ ├── core/ # "core" = official Aggrega standard library
│ │ ├── ai-agent/ # AI agent frameworks, platforms, patterns
│ │ │ └── ... # anthropic, crewai, langflow, pydantic-ai, …
│ │ ├── ai-model/ # model providers and inference runtimes
│ │ │ └── ... # ai21, anthropic, azure-openai, openai, …
│ │ ├── ai-tool/ # tools agents invoke
│ │ │ └── ... # browser, mcp, search, …
│ │ ├── ai-pipeline/ # AI data/processing pipelines
│ │ │ └── ... # argo-workflows, temporal
│ │ ├── datastore/ # persistent datastores
│ │ │ ├── mariadb/
│ │ │ │ └── 1.0.0/
│ │ │ │ └── component.yaml
│ │ │ ├── postgres/
│ │ │ │ └── 1.0.0/
│ │ │ │ └── component.yaml
│ │ │ └── ... # etcd, ferretdb, qdrant, redis, valkey, …
│ │ ├── gateway/ # API and AI gateways
│ │ │ └── ... # apisix, contour, kong, nginx, …
│ │ ├── compute/ # generic compute primitives
│ │ │ └── ... # function, keda, server, task, worker, …
│ │ ├── messaging/ # event buses, queues
│ │ │ └── ... # kafka, nats, rabbitmq, …
│ │ ├── observability/ # metrics, logs, traces
│ │ │ └── ... # grafana, loki, otel-collector, prometheus, tempo, …
│ │ ├── security/ # identity, secrets, certificates
│ │ │ └── ... # cert-manager, external-secrets, keycloak, …
│ │ ├── devtool/ # developer-facing tooling
│ │ │ └── ... # adminer, promptlayer, …
│ │ └── storage/ # object/file storage, and the backup controllers
│ │ │ # that copy a cluster's resources, or its
│ │ │ # volumes' files, into a bucket
│ │ ├── s3-object-store/
│ │ │ └── 1.0.0/
│ │ │ └── component.yaml
│ │ └── ... # barman-cloud-plugin, gcs, k8up, velero, …
│ └── example/ # a second publisher, same three-segment shape
│ └── compute/
│ └── greeter/
│ └── 1.0.0/
│ └── component.yaml
│
├── feature/ # DOMAIN 2: Abstract Interfaces
│ │ # Flat: {publisher}/{name} (no category segment)
│ │ # Path: {publisher}/{name}/{version}/feature.yaml
│ │ # type: core/data-masking:1.0.0
│ │ # → feature/core/data-masking/1.0.0/feature.yaml
│ │
│ ├── core/
│ │ ├── data-masking/
│ │ │ └── 1.0.0/
│ │ │ └── feature.yaml
│ │ ├── secret-value/ # feature.aggrega.ai/kind: secret
│ │ │ └── 1.0.0/
│ │ │ └── feature.yaml
│ │ └── ... # k8s-dns-resolver, public-ingress, retry-policy, …
│ └── ... # other publishers, same flat shape
│
├── aggregate/ # DOMAIN 1: Reusable Aggregate Modules
│ │ # Path: {publisher}/{name}/{version}/aggregate.yaml
│ └── core/
│ ├── keycloak/
│ │ └── 1.0.0/
│ │ └── aggregate.yaml
│ └── ... # agenta, apisix, dify, harbor, kong, thanos, …
│
├── recipe/ # DOMAIN 3: Concrete Implementations
│ │ # Organized by CAPABILITY (the one a Recipe declares
│ │ # in spec.capability).
│ │ # Path: {capability}/{name}/{version}/recipe.yaml
│ │ # The version directory may bundle the Recipe's own
│ │ # source charts or modules beside recipe.yaml.
│ │ # OCI: hub.aggrega.ai/recipe/helm/mariadb:1.0.0
│ │
│ ├── helm/
│ │ ├── mariadb/
│ │ │ └── 1.0.0/
│ │ │ └── recipe.yaml
│ │ └── postgres/
│ │ └── 1.0.0/
│ │ └── recipe.yaml
│ ├── compose/
│ │ └── mariadb/
│ │ └── 1.0.0/
│ │ └── recipe.yaml
│ ├── terraform/
│ │ └── mariadb-rds-module/
│ │ └── 1.0.0/
│ │ ├── recipe.yaml
│ │ └── module/ # bundled Terraform source
│ │ ├── main.tf
│ │ └── variables.tf
│ └── cloudformation/
│ └── postgres-rds/
│ └── 1.0.0/
│ └── recipe.yaml
│
├── feature-recipe/ # DOMAIN 3: Concrete Implementations
│ │ # Capability leads the path, same as recipes.
│ │ # Path: {capability}/{name}/{version}/recipe.yaml
│ │
│ ├── helm/
│ │ ├── k8s-secret-from-parameter/
│ │ │ └── 1.0.0/
│ │ │ └── recipe.yaml
│ │ └── public-ingress/
│ │ └── 1.0.0/
│ │ ├── recipe.yaml
│ │ └── chart/ # bundled Helm source
│ │ ├── Chart.yaml
│ │ └── templates/
│ │ └── ingress.yaml
│ ├── compose/
│ │ └── dotenv-secret/
│ │ └── 1.0.0/
│ │ └── recipe.yaml
│ └── ... # terraform, cloudformation
│
└── plugin/ # ARTIFACTS: Plugin entities, each a content-addressed
│ # reference to a Wasm artifact. The compiled artifact
│ # is published separately and is not stored here.
│ # Path: {pluginType}/{name}/{version}/plugin.yaml
│
├── linter/
│ └── publishing/
│ └── 0.5.0/
│ └── plugin.yaml
└── provider/ # the directory mirrors metadata.pluginType
├── helm/
│ └── 0.5.0/
│ └── plugin.yaml
└── ... # cloudformation, compose, helm-chart, terraform

Bileşen kategorileri kapalı bir kümedir ve kategori yetkisi dosya sistemi değil — bu kümedir. Henüz hiçbir varlığı olmayan bir kategori değeri ayrılmış sözcük dağarcığıdır: göz atma ekseni kararlı kalır ve bir yazar gelecekteki bir bileşenin nereye düşeceğini bilir; dolayısıyla boş bir raf, bir doldurulmayı bekleyen boşluk değil, doğru bir durumdur. Katalog yer tutucu dosya taşımadığından, böyle bir değerin dizini ilk varlığı geldiğinde oluşturulur.

Yetkili liste — her kategori, ne içerdiği, varlıklarının tipik olarak taşıdığı operasyonel type değerleri ve hangi dizinlerin var olduğu — katalog uzlaşımları kılavuzunun Component kategorileri bölümüdür; bu kılavuz, yönettiği standart kitaplık kataloğuyla birlikte yayımlanır.

type ekseni yalnızca operasyonel temel öğeleri taşır — bilişsel sözcük dağarcığı hiçbir zaman burada görünmez ve yayımlanmış Component şeması ayrılmış anahtarın aldığı değerleri listeler; bu nedenle oraya yazılan bilişsel bir sözcük belge yüklenirken reddedilir. Üç eksenli ayrım: operasyonel type (altyapının bileşene nasıl davrandığı), bilişsel category (bileşenin ne olduğu, dizin tarafından yansıtılır) ve rol başına yetenek etiketleri (davranışsal alt kümeler — bir varlık category: datastore artı kendi ürün kimliğinin taşıdığı datastore.aggrega.ai/engine değeridir; böylece core/datastore/qdrant vector’ü, core/datastore/redis de kv’yi taşır ve her iki eksen de sorgulanabilir). Doğruluğu bir yazarın neyi yapılandırdığına bağlı olan bir yetenek katalogda hiç taşınmaz: derleme zamanında, geliştiricinin bildirdiği values’ı okuyan yönetişim soketinin label-transform rolü tarafından enjekte edilir. Tamamen yapay zekâya yönelik kategoriler ai- önekini taşır; çift kullanımlı kategoriler öneksiz görünür ve yapay zekâ niteliği yetenek etiketleriyle ifade edilir. Kategoriler, derleyicinin nasıl sınıflandırdığına göre değil, kullanıcıların nasıl gezindiğine ve göz attığına göre seçilir — kategori sözcük dağarcığı ve yetenek etiketleri, derleyicinin seçicileri eşleştirdiği ve hiçbir anlam yüklemediği terimlerdir. Bir bileşenin adı kategorisini tekrarlamaz: standart kitaplığın OpenAI modeli core/ai-model/openai-model değil, core/ai-model/openai’dır.

2. Bölünmüş şema ve köprü sentezi işlem hattı

Topoloji soketi bildirimlerinin etrafındaki Component başına şablon kodu ortadan kaldırmak için Aggrega doğrulamayı iki parçaya böler ve her birini konusunun bulunduğu yerde denetler:

  1. usesSchema (bildirimsel YAML). Bir katalog varlığının sunduğu topoloji soketlerini bildirir ve her birine bir sözleşme verir. Go CLI, statik analiz sırasında etiket eşleştirmesi için selector: dizelerini çıkarmak ve izin verilen inject mekanizmalarını doğrulamak için bunu yerel olarak okur. Her soket girdisi isteğe bağlı bir required: true alanını destekler (varsayılan false) — ayarlandığında, o sokette hiçbir bağımlılık bildirilmemişse derleyici bir doğrulama hatası üretir. Bu, featuresSchema girdilerindeki required: true semantiğinin soket karşılığıdır: ikisi de derlemeyi durdurur. Bir soketi burada bildirmek, standart kütüphane kataloğunun yaptığı şeydir ve daha iyi yol olmayı sürdürür — ancak bir geliştiricinin bir kenar çizebileceği tek yol bu değildir. Bir Aggregate yazarı, kendi bileşeni üzerinde bu usesSchema’nın bildirmediği bir soketi adlandırabilir; buna hiç usesSchema bildirmeyen bir varlık da dahildir; böyle bir ad hoc soket hiçbir seçici, hiçbir inject izin listesi ve hiçbir kenar başına şema taşımaz, çünkü burada bunları taşıyacak bir girdi yoktur. Bir Feature eklemesinin uses’u ve bir Release’in kenar başına uses’u bu şekilde açık değildir — ikisi de yalnızca bildirilmiş bir soketi adlandırabilir. Tam sözleşme ve bir ad hoc soketin nelerden vazgeçtiği için bkz. dependency-resolution §“Alan 2: Bölünmüş şema”.
  2. Desugaring. Geliştiriciler YAML dizi kısaltmasını (uses: databases: ["db1"]) kullanırsa CLI bunu bir eşlemeye ({"db1": {"target": "db1"}}) normalleştirir.
  3. Köprü sentezi. Derleyici, featuresSchema: yuva tablosunu bir JSON Schema 2020-12 parçasına yansıtır — her ekleme yuvası için bir özellik; bu özellik, yuvayı bağlayabilecek bir dolgunun biçimini tanımlar ve bir inject izin listesi bildiren yuvada bir x-aggrega-inject: uzantı anahtar sözcüğü bulunur. JSON Schema doğrulaması, yapısal doğrulama sırasında uzantı anahtar sözcüklerini yok sayar ve hiçbir şey bunlardan birini parçadan geri okumaz: bir yuvanın izin listesine ihtiyaç duyan bir denetim yuvanın kendisini okur. usesSchema: soket tablosu hiçbir parçaya yansıtılmaz. Bir soketin selector: ve inject: değerleri, mimarın yazdığı tipli YAML’da kalır ve oradan okunur; bir soketin kenar başına valueSchema: / infraSchema: değeri ise kendi başına sarmalanır ve derlenir, etrafına hiçbir kısıtlama uydurulmaz.
  4. Kompozisyon. Platform mimarı, values, infra ve provides tanımlayan katı bir schema: bildirimi (kompakt biçim veya tam JSON Schema 2020-12) yazar. Bu bildirim varlığın kendi sözleşmesidir ve kendi başına derlenir: ne yuva parçası ne de soket tablosu bunun içine katılır. Her yüzey, konusunun bulunduğu yerde denetlenir; böylece bir soket hatası, schema: bloğunun içindeki bir yolda değil, mimarın yazdığı soket girdisinde raporlanır — ve mimar yine hiçbir uses şablon kodu yazmaz.

Örnek — bir soket bildirimi ve derleyicinin onunla ne yaptığı: Platform mimarının YAML’ı

spec:
usesSchema:
databases:
selector: "component.aggrega.ai/type=stateful-server"
inject: ["env", "file", "ssm_param"] # env and file are core mechanisms; ssm_param is a user-provided mechanism
schema:
values:
ha_mode: { type: boolean, default: false }
infra:
replicas: { type: integer, min: 1 }
provides:
host: { type: string, required: true }
assertions:
# The Architect can write cross-pillar invariants against the unified instance content.
ha-mode-needs-two-databases: |
{{- if eq .values.ha_mode true -}}
{{- if lt (len .uses.databases) 2 -}}
{{- fail "ha_mode=true requires at least two database attachments" -}}
{{- end -}}
{{- end -}}

Derleyicinin onunla ne yaptığı Soket tablosu, olduğu gibi tipli YAML olarak okunur: selector: dizesi yerel etiket eşleştirme motoruna gider ve inject: listesi, o soketten geçen bir kenarın hangi teslim mekanizmalarını adlandırabileceğini kısıtlar. schema: bloğu, varlığın kendi values / infra / provides sözleşmesi olarak ayrıca derlenir. Statik analizör, selector: dizesini mimarın yazdığı soket girdisinden okur — Feature varlıklarındaki appliesTo / appliesToAnyOf ile birlikte — ve düğümler arası tür güvenliğini doğrulamak için etiket eşleştirmesini her hedefin metadata.labels değerine karşı değerlendirir.

usesSchema’da Kubernetes tarzı seçiciler

Go derleyicisinin yerel etiket eşleştirme motoru, seçici dizelerini standart Kubernetes tarzı seçim semantiğiyle değerlendirir (AND virgülle, OR in() ile, NOT !=/notin() ile). Aynı motor — ve aynı seçici dizesi dilbilgisi — Feature ekleme seçicilerini de (appliesTo ve appliesToAnyOf’un her öğesi) değerlendirir. Seçici katmanı yalnızca topoloji kapısıdır — sütun başına schema: bildirimleri values, infra ve provides içeriğini bağımsız olarak doğrular. Go derleyicisi topoloji oluşturma sırasında topolojik kenarları çizdikten sonra statik analizör, selector dizelerini mimarın yazdığı soket girdilerinden okur ve düğümler arası tür güvenliğini doğrulamak için bunları hedef düğümün katalog labels değerine karşı değerlendirir.

usesSchema:
# 1. The AND Operator (Comma)
databases:
selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
# 2. The OR Operator (Set-based 'in')
datastores:
selector: "datastore.aggrega.ai/engine in (relational, vector)"
# 3. The NOT Operator
internal_systems:
selector: "compliance.aggrega.ai/data-class!=public"

Motorun altı gereksinim biçiminden biri olarak okuyamadığı bir seçici — boş bir gereksinim, boşluk ya da =, !, (, ) ve virgülden birini içeren bir anahtar, kapatılmamış bir küme — başka bir seçici olarak okunmak yerine koruduğu her kenarda derlemeyi durdurur. Seçici dilbilgisi biçimleri ve her reddi listeler.

3. Şema biçimleri ve kompozisyon

Hem katı doğrulama hem de standart katalog meta verileri (yazar, sürüm, açıklama) sağlamak için Alan 2 (Arayüzler) ve Alan 3 (Gerçeklemeler) tanımları YAML zarfları olarak yazılır. Alan 2, kompakt biçimde (varsayılan; ~15 anahtar sözcük, mekanik olarak JSON Schema 2020-12’ye dönüştürülür) ya da tam JSON Schema YAML’ında ifade edilen gömülü schema: bildirimlerini kullanır.

Her katalog YAML’ı neden zarfı tekrarlar. Zarf (apiVersion, kind, metadata bloğu), gövde ne kadar kısa olursa olsun her katalog dosyasının en üstünde yer alır — Component, Feature, Recipe, FeatureRecipe, Aggregate, Manifest, Release, Plugin. Tekrar kasıtlıdır: her dosya, bağımsız bir yapıt olarak ayrıştırılmak, doğrulanmak, lint’ten geçirilmek ve incelenmek üzere tasarlanmıştır. OCI kayıt defterinden çekilen, bir CI sanal alanına bırakılan ya da üçüncü taraf bir düzenleyicide açılan tek bir dosya, aşağı akıştaki araçların hangi tür varlığı temsil ettiğini ve hangi şema sürümünün geçerli olduğunu belirleyebileceği kadar öz tanım taşımalıdır. Dizin konumu hiçbir zaman zarfın yerini tutmaz: her ayrıştırıcı, doğrulayıcı ve linter varlığın türünü ve şema sürümünü zarftan okur. Maliyet, dosya başına mekanik şablon koddur; fayda ise bağımsız araç garantisinin OCI dağıtım yüzeyi, yerel dosya sistemi ve IDE / CI / inspect yüzeyleri boyunca geçerli olmasıdır. Yazarlar yeni katalog içeriği yazarken zarfı mevcut dosyalardan kopyalar ya da tür için apiVersion ve kind doldurulmuş bir başlangıç belgesi yazdıran aggrega scaffold <kind> ile başlar.

DRY (Don’t Repeat Yourself, “kendini tekrarlama”) ilkesini korumak için katalog iki ayrı kompozisyon mekanizması kullanır:

  • Paylaşılan SchemaLibrary girdileri (belgeler arası $ref:): Yeniden kullanılabilir JSON Schema tanımları SchemaLibrary katalog varlıklarında (Tier 3) saklanır. Bunlara, tüketen herhangi bir Component veya Feature şemasından belgeler arası $ref: (<library>#/schemas/<entry>, ana bilgisayarsız — sürüm kilit dosyasından gelir) aracılığıyla kimlikle başvurulur. Zincir derleme zamanında dolaşılır. Kütüphane varlığının yazım biçimi için entities/schemalibrary, çözümleme semantiği için vocabulary/cross-document-ref sayfasına bakın.
  • Tekli kalıtım (extends): Eksiksiz bileşen temelleri için varlıklar extends: "URI" özelliğini kullanabilir. Go derleyicisi üst öğe zincirini özyinelemeli olarak okur ve YAML meta verilerini derinlemesine birleştirir (çakışmada etiketlerin üzerine yazar ve dizileri sona ekler). Ardından iki katalog türü veri sütunlarında yollarını ayırır. Bir Feature’ın schema: değeri, JSON Schema 2020-12 kompozisyonu altında tabanınkiyle birleşir. Genişleten bir Component hiç sütun içeriği yazmaz: schema: inherited sabit işaretçisini yazar ve tabanının schema: bloğunu, zincirin her derinliğinde, taban onu nasıl yazdıysa tam olarak öyle alır. Böyle bir Component’in bunun yerine birleştirdiği şey yapıdır — ekleme yuvaları (featuresSchema), topoloji soketleri (usesSchema), öz enjeksiyon izin listesi (inject) ve adlandırılmış assertions değerleri zincir boyunca birleşir. Taban ve alt bileşen genişletme örnekleri için entities/component + kalıtımın yapısı gereği neyi çözdüğü ve neyin bir yayımlama disiplini kuralı olarak kaldığı için governance-and-compliance §“Kalıtım ve yayımlama disiplini” sayfasına bakın.

Taban ve alt bileşen genişletme örnekleri için entities/component, eksiksiz örneklerle işaretçi ve eşleyici tabanlı Recipe yazımı için entities/recipe sayfasına bakın.

4. Çalışma alanı yapılandırması (.aggrega-config.yaml)

Çalışma alanı kökündeki .aggrega-config.yaml dosyası, projenin çalışma alanı yapılandırmasıdır — çalışma alanının kendi bildirimidir ve go.mod ya da package.json gibi kaynak denetimine uygundur. .aggrega/ dizini uzlaşım gereği kaynak denetiminin dışında tutulur — node_modules/ veya .terraform/ için yapacağınız gibi onu .gitignore dosyasına ekleyin.

workspace bölümü kök işaretçisidir: varlığı çalışma alanı kökünü belirler ve yalnızca kökü tanımlayan katalog dizinlerini taşır — catalog_dirs ve bir Release’e kendi katalog dizinlerini veren releases eşlemesi. Diğer tüm ayarlar en üst düzeyde yer alır. Birçoğu tekil değerdir; diğerleri ise tek bir konunun ayarlarını tek bir anahtar altında toplayan bölümlerdir. Her alan isteğe bağlıdır ve belgelenmiş varsayılanlara sahiptir. Her biri türü, varsayılanı ve anlamıyla birlikte en üst düzey anahtarların eksiksiz ve güncel kümesi schema/other/aggrega-config adresindeki şemadan üretilir; aşağıdaki örnek, kök işaretçisini tek değerli ayarlardan birkaçıyla birlikte gösterir:

.aggrega-config.yaml
workspace: # Root marker; presence marks the workspace root
catalog_dirs: # Ordered list of local catalog directories (checked before cache)
- ./aggrega-catalog
default_registry: hub.aggrega.ai # Default registry for unqualified URIs
offline: false # Set true for air-gapped environments
auto_pull: true # Opt in to the implicit pull; the default is false, keeping build read-only
artifact_cache_dir: .aggrega/cache # On-disk artifact cache root

Bir signing: bloğu, aggrega push --sign ve aggrega sign tarafından kullanılan yapıt imzalama varsayılanlarını hem en üst düzeyde (genel) hem de kayıt defteri başına taşır:

.aggrega-config.yaml
signing: # Global signing defaults
fulcio_url: https://fulcio.sigstore.dev # Keyless certificate authority (defaults to public-good)
rekor_url: https://rekor.sigstore.dev # Keyless transparency log (defaults to public-good)
timestamp_url: https://tsa.example.com/api/v1/timestamp # Optional RFC3161 timestamp authority (no default; opt-in)
key_path: ./keys/signing.pem # Optional: path to a held keyed-key PEM (a pointer, never inline material)
registries:
- host: hub.example.com
signing: # Per-registry override of the global signing block
key_path: ./keys/hub.pem

Alan başına öncelik sırası şöyledir: CLI bayrağı > kayıt defteri başına signing > genel signing > kamu yararına varsayılan. Fulcio ve Rekor varsayılan olarak Sigstore’un kamu yararına örneklerini kullanır, bu nedenle isteğe bağlıdır; timestamp_url’nin varsayılanı yoktur — anahtarsız güvenilir zaman damgası, Rekor’un şeffaflık günlüğüne dahil edilmeden gelir ve bir RFC3161 zaman damgası yetkilisi isteğe bağlıdır (birini etkinleştirmek için timestamp_url veya --timestamp-url değerini tam bir uç noktayla ayarlayın). Güvenlik: signing: bloğu hiçbir gizli malzeme taşımaz — OIDC kimlik belirteci hiçbir zaman bir yapılandırma alanı değildir (kısa ömürlü bir sırdır ve imzalama anında sağlanır: etkileşimli bir terminalde bir tarayıcı akışıyla ya da GitHub Actions’ta iş akışından edinilir, aksi hâlde --identity-token ile iletilir veya AGGREGA_IDENTITY_TOKEN ya da SIGSTORE_ID_TOKEN olarak dışa aktarılır) ve özel anahtar hiçbir zaman satır içi değildir; key_path bir anahtar dosyasının yoludur. Bu, satır içi bir genel anahtarı sabitleyen doğrulama tarafıyla kasıtlı bir asimetridir; imzalama tarafında ise her zaman yalnızca bir anahtar yolu bulunur.

Satıcıya dahil edilmiş katalogu olmayan bir kökü workspace: {} yazarak işaretleyin. catalog_dirs listesi, paylaşılan bir kataloğun kardeş bir dizinde bulunduğu monorepo kurulumlarını destekler. Derleyici her dizini sırayla denetler. offline: true bayrağı her türlü ağ erişimini engeller — derleyici yalnızca yerel yolları ve önbelleği kullanır, bir varlık yerel olarak bulunamazsa durur. Bölümlü ayarların her biri tek bir konuyu toplar. Bunlar arasında şunlar vardır: derleme zamanı katılık ayarları ve yazım ipuçları; her biri bir eklenti başvuruları listesi alan çalışma alanı düzeyindeki Wasm ekleme soketleri (governance, linter, importer, providers, cli); yayımlama disiplini ilke anahtarları dahil kural başına lint katılığı; arka plan hizmetinin ayrıştırma önbelleği ayarı ve istek dağıtımı çalışan havuzunun boyutu; ve makine genelindeki derlenmiş modül deposunun boyut sınırı. Diğerleri ise imzalama ve imza güveni varsayılanlarını ve arka plan hizmetinin kendi davranışını taşır. Her en üst düzey anahtar, schema/other/aggrega-config adresinde eksiksiz olarak belgelenmiştir.

Üç ayrı önbellek yapılandırılabilir ve adları benzer, kapsamları ise farklı olduğu için bunları birbirinden ayırmaya bir dakika ayırmaya değer. artifact_cache_dir, aşağıda açıklanan çalışma alanı başına diskteki içerik önbelleğini adlandırır. parse_cache, arka plan hizmetinin yalnızca hizmet çalıştığı sürece yaşayan bellek içi ayrıştırma önbelleğini sınırlar. compiled_module_cache, derlenmiş eklenti makine kodunun diskteki deposunu sınırlar — bu, makinedeki tüm çalışma alanlarının paylaştığı önbelleklerden biridir, çünkü bir eklentinin derlenmiş biçimi onu kullanan projeye değil, eklentinin kendisine bağlıdır:

# .aggrega-config.yaml — most at home in the global config file, since the store is machine-wide
compiled_module_cache:
max_bytes: 53687091200 # Default 50 GiB; 0 disables the cap

Makinedeki tüm projelerin paylaştığı önbellekler arasında disk önbelleği kullanımına hâkim olabilecek olan budur, çünkü makinenin çalıştırdığı her eklenti buna bir kez derlenir ve saklanır; bu yüzden kalıcı bir boyut sınırı olan tek önbellek de budur. Depoyu açan her çağrı, herhangi bir şey derlemeden önce sınırı uygular ve kalan kısım sığana kadar, en önce derlenenden başlayarak girdileri bütün olarak kaldırır. (--disable-plugin-cache ile çalıştırılan bir derleme bunun yerine belleğe derler, bu nedenle depoyu ne büyütür ne de kırpar.) Bir girdiyi kaldırmanın maliyeti sonraki bir yeniden derlemeden ibarettir; sınırı düşürmeyi ve aynı makinede başka derlemeler çalışırken uygulamayı güvenli kılan da budur. Sınırı tek bir derlemenin derlediğinin üzerinde ayarlayın: sınır derlemeden önce uygulandığı için, tek bir derlemenin kendi çalışma kümesinin altındaki bir sınır her derlemenin aynı modülleri atıp yeniden derlemesine yol açar; aynı nedenle depo, derlemeler arasında sınırın üzerinde kalabilir ve bir sonrakinin başında yeniden kırpılır. aggrega cache status deponun boyutunu bildirir, aggrega cache evict --max-size ise onu istek üzerine komut satırında verilen bir sınıra kırpar.

artifact_cache_dir kökü, tek bir aggrega pull çağrısının tek tip biçimde doldurduğu, sabitlenmiş bağımlılığın her sınıfı için bir tane olmak üzere üç paralel alt ağaç taşır: katalog varlıkları (Components, Features, Recipes, FeatureRecipes, Aggregates, kütüphaneler ve yayımladıkları yürütülebilir dosyalarla birlikte Plugins) için <artifact_cache_dir>/entities/<encoded-kind>/<encoded-reference>/<encoded-version>/, burada tür varlığın yayımlandığı türdür, bu yüzden bir başvuruyu ve bir sürümü paylaşan farklı türlerden iki varlık — aynı adı taşıyan bir Component ile bir Recipe — iki ayrı yuvadır; Recipe / FeatureRecipe spec.source alanlarından çekilen kaynak yapıtları (Helm chart’ları, compose parçaları) için <artifact_cache_dir>/source-artifacts/<kind>/<host>/<path>/<version>/<digest-prefix>/; ve harici girdiler için <artifact_cache_dir>/inputs/sha256/<hex-digest> — bir provider’ın işleme sırasında ana bilgisayardan istediği uzak belgeler, örneğin bir chart’ın values.schema.json dosyasında bir URL’yi gösteren bir $ref. Her kaynak yapıt önbellek yuvası, yetkili .tgz arşivini, her derleme okumasında yeniden üretilen türetilmiş bir extracted/ dizinini ve yapıtın {kind, url, version, digest, mediatype, pulled_at} kimliğini kaydeden bir metadata.yaml dosyasını taşır. Her varlık önbellek yuvası, yayımlanan yapıtı getirildiği hâliyle ve doğrulandığı OCI manifestini taşır. Belgesi yanında bir dosyayı adlandırabilen her türün yuvası — bir Recipe, bir FeatureRecipe, bir Component, bir Feature — ayrıca o yapıtın taşıdığı dosyaları, yapıtın içerik özetiyle adlandırılmış bir dizinde tutan türetilmiş bir extracted/ dizini taşır: varlık arşiv olarak yayımlandıysa belge ve varlığın bildirdiği dosyalar, belge olarak yayımlandıysa yalnızca belge (§6). Varlığın dizini, bir kaynak yapıtın dosyalarında olduğu gibi, her okumada doğrulanmış yapıttan oraya yerleştirilir: her dosya yapıta karşı denetlenir, o dizinde elle değiştirilen veya eklenen bir dosya okunmak yerine atılır, extracted/ altındaki başka hiçbir şey okunmaz ve doğrulamayı geçemeyen bir yapıt, herhangi bir şey yerleştirilmeden önce reddedilir. Bir okuma yalnızca yapıttan farklı olanı yeniden yazar; böylece aynı anda tek bir önbelleği okuyan derlemeler — aggrega serve’ün yan yana işlediği istekler ya da tek bir çalışma alanı üzerindeki iki komut — kendilerine verilen dosyaları her biri eksiksiz bulur. 12 karakterlik <digest-prefix> kesimi, farklı upstream özetlerinde yeniden etiketlenmiş aynı {kind, url, version} değerini ayrı yuvalara ayırır. Harici bir girdinin böyle bir yuvaya ihtiyacı yoktur: kilit dosyasının onu sabitlediği içerik özetiyle adlandırılmış tek bir dosya olarak saklanır; böylece sonraki bir derlemenin okuduğu şey, baytların geldiği URL ile değil, sabitlemeyle adreslenir — o derlemenin girdiyi ağ engellenmişken sunabilmesini sağlayan da budur.

Bu üçünün yanında üç dizin daha görünebilir ve hiçbiri sabitlenmiş bağımlılık içeriği tutmaz: index/, aggrega registry update’in yazdığı kayıt defteri başına aranabilir anlık görüntüleri taşır (§8); signatures/, doğrulanan her imza paketini kendi özeti altında önbelleğe alır, böylece sonraki bir okuma, paketi yeniden getirmek yerine önbellekteki blob’u kaydedildiği özete karşı yeniden denetler; catalog-snapshots/ ise bir içe aktarmanın okuduğu her yayımlanmış katalog anlık görüntüsünü saklar (§8) — arşiv ve manifestosu, manifesto özetiyle adlandırılmış bir yuvada durur, katalog ağacı her okumada arşivden yeniden yerleştirilir ve hiçbir şey başka birini adlandırmadığında çalışma alanının okuduğu anlık görüntüyü adlandıran bir current dosyası bulunur.

Belge paketi bunlar arasında değildir. Baytları yalnızca yayımlandığı kayıt defterine ve yayımlandığı sürüme bağlıdır; bu nedenle makine başına bir kez, aynı kullanıcı başına önbellek kökü altında derlenmiş modül deposunun yanında, o kökün altındaki docs-bundles/<encoded-reference>/<encoded-version>/ konumunda tutulur: paket, doğrulandığı manifest ve getirmelerinin doğruladığı imzalar. artifact_cache_dir ona ulaşmaz. Ondan bir sayfa okunmadan önce bu imzalar, okuyan çalışma alanının paketin kayıt defteri için kendi imza denetimi altında yeniden doğrulanır; böylece bir çalışma alanının daha gevşek ayarlarının içeri aldığı bir kopya, denetimi onu reddeden bir çalışma alanına sunulmaz — bkz. aggrega-explain ve aggrega-cache.

artifact_cache_dir, çalışma alanı köküne göreli olarak yazılır ve bir komutun hangi dizinden çağrıldığından ya da hangi katalog dizinlerinin tarandığından bağımsız olarak aynı dizini ifade eder. Mutlak bir değer, yapılandırma yüklenirken alanı adlandıran bir tanılamayla reddedilir: ayarın her okuyucusu onu çalışma alanı köküne göre çözümler; bu yüzden mutlak bir yol hiçbirinin ulaşamadığı bir konumu adlandırır ve hata aksi hâlde sessiz kalırdı — bir pull’un yazdığı önbellek, sessizce bir derlemenin okuduğu önbellek olmaktan çıkardı. Önbellek bir katalog dizininin içinde bulunabilir ve varsayılan düzende de öyledir, çünkü bir katalog dizini genellikle çalışma alanı kökünün kendisidir. Yapmaması gereken şey, bir katalog dizini olmaktır: bir katalog taraması önbelleği atlar; bu nedenle aynı zamanda bir katalog dizini olan bir önbellek dizini, o dizinin tüm içeriğini her taramanın dışında bırakır. artifact_cache_dir: . çalışma alanı kökünü adlandırır; bu, varsayılan düzende tam olarak bu durumdur ve yapılandırma yüklenirken alanı adlandıran bir tanılamayla reddedilir — çalışma alanı köküne indirgenen diğer her yazım gibi. Bu iki biçim, yukarıdaki mutlak yolla birlikte, yapılandırma denetiminin kendi başına tanıyabildikleridir. Başka bir katalog dizinini adlandıran bir değer — catalog_dirs değeri sub’ı listeleyen bir çalışma alanında sub — itirazsız yüklenir ve tek belirti, altındaki varlıkların artık bulunamamasıdır. Bu nedenle önbelleği workspace.catalog_dirs içinde listelenen her dizinin dışında tutmak, yapılandırmanın sizin için denetlediği bir şey değil, yapılandırmayı yazmanın bir parçasıdır.

Önbelleği atlamak, bir çözümleme yapıtının sanki bir yazar yazmış gibi okunmasını önleyen şeydir. Bir önbellek yuvası, bir kayıt defteri getirmesinin oraya yerleştirdiği, getirildikleri koordinat altında saklanan ve bir kilit dosyası özetiyle güvence altına alınan baytları tutar; bunlardan birini yazılmış katalog içeriği olarak alan bir tarama, yazarın düzenleyemediği bir yolda hiçbir şeyin doğrulamadığı baytları almış olurdu. Bir sonucu açıkça belirtmekte yarar var: önbellek, hiçbir kilit dosyasının sabitlemediği bir varlık tutuyorsa — yarıda kalan bir pull’dan geriye kalmış, elle kopyalanmış ya da bir Release ona başvurmayı bıraktığında sahipsiz kalmış — o varlık bir katalog taramasına görünmez ve ona bağlı bir derleme ya da doğrulama, varlığın bulunamadığını söyleyerek durur. Çözüm, Release’i yeniden pull etmektir; böylece varlık kilit dosyası üzerinden çözümlenir ve özeti kaydedilir; durma, eksik sabitlemenin belirlenebilmesi için varlığı adlandırır. Alternatif — onu yine de çözümlemek — tam da önbelleği atlamanın önlemek için var olduğu doğrulanmamış okumadır.

Lockfile her Release için ayrıdır: release.yaml çözümlendiğinde yanına release.lock yazılır (Release dosyasının kök adı artı .lock). aggrega pull bağımlılıkları çözümler ve lockfile’ı yazar; aggrega build onu okur ve derleme anındaki registry durumundan bağımsız olarak sabitlenmiş sürümleri kullanır. Derlemenin makineler arasında yeniden üretilebilirliği önemli olduğunda çalışma alanları lockfile’ı commit eder; çalışma alanında bir varlık, bir kütüphane, bir plugin ya da Release’in kendisi değiştikten sonra aggrega pull --release <release> onu yeniler, değişeni yeniden çözümlerken diğer tüm sabitlemeleri korur; bir registry’nin artık sunduğu daha yeni bir sürüm ise aggrega pull --upgrade --release <release> ile benimsenir. Lockfile, çözümlenen her varlığı türü, yazıldığı haliyle URI’si, çözümlenen sürümü, içerik digest’i ve ona başvuran yerlerle birlikte kaydeder. Tür ve URI birlikte bir girdiyi tanımlar; bu nedenle Aggregate’i ile Manifest’i aynı adı taşıyan bir Release her biri için bir girdi kaydeder ve bunlardan herhangi birinde yapılan bir düzenleme, bir pull onu kaydedene kadar sonraki derlemeyi durdurur:

# release.lock
entities:
- kind: component
uri: core/datastore/mariadb:1.0.0
resolved_version: 1.0.0
digest: sha256:5deeedb9acc1be00d4e0f98e55e01d301a0bcc01d702c015a9d9628ff573650a
referenced_from:
- aggregate.spec.components.db.type
- kind: recipe
uri: mariadb-bitnami:1.0.0
resolved_version: 1.0.0
digest: sha256:215b54e2da1ce512fcdccff87f6f71daac707bc77e4214b60b946b27a24e483a
referenced_from:
- manifest.spec.mappings.components.type.core/datastore/mariadb:1.0.0
generated_at: "2026-06-11T16:48:15Z"
mapping_libraries: []
plugins: []
release: release.yaml
schema_libraries: []
source_artifacts: []
version: 1

Sabitlenmiş her girdi tür + URI + çözümlenen sürüm + içerikle adreslenebilir digest taşır. Digest her getirmede doğrulanır; sabitlenmiş digest ile eşleşmeyen baytlar derlemeyi bir bütünlük hatasıyla durdurur. Bir varlığın digest’i, aktarıldığı baytlar üzerinden değil, onun bir yayınının taşıdıkları üzerinden alınır — belgesi ve yanında bildirdiği her dosya, her biri yolu ve baytlarıyla — böylece aynı varlık, ister bir katalog dizininden okunsun ister bir registry’den getirilsin, arşivi nasıl sıkıştırılmış olursa olsun ve bir checkout dosyalarına yürütme biti dahil hangi izin bitlerini vermiş olursa olsun aynı digest’i kaydeder. Bir getirme önce, registry’nin yayınlanan baytlar üzerinden kendi hesapladığı digest’e karşı denetlenir; bu, registry üzerinden çözümlenen bir girdinin kendi digest’inin yanına kaydettiği manifest digest’i aracılığıyla yapılır.

5. Üç katmanlı varlık çözümleme modeli

Derleyici, derleme sırasında karşılaştığı her varlık başvurusunu katı bir kademeli arama ile çözümler. Üç katman — yerel yol, çalışma alanı ve önbellek, registry — sağlıklı bir Aggrega projesinde bir arada bulunan üç yazım iş akışına karşılık gelir: yanındaki dosyaları adlandıran bir Release, depoya işlenmiş bir kataloğu ve daha önce çekilmiş önbelleği kullanan bir ekip ve henüz getirilmemiş bir artefakt için registry’ye ulaşan bir pull. Aynı kademenin çalışma alanı ve önbellek katmanı ile registry katmanı, Aggregates içindeki type alanlarını, Manifest eşlemelerindeki URI değerlerini, Recipes ve FeatureRecipes üzerindeki implements bildirimlerini ve Recipe ile FeatureRecipe işlem hatlarındaki plugin başvurularını değerlendirir; yerel yol katmanına yalnızca bir Release’in ve onun Manifest’inin adlandırdığı dosyalar ulaşır.

Yerel yol. Bir Release’in ./ veya ../ (bir POSIX göreli yol öneki) ile başlayan aggregate, manifest veya extends başvurusu ya da bir Manifest’in extends başvurusu, Release’e göre doğrudan diskten okunur. Katalog araması yok, registry çağrısı yok. Açık önek, sözdizimi düzeyinde yerel yol niyetini ad aramasından ayırır: aggregate: ./aggregate.yaml yazan bir Release bir dosyayı adlandırır; aggregate: checkout ise bir Aggregate’i metadata.name değeriyle adlandırır. Çözümleyici, hangi katmanın uygulanacağına karar vermek için dizenin içeriğini asla koklamaz — ayırt edici olan önektir. Bir Aggregate içindeki bir Component type değeri de dahil olmak üzere diğer her başvuru, çalışma alanı ve önbellek katmanı ile registry katmanı üzerinden çözümlenir: yerel olarak yazılmış bir varlık, çalışma alanı kökündeki catalog/ altına veya workspace.catalog_dirs içinde listelenen bir dizine yerleştirilir ve göreli bir dosya yolu olarak yazılmış bir type, hiçbir kataloğun içermediği bir varlık olarak derlemeyi durdurur.

Çalışma alanı ve önbellek. Açık bir yerel yol öneki olmayan bir başvuru önce workspace.catalog_dirs içinde listelenen dizinlerde aranır (depo içinde yazılmış ya da depoya kopyalanmış, projeye yerel katalog ağaçları — yapılandırmanın biçimi için bkz. §4) — ya da yapılandırmanın workspace.releases altında kendine ait dizinler verdiği bir Release için o Release’in dizinlerinde — ardından çalışma alanı kökünün catalog/ dizininde, sonra da artifact_cache_dir içinde (önceki registry çözümlemelerinden çekilmiş artefaktları tutan, git tarafından yok sayılan .aggrega/cache/ konumu; alt ağaçlarını §4 açıklar). İkinci ve sonraki derlemelerdeki önbellek isabeti, proje uzak katalog içeriğine bağlı olsa bile iç döngüyü ağdan bağımsız tutan şeydir.

Registry. Çalışma alanı ve önbellek katmanı eşleşme döndürmezse aggrega pull — ya da --auto-pull ile veya çalışma alanının auto_pull ayarıyla çalıştırılan bir derleme — default_registry’ye (varsayılan hub.aggrega.ai) karşı ORAS tabanlı bir OCI pull gerçekleştirir, sonraki derlemeler için artefaktı önbelleğe açar ve çözümlenen varlıkla devam eder. İkisi de olmayan bir derleme yalnızca kilit dosyasının sabitlediğini okur ve kilit dosyası eksik olduğunda aggrega pull’u adlandırarak durur. Registry çağrısının oluşturduğu OCI URI biçimi, §6’da (Artefakt paketleme & OCI taksonomisi) açıklanan varlık türü taksonomisini izler. Aggregates ve Manifests içindeki kısaltılmış URI’ler, registry çağrısından önce tam OCI biçimlerine genişletilir; bu genişletmeyi yönlendiren çıkarım kuralları Manifest’in Bağlama duyarlı kısaltılmış URI’ler başvurusunda ve aşağıdaki §8’de yer alır.

Öncelik ve gölgeleme. Çözümleme önceliği kesinlikle yerel yol > çalışma alanı ve önbellek > registry şeklindedir. Yerel bir katalog dizininde bulunan ve bir registry varlığıyla aynı kimliğe sahip bir varlık, registry varlığını gölgeler — bu kasıtlıdır ve katalog yazarlarının yayınlamadan önce değişiklikleri denemesine olanak tanır. Aynı gölgeleme catalog_dirs ile önbellek arasında da geçerlidir: bir çalışma alanı katalog dizininde bulunan bir varlık, önbellekteki bir kopyaya tercih edilir; böylece depoya kopyalanmış bir katalogdaki yerel düzenlemeler hemen etkili olur.

Çalışma alanı ve önbellek katmanı içinde catalog_dirs, sıralı bir ilk kazanır öncelik yığınıdır. Aynı varlık kimliği listelenen birden fazla katalog dizininde göründüğünde, daha önce listelenen dizin kazanır ve sonraki oluşum gölgelenir — geçersiz kılınır, yüklenmez ve bu bir hata değildir. Bu, bir projenin kendi katalog dizinini paylaşılan ya da depoya kopyalanmış bir dizinin önüne koymasına ve seçilen varlıkları kimliğe göre geçersiz kılmasına, geri kalanların ise paylaşılan dizine düşmesine olanak tanır. Geçersiz kılma gözlemlenebilirdir: çözümleme ayrıntısı hangi dizinin kazandığını ve hangisinin gölgelendiğini bildirir, böylece bir katmanlama asla sessiz kalmaz. Gölgeleme yalnızca dizinler arasında uygulanır; tek bir dizinde aynı kimliği talep eden iki dosya bir yazım hatasıdır ve yüklemeyi durdurur. Birden fazla kez belirtilen bir dizin — bir --catalog bayrağıyla ve catalog_dirs içinde ya da listede iki kez — yığının tek bir girdisidir ve ilk belirtildiği yerde bir kez aranır; böylece bir gölgeleme her zaman iki farklı dosyayı kapsar, asla kendisine karşı okunan bir dizini değil. Öncelik yazarın denetlediği dizin sırasını izlediğinden, çözümlenen küme deterministiktir.

Çalışma alanı kökünün catalog/ dizini bu yığına başından değil sonundan katılır ve yalnızca dizin mevcut olduğunda — böylece bir projenin listelediği her şey çakışmada ona karşı kazanır ve ilgisiz bir dizini listelemek, onun okunmasını asla sessizce durdurmaz. Listelenen bir girdi ona zaten ulaşıyorsa atlanır; çünkü listelenen bir dizinin taranması özyinelemelidir ve çalışma alanı kökünü belirten bir yığın onu zaten okumuştur. catalog_dirs’ı atlamak ile onu boş bir liste olarak yazmak farklı ifadelerdir: atlandığında çalışma alanı yine catalog/ dizinini okur; [] olarak yazıldığında hiçbir yerel katalog okumaz ve bir çalışma alanı hiç kataloğu olmadığını bu şekilde bildirir.

Ağdan yalıtılmış derlemeler. offline: true (§4) ayarlamak registry katmanını tamamen atlar. Yerel yol katmanında veya çalışma alanı ve önbellek katmanında çözümlenemeyen bir başvuru, sessizce bir ağ çağrısı denemek yerine eksik varlık hatası verir; bu da yasal olarak ağa erişemeyen CI işlem hatlarına deterministik bir hızlı başarısızlık sözleşmesi sağlar.

Kademenin çalıştığı yer. Kademe varlığı belleğe getirir; bunun üzerine kurulan diğer çözümleme mekanizmaları — Manifest’in iki katmanlı type ve name araması, vocabulary/inheritance-and-interface adresindeki implements’in üç biçimli sürüm eşleştirmesi (tam / ana sürümle uyumlu aralık / sürümsüz) ve sağlayıcıya ve bileşen örneğine göre eksen başına Recipe seçimi — çözümleyicinin bu kademe aracılığıyla zaten çektiği varlıklar üzerinde çalışır.

6. Artefakt paketleme & OCI taksonomisi (öncü segment olarak yetenek)

Aggrega, altyapı mantığını Docker’ın konteyner imajlarını ele aldığı şekilde ele alır ve ORAS (OCI Registry As Storage) aracılığıyla Open Container Initiative (OCI) standartlarını kullanır. Kullanıcılar Aggrega kataloglarını herhangi bir standart registry’de barındırabilir (GHCR, AWS ECR, Aggrega Hub).

Recipes kesinlikle bir işleme yeteneğiyle 1:1 olduğundan — bir Recipe spec.capability içinde tek bir yetenek belirtir ve iki yeteneği hedefleyemez — bunları bir OCI registry’de düzenlemenin en temiz yolu yeteneği öncü depo segmentine koymaktır.

OCI taksonomisi tüm varlık türlerini kapsar. Bir depo adı, kind segmentidir — varlığın küçük harfe çevrilmiş kind değeri — ve ardından baştan sona küçük harfe çevrilmiş varlık kimliği gelir:

  • hub.aggrega.ai/component/core/datastore/mariadb:1.0.0 — Component, yayıncı core, kategori datastore
  • hub.aggrega.ai/component/core/compute/api-server:1.0.0 — Component, yayıncı core, kategori compute
  • hub.aggrega.ai/feature/core/data-masking:1.0.0 — Feature, yayıncı core (düz, kategori yok)
  • hub.aggrega.ai/aggregate/core/db-module:1.0.0 — Yeniden kullanılabilir Aggregate modülü
  • hub.aggrega.ai/recipe/helm/mariadb:1.0.0 — Recipe, yetenek helm
  • hub.aggrega.ai/recipe/helm-chart/mariadb:1.0.0 — Recipe, yetenek helm-chart
  • hub.aggrega.ai/recipe/compose/mariadb:1.0.0 — Recipe, yetenek compose
  • hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0 — FeatureRecipe, yetenek helm
  • hub.aggrega.ai/schemalibrary/aidatastores:1.0.0 — SchemaLibrary, paylaşılan şema tanımları; PascalCase metadata.name değeri AIDatastores, depo adında küçük harfe çevrilir
  • hub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0 — MappingLibrary, paylaşılan Go şablonu eşleme parçaları
  • hub.aggrega.ai/plugin/provider/helm:0.5.0 — Plugin, soket türü provider (metadata.pluginType segmenti)

Yayınlanabilir kind’lar, katalog yazım kind’larını, Aggregate’i — yeniden kullanılabilir bir modül (daha sonra bir Release’in üst düzey spec.aggregate değeri olarak başvurulsun ya da başka bir Aggregate’in aggregates: bloğunda iç içe yerleştirilsin, yayınlanabilir) — ve Plugin’i, yani derleyicinin yönlendirdiği ve çalışma zamanının yürüttüğü bir WebAssembly artefaktına içerikle adreslenmiş bir başvuruyu kapsar. Plugin, bir katalog yazım kind’ı değil, yapısal bir yayınlanabilir artefakttır. Release ve Manifest, kaynak denetiminde yaşayan ve asla push edilmeyen dağıtım tarafı girdileridir — aggrega push bunları reddeder — bu yüzden bir yayın mediatype’ları yoktur. aggrega push --list-kinds, kurulu ikili dosyanın yayınladığı kümeyi her satıra bir kind olacak şekilde bildirir. Yayınlanabilir her kind’ın, bir yayının aldığı iki biçimin her birinde kendi OCI mediatype’ı vardır:

Varlık kind’ıBelgesi olarak yayınlanırBildirdiği dosyalarla yayınlanır
Componentapplication/vnd.aggrega.component.v1beta1+yamlapplication/vnd.aggrega.component.v1beta1+tar+gz
Featureapplication/vnd.aggrega.feature.v1beta1+yamlapplication/vnd.aggrega.feature.v1beta1+tar+gz
Recipeapplication/vnd.aggrega.recipe.v1beta1+yamlapplication/vnd.aggrega.recipe.v1beta1+tar+gz
FeatureRecipeapplication/vnd.aggrega.featurerecipe.v1beta1+yamlapplication/vnd.aggrega.featurerecipe.v1beta1+tar+gz
Aggregateapplication/vnd.aggrega.aggregate.v1beta1+yaml— hiçbir dosya bildirmez
SchemaLibraryapplication/vnd.aggrega.schemalibrary.v1beta1+yaml— hiçbir dosya bildirmez
MappingLibraryapplication/vnd.aggrega.mappinglibrary.v1beta1+yaml— hiçbir dosya bildirmez
WorkloadLibraryapplication/vnd.aggrega.workloadlibrary.v1beta1+yaml— hiçbir dosya bildirmez
ArtifactLibraryapplication/vnd.aggrega.artifactlibrary.v1beta1+yaml— hiçbir dosya bildirmez
Pluginapplication/vnd.aggrega.wasmplugin.v1beta1+yaml— kendi manifest’i aracılığıyla yayınlanır

Bir yayının taşıdıkları, dolayısıyla biçimi, varlığın bildirdiklerinden kaynaklanır — kind’ından değil, dizininde bulunanlardan da değil. Bir yayın, varlık belgesini ve varlığın kendisinin yanında belirttiği dosyaları taşır: bir Recipe’in ya da FeatureRecipe’in yerel source: değeri — bir dizin, entity.lock dosyasına kaydedilen yok sayma kurallarının tuttuğu altındaki her dosyayla birlikte gider — valuesMapping:, workload: ve artifacts: girdilerinin $import: ile içe aktardığı her dosya ve sabitleme adımının yazdığı entity.lock; ayrıca bir Component’in ya da Feature’ın içe aktardığı her şema dosyası, bir içe aktarma zincirinin her dosyası dahil. Dizindeki başka hiçbir şey gitmez: varlığın yanındaki bir not, bir README ya da bir derlemenin çıktısı, adı ne olursa olsun, yayınladığı şeyin parçası değildir ve yayınlandığı biçimi değiştirmez. Hiçbir şey belirtmeyen bir varlık, yazılmış belgesi olarak, bayt bayt, kind’ının +yaml mediatype’ı altında yayınlanır; bir dosya belirten varlık ise belgenin ve bu dosyaların gzip ile sıkıştırılmış bir tar’ı olarak, kind’ının +tar+gz mediatype’ı altında yayınlanır. Bir Aggregate, bir Plugin ve kütüphane kind’ları belgelerinin yanında hiçbir dosya bildirmez, bu yüzden her zaman belge olarak yayınlanırlar — bir çalışma alanı kökündeki Aggregate da dahil, çünkü bildirdiği her yol taşıdığı bir dosyayı değil başka bir varlığı belirtir; içeriğinin tamamı satır içi olan bir Recipe de öyle. Uzak bir kaynak bir dosya değil bir başvurudur, bu yüzden hiçbir şey taşımaz; ancak sabitlemesini kaydeden entity.lock böyle bir Recipe’i bir arşive dönüştürür. Her mediatype’ın sürüm segmenti tüm yayınlanabilir kind’lar için ortaktır ve kodlama segmenti baytların iki biçimden hangisinde olduğunu söyler. Aşağı akış araçları tam mediatype dizesine göre — kind, sürüm ve kodlama birlikte — yönlendirme yapar.

Yazılmış bir biçim, bir yayının bilebileceği hiçbir dizini belirtmez: şablon olarak yazılmış yerel bir kaynak. Dizini ancak bir Release şablonu doldurduğunda seçilir; bu yüzden varlık, kayıtlı yok sayma kurallarının tuttuğu kendi dizinindeki her dosyayı taşır, böylece bir Release hangi dizini seçerse seçsin o dizin gitmiş olur; bu gerçekleştiğinde aggrega push bunu belirtir. Yalnızca belirtileni taşımanın bir bedeli vardır ve bu bedel tüketiciye düşer: bir varlığın okuduğu ama hiçbir yerde belirtmediği bir dosya gitmez ve onun yokluğuyla karşılaşan, yayıncının push’u değil, bir tüketicinin derlemesidir; bu derleme, önbellek yuvası içinde eksik olan yolu belirtir.

Bir kaynak dizinindeki hangi dosyaların varlığa ait olduğuna, varlık sabitlendiğinde bir kez karar verilir ve bu kaydedilir. Yazarın çalışma alanında varlığın yeteneğine hizmet eden plugin, ekosisteminin asla dağıtmadığı şeyleri bildirir — bir chart plugin’inin sürüm denetimi dizinleri ve bir chart’ın .helmignore dosyasına uyması, bir modül plugin’inin .terraform/ dizini — ve son sözü, varlığın yanındaki yazarın .aggregaignore dosyası söyler. Sabitleme adımı bu plugin’i ve birleştirilmiş kuralları entity.lock içine kaydeder; yayın, kaynağın sabitlemelerinin her karşılaştırması, varlığın lockfile satırı ve işleme, bir plugin’e yeniden sormak yerine kaydedilmiş kuralları uygular; böylece yayınlanan şey, yazarın kendi derlemesinin işlediği şeydir ve değişen bir bağlama ya da daha yeni bir ikili dosya, varlık yeniden sabitlenene kadar hiçbir digest’i değiştirmez. Derleyicinin herhangi bir ekosistem hakkında bir görüşü yoktur: kurallar plugin’den ve yazardan gelir, derleyici yalnızca onları eşleştirir. Bir varlığın dosyaları arasındaki sembolik bağlantı izlenmek yerine reddedilir, çünkü gösterdiği şey onun adı altında giderdi. aggrega pin kuralları eksiksiz anlatır.

Bir Recipe’nin adı ne bir alan öneki ne de yeteneği taşır: varlık türü dizini ve yetenek segmenti ikisini de zaten belirtir.

Adlandırma uzlaşımı: Components (Alan 2) {publisher}/{category}/{name} biçimini, Features (Alan 2) ve yeniden kullanılabilir Aggregates (Alan 1) ise {publisher}/{name} biçimini kullanır; burada yayıncı segmenti satıcıyı/yazarı belirtir (core = resmî standart kütüphane, acme = kurumsal). Alan 3 varlıkları (Recipe, FeatureRecipe), yeteneğin varlığın spec.capability içinde bildirdiği sağlayıcı olduğu {capability}/{name} biçimini kullanır; bir başvuru varlığı yalnızca yaprakla, öneksiz olarak da belirtebilir. Recipe adları yeteneği de İÇERMEZ, çünkü yetenek zaten kanonik URI’nin öncü segmentidir.

Recipes, karşıladıkları arayüze bağlanmak için implements anahtar sözcüğünü kullanır. implements alanı tam, ana sürümle uyumlu aralık veya sürümsüz eşleştirmeyi destekler (implements sürüm eşleştirmesi için bkz. vocabulary/inheritance-and-interface). Bir Manifest eşleme girdisinin Recipe’si, eşlendiği türü veya o türün extends ile genişlettiği bir tabanı uygulamalıdır: girdinin anahtarını ve anahtarın adlandırmadığı bir sürümde ulaştığı her bileşen örneğinin türünü, derlemenin o örneği derlediği sürümde — bu nedenle bir anahtar bir örneği, türünün başka bir sürümü için yazılmış bir Recipe’ye gönderemez.

Bir Ops mühendisi aggrega push komutunu çalıştırdığında CLI, varlığı bu biçimde, sürümünde değişmez olarak yayınlar. Bir tüketici onu Üç Katmanlı Çözümleme Modeli aracılığıyla getirir, yerel olarak .aggrega/cache/ içinde önbelleğe alır ve taşıdıklarını varlığın önbellek yuvasına (§4) yerleştirir — bir arşivin dosyalarını ya da yalnızca belgeyi.

Çekilmiş bir varlık, taşıdığı dosyaları, bir katalog dizininde yanındayken okuduğu şekilde okur. Varlık, yerleştirilmiş o ağaçtaki yerinden okunur; bu yüzden bildirdiği göreli bir source: ya da $import: — açıkça yazılmış ya da bir şablonca üretilmiş — yayınlananın içinde çözümlenir ve varlığın kendi dizininden çıkan bir yol, tıpkı bir katalog dizininde olduğu gibi orada da reddedilir. Ağacın dışındaki hiçbir şey onun yerine okunmaz: ne bir derlemenin çalıştığı dizin ne de önbellek yuvasına yerleştirilmiş bir dosya. Şeması bir dosyadan içe aktarılan bir Component ya da Feature o dosyayı taşır; böylece çekilmiş bir kopya yayınlanan sözleşmeyi yükler ve ona göre yazılmış değerleri, bir katalog dizininden okunan bir kopyanın yaptığı gibi aynen doğrular.

Varlığı bir paketten geri okumak ters adımdır ve varlığı adıyla değil, belgenin ne olduğuyla tanımlar: paketin en üstünde, kind: değeri yayınlanabilir bir varlık kind’ı olan belge. Varlık dosyasının adı bir sözleşme değil bir katalog uzlaşımıdır; bu yüzden recipe.yaml, biçimin gerektirdiği şey değil standart kütüphane kataloğunun yazdığı şeydir ve varlığın yanında taşınan bir dosya — bir chart şablonu, bir compose parçası — onunla karıştırılmaz. Kural tersi olamaz, yani tüketicinin aradığı kind’a göre anahtarlanamaz: kind, paketin içinde olan varlıktan okunur, bu yüzden paketin açılması gereken anda anahtar olacak bir kind yoktur. Okuyan taraf, bir paketin en üstünde iki varlık belgesi bulunduğunda seçim yapmak yerine durur — başka bir istemcinin iki varlık içeren bütün bir dizini paketleyerek ürettiği ve ardından yayınlanmış koordinatlarının her biri altında tek bir artefakt olarak duracak paket. Bu ürünün yayını bunu üretemez, çünkü her varlık yalnızca bildirdiğini taşır; üstelik yayınlayan taraf böyle bir dizini reddeder: Aggregate, Release ve Manifest dışında her kind’ın kendine ait bir dizini vardır ve aggrega pin ile aggrega push, yanında başka bir varlık bulunan diğer herhangi bir kind’daki varlığı reddeder; bir katalog yüklemesi, bir lint ve bir derleme ise dizine dokunmaz. Bir dizinin adı hiçbir tarafta değerlendirilmez: <name>/<version>/ düzeni standart kütüphane kataloğunun uzlaşımıdır.

Yayınlanmış bir varlık da aynı adımla okunur. Bir koordinat, varlığının tam olarak bir kopyasını, bildirimlerinin ona verdiği biçimde taşır ve bir kişi ona yanında yayınlanmış okunabilir bir kopya aracılığıyla değil aggrega inspect oci://<registry>/<repository>:<tag> ile bakar — böylece bir derlemenin çözümlediğiyle çelişebilecek ikinci bir kopya olmaz. Komut, bir arşivi yukarıdaki kurala göre açar, bir Plugin’in varlığını onunla yayınlanan yürütülebilir dosyadan değil manifest’inden okur ve sonucu o kind’daki bir dosyanın işlendiği gibi işler; bkz. Yayınlanmış bir varlığı okuma.

Aranabilir manifest ek açıklamaları. Her yayın, artefaktın OCI manifest’ine küçük bir aranabilir ek açıklama kümesi işler; böylece bir registry dizini ya da bir katalog tarayıcısı, her varlık gövdesini getirip ayrıştırmadan artefaktları katalog meta verilerine göre filtreleyebilir. Her varlık, insan tarafından okunabilir açıklamasını (standart OCI açıklama ek açıklaması) ve ayrıca katalog kategorisini ve kind’ını taşır. Bir Plugin ek olarak soket türünü ve hizmet verdiği yetenekleri taşır. aggrega registry update komutunun yerel aranabilir dizine (§8) geri okuduğu şey bu ek açıklamalardır.

Yayınlanan her dosya adlandırılır. Bir yayının taşıdığı her dosya, manifest üzerinde standart org.opencontainers.image.title ek açıklamasıyla adlandırılır; bu ad, genel bir OCI istemcisinin artefaktı bir dizine çektiğinde o dosyayı yazdığı addır. Ad, dosyanın ne olduğunu söyler ve uzantısı dosyanın medya türünü izler:

YayınlananGenel bir OCI istemcisinin yazdığı dosya
belgesi olarak yayınlanan bir varlıkentity.yaml
bildirdiği dosyalarla yayınlanan bir varlıkentity.tar.gz
bir Pluginvarlık olan entity.yaml, yürütülebilir dosyası olan entity.wasm ile yan yana
bir artefakta eklenmiş bir imzasignature.json
bir artefakta eklenmiş bir kullanımdan kaldırma işaretideprecation.json
aggrega push-artifact ile yayınlanan bir veri artefaktı--name ile verilen ad

Böylece oras pull hub.aggrega.ai/component/core/compute/server:1.0.0 -o ./server, yayınlanan varlığı ./server/entity.yaml konumunda, yayınlandığı haliyle bayt bayt bırakır. oras, ad taşımayan bir tanımlayıcıyı atlar ve yine de başarı bildirir; bu yüzden bir yayının paketlediği her tanımlayıcı bir ad taşır. Ad yalnızca medya türünden türetilir, asla yayınlanan dosyanın adından değil; böylece farklı adlı bir dosyadan yayınlanan aynı baytlar aynı manifest’i üretir. Dosyalarıyla yayınlanan bir varlık paketi olarak gelir: entity.tar.gz paketi adlandırır ve içindeki varlık herhangi bir dosya adıyla değil yukarıdaki kuralla bulunur. Aggrega’nın kendi çözümlemesi bu adları asla okumaz — her dosyayı medya türüne göre seçer ve digest’ine göre güvenir — dolayısıyla bu adlar diğer tüm istemciler için oradadır.

7. Recipe mimarisi: İşaretçiler ve eşleyiciler

Recipe yazımının tüm yüzeyi için bkz. entities/recipe — source: (işaretçi), valuesMapping: (eşleyici, üç yazım kipiyle: satır içi blok skaler, dosya $import:, bir MappingLibrary girdisine kütüphane $import:), Wasm güdümlü kaynak şemaları, yerel IaC desteği ve uygulamalı örnekler.

8. Varsayılan kayıt defteri ve bağlama duyarlı kısaltılmış URI’ler

YAML şişkinliğini ortadan kaldırmak için derleyici, kısaltılmış URI’leri göründükleri şema konumuna göre bağlama duyarlı biçimde çözümler. Varsayılan kayıt defteri .aggrega-config.yaml içinde yapılandırılır (varsayılan değeri hub.aggrega.ai’dir).

Bir kayıt defteri ana bilgisayarının tek bir okunuşu vardır. Her registries[].host, ana bilgisayarın kendisi olarak yazılır — nokta içeren küçük harfli bir ana bilgisayar adı, localhost, ardından bir port gelen tek bir ad, bir IPv4 adresi veya köşeli parantez içinde bir IPv6 adresi; her biri isteğe bağlı bir :port ile ve şema, yol, kimlik bilgisi ya da büyük harf olmadan — çünkü bu yazım, kayıt defterine özgü her güven ilkesinin altında bulunduğu anahtardır ve resmî hub’ın yerleşik imza gereksinimi hub.aggrega.ai anahtarına bağlıdır. default_registry bir ana bilgisayarı aynı şekilde adlandırır ve ardından ghcr.io/acme gibi bir depo yolu gelebilir: bu durumda varsayılan üzerinden yayımlanan her şey bu yolun altına düşer ve her kısa başvuru bu yolun altında çözümlenir; güven ise yine yalnızca ana bilgisayara göre belirlenir. default_registry bunun yerine bir registries girdisinin name: değeri olarak da yazılabilir ve bu durumda o girdinin ana bilgisayarını temsil eder. Ad, yapılandırma çözümlenirken, tüm yapılandırma dosyaları ve ortamdan sonra geçerli olan girdilere karşı bir kez okunur; böylece varsayılanı okuyan her şey — yayımlama, konum bağlama, imza doğrulama ve her güven araması — o tek girdinin ana bilgisayarını okur ve hiçbiri adla aynı yazılan bir ana bilgisayara ulaşmaz; ardından yol gelen bir ad reddedilir, çünkü ad bir konumu değil bir girdiyi temsil eder. Ad, ana bilgisayar yazımından önce eşleştirilir ve iki girdinin taşıdığı bir ad belirsiz olarak reddedilir. Aynı okunuş, bir çekme işleminin ana bilgisayarla yaptığı üç şeyi belirler: ana bilgisayarsız bir katalog kimliğinin bağlandığı kayıt defteri konumunu, getirilen yapıtın imzası denetlenen bir kayıt defterini adlandırıp adlandırmadığını ve bu denetimin hangi güven ilkesine karşı çalıştığını. Bir kayıt defterine ulaşıp ilkesini kaçırabilecek bir yazım — büyük harfler, açıkça yazılmış varsayılan HTTPS portu, bir şema, kimlik bilgileri, bir registries girdisinin ana bilgisayarında bir yol — yapılandırıldığı yerde, yazılması gereken yazımı belirterek reddedilir; hiçbir girdiyi adlandırmayan, portsuz tek bir ad da reddedilir, çünkü bu bir ana bilgisayarın değil, bir katalog kimliğinin ilk bölümünün biçimidir. Ret, değeri ayarlayabilen her katmanda uygulanır: şemanın her registries[].host üzerinde aynı biçimi bir desen olarak belirttiği yapılandırma dosyasında; AGGREGA_DEFAULT_REGISTRY ortam değişkeninde ve komut satırında. Böylece bir yapılandırmanın adlandırabileceği her ana bilgisayar, yapıtları kendisi için yazılmış ilkeye göre doğrulanan bir ana bilgisayardır. Ana bilgisayar yalnızca yazımına göre değerlendirilir; adın çözümlenip çözümlenmediği veya orada bir kayıt defterinin yanıt verip vermediği, derleyicinin hiçbir zaman getirmediği çalışma zamanı durumudur. configuration kabul edilen biçimleri örneklerle açıklar.

Kısaltılmış URI’ler Manifest’e göre bağlama duyarlı biçimde çözümlenir; belirli çıkarım kuralları için ../language-reference/entities/manifest.md §Context-Aware Shorthand URIs bölümüne bakın.

Kayıt defterlerini yönetme

aggrega registry, çalışma alanının bildiği kayıt defterlerini ve bunların imza güven ilkesini yönetir. Bir kayıt defterinin kimliği ana bilgisayarıdır; alt komutlar tek bir adresleme modelini paylaşır:

  • aggrega registry add <host> bir kayıt defterini kaydeder ve güven ilkesini sabitler; güven bayrakları elle bir ilke sağlamadıkça ilk temasta kayıt defterinin duyurduğu ilkeyi getirir. İsteğe bağlı bir --name <alias>, ana bilgisayar anahtarlı aynı girdiye kolay bir takma ad ekler — kimlik yine ana bilgisayardır ve takma ad, bir kayıt defterinin adlandırıldığı her yerde ona çözümlenir. Bir takma ad, kayıt defterleri arasında benzersizdir.
  • aggrega registry list, yapılandırılmış her kayıt defterini — ana bilgisayar, takma ad, kısa bir güven durumu özeti ve varsayılanda bir işaret — artan ana bilgisayar sırasıyla yazdırır. Çözümlenmiş yapılandırmayı okur ve ağa bağlanmaz.
  • aggrega registry remove <name|host>, ana bilgisayarı veya takma adıyla belirtilen bir kayıt defterinin güven ilkesi girdisini kaldırır. Yalnızca güven ilkesini kaldırır: default_registry işaretçisine dokunulmaz ve o ana bilgisayara gönderme yeteneği etkilenmez; böylece ana bilgisayar erişilemez hâle gelmek yerine varsayılan güvene döner. Kaldırılan girdinin adı olarak yazılmış bir default_registry bundan sonra hiçbir şeyi adlandırmaz ve yeniden yazılana kadar reddedilir.
  • aggrega registry update, aşağıda açıklanan yerel aranabilir dizini yeniler.

Bir kayıt defterinin adlandırıldığı her yerde — bir registry alt komut bağımsız değişkeni veya aggrega push ve aggrega push-artifact üzerindeki --registry bayrağı — belirteci aynı çözümleyici yorumlar: yapılandırılmış bir takma ad kendi ana bilgisayarına çözümlenir, diğer her belirteç ise bir başvurunun şeması, yolu ve kimlik bilgileri atılarak adlandırdığı ana bilgisayar olarak okunur. Bu ana bilgisayarın bir imzalama kararının kendisine karşı verildiği bir şeye dönüştüğü yerde — aggrega push veya aggrega push-artifact hedefi ya da aggrega registry add komutunun bir girdiyi altına yazdığı anahtar — yukarıdaki tek okunuşa tabi tutulur ve bu şekilde yazılmadığında, yazılması gereken yazım belirtilerek reddedilir. Bu şekilde yazılmış, kayıtlı olmayan bir ana bilgisayar meşru bir hedeftir ve kabul edilir.

Yerel aranabilir dizin

aggrega registry update [<name|host>], çalışma alanının bildiği kayıt defterlerinin yerel bir aranabilir dizinini oluşturur. Yapılandırılmış her kayıt defterinin depolarını dolaşır, her birinin yayımlanmış en yüksek sürümünü seçer, o sürümün aranabilir manifest ek açıklamalarını (§6) okur ve yapıt önbelleğine kayıt defteri başına bir dizin yazar. Bağımsız değişken verilmezse yapılandırılmış her kayıt defterini dizinler; tek bir kayıt defteri bağımsız değişkeniyle (bir ana bilgisayar veya takma ad) yalnızca onu dizinler.

Dizin, paket yöneticilerinden tanıdık açık yenileme modelini izler: registry update kayıt defterleriyle iletişim kuran komuttur ve sonraki bir aggrega search yazılmış dizini çevrimdışı okur. Bir kayıt defterinin kayıt dosyası deterministiktir — aynı kayıt defteri durumuna karşı yapılan iki güncelleme bayt bayt aynı çıktıyı üretir ve güncellik zaman damgası, kayıtları hiçbir zaman bozmaması için kardeş bir dosyada tutulur. Yayımlanmış sürümü olmayan veya okunamayan bir depo atlanır; böylece okunamayan tek bir depo hiçbir zaman dizinin tamamından vazgeçilmesine yol açmaz.

Yayımlanmış katalog anlık görüntüsü

Standart kütüphane kataloğunun her yayımlanışı, kataloğu bir bütün olarak da yayımlar: tek bir OCI yapıtı, yani o yayımlamanın yayımladığı commit’te katalog ağacının barındırdığı her dosyanın gzip ile sıkıştırılmış bir tar arşivi; kataloğun yayımlandığı kayıt defterinin altında catalog/snapshot konumunda bulunur — resmî hub için hub.aggrega.ai/catalog/snapshot. Yalnızca o yayımlamanın her varlığı kayıt defterinde bulunduktan sonra gönderilir, bu nedenle kayıt defterinin barındırmadığı hiçbir varlığı adlandırmaz. Derlendiği commit ile ve latest ile etiketlenir ve yayımlamanın her varlığı gibi yayımcı tarafından anahtarsız olarak imzalanır, böylece yayımcının kimliği onu kayıt defterinin güven politikası altında doğrular; latest bir anlık görüntüye ancak o imzalandıktan sonra geçer. Arşiv tek bir sabit düzene göre yazılır — girdiler adlarına göre artan sırada, her biri aynı mod, sahip ve değiştirme zamanıyla — böylece bir commit her zaman aynı tar arşivini üretir.

Tek okuyucusu, çalışma alanı hiçbir katalog klasörü adlandırmayan bir içe aktarmadır: workspace.catalog_dirs yok, AGGREGA_CATALOG_DIRS yok ve çalışma alanı kökünde catalog/ dizini yok. aggrega import, düzenleyici oturumunun içe aktarması ve asistanın içe aktarma aracı aynı işlemi çalıştırır, bu nedenle her biri anlık görüntüyü aynı şekilde edinir. İçe aktarma onu, bir çekme işlemiyle aynı giden trafik kapısı ve oturum açma üzerinden çalışma alanının varsayılan kayıt defterinden getirir, herhangi bir şey saklanmadan önce imzasını o kayıt defterinin güven politikası altında doğrular, çalışma alanının yapıt önbelleğinde saklar ve orada, özetine bağlı tutarak bir katalog klasörü olarak okur — böylece içe aktarıcıya kataloğun Components’i sunulur ve --target, onun Recipes’inden bir Manifest taslağı oluşturur; tam olarak bir katalog klasörünün izlediği yol üzerinden. İçe aktarmanın taslaklarının yanına yazdığı kayıt, anlık görüntüyü manifesto özetiyle adlandırır; böylece aynı taslakların sonraki bir içe aktarması aynı kataloğu bir istek göndermeden okur ve aggrega import --upgrade en yeni anlık görüntüyü getirir ve o andan itibaren ona göre içe aktarır. Çevrimdışı duruşta, bir anlık görüntü getirmesi gereken bir içe aktarma, neyin çalıştırılacağını belirterek durur. Bir katalog klasörü adlandıran bir çalışma alanı ona göre içe aktarır ve hiçbir anlık görüntü getirmez. Başka hiçbir komut anlık görüntüyü okumaz: bir çekme, bir derleme ve bir doğrulama her varlığı §5’in katmanları üzerinden çözümler ve kilit dosyasında sabitler; bir içe aktarmanın taslakları ise katalog varlıklarına adlarıyla başvurur, bu nedenle onları derlemek bu varlıkları aynı şekilde çözümler.

9. Kilit dosyasıyla sabitleme ve yapıt değişmezliği

Kilit dosyasıyla sabitleme disiplini, her bağımlılığı içerik adreslenebilir belirli bir yapıta bağlar. İlk kilit dosyası çözümlemesinde (aggrega pull) çözümleyici kayıt defterine başvurur, URI’nin üç biçimli kısıtına (tam / aralık / sürümsüz) göre bir sürüm seçer ve sabitlenen sürümü + özeti Release’in <release-stem>.lock dosyasına yazar. Sonraki aggrega build çağrıları, kayıt defterinin değişebilirliğinden bağımsız olarak sabitlenen değerleri kullanır; yeni sürümler mevcut kilit dosyasını etkilemeden yayımlanabilir.

Sabitleme modeli, yükü taşıyan tek bir kural içerir: bir name:version bir kayıt defterine yayımlanıp D özetine çözümlendiğinde bu eşleme kalıcıdır. Aynı name:version’ın farklı içerikle yeniden yayımlanması push sırasında reddedilir. aggrega push bunu her yayımlamada kendisi uygular: hedef kayıt defterinde name:version konumundaki mevcut yapıtı çözümler; yapıt varsa ve özet gönderilmek üzere olan içerikle eşleşiyorsa push hiçbir şey yüklemez ve yalnızca o yayımlamada hâlâ eksik olanı ekler — yayımlanma tarihini ve push imzalıyorsa imzasını; yapıt varsa ve özet farklıysa push, her iki özeti de belirten bir değişmezlik ihlali hatasıyla durur.

Değişmezlik iki sonuç açısından önemlidir:

  1. Kilit dosyası sabitlemeleri dürüsttür. Kilit dosyası mariadb:1.0.0’ı D özetiyle kaydettiğinde, özete göre getiren bir derleme D’nin baytlarını alır. Değişmezlik olmasaydı, kayıt defteri tarafındaki bir değişiklik kilit dosyası sabitlemesinin altında D’nin baytlarını değiştirebilir ve kilitleme anından derleme anına kadarki kararlılığı zayıflatabilirdi. Yeniden üretilebilir derlemeler bu güvenceye dayanır.
  2. Yayımlama sonrası meta veri değişikliklerinin açık bir yolu vardır. Yayımlanmış bir sürümü kullanımdan kaldırılmış olarak işaretlemek, imzalama anahtarlarını döndürmek veya tasdikleri değiştirmek, yayımlanmış yapıtı değiştirerek yapılamaz (kural bunu yasaklar). Bu, yeni bir yama sürümü ya da meta veri değişikliğini ayrıca kaydeden yan bir yapıt yayımlanarak yapılmalıdır. Her iki yol da denetlenebilirdir — yeni bir sürüm veya yan yapıt ayrı bir kayıt defteri girdisi olarak görünür — ve hiçbiri özgün yapıtın baytlarını değiştirmez.

Değişmezlik kuralı, OCI ile yayımlanan her Aggrega yapıtına (varlıklar, SchemaLibrary, MappingLibrary, Recipe pipeline[].plugin: / FeatureRecipe pipeline[].plugin: / çalışma alanı yapılandırması plugins.{governance,linter,importer}[]: tarafından başvurulan Wasm eklentileri) aynı şekilde uygulanır. Kilit dosyasında name:version ve bir içerik özetiyle sabitlenen her şey değişmezliğe tabidir.

Değişmezlik koşulsuzdur ve hiçbir yapılandırma onu gevşetmez. Üzerine yazmaya izin veren hiçbir bayrak ve hiçbir çalışma alanı yapılandırma ayarı yoktur, çünkü kayıt defteri bir operatörün tercih edebileceği bir üzerine yazma yolu sunmaz. Değişmiş içerik yeni bir sürüm altında yayımlanır ve aggrega lint --pre-publish, sürüm artışının değişikliğin sınıflandırmasıyla eşleştiğini doğrular.

Daha yeni bir sürüme yeniden çözümleme, kullanıcının açık bir eylemini gerektirir: aggrega pull --upgrade --release <release> <uri> diğer tüm sabitlemeleri koruyarak tek bir bağımlılığı yeniden çözümler, aggrega pull --upgrade --release <release> ise tüm bağımlılıkları kayıt defterinin güncel durumuna göre yeniden çözümler. Aralık biçimli ve sürümsüz biçimli bağımlılıklar eşleşen en son sürüme yeniden çözümlenir; tam biçimli sabitlemeler, kullanıcı açıkça farklı bir tam sürüme yükseltmedikçe değişmez. Kilit dosyası derlemeler için doğruluk kaynağıdır; kullanıcının yazdığı biçim ise yazım anındaki sürüm kısıtını ifade eder.

10. Katalog varlık adı biçiminin denetlenmesi

Katalog varlık adları varlık türüne özgü kalıplara uyar; bu kalıplar aşağıda sıralanmış, her tür için ayrıntıları ise Varlık başvurusuna genel bakış sayfasında verilmiştir. Bunlar, bir geliştiricinin bir Aggregate ya da Release içinde yazdığı ve türden bağımsız olarak tek bir kalıbı paylaşan örnek adlarından farklı bir yüzeydir; o kalıp ../language-reference/02-naming-conventions.md “Instance Names” bölümündedir. Bir katalog YAML’ının bildirdiği metadata.name alanı, varlığın kanonik başvuru URI’si ile her zaman aynı değildir: Component ve Feature, yayımcı ve gruplama segmentlerini doğrudan metadata.name içine gömer; Recipe ve FeatureRecipe yalnızca yaprak içeren bir metadata.name bildirir ve iki segmentli kanonik URI’leri bu yaprağı varlığın bildirdiği spec.capability ile eşler; her kütüphane türü metadata.name içinde PascalCase bir belirteç bildirir.

Varlık türüne özgü biçimler:

  • Component — metadata.name içinde bildirilen üç kebab-case segment: {publisher}/{category}/{name}. Örnek: core/datastore/postgres.
  • Feature — metadata.name içinde bildirilen iki kebab-case segment: {publisher}/{name}. Örnek: core/data-masking.
  • Recipe — metadata.name içinde tek bir kebab-case yaprak (ör. postgres). Kanonik başvuru URI’si {capability}/{name} (yukarıdaki §6 uyarınca), varlığın bildirdiği spec.capability değerini bu yaprakla eşler; baştaki segment varlığın diskteki konumuyla değil spec.capability ile eşleştirilir, dolayısıyla bir recipe.yaml dosyasını taşımak ona nasıl başvurulduğunu değiştirmez. Standart kütüphane kataloğu varlığı <catalog-root>/recipe/<capability>/<name>/<version>/recipe.yaml konumuna yerleştirir, böylece ağaç koordinatı yansıtır; ancak bu yansıtma URI’nin kaynağı değil, bir katalog uzlaşımıdır. Bir başvuru recipe’yi yalın olarak da, yani capability segmenti olmadan yalnızca yaprakla adlandırabilir; bu, pratikte baskın biçimdir ve katalogda bu adı taşıyan tek bir recipe bulunduğunda çözümlenir. Bir Recipe URI’sinde yayımcı segmenti yer almaz ve üçüncü bir segment taşıyan başvuru hiçbir recipe ile eşleşmez.
  • FeatureRecipe — metadata.name içinde tek bir kebab-case yaprak (ör. k8s-secret-from-parameter), Recipe ile simetriktir: kanonik URI {capability}/{name}, bildirilen spec.capability ile yaprağın birleşiminden oluşur, yalın yaprak aynı şekilde kabul edilir ve <catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yaml ağacı koordinatı uzlaşım gereği yansıtır.
  • Kütüphane türleri — SchemaLibrary, MappingLibrary, WorkloadLibrary ve ArtifactLibrary — metadata.name içinde ^[A-Z][A-Za-z0-9]*$ ile eşleşen tek bir PascalCase belirteç (ör. BaseComponents, AIDatastores, BaseWorkloads). Biçim her kütüphane türünde aynıdır; bu nedenle bir girdiyi kütüphaneler arasında taşımak hiçbir zaman farklı bir uzlaşıma göre yeniden adlandırmak anlamına gelmez. Her kütüphane türünün JSON Schema zarfı, aşağıda açıklanan denetime ek olarak kalıbı ayrıca bildirir.

Component, Feature, Recipe ve FeatureRecipe için metadata.name alanının JSON Schema’sı boş olmayan herhangi bir dizeyi kabul eder; bu nedenle bu türlerde biçime ilişkin hiçbir şey yapısal değildir. Belgelenen her biçim — zarfları kalıplarını ayrıca bildiren kütüphane türleri de dahil — kalıpları derleyici dağıtımıyla paylaşılan tek doğruluk kaynağı niteliğinde bir regex olarak taşıyan yayımlama disiplini eklentisi tarafından denetlenir. Burada hiçbir türe, eklentinin sonradan yok saydığı bir biçim verilmez.

Denetim isteğe bağlıdır: onu tek bir komut gerçekleştirir ve yalnızca bir yazar istediğinde çalışır. Bu denetimi gerçekleştirdiği en sık varsayılan iki komut bunu yapmaz:

  • aggrega lint ad biçimi ihlallerini raporlar. Eklenti, her varlığın metadata.name değerini türünün kalıbıyla karşılaştırır. Denetim, bir yazar aggrega lint komutunu çağırdığında çalışır — tek bir varlık üzerinde, --release ile bir Release’in bağımlılık kapanışı üzerinde ya da bağımsız değişken olmadan çağrıldığında tüm katalog varlıkları üzerinde — ve aynı kural kümesine CLI’ın sunduğu, düzenleyiciye yönelik araç yüzeyinden de erişilebilir. Bulgular tavsiye niteliğindedir: warn önem düzeyinde raporlanır ve işlemi durdurmaz.
warn: E0278 name-shape: metadata.name "mariadbSynth" does not match the documented pattern for Recipe entities (^[a-z][a-z0-9-]*$)

Bulgu, önem düzeyi ve kuralının kayıtlı olduğu kısa kodla başlar; bu kodu aggrega explain E0278 genişletir. Sorunlu dosyanın yolu bulgunun üstünde yazdırılır ve tüm kataloğu kapsayan bir çalıştırma, denetlenen varlıkların ve üretilen tavsiye niteliğindeki bulguların sayısıyla sona erer.

  • aggrega build ad biçimini denetlemez. İşlenmiş çıktı Aggrega varlık adlarına bağlı değildir; bu nedenle uyumsuz adlar taşıyan bir katalog üzerindeki derleme hiçbir uyarı ve hiçbir tanılama üretmez ve aksi durumda olacağı gibi başarıyla tamamlanır.
  • aggrega push da ad biçimini denetlemez. Yayımlama başka gerekçelerle reddedilir — özellikle yukarıdaki değişmezlik kuralı nedeniyle; bu kurala göre mevcut bir name:version farklı içerikle yeniden yayımlandığında işlem durur. Bir ret mesajı aggrega lint --pre-publish komutunu adlandırdığında, yazara hangi komutu çalıştırması gerektiğini söyler; push bu komutu çalıştırmaz.

Ne derleme ne de yayımlama biçimi denetlediği için, uzlaşıma uyulmasını isteyen bir katalog aggrega lint komutunu bilinçli olarak çalıştırır — bir pre-commit kancasında ya da bir pipeline adımı olarak. Ad biçimi bulgusunun tavsiye niteliğinde olduğunu unutmayın: aggrega lint bulguyu raporlar ve yine de başarıyla çıkar; bu nedenle uzlaşıma göre geçit uygulamak isteyen bir pipeline, çıkış durumuna güvenmek yerine raporlanan bulguları okur.

Çalışma alanı düzeyindeki bir politika kuralı bastırır:

# .aggrega-config.yaml — lint section
lint:
publishing_discipline:
allow_nonstandard_names: true # default false

Politika ayarlandığında ad biçimi kuralı hiçbir şey raporlamaz. Ayrıca aggrega lint --allow-nonstandard-names ile tek bir çağrı için ayarlanabilir ya da --no-allow-nonstandard-names ile yeniden kapatılmaya zorlanabilir. Meşru kullanımlar arasında hiçbir zaman yayımlanmayacak kataloglar, çok yayımcılı deneyler ve özel amaçlı varlıklar bulunur.

11. Ek açıklama güdümlü Feature genişletmesi

Manifest’in mappings.features.annotations bloğu, ek açıklama anahtarları ile Feature türleri arasındaki bağlamaları ve her ek açıklamanın doldurabileceği Feature şema özelliklerini adlandıran, sütunlara göre gruplanmış bir yönlendirme tablosunu (maps.infra, maps.values) bildirir. Çözümlemenin ek açıklama genişletme alt aşaması, Release sınırlarını dıştan içe ve Aggregate alt sistemlerini dıştan içe dolaşır; bileşen başına etkin ek açıklama kümelerini, tüm değer ve alt anahtar başına null ile devre dışı bırakma destekli basamaklama ve geçersiz kılma yoluyla hesaplar ve IR kökeninde origin: annotation taşıyan sentetik Feature eklemeleri enjekte eder. Bağlama biçiminin ve yazımın tam anlatımı language-reference/entities/manifest.md ve language-reference/providers/well-known-annotations.md sayfalarındadır; bu bölüm, genişletme yolunun dayandığı katalog yükleme zamanı ve inceleme zamanı mekanizmalarını belgeler.

Şema derleme önbelleği. Her Feature’ın spec.schema.{infra,values} alanı derleme başına bir kez derlenir ve basamaklama dolaşımları boyunca yeniden kullanılır. Aynı Feature şemasına karşı tekrarlanan alt anahtar başına tür doğrulaması (yüzlerce bileşenin her biri için bir basamaklama kapsamı) derlenmiş şemayı yeniden derlemek yerine okur. Derlemeler arasında hiçbir şey tutulmaz; bu nedenle değişen bir Feature şeması bir sonraki derlemede baştan derlenir.

Bağlama hedefi doğrulaması (katalog yükleme). Katalog yüklenirken derleyici her Manifest features.annotations bağlamasını dolaşır ve maps.infra ile maps.values altında bildirilen her noktalı yolun, başvurulan Feature’ın spec.schema.<pillar> alanının gerçekten bildirdiği bir özelliğe karşılık geldiğini doğrular. Feature şemasının listelemediği bir yola yönlendiren bir bağlama, bağlama anahtarını, eksik yolu, Feature URI’sini ve kaynak konumunu adlandıran açık bir OPS_ERROR ile katalog yüklemesini durdurur.

Şema sütunu çakışması lint denetimi (katalog yükleme). Bir Feature’ın spec.schema alanı aynı özellik adını hem infra hem values sütununda bildirdiğinde tavsiye niteliğinde bir uyarı verilir. Çakışma nadiren kasıtlıdır: sütunlar arasında aynı adı taşıyan özellikler yazım niyetini belirsizleştirir (bir ek açıklama ortak adı hedeflediğinde hangi sütun devreye girer?) ve tanılama mesajlarını karmaşıklaştırır. Uyarı engelleyici değildir ve devre dışı bırakılamaz: çakışmayı kasteden yazar onu ve uyarıyı korur, kastetmeyen ise özelliği sütunlardan birinde yeniden adlandırır.

Bağlama eşlemi çakışması lint denetimi (çözümleme). Bir alt anahtar yolu, Manifest’in bağlamaları genelinde hem maps.infra hem maps.values altında göründüğünde tavsiye niteliğinde bir uyarı verilir. Her iki sütun listesinde görünen bir yol tutarsızdır: tek bir ek açıklama alt anahtarı aynı anda iki sütuna birden yönlendirilemez ve derleyicinin uyguladığı belirlenimci eşitlik bozma (her iki listede görünen yol infra’ya yönlenir; Aggregate’te yazılan bir ek açıklama yalnızca values üzerinden yönlenebilir, bu yüzden orada o yol için yazılan ek açıklama reddedilir) amaçlanan bir yazım biçimi değil, bir güvenlik ağıdır. Uyarı engelleyici değildir; uyarıyı yok sayarak çalışan yazarlar yine temiz bir derleme elde eder ve eşitlik bozma IR kökeninde görünür.

aggrega inspect köken gösterimi. Inspect komutu, her Feature eklemesi için doldurulan her yaprağın kaynağını kaydeden bir köşeli parantez gösterir:

  • [explicit] — Feature, bir Aggregate ya da Release features: bloğu aracılığıyla açıkça eklenmiştir.
  • [annotation: <key> from <source>] — doldurulan her yaprak aynı ek açıklama anahtarından gelmiştir. Köşeli parantez, anahtarı ve ek açıklamanın bildirildiği yeri adlandırır: dosyayı ve dosya içindeki noktalı anahtar yolunu.
  • Yaprak başına köşeli parantezler — doldurulan her yaprağın kendi kaynak köşeli parantezi ile gösterildiği taraflar arası birleşim (bazıları [explicit], bazıları [annotation: <key> from <source>]). Bu biçim, alan başına açık olanın kazandığı birleştirmeyi ortaya koyar: açık bir ekleme ile bir ek açıklama katkısı aynı Component üzerindeki aynı Feature örneğini hedefleyip farklı yapraklara yazdığında, her iki katkı da kendi yaprağında geçerli kalır ve inspect çıktısı her yaprağın kaynağını ayrı ayrı adlandırır.

Inspect gösterimi, IR’nin sütun başına values_provenance ve infra_provenance eşlemlerini okur — bunlar ek açıklama genişletmesi sırasında sentetik ekleme enjeksiyonuyla birlikte doldurulur — ve yaprakların toplu kaynağını en iyi özetleyen köşeli parantez biçimini üretir. Inspect mekanizması, belirli bir Feature eklemesinin neden belirli bir Component’e yerleştiğini ve değerlerinin nereden geldiğini anlamak için standart iç gözlem yüzeyidir.