Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Aggregate

Peran konseptual entitas Aggregate (Domain 1 — cetak biru topologi deklaratif milik Developer) dijelaskan di architecture/04-entity-taxonomy.md. Pola komposisi (subsistem, aggregate bersarang, Zero-Port Convention, Parameter Hoisting) dijelaskan di architecture/06-data-taxonomy-and-composition.md. Halaman ini membahas permukaan penulisan katalog Aggregate — khususnya, penulisan modul Aggregate yang dapat digunakan ulang untuk distribusi katalog.

Cakupan Component: subsystem bawaan

Sebuah Aggregate mengorganisasi komponen ke dalam subsistem — pengelompokan bernama untuk kepentingan lintas bagian (tingkat data, tingkat edge) yang membawa kaskade anotasinya sendiri. Sebagian besar Aggregates memiliki satu pengelompokan saja, sehingga tidak memerlukan seremoni apa pun.

Cakupan tunggal (bawaan). Tulis komponen langsung di bawah spec.components: dan hilangkan blok subsystems::

spec:
components:
api:
type: core/server:1.0.0
worker:
type: core/worker:1.0.0

Compiler melipat komponen-komponen ini ke dalam subsistem default yang disintesis. Identitas node tidak berubah — api tetap api, tidak pernah default.api — sehingga Aggregate yang ditulis dengan cara ini dapat dipertukarkan dengan bentuk subsistem tunggal yang eksplisit, dan pengalamatannya (dalam target uses:, dalam diagnostik) menggunakan path spec.components.<name> tanpa awalan. Cakupan yang disintesis dicatat secara jujur dalam IR yang diekspor (dengan membawa penanda subsistem tersintesis), tetapi tidak pernah muncul dalam path yang ditulis atau dibaca oleh penulis.

Beberapa cakupan. Ketika komponen terbagi ke dalam kelompok lintas bagian yang berbeda, deklarasikan subsistem bernama di bawah subsystems:. Setiap subsistem membawa komponen dan kaskade anotasinya sendiri, dan dapat memuat subsistem bersarang lebih lanjut.

Saling eksklusif. spec.components: dan spec.subsystems: saling eksklusif pada root Aggregate — tulis salah satunya, jangan keduanya. Dokumen yang mendeklarasikan keduanya akan terhenti saat dimuat dengan galat envelope. (Subsistem yang secara eksplisit dinamai default oleh pengembang adalah subsistem terdeklarasi biasa, yang dialamatkan pada path lengkapnya spec.subsystems.default.components.<name> — penghilangan cakupan tersintesis didasarkan pada asal-usul, bukan pada nama.)

Modul Aggregate yang dapat digunakan ulang

Aggregates berfungsi sebagai Aggregate akar yang di-build oleh Release sekaligus modul yang dapat digunakan ulang. Aggregate induk dapat mendeklarasikan Aggregate anak persis seperti sebuah komponen, dengan meneruskan parameters ke dalamnya. Untuk mencegah keterikatan yang erat, Aggregates anak mengekspos kontrak exportedComponents:, yang menetapkan nama antarmuka publik yang stabil. Induk menjangkau komponen modul hanya melalui antarmuka ini: target uses: adalah nama modul, sebuah titik, dan salah satu alias yang diekspornya, dan compiler menyambungkan edge ke komponen internal yang disebut oleh alias tersebut. Target yang menjangkau ke dalam modul dengan nama lain apa pun — nama komponen di dalam modul, atau path ke modul yang bersarang di dalamnya — menghentikan build, dengan menyebut modul dan alias yang diekspornya; lihat A uses target names a module’s component the module does not export (Target menyebut komponen modul yang tidak diekspor oleh modul).

Mengapa daftar exportedComponents: eksplisit. Penulis modul menentukan komponen mana yang membentuk antarmuka publik dan mana yang tetap menjadi detail implementasi. Karena induk hanya dapat menyebut apa yang diterbitkan daftar tersebut, bagian dalam modul dapat direfaktor — mengganti nama komponen, memecah satu komponen menjadi dua, mengganti worker dengan layanan terkelola — tanpa merusak induk mana pun, selama setiap nama yang diterbitkan masih menunjuk ke sebuah komponen. Daftar ini membutuhkan satu entri per komponen yang diterbitkan, dan sebuah komponen dapat diterbitkan dengan namanya sendiri (store: store) jika itulah nama yang harus digunakan pengimpor. Aturan yang sama berlaku di dalam komposisi: modul menjangkau modul yang diimpornya melalui alias yang diekspor modul tersebut. Release dapat menyambungkan dua komponen dari satu modul satu sama lain, karena koneksi itu tidak melintasi antarmuka modul mana pun.

Mengekspor ulang antarmuka modul bersarang. Sebuah entri exportedComponents: dapat menunjuk ke alias yang diekspor oleh sub-aggregate bersarang alih-alih ke komponen yang dideklarasikan langsung — sebuah modul yang mempublikasikan ulang sebagian modul yang diimpornya, di bawah nama antarmukanya sendiri dan secara opsional dengan nama baru. Edge uses: yang menargetkan alias yang diekspor ulang tersebut di-resolve secara transitif melalui rantai hingga ke node internal yang konkret, sehingga sebuah modul menyusun modul-modul yang lebih dalam ke dalam antarmuka publiknya sendiri tanpa mengekspos tata letak internalnya, dan konsumen tidak pernah perlu tahu seberapa dalam target bersarang. Disiplin antarmuka stabil berlaku di setiap lompatan: setiap modul hanya mengekspor ulang apa yang dipilihnya untuk dipublikasikan. Target yang diekspor ulang yang tidak ter-resolve ke node internal mana pun akan berhenti secara tegas dengan cara yang sama seperti target menggantung langsung, dan rantai ekspor ulang yang menutup kembali ke dirinya sendiri ditolak alih-alih diikuti tanpa batas.

Deklarasi modul diperiksa sama seperti deklarasi Aggregate. Dokumen modul hanya dibaca saat komposisi yang mengimpornya di-build, dan deklarasinya diperiksa sejak saat itu, pada kedalaman penyarangan mana pun. Blok inject: milik komponen modul itu sendiri tunduk pada allowlist spec.inject milik tipenya, serta pada aturan yang melarang mengklaim satu kunci pengiriman dua kali dan membaca kunci yang tidak diterbitkan tipe tersebut. Lampiran yang ditulis pada salah satu subsistem milik modul itu sendiri hanya boleh menyebut socket yang dideklarasikan Feature-nya, begitu pula lampiran yang ditulis Release terhadap komponen yang disumbangkan modul.

Lampiran subsistem modul menjangkau komponennya. Feature yang dilampirkan modul pada salah satu subsistemnya sendiri mengalir ke setiap komponen yang dideklarasikan modul di bawah subsistem tersebut, termasuk subsistem bersarang, persis seperti lampiran subsistem di Aggregate — dan hanya ke komponen-komponen tersebut, tidak pernah ke komponen Aggregate pengimpor di bawah subsistem dengan nama yang sama. Lampiran itu dievaluasi tepat setelah lampiran milik komponen itu sendiri, subsistem luar sebelum subsistem dalam. Pada field yang ditulis keduanya, lampiran milik komponen itu sendiri dengan nama yang sama yang menang, dan field yang dihilangkannya mempertahankan nilai dari subsistem. Setiap komponen yang dijangkaunya memeriksanya terhadap appliesTo milik Feature tersebut. Temuan tentang deklarasi milik modul itu sendiri menyebut modul dan kunci di dalam dokumennya — misalnya .spec.subsystems.<subsystem>.features.<attachment> — sehingga perubahan dilakukan di modul, tempat deklarasi berada, bukan di Aggregate yang mengimpornya.

Lokasi katalog

Modul Aggregate yang dapat digunakan ulang berada di bawah direktori jenis aggregate/ pada path yang dieja oleh metadata.name-nya, segmen demi segmen, dengan direktori versi di ujungnya:

aggrega-catalog/
└── aggregate/
└── {module-name}/ # the module's metadata.name, segment for segment
└── {version}/ # the module's metadata.version
└── aggregate.yaml # The module definition

Nama modul dapat membawa segmen {publisher} di depan yang menyebut vendor atau penulis — core untuk pustaka standar, acme untuk sebuah perusahaan — dan modul pustaka standar yang dipublikasikan dinamai dengan cara itu: core/agenta berada di aggregate/core/agenta/1.0.0/aggregate.yaml. Nama yang terdiri dari satu token berada satu tingkat lebih dangkal, di aggregate/{module-name}/{version}/aggregate.yaml. Kedua bentuk sama-sama valid; nama adalah apa yang ditulis penulis, dan direktori mencerminkannya. Pencerminan itu adalah konvensi katalog, bukan sesuatu yang diperiksa kompiler — sebuah modul ditemukan berdasarkan nama yang dideklarasikannya, bukan berdasarkan letak berkasnya.

URI OCI: hub.aggrega.ai/aggregate/{module-name}:{version}, dalam huruf kecil — jadi modul bernama core/agenta dipublikasikan ke hub.aggrega.ai/aggregate/core/agenta:1.0.0, dan modul bernama db-module ke hub.aggrega.ai/aggregate/db-module:1.0.0.

Pola modul

Modul anak (aggregate/child-database-module/1.0.0/aggregate.yaml, dipublikasikan sebagai hub.aggrega.ai/aggregate/child-database-module:1.0.0):

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
components:
internal-pg-primary:
type: core/postgres:1.0.0
exportedComponents:
# The Public Contract (Written once by the module author)
primary_db: "internal-pg-primary"

Aggregate induk:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
aggregates:
finance-db-subsystem:
type: child-database-module:1.0.0
components:
billing-api:
type: core/python-worker:1.0.0
uses:
databases:
- finance-db-subsystem.primary_db

Label modul

Ketika sebuah Aggregate diterbitkan ke katalog sebagai modul yang dapat digunakan ulang, ia dapat membawa metadata.labels pada amplop YAML-nya — misalnya aggregate.aggrega.ai/tier: infrastructure atau aggregate.aggrega.ai/compliance: pci-dss. Label ini mendeskripsikan identitas modul dan dibawa pada dokumen modul sebagaimana diterbitkan; belum ada perintah yang membacanya. Pencarian katalog tidak mengindeks Aggregates, dan graf build tidak membawa label modul maupun nama katalognya, sehingga kebijakan tata kelola tidak dapat memilih komponen modul berdasarkan modul asalnya.

Perbedaan penting. Label Aggregate mendeskripsikan identitas modul yang dapat digunakan ulang di katalog. Label tersebut tidak menurun ke node komponen anak. Label komponen berasal secara eksklusif dari entitas katalog Component di Domain 2. Jika pengembang mengimpor modul berlabel aggregate.aggrega.ai/tier: infrastructure, komponen-komponen individual di dalam modul tersebut hanya mempertahankan label yang didefinisikan Katalog miliknya sendiri (mis., component.aggrega.ai/type: stateful-server). Label Aggregate tidak pernah disuntikkan ke dalam kamus labels node IR.

Lihat architecture/06-data-taxonomy-and-composition.md §6 untuk pembahasan lengkap Composite Aggregates / Pola Modul (termasuk aturan tanpa sub-komponen untuk Components), serta untuk mekanisme pengelompokan lintas bagian subsystems. Lihat vocabulary/data-pillars untuk permukaan penulisan kontrak parameters bertipe.

Kontrak parameter bertipe

Blok spec.parameters: milik Aggregate mendeklarasikan kontrak bertipe untuk parameter yang dipenuhi oleh Release. Setiap slot parameter membawa type yang dideklarasikan, description opsional, default opsional, batasan ruang nilai opsional, dan (untuk slot bertipe objek) struktur bersarang. Kompiler memvalidasi setiap nilai yang diberikan Release terhadap kontrak tersebut selama resolusi, sebelum interpolasi parameter dijalankan.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: web-app
version: 1.0.0
spec:
parameters:
region:
type: string
description: Cloud region the deployment targets
enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1]
default_locale:
type: string
description: Default UI locale presented to end users
enum: [en-US, en-GB, fr-FR, ja-JP]
default: en-US
enable_debug:
type: boolean
description: Toggle verbose request logging
default: false
feature_flags:
type: object
description: Per-feature enablement map
valuesType: { type: boolean }
default: {}
allowed_hosts:
type: array
description: Hostnames the ingress accepts
items: { type: string, format: hostname }
min: 1
default: ["web-app.example.com"]
components:
web:
type: core/web-server:1.0.0
values:
default_locale: "{{ .parameters.default_locale }}"
region: "{{ .parameters.region }}"
debug: {{ .parameters.enable_debug }}

Pengutipan pada setiap referensi disengaja: pengutipan itulah yang menentukan tipe nilai yang diangkat saat tiba. Lihat templates/parameters-context.md.

Kosakata slot parameter

Blok parameters: bertipe menerima kosakata bentuk ringkas: type, description, default, enum, min, max, pattern, minLength, maxLength, format, validate dan validateMessage (pemeriksaan kustom dan pesan yang dilaporkannya), items (untuk array), properties (untuk objek), valuesType (untuk map bernilai bertipe), dan required: true (penanda per slot). Tiga dari kata kunci tersebut menerima kontrak sebagai nilainya, bukan pengaturan biasa — items, valuesType, dan setiap entri di bawah properties — dan pada slot parameter, kontrak bersarang itu ditulis dalam bentuk bertipe yang sama dengan slot di sekitarnya: valuesType: { type: boolean }, bukan valuesType: boolean. Sebelum interpolasi, kompiler memeriksa map parameter gabungan langsung terhadap deklarasi ini: parameter yang tidak dideklarasikan oleh slot mana pun ditolak, slot bertanda required: true yang tidak diisi oleh Release maupun disediakan oleh default menghentikan build, dan setiap nilai yang diberikan diperiksa terhadap type yang dideklarasikan slotnya, keanggotaan enum-nya, batas minLength dan maxLength, ekspresi reguler pattern dan format pada slot string, serta batas min dan max — nilai slot numerik, panjang slot string, dan jumlah item slot array. Slot objek dan array diperiksa secara rekursif: setiap entri di bawah properties dan setiap elemen terhadap items diperiksa dengan cara yang sama, kontrak valuesType mengatur kunci yang tidak disebutkan oleh properties, dan kunci bersarang yang tidak disebutkan oleh deklarasi mana pun ditolak. Lihat vocabulary/compact-form-authoring.md untuk kosakata kata kunci lengkap, termasuk tempat pilar schema: mengeja kata kunci ini secara berbeda.

Kata kunci di bawah ini juga diperiksa pada deklarasi itu sendiri, sebelum nilai Release apa pun dibaca, sehingga slot yang tidak dapat membatasi apa pun menghentikan build bahkan ketika tidak ada Release yang memberikannya:

  • Batas panjang bernilai nol atau lebih. minLength atau maxLength negatif pada deklarasi parameter itu sendiri ditolak oleh skema Aggregate saat Aggregate dimuat, dengan menyebutkan parameter dan kuncinya. Di dalam kontrak bersarang — di bawah items, properties atau valuesType — batas panjang dibaca sebagaimana ditulis dan tidak diharuskan memenuhi batas bawah tersebut saat Aggregate dimuat, jadi tulislah batas itu sebagai nol atau lebih di sana juga: minLength negatif tidak membatasi apa pun, dan maxLength negatif menolak setiap nilai.
  • min dan max harus membatasi sesuatu. Pada slot boolean atau objek, pasangan ini tidak membatasi apa pun, sehingga min atau max yang ditulis di sana ditolak saat Aggregate dimuat, dengan menyebut parameter dan kuncinya.
  • Pattern harus dapat dikompilasi. Setiap pattern dikompilasi sebagai ekspresi reguler saat kontrak parameter dibaca — pada slot itu sendiri dan di dalam kontrak bersarang mana pun, pada kedalaman berapa pun — dan pattern yang tidak dapat dikompilasi ditolak dengan menyebutkan parameter, pattern, dan alasannya. Kontrak dibaca untuk setiap build, pull, dan validasi Release yang mencapai Aggregate, baik itu Aggregate milik Release itu sendiri maupun modul yang diimpor oleh Aggregate tersebut. Pemeriksaan nilai kemudian mencocokkan setiap nilai yang diberikan dengan ekspresi terkompilasi yang sama.
  • Format harus salah satu yang diperiksa kompiler. format menyebutkan salah satu dari email, uri, hostname, ipv4, ipv6, uuid, date-time dan date, dieja sebagaimana JSON Schema mengejanya. Nama lain apa pun — salah ketik seperti emial, atau nama yang tidak didefinisikan JSON Schema seperti password — ditolak saat Aggregate dimuat, dengan menyebutkan parameter dan mencantumkan nama-nama yang didukung: pada slot itu sendiri oleh skema Aggregate, dan di dalam kontrak bersarang, pada kedalaman berapa pun, saat kontrak parameter dibaca. String yang diberikan tetapi tidak memiliki format yang disebutkan kemudian ditolak dengan menyebutkan parameter, nilai, dan formatnya. Apa yang diperiksa oleh setiap nama dijelaskan di vocabulary/compact-form-authoring.md.

Parameter bertipe objek dan bertipe array

Slot parameter menerima tipe apa pun yang didukung bentuk ringkas, termasuk objek bersarang dan array berisi elemen bertipe:

spec:
parameters:
database_config:
type: object
description: Database connection configuration
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full], default: require }
pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels:
type: array
description: Custom Prometheus labels to attach to scraped metrics
items:
type: object
properties:
name: { type: string, required: true }
value: { type: string, required: true }

Release memenuhi parameter bertipe objek dengan YAML terstruktur; kompiler memvalidasi struktur tersebut terhadap skema yang dideklarasikan sebelum interpolasi. Template yang mereferensikan field objek menggunakan sintaks template Go standar: {{ .parameters.database_config.host }}, {{ .parameters.database_config.port }}, dan seterusnya.

Validasi kontrak parameter

Kontrak itu sendiri diperiksa lebih dahulu, saat dibaca — pemeriksaan batas panjang dan pola di bawah “Kosakata slot parameter” di atas. Kompiler kemudian menjalankan tiga sub-langkah selama pemrosesan parameter:

  1. Pengisian default — slot yang mendefinisikan default: dan tidak memiliki nilai yang disediakan Release menerima nilai default-nya. Parameter objek bersarang membawa semantik penulisan tiga kasus untuk slot induk yang dihilangkan, yang ditulis kosong secara eksplisit, dan yang ditulis sebagian: menghilangkan induk akan mengisi default anak-anaknya, menulis induk sebagai {} mempertahankan kekosongan eksplisit (menekan default anak-anaknya), dan menulis induk sebagai map yang tidak kosong hanya mengisi anak-anak yang tidak disediakan Release. Lihat templates/parameters-context.md untuk contoh YAML dan panduan keputusan “kapan menggunakan setiap bentuk”.
  2. Validasi kontrak — setiap nilai dalam map gabungan, baik yang disediakan Release maupun yang diisi oleh default:, divalidasi terhadap batasan type / enum / min / max / pattern / struktur bersarang yang dideklarasikan. Kegagalan validasi menghentikan build dengan galat yang jelas yang menyebutkan slot yang bermasalah, nilai yang disediakan, dan batasan yang dilanggar. Parameter wajib yang hilang tanpa default: menghasilkan penghentian serupa dengan nama slotnya.
  3. Interpolasi — kompiler mengevaluasi seluruh teks Aggregate sebagai templat, sebelum membacanya sebagai YAML, dan mengganti setiap referensi {{ .parameters.<slot> }} — biasanya di dalam string values: milik component / feature / sub-aggregate — dengan nilai yang telah diresolusi; setiap {{ lain dalam teks juga dibaca sebagai sintaks templat, sehingga nilai yang membawa kurung kurawal gandanya sendiri — misalnya definisi yang diekspor dari sebuah platform alur — menulis setiap {{ sebagai {{"{{"}}, seperti yang dijelaskan dalam Teks yang membawa kurung kurawal gandanya sendiri. Setelah tahap ini, permukaan templat nilai mengonsumsi literal yang sudah diinterpolasi dan tidak menerima .parameters dalam konteks templatnya.

Map parameter gabungan tetap hidup selama rendering untuk mendukung evaluasi templat path. Templat directory: dan subDirectory: yang ditulis operator pada batas Release membaca .parameters.<slot> secara langsung pada waktu render terhadap allowlist tertutup; emisi path memerlukan kosakata region / environment untuk tata letak artefak per environment, dan pemberian akses yang asimetris ini menjaga urusan operator tersebut tetap di dalam permukaan operator tanpa harus bolak-balik melalui values milik Aggregate. Map tetap dapat dibaca hingga setiap fase render selesai dan hanya dapat dijangkau dari kompilasi yang menjadi tujuan resolusinya; recipe yang mengonsumsi values: yang ditulis pengembang melihat string pasca-interpolasi, sedangkan templat path melihat data .parameters yang hidup selama rendering. Lihat templates/expansion-matrix.md baris 3 untuk matriks ketersediaan templat path dan path-template-variables.md untuk allowlist variabel templat path.

Untuk daftar periksa pengangkatan parameter yang lebih luas (deklarasi Aggregate → referensi values → pemenuhan Release → konsumsi Recipe) dan mekanisme lintas pilar, lihat vocabulary/data-pillars.md §“Parameters” dan §“The parameter-hoisting checklist”. Untuk field konteks templat yang diekspos selama interpolasi dan pengecualian templat path, lihat templates/parameters-context.md.

Edge uses adalah panggilan yang dideklarasikan Aggregate

Edge uses adalah pernyataan Aggregate bahwa satu komponen memanggil komponen lain. Compiler menyalurkan nilai-nilai yang dipublikasikan target ke pemanggil dan tidak membatasi apa pun: dengan sendirinya, sebuah edge tidak mengizinkan pemanggil dan tidak menolak pihak lain, dan workload yang menjangkau alamat target tanpa edge tetap menjangkaunya.

Membatasi siapa yang boleh memanggil sebuah komponen, dan apa yang boleh dipanggilnya, adalah keputusan operator, yang dibuat per lingkungan di dalam Release. Jika sebuah Release melampirkan Feature core/caller-allowlist dari katalog pustaka standar ke sebuah komponen, build menulis network policy yang mengizinkan tepat komponen-komponen yang edge uses-nya mengarah ke komponen tersebut, pod milik komponen itu sendiri, dan sumber-sumber yang disebutkan oleh lampiran tersebut. Pasangan arah keluarnya, core/egress-allowlist, membuat komponen tempat ia dilampirkan hanya dapat menjangkau komponen-komponen yang dituju oleh edge uses miliknya sendiri, pod miliknya sendiri, DNS kluster, dan rentang alamat yang dicantumkan Release. Panggilan yang tidak dideklarasikan Aggregate sebagai edge kemudian dapat ditolak oleh kluster di salah satu ujungnya, di mana pun plugin jaringannya menerapkan network policy. Karena itu, tulislah edge untuk setiap panggilan yang dilakukan komponen Anda, termasuk panggilan yang tidak menyuntikkan nilai apa pun: edge yang hilang adalah panggilan yang dapat ditolak oleh komponen yang dipagari. model-server-caller-allowlist menunjukkan model server yang hanya dapat dijangkau melalui gateway di depannya.

Lampiran milik koneksi sendiri: features pada entri uses

Koneksi yang dibuat oleh sebuah komponen dalam bentuk uses: verbosenya adalah entri tersendiri, dan di samping target, inject, dan values, koneksi tersebut dapat membawa lampiran, di bawah features:. Setiap lampiran dikunci oleh slot yang dideklarasikan oleh soket: Component yang mengonsumsi mencantumkan, dalam featuresSchema soket, slot-slot yang dapat diisi oleh setiap koneksi yang dihubungkan melalui soket tersebut (lihat Topology Sockets). Dengan cara inilah satu komponen memegang kredensial yang berbeda untuk setiap komponen yang dijangkaunya — sebuah gateway yang memanggil dua model dengan dua kunci, atau sebuah agen yang menyajikan kuncinya sendiri kepada sebuah model.

spec:
parameters:
openai_key_secret: { type: string }
components:
router:
type: core/gateway/litellm # its `models` socket declares a `credential` slot
values: { model: gpt } # the alias it publishes as its model
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
values:
origin: "{{ .parameters.openai_key_secret }}"
key: api-key
plain:
target: plain # this connection carries no attachment
gpt:
type: core/ai-model/openai
values: { model: gpt-4o-mini }
plain:
type: core/ai-model/ollama
values: { model: llama3.1 }

Lampiran pada koneksi membawa type (wajib), description opsional, dan values untuk Feature. Lampiran tersebut tidak membawa uses maupun inject: lampiran pada koneksi tidak bersarang, dan cara materialnya mencapai konsumen ditentukan oleh Recipe milik komponen yang mengonsumsi, bukan oleh blok inject. Dokumen yang menuliskan salah satunya ditolak saat dimuat, dengan menyebutkan kuncinya.

Hanya slot yang dideklarasikan oleh soket. Lampiran dengan nama yang tidak tercantum dalam featuresSchema soket menghentikan build saat dimuat, dengan menyebutkan koneksi, soket, komponen, dan slot-slot yang memang dideklarasikan oleh soket — serta, jika nama tersebut berjarak satu suntingan dari salah satunya, slot tersebut, sebagai ejaan yang kemungkinan dimaksud. Slot yang terisi kemudian tunduk pada deklarasi slot itu sendiri pada setiap koneksi: selector yang tidak dipenuhi oleh label Feature menghentikan build pada entri ini, dan slot required yang dibiarkan kosong pada koneksi mana pun menghentikan build dengan menyebutkan koneksi tersebut. Soket yang tidak mendeklarasikan slot tidak menerima lampiran pada koneksinya, demikian pula soket ad-hoc — soket yang dihubungkan oleh Aggregate tanpa dideklarasikan oleh Component — karena soket tersebut sama sekali tidak mendeklarasikan slot. Komponen yang disumbangkan oleh sub-modul tunduk pada aturan yang sama, dan temuannya menunjuk ke dokumen sub-modul itu sendiri. Lihat A connection carries an attachment under a name its socket declares no slot for (Sebuah koneksi membawa lampiran dengan nama yang tidak dideklarasikan slotnya oleh soketnya).

Koneksi yang dibuat oleh Feature tidak membawa lampiran. Blok uses: milik Feature yang dilampirkan — pada komponen atau pada subsistem — ditulis dalam bentuk yang sama, tetapi menolak features: saat dokumen dimuat. Kredensial yang dibutuhkan koneksi semacam itu mengisi slot yang dideklarasikan Feature dalam featuresSchema miliknya sendiri, dilampirkan di samping Feature tersebut; lihat A Feature’s Own Credential.

Nama yang diambil lampiran. Setiap lampiran koneksi menjadi lampiran milik komponen yang mengonsumsi, dengan nama <alias>.<slot> — alias tempat koneksi ditulis, sebuah titik, dan slot: gpt.credential di atas. Titik adalah pemisah yang dicadangkan untuk nama yang disusun oleh kompiler, yang tidak boleh terdapat dalam alias, slot, atau nama lampiran mana pun dalam Aggregate, sehingga nama yang disusun tidak pernah sama dengan nama yang ditulis pada blok features: milik komponen itu sendiri; Release yang menuliskannya pada komponen atau batas akan ditolak (lihat Per-edge connection configuration). Nama inilah yang digunakan tingkat per-instans Manifest sebagai kunci lampiran (lihat Flat URI mapping), nama yang digunakan diagnostik dan graf IR untuk melaporkannya, dan nilai yang dibaca FeatureRecipe lampiran tersebut sebagai .attachment_name (lihat Names derived from a connection’s attachment).

Dari situ, lampiran ini diselesaikan seperti lampiran lainnya: Manifest mengikat tipe Feature-nya ke sebuah FeatureRecipe, values-nya divalidasi terhadap skema Feature — kegagalan dilaporkan pada entri koneksi yang menuliskannya — dan FeatureRecipe-nya dirender terhadap values dan infra milik lampiran itu sendiri. Dua hal membedakannya dari lampiran milik komponen itu sendiri:

  • Lampiran ini tidak ada di .features milik Recipe yang mengonsumsi. Pilar tersebut hanya membawa lampiran yang ditulis pada blok milik komponen itu sendiri, sehingga Recipe yang mencari lampirannya sendiri berdasarkan tipe melalui .features tidak pernah diberi kredensial milik koneksi. Recipe membaca lampiran koneksi dari koneksi itu sendiri, di .context.uses.<alias>.features.<slot>, dalam bentuk yang dibawa .features — termasuk provides yang telah diselesaikan (lihat A connection’s attachments).
  • Lampiran ini hanya diterapkan pada konsumen. Keluaran yang dirender dari target tetap sama, apa pun yang dibawa oleh koneksi yang menjangkaunya.

Salinan graf atas blok yang ditulis. Graf IR menyimpan blok uses: setiap komponen sebagaimana ditulis, dan di sana lampiran koneksi mempertahankan type dan description-nya tanpa satu pun values-nya. Nilai-nilai tersebut muncul sekali, pada lampiran yang dibawa konsumen, tempat nilai yang dideklarasikan sensitif oleh Feature disembunyikan.

Release dapat menentukan ukuran lampiran yang dideklarasikan di sini dengan infra, atau melampirkan lampirannya sendiri pada koneksi yang dijangkaunya — lihat Per-edge connection configuration.

Menonaktifkan komponen atau modul: active:

Instans komponen dan modul sub-aggregate masing-masing menerima sakelar active: yang menentukan apakah entitas tersebut menjadi bagian dari topologi hasil kompilasi sama sekali. Jika dihilangkan, entitas tersebut ada; itulah bawaan dan kasus yang lazim.

spec:
parameters:
enable_cache:
type: boolean
default: false
components:
api:
type: core/server:1.0.0
redis:
type: core/redis:1.0.0
active: "{{ .parameters.enable_cache }}"
aggregates:
reporting:
type: my-catalog/reporting-module:1.0.0
active: false

Tuliskan boolean secara langsung, atau templat atas .parameters yang menghasilkan boolean. Bentuk templat adalah alasan sakelar ini ada: bentuk ini memungkinkan sebuah Release menentukan keberadaan entitas dengan memenuhi sebuah parameter, sehingga satu Aggregate mencakup lingkungan-lingkungan yang berbeda dalam bagian mana yang di-deploy — tanpa Release mendeklarasikan apa pun yang tidak dideklarasikan oleh Aggregate.

Apa yang dihapus oleh sakelar bernilai false. Entitas dipangkas sebelum graf dibangun, dan pemangkasan itu berantai: sebuah komponen membawa serta edge uses: miliknya dan Features yang dilampirkan padanya, dan sebuah modul membawa serta semua yang dikontribusikannya — komponennya, edge-nya, lampirannya. Tidak ada yang dibawa oleh entitas yang dipangkas yang di-render. Yang tidak dijangkau oleh pemangkasan adalah referensi ke entitas itu dari tempat lain yang tetap bertahan, yang dibahas pada paragraf berikutnya.

Komponen yang bertahan tetapi masih menunjuk ke komponen yang dipangkas akan menghentikan build. Jika api mendeklarasikan edge uses: ke redis dan redis dinonaktifkan, build berhenti alih-alih membiarkan edge tersebut lenyap, yang akan membuat nilai yang diinjeksikan ke api kosong secara diam-diam saat deploy. Tentukan mana dari keduanya yang termasuk dalam lingkungan ini: aktifkan kembali target, batasi konsumen dengan parameter yang sama sehingga keduanya hilang bersama, atau hapus edge tersebut dari blok uses: milik konsumen.

Sakelar yang ditulis harus menghasilkan boolean, dan nilai kosong bukan boolean. Sakelar dibaca secara ketat setelah templatnya diresolusi, dan literal yang tidak dapat di-parse sebagai boolean menghentikan build alih-alih menggunakan nilai bawaan apa pun. Kasus yang perlu diwaspadai adalah sakelar yang membaca parameter tanpa nilai: sakelar itu menghasilkan kekosongan, dan membaca kekosongan sebagai “ada” akan men-deploy entitas yang justru Anda batasi dengan parameter tersebut. Jadi, menulis active: tanpa apa pun setelahnya tidak sama dengan menghilangkan kunci tersebut — hanya sakelar yang tidak ditulis siapa pun yang bawaannya ada. Berikan parameter tersebut default: di spec.parameters agar setiap lingkungan memiliki jawaban, atau penuhi parameter itu di Release. Untuk membuat entitas ada tanpa syarat, hapus kunci active: alih-alih mengosongkannya. Penghentian ini dijelaskan pada “An active: toggle does not resolve to true or false (Sakelar tidak menghasilkan true atau false)” di referensi kondisi penghentian.

Komponen yang dinonaktifkan tetap dapat disebut dari Release. Sebuah Release masih dapat menyebutnya dalam boundary, dan hal itu disengaja: menonaktifkan komponen adalah tindakan penulisan, dan Release yang mengonfigurasinya tidak diharapkan ditulis ulang dalam suntingan yang sama.

Anotasi pada subsistem dan komponen

Subsistem dan instans komponen sama-sama memiliki bidang annotations:. Anotasi yang ditulis pengembang pada permukaan Aggregate menggerakkan kaskade anotasi sisi Aggregate — anotasi subsistem merambat ke setiap subsistem bersarang dan setiap komponen yang dikandungnya, dengan penimpaan dari tingkat yang lebih dekat pada granularitas per kunci. Peta mappings.features.annotations milik Manifest mendeklarasikan binding yang menerjemahkan kunci anotasi menjadi lampiran Feature sintetis pada waktu build. Invarian Aggregate-as-Authoring-Surface membatasi anotasi ini agar hanya dirutekan melalui jalur maps.values milik binding; binding yang hanya mendeklarasikan jalur maps.infra dipicu dari sisi Release, bukan dari sisi Aggregate.

Bentuk nilai

Setiap kunci anotasi memiliki salah satu dari empat bentuk, yang membedakan “saya diam” dari “saya mendeklarasikan nilai” — skalar atau objek terstruktur — dari “saya memilih keluar”:

  • Kunci tidak ada — cakupan tidak mendeklarasikan nilai untuk anotasi ini. Subsistem bersarang dan komponen yang dikandung mewarisi binding apa pun dari cakupan leluhur.
  • String skalar — satu nilai tunggal. Binding Manifest harus mendeklarasikan tepat satu jalur secara total; skalar dirutekan ke jalur tersebut.
  • Objek terstruktur — peta dari subkunci ke subnilai. Setiap subkunci objek dirutekan melalui maps milik binding Manifest ke bidang skema Feature yang sesuai pada pilar yang dideklarasikan.
  • YAML null eksplisit — cakupan menghapus binding warisan apa pun untuk kunci ini dari subpohonnya. Komponen bersaudara dan subsistem bersaudara tetap mempertahankan warisannya; hanya cakupan yang memilih keluar yang kehilangan binding tersebut.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker
components:
api:
type: core/server:1.0.0
# inherits feature.myco/db-pool: "shared-pool"
worker:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

Nilai terstruktur untuk Features multibidang

Feature dengan beberapa bidang yang dapat dikonfigurasi cocok menggunakan nilai anotasi terstruktur: satu kunci anotasi membawa nilai untuk beberapa bidang skema Feature dalam satu deklarasi. Sisi Aggregate hanya memicu subkunci yang pilar peta binding-nya adalah values; subkunci yang dirutekan ke infra termasuk dalam anotasi sisi Release.

spec:
subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "prod-db"
read_replicas: 5
components:
api:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
db_name: "api-override" # closer-level override at subkey granularity
# read_replicas not listed → inherits 5 from parent
analytics:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
read_replicas: null # per-subkey opt-out

Nilai terstruktur berkaskade dengan penggabungan mendalam per subkunci: subkunci dari tingkat yang lebih dekat menimpa subkunci induk; null eksplisit pada sebuah subkunci menekan subkunci warisan untuk cakupan tersebut sementara subkunci bersaudara tetap berlaku. Untuk penjelasan lengkap tentang nilai terstruktur — komposisi lintas sisi dengan subkunci infra sisi Release, validasi tipe per subkunci, disiplin default longgar untuk bidang skema tanpa type yang dideklarasikan — lihat providers/well-known-annotations.md §“Structured annotation values”.

Independensi per kunci

Setiap kunci anotasi mewarisi, menimpa, dan memilih keluar secara independen. Komponen yang mendeklarasikan annotations.feature.myco/db-pool: null hanya memilih keluar dari kunci tersebut; kunci lain yang diwarisi dari subsistem yang melingkupinya tetap merambat ke komponen itu. Komponen bersaudara dalam subsistem yang sama mempertahankan peta anotasinya masing-masing secara independen — pilihan keluar satu komponen tidak memengaruhi saudaranya.

Anotasi komponen tingkat atas

Komponen tingkat atas (dideklarasikan langsung di bawah spec.components, bukan di dalam subsistem) tidak memiliki kaskade warisan. Bidang annotations: miliknya mendeklarasikan nilai langsung pada cakupan komponen; ekspansi menyintesis lampiran Feature dari setiap anotasi yang dideklarasikan yang binding-nya tersedia di Manifest.

Untuk aturan kaskade sisi Aggregate yang diterapkan pada binding, pembagian sisi terhadap pilar, dan contoh lengkap dari awal hingga akhir yang menunjukkan binding menerjemahkan anotasi menjadi lampiran Feature sintetis, lihat providers/well-known-annotations.md §“Aggregate-side annotation cascade”.

Pola anchor YAML (blok defs:)

Skema Aggregate menerima blok defs: opsional di tingkat akar — daftar string YAML yang digunakan semata-mata sebagai wadah bagi anchor YAML standar (&anchor) dan referensi (*anchor). Isi blok ini tidak pernah dibaca oleh compiler; blok ini ada agar penulis dapat mendeklarasikan definisi anchor di satu tempat dan mereferensikannya di seluruh bagian lain Aggregate, sehingga nilai yang berulang tetap DRY tanpa kehilangan kamus datar O(1) yang diiterasi oleh compiler. Mekanisme ini mencerminkan blok defs: yang setara pada entitas Manifest.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: anchored-app
version: 1.0.0
defs:
- &default_log_level "info"
spec:
components:
primary:
type: core/compute/api-server:1.0.0
values:
log_level: *default_log_level
secondary:
type: core/compute/python:1.0.0
values:
log_level: *default_log_level

Anchor di-resolve pada saat parsing YAML, sehingga *default_log_level sudah menjadi string "info" ketika compiler membaca blok values. Blok defs: adalah tempat konvensional untuk definisi anchor; YAML mengizinkan anchor dideklarasikan di mana saja, tetapi menempatkannya bersama-sama menjaga bagian lain Aggregate tetap mudah dibaca. Blok ini opsional — Aggregates yang tidak memerlukan anchor menghilangkannya sepenuhnya.