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

Component

Peran konseptual entitas Component (antarmuka node komputasi abstrak di Domain 2) dijelaskan di architecture/04-entity-taxonomy.md. Halaman ini membahas permukaan penulisan Component: Semantic Label Taxonomy yang digunakan para Architect untuk melapisi identitas kognitif di atas ontologi dasar operasional, deklarasi schema: untuk pilar data, tabel deklaratif usesSchema dan featuresSchema untuk soket topologi dan slot lampiran, mandat kehadiran, mekanisme pewarisan extends:, serta blok aturan lintas bidang assertions:.

Taksonomi label semantik (konvensi pustaka standar)

Jika tipe dasar sepenuhnya cloud-native, kecerdasan operasional dan kognitif arsitektur dilapiskan seluruhnya melalui duck-typing semantik.

Compiler inti Go tidak menafsirkan label-label ini. Compiler membangun graf Intermediate Representation (IR) yang datar tanpa menafsirkan semantik label. Label-label ini merupakan Konvensi Pustaka Standar—“penanda genetik” yang tidak dapat diubah, ditulis oleh Platform Architect di Domain 2. Label-label ini menyediakan kait semantik eksplisit yang digunakan oleh validator kebijakan Wasm dan Recipes Ops fisik untuk mengatur arsitektur.

(A) Lapisan cloud generik Label-label ini mendeskripsikan perilaku universal, sehingga mesin kebijakan dan proxy L7 yang dihasilkan dapat mengatur arsitektur enterprise standar tanpa perlu memahami kerangka kerja AI secara native.

Prefiks labelNilai yang diizinkan (konvensi)Mengapa Platform Ops membutuhkannya (kait kebijakan)
tool.aggrega.ai/impactread-only, mutatingMemungkinkan mesin kebijakan mengevaluasi AuthZ Least-Privilege. Alat yang melakukan mutasi dapat secara otomatis memicu kebijakan yang mewajibkan sidecar approval-gate yang ketat untuk dipasang.
datastore.aggrega.ai/enginerelational, document, kv, vector, graph, semantic-memory, search (himpunan nilai sedang distabilkan terhadap katalog yang terisi)Memungkinkan mesin kebijakan menegakkan keamanan tipe lintas node (misalnya, mencegah agen mencoba mengirim payload SQL ke Vector DB).
gateway.aggrega.ai/intelligencesemantic, l4-meshMenentukan fitur apa yang secara fisik dapat didukung oleh sebuah router (misalnya, mencegah Feature yang merutekan berdasarkan model yang disebut oleh permintaan, seperti rantai fallback, dipasang pada mesh TCP standar).
dataplane.aggrega.ai/request-mirroringfull-rate, sampledMemungkinkan Feature yang menyalin lalu lintas langsung ke tujuan kedua memilih proxy yang memang dapat menyalin, serta membedakan proxy yang menyalin setiap permintaan yang cocok dari proxy yang porsi permintaan yang disalinnya dapat diatur.
dataplane.aggrega.ai/caller-identityclient-certificate, injected-headerMemungkinkan Feature yang membutuhkan pemanggil asli teridentifikasi bagi layanan di balik proxy memilih komponen yang dapat menyampaikan identitas tersebut, dan membaca mekanisme mana yang menyampaikannya — detail sertifikat TLS milik klien sendiri yang diteruskan, atau header yang disusun sendiri oleh proxy setelah mengautentikasi pemanggil.
dataplane.aggrega.ai/content-maskingentity-recognition, pattern-listMemungkinkan Feature yang menyamarkan teks sensitif memilih komponen yang dapat menggantinya dengan placeholder dalam payload chat dan completion yang dirutekannya, sebelum teks itu berjalan lebih jauh. Nilainya menyebutkan tingkat fidelitas: dengan entity-recognition komponen mengganti kecocokan pola yang diberikan dalam konfigurasinya, serta tipe entitas yang dideteksi oleh layanan pengenal yang dipanggilnya; dengan pattern-list komponen hanya mengganti kecocokan pola yang diberikan dalam konfigurasinya, dan tidak memanggil layanan pengenal apa pun.
dataplane.aggrega.ai/prompt-guardpattern-list, classifierMemungkinkan Feature yang menyaring prompt model memilih komponen yang dapat memeriksa payload chat dan completion yang dirutekannya dan menolak permintaan berdasarkan isinya. Nilainya menyebutkan tingkat fidelitas: dengan pattern-list pencocokan dilakukan terhadap pola yang diberikan dalam konfigurasinya, atas payload model dan bukan body HTTP sembarang; dengan classifier keputusannya berasal dari pengklasifikasi teks terlatih, yang dicapai melalui layanan deteksi yang dipanggil komponen, terhadap ambang batas yang diberikan dalam konfigurasinya.
dataplane.aggrega.ai/upstream-tlstrust-anchorMemungkinkan Feature yang mengharuskan proxy memeriksa dengan siapa ia berkomunikasi memilih komponen yang mampu memverifikasi sertifikat upstream terhadap trust anchor yang disediakan oleh Release.
dataplane.aggrega.ai/upstream-pinningpublic-keyMemungkinkan Feature yang menyematkan kunci mana yang boleh ditunjukkan oleh upstream memilih komponen yang mampu menolak upstream kecuali sertifikat yang ditunjukkannya memuat salah satu kunci publik yang disediakan oleh Release. Ini asersi yang berbeda dari upstream-tls: pin menyatakan kunci apa yang harus dimiliki sertifikat, sedangkan anchor menyatakan apa yang harus dinyatakan oleh sertifikat.
dataplane.aggrega.ai/period-budgetcost, tokensMemungkinkan Feature yang membatasi apa yang boleh dikonsumsi lalu lintas selama suatu periode memilih komponen yang mampu menolak permintaan model setelah apa yang telah dihitungnya selama periode itu melampaui batas yang ditetapkan dalam konfigurasinya. Nilainya menyebutkan apa yang dihitung: cost, biaya lalu lintas, dihitung dari tabel harga yang disimpan komponen per model; tokens, token yang dilaporkan oleh balasan setiap model sebagai dibaca, ditulis, atau keduanya, yang dihitung oleh komponen tanpa menetapkan harga apa pun.
dataplane.aggrega.ai/concurrency-captotal, per-targetMemungkinkan Feature yang membatasi berapa banyak permintaan yang dibawa komponen sekaligus memilih komponen yang mampu menahan atau menolak permintaan yang melewati batas yang ditetapkan dalam konfigurasinya. Nilainya menyebutkan apa yang dihitung oleh satu batas: total, setiap permintaan yang diteruskan komponen, terhadap satu batas; per-target, permintaan yang sedang berjalan ke setiap target upstream yang dituju, dengan batas untuk masing-masing dan tanpa batas atas totalnya.

Kunci dataplane.aggrega.ai/ menyebutkan posisi pada jalur lalu lintas, bukan jenis komponen, sehingga proxy, ingress gateway, dan service mesh semuanya mendeskripsikan dirinya dalam satu kosakata alih-alih masing-masing membutuhkan kosakatanya sendiri. Dua sifat keluarga ini perlu dibaca dengan cermat, karena keduanya mudah tertukar:

  • Nilai membawa tingkat fidelitas, bukan sekadar keberadaan kemampuan. Dua komponen sama-sama dapat mencerminkan permintaan namun tetap berbeda dalam hal yang dipedulikan Feature, sehingga perbedaannya dibawa dalam nilai dan Feature memilih tingkat fidelitas yang dibutuhkannya. Komponen yang menawarkan fidelitas lebih kuat membawa nilai yang lebih kuat dan tidak ada nilai lain.
  • Nilai menyatakan apa yang mampu dilakukan produk, tidak pernah apa yang telah diaktifkan oleh suatu deployment. Keduanya terbaca mirip dan hanya yang pertama merupakan sifat komponen. Proxy yang dapat memverifikasi sertifikat upstream membawa upstream-tls: trust-anchor terlepas dari apakah suatu deployment mengaktifkan pemeriksaan tersebut atau tidak, karena label adalah dasar pemilihan Feature sebelum apa pun dikonfigurasi.

Komponen yang tidak memiliki apa pun untuk dideskripsikan pada salah satu sumbu ini tidak membawa nilai di sana, alih-alih nilai terlemah, persis seperti di bagian lain taksonomi: ketiadaan berarti sumbu tersebut tidak memiliki subjek pada komponen itu, sehingga Feature yang mensyaratkan nilai apa pun pada sumbu itu secara benar tidak terpasang.

(B) Lapisan AI khusus (identitas kognitif) Label-label ini mendeskripsikan identitas kognitif workload, sehingga arsitektur dapat mengamankan kerangka kerja AI modern.

Prefiks labelNilai yang diizinkan (konvensi)Mengapa Platform Ops membutuhkannya (kait kebijakan)
model.aggrega.ai/capabilitygenerative, embedding, transcriptionDigunakan oleh string selektor usesSchema (dievaluasi secara native oleh compiler Go selama analisis statis) untuk menjamin developer tidak secara tidak sengaja merutekan payload teks generatif ke endpoint embedding.
model.aggrega.ai/apiopenai, anthropic, gemini, nativeMenyebutkan API model mana yang menjawab di alamat yang dipublikasikan komponen: openai jika itu adalah OpenAI API, baik milik vendor sendiri maupun implementasi server atasnya, anthropic jika itu adalah Messages API Anthropic, baik milik vendor sendiri maupun implementasi server atasnya, gemini jika itu adalah Gemini API Google, dan native jika itu adalah API milik produk sendiri dan bukan salah satu dari itu. Setiap komponen model membawanya, begitu pula gateway yang mampu melayani API model, sehingga soket yang memilih component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api menerima model atau gateway semacam itu dan menolak gateway yang tidak mampu melayani satu pun, sedangkan soket yang menyebutkan satu nilai, seperti model.aggrega.ai/api=anthropic, hanya menerima yang melayani API tersebut. Label ini menyebutkan apa yang dilayani produk, bukan apa yang dihubungkan oleh satu Release: gateway yang model-modelnya dihubungkan ke soketnya sendiri tetap membawanya meskipun tidak ada yang dihubungkan. Label ini adalah string yang dicocokkan oleh selektor; tidak ada yang memeriksa apa yang sebenarnya menjawab di alamat tersebut.
agent.aggrega.ai/autonomyautonomous, copilotMengidentifikasi risiko eksekusi dari loop kognitif, sehingga kebijakan dapat mewajibkan fitur persetujuan manusia untuk agen yang sepenuhnya otonom.

(C) Lintas sektoral (tata kelola, state, & perangkat keras) Ini merupakan tag enterprise dasar yang mendorong validasi Zero-Trust dan perutean perangkat keras.

Prefiks labelNilai yang diizinkan (konvensi)Mengapa Platform Ops membutuhkannya (kait kebijakan)
component.aggrega.ai/hostingself-hosted, managed, external, mixedMencatat siapa yang mengoperasikan sumber daya yang mendasari komponen — sumbu batas kepercayaan. Mesin kebijakan membacanya untuk menghitung risiko Data Exfiltration (misalnya, data internal yang dirutekan ke API pihak ketiga managed meninggalkan batas operator). Lintas sektoral: nilai yang sama mendeskripsikan database terkelola, API model terkelola, dan server inferensi yang dijalankan sendiri secara setara. mixed menandai komponen yang Recipes-nya mencakup lebih dari satu bentuk pengoperasian — penyimpanan data yang di-host sendiri oleh Recipes Helm dan Compose-nya dan dikelola oleh Recipes RDS-nya — sehingga bentuk pengoperasian sebuah Release mengikuti Recipe yang dipilih oleh Manifest-nya.
compliance.aggrega.ai/data-classpublic, internal, restrictedKelas data yang disimpan sebuah komponen. Compiler membawanya ke graf build sebagai string dan tidak memberi peringkat apa pun; sebuah kebijakan yang dipasang operator pada peran ir-verdict memberikan urutan kelas-kelas tersebut dalam pengaturannya sendiri dan membaca label di sepanjang rute yang dienumerasi compiler — misalnya menghentikan build ketika komponen restricted menjangkau komponen dari kelas lain tanpa Feature deklasifikasi yang terpasang pada rute tersebut (policy-data-class-route). Tidak ada Component pustaka standar yang membawanya: kelas adalah pernyataan tentang cara sebuah estate menggunakan komponen, yang dibawa oleh Component milik estate itu sendiri — misalnya spesialisasi melalui extends.
compliance.aggrega.ai/contains-piitrue, falseSecara eksplisit menandai workload untuk cakupan GDPR/CCPA. Kebijakan yang dipasang operator dapat membacanya untuk mewajibkan Features tertentu pada rute yang dilalui lalu lintas workload tersebut — misalnya core/data-masking pada gateway AI yang dilalui lalu lintas modelnya, bentuk yang diperiksa policy-data-class-route untuk kelas data. Tidak ada Component pustaka standar yang membawanya; seperti kelas data, ini adalah pernyataan sebuah estate tentang komponennya sendiri.
hardware.aggrega.ai/acceleratorgpu, tpu, npuDigunakan oleh DevOps dalam berkas Release. Mereka secara eksplisit merutekan komponen-komponen ini ke batas pool perangkat keras fisik (misalnya, klaster yang mendukung GPU) melalui map components: {}, sementara peran verdict tata kelola dapat memastikan bahwa komponen berlabel GPU tidak pernah ditempatkan di batas non-GPU.
state.aggrega.ai/retentionretain, deleteMengatasi AOT Deletion Gap. Jika pengembang menghapus basis data dari Aggregate miliknya, orkestrator GitOps akan secara fisik menghapus disk. Langkah pipeline: milik Recipe dapat membaca label retain dan menambahkan perlindungan bawaan orkestrator ke artefak yang dirender (misalnya, helm.sh/resource-policy: keep).
state.aggrega.ai/backup-tiermission-critical, standard, ephemeralHook ketersediaan SOC2. Memberi tahu FeatureRecipe Ops apakah konfigurasi Snapshot/Volume Backup otomatis perlu dibuat secara fisik untuk sumber daya tersebut.

(D) Konteks bisnis dinamis (anotasi berjenjang) Sementara labels mendefinisikan DNA Katalog yang tidak dapat diubah, konteks bisnis dinamis (seperti cakupan audit SOC2 atau pelacakan biaya FinOps) berubah tergantung siapa yang men-deploy aplikasi dan di mana aplikasi berjalan. Konteks ini diatur oleh anotasi yang disuntikkan secara dinamis oleh subsystems milik pengembang, batas Release Ops, atau plugin tata kelola yang dipasang pada peran annotation-transform.

Prefiks anotasiNilai yang diizinkan (konvensi)Mengapa Platform Ops membutuhkannya (kait kebijakan)
business.aggrega.ai/cost-centermisalnya, finance, ai-researchDiperlukan oleh plugin rendering Wasm untuk menyuntikkan penandaan fisik (misalnya, tag AWS atau label K8s) ke dalam artefak akhir yang dihasilkan untuk dasbor penagihan cloud.
business.aggrega.ai/ownermisalnya, team-alpha@corp.comPerutean respons insiden. Menjamin infrastruktur dipetakan ke tim manusia.
compliance.aggrega.ai/frameworksmisalnya, soc2, hipaaPemicu cakupan SOC2. Disuntikkan melalui Release lingkungan. Plugin Wasm membaca string ini untuk secara otomatis membuat sidecar audit-logging yang ketat dan menonaktifkan port debug ketika aplikasi memasuki batas kepatuhan produksi.

Taksonomi ini adalah konvensi katalog, bukan aturan compiler. Perusahaan dapat mengabaikannya, menghapusnya, atau membuat kosakata label sendiri (mycompany.com/custom-trait). Plugin Wasm mengevaluasi kunci label apa pun yang ditulis perusahaan.

Penulisan skema

Skema Component (beserta padanannya, Feature, termasuk Features kredensial yang berlabel feature.aggrega.ai/kind: secret) mendeklarasikan kontrak validasi untuk values yang ditulis pengembang melalui blok spec.schema:. Blok ini menerima JSON Schema 2020-12 yang dinyatakan dalam singkatan YAML bentuk ringkas (bawaan; sekitar 15 kata kunci, yang ditransformasikan secara mekanis menjadi JSON Schema pada waktu kompilasi) atau dalam YAML JSON Schema lengkap (bentuk verbose), dengan referensi lintas dokumen melalui $ref: untuk entri SchemaLibrary yang digunakan bersama oleh beberapa Components.

  • Bentuk ringkas inline (permukaan penulisan bawaan): blok YAML tertanam yang memuat leaf bentuk ringkas langsung di dalam YAML Component. Cocok untuk sebagian besar konten skema katalog dengan jumlah baris yang jauh lebih sedikit dibandingkan JSON Schema lengkap. Lihat vocabulary/compact-form-authoring.md untuk kosakata kata kunci dan konvensi penulisan.
  • YAML JSON Schema inline: bentuk verbose, sesuai bila skema memerlukan kata kunci JSON Schema 2020-12 yang tidak dimuat langsung oleh bentuk ringkas ($dynamicRef, unevaluatedProperties yang dalam, komposisi not: yang kompleks). Bentuk ringkas dan JSON Schema dapat dicampur pada batas node mana pun dalam satu blok schema: melalui jalan keluar $jsonschema:.
  • Referensi lintas dokumen ($ref: ke entri SchemaLibrary): $ref: bawaan JSON Schema yang menunjuk ke entri SchemaLibrary berdasarkan identitas (Datastores#/schemas/MariaDBValues atau sejenisnya). Skema perusahaan yang mencakup ratusan baris dan digunakan ulang di beberapa Components disimpan dalam entitas SchemaLibrary; Component konsumen mereferensikan entri tersebut tanpa menyisipkan kontennya. Lihat entities/schemalibrary.md dan vocabulary/cross-document-ref.md untuk entitas pustaka dan semantik resolusinya.

Ketiga bentuk di atas menulis konten pilar, dan tersedia bagi Component yang tidak memperluas apa pun. Component yang mendeklarasikan extends: sama sekali tidak menulis konten pilar: Component tersebut menulis penanda literal schema: inherited dan menerima blok pilar dari basisnya persis seperti yang ditulis basis tersebut. Penanda itu adalah satu-satunya nilai yang dapat diambil schema: pada Component semacam itu. Lihat “Catalog Authoring: Extending Base Components” di bawah.

Kompiler meresolusi blok schema: — mengekspansi bentuk ringkas, mendereferensi URL $ref:, menerapkan rantai pustaka-ke-pustaka SchemaLibrary — dan menyatukan JSON Schema yang dihasilkan dengan basis yang dibuat otomatis dari usesSchema dan featuresSchema (lihat bagian di bawah) selama tahap validasi Component. Validasi dijalankan terhadap skema yang telah diresolusi; jalur penulisan tidak terlihat oleh tahap pipeline selanjutnya.

Instans yang ditulis divalidasi terhadap skema yang telah diresolusi ini pada waktu build: values yang ditulis pengembang pada instans komponen dan infra yang diresolusi oleh Operator, beserta values/infra pada setiap lampiran Feature, harus sesuai dengan pilar yang dideklarasikan — nilai dengan tipe yang salah, angka di luar rentang, string yang tidak memiliki format yang dideklarasikan, field wajib yang hilang, atau (untuk values, yang divalidasi secara tertutup) properti yang tidak dideklarasikan akan menghentikan build pada sumber penulisannya alih-alih menghasilkan manifest yang rusak pada waktu deploy. Pilar yang skemanya menyebut format yang tidak diperiksa oleh kompiler — apa pun di luar email, uri, hostname, ipv4, ipv6, uuid, date-time dan date, termasuk password — ditolak saat katalog dimuat, dengan mencantumkan nama-nama yang didukung; lihat vocabulary/compact-form-authoring.md untuk apa yang diperiksa oleh setiap nama. Instans dari Component yang melakukan extends: terhadap suatu basis divalidasi terhadap blok pilar basis tersebut, yang diwarisi tanpa perubahan oleh Component yang memperluasnya — sehingga instans basis dan instans dari apa pun yang memperluasnya menghadapi kontrak pilar yang sama. Lihat errors/fatal-halts.md §“Authored values or infra do not conform to the declared schema (Values atau infra yang ditulis tidak sesuai dengan skema yang dideklarasikan)” untuk diagnostik dan aturan per pilar (termasuk cara infra divalidasi terhadap gabungan kunci Component dan provider).

Default yang dideklarasikan diwujudkan ke dalam pilar yang dirender. Selain validasi, default: yang dideklarasikan pada field values (atau field infra) diisikan ke dalam pilar yang dirender pada waktu build untuk setiap kunci yang dihilangkan oleh penulis — sehingga template Recipe yang membaca {{ .values.charset }} menerima utf8mb4 yang dideklarasikan skema alih-alih nilai kosong. Nilai yang diberikan penulis selalu diutamakan; objek bertingkat diisi per anak yang dihilangkan. Karena perwujudan ini menggunakan resolusi skema yang sama dengan validasi, default yang dicapai melalui $ref: lintas dokumen ke SchemaLibrary juga diwujudkan — baik referensi seluruh pilar (values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}) maupun bentuk basis-plus-varian ($ref: basis berdampingan dengan properties saudara, masing-masing membawa default-nya sendiri). Default yang dideklarasikan hanya di dalam referensi lokal dalam dokumen #/$defs/, atau di bawah cabang allOf / oneOf / anyOf, tidak diwujudkan; pustaka standar menyusun pilar melalui $ref: lintas dokumen, yang diwujudkan.

Pilar values

Skema Component memisahkan tiga pilar berdasarkan kepemilikan: values diisi oleh Developer di Aggregate (niat kognitif — nama basis data, versi, charset), infra diisi oleh Operator di Release (ukuran operasional — komputasi, penyimpanan, HA), dan provides ditetapkan oleh Recipe (kontrak API publik — host, port, protokol). Developer tidak pernah melihat infra; Operator tidak pernah melihat values. Recipes mengonsumsi kedua pilar selama rendering dasar, memetakan pilar abstrak ke dalam bentuk konkret yang diharapkan oleh provider targetnya. Bagian ini membahas permukaan penulisan pilar values. Lihat vocabulary/data-pillars.md untuk taksonomi pilar yang lebih luas dan disiplin kaskade lintas pilar.

values membawa niat kognitif Developer — pilihan yang menggambarkan apa aplikasi itu atau apa yang dilakukannya, bukan bagaimana ukurannya atau cara menjalankannya. Nama basis data, charset, versi engine, tingkat log, feature flag, serta pengaturan tingkat aplikasi yang berubah antarversi aplikasi tetapi tetap stabil di seluruh lingkungan adalah konten values yang umum. Operator tidak pernah menimpa values: (skema Release secara mekanis menolak blok values: sesuai architecture/06-data-taxonomy-and-composition.md §8 Batasan 4); variasi per lingkungan dialirkan melalui Parameter Hoisting — Aggregate mengekspos parameters.* bertipe, templat values milik Component mereferensikannya, dan Release memenuhi parameter tersebut.

# Component schema declares the values shape:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
charset: { type: string, default: utf8mb4, enum: [utf8mb4, latin1, ascii] }
engine_version: { type: string, default: "10.11" }
log_level: { type: string, default: info, enum: [debug, info, warn, error] }
# Aggregate fragment — the developer fills values:
components:
customer-db:
type: core/datastore/mariadb
values:
database_name: customers
charset: utf8mb4
engine_version: "{{ .parameters.mariadb_version }}" # Parameter Hoisting
log_level: info

Konsumsi di sisi Recipe. Recipes membaca nilai yang telah diresolusi melalui .values.<field> di valuesMapping:, provides:, assertions:, dan permukaan templat lainnya — lihat entities/recipe.md untuk matriks ketersediaan per templat. Compiler menyatukan skema values milik Component dengan skema values: dari lampiran Feature mana pun pada node Component yang sama sehingga konteks templat yang telah diresolusi membawa setiap field yang berlaku.

Disiplin lintas pilar. values adalah satu-satunya pilar yang ditulis Developer di Aggregate. Field yang benar-benar ditujukan bagi developer ditempatkan di sini; pengaturan operasional (jumlah replika, batas CPU/memori) ditempatkan pada pilar infra milik Component sehingga berada di Release; output publik (host, port) ditempatkan pada provides milik Recipe. Mencampurkan hal-hal ini merusak invarian kepemilikan; lihat vocabulary/data-pillars.md “Mekanika lintas pilar” untuk kasus langka di mana penyaluran lintas pilar yang disengaja dapat dibenarkan.

Pilar infra

Skema Component memisahkan tiga pilar berdasarkan kepemilikan: values diisi oleh Developer di Aggregate (maksud kognitif — nama basis data, versi, charset), infra diisi oleh Operator di Release (penentuan ukuran operasional — komputasi, penyimpanan, HA; cadangan penyimpanan data tidak ditentukan ukurannya di sini, melainkan merupakan Feature core/backup yang dilampirkan Operator di Release), dan provides ditetapkan oleh Recipe (kontrak API publik — host, port, protokol). Developer tidak pernah melihat infra; Operator tidak pernah melihat values. Recipes mengonsumsi keduanya selama rendering dasar, dengan memetakan pilar abstrak ke bentuk konkret yang diharapkan oleh provider targetnya.

Tiga konvensi infra penting di setiap Component yang agnostik terhadap kapabilitas dalam pustaka standar: jalan keluar berupa struct terbuka untuk pengaturan khusus provider, override opsional untuk versi artefak upstream, dan kosakata berbasis maksud untuk bidang ketersediaan tinggi. Component referensi kanonis adalah core/datastore/mariadb dalam katalog pustaka standar — dapat diimplementasikan oleh Recipes Helm yang menjalankan image mariadb resmi atau menyerahkan custom resource MariaDB ke controller mariadb-operator, Recipes Terraform terhadap AWS RDS, Recipes CloudFormation terhadap permukaan RDS yang sama, dan Recipes Compose terhadap kontainer lokal — dan blok infra-nya mengilustrasikan pola pertama dan ketiga.

infra.overrides

Bidang infra universal — compute, storage, ha — mencakup sebagian besar penentuan ukuran operasional di berbagai provider. Sisanya tidak dapat direduksi dan bersifat khusus provider: Recipe Kubernetes memerlukan nodeSelector, Recipe Terraform RDS memerlukan instance_class, Recipe CloudFormation RDS memerlukan DBInstanceClass, Recipe Compose memerlukan override image. Skema Component menyediakan map yang benar-benar terbuka sebagai jalan keluar agar pengaturan ini dapat diteruskan tanpa membengkakkan skema:

infra:
# ... universal fields ...
# Provider-specific overrides. Accepts any nested structure.
# Each Recipe documents which keys it reads.
overrides:
type: object
additionalProperties: true # genuinely open map: arbitrary nested structure permitted

type: object eksplisit dengan additionalProperties: true memilih semantik map terbuka. Compiler meneruskan struktur tersebut tanpa diubah; badan templat Recipe membaca kunci mana pun yang dikenalnya dan mengabaikan sisanya. Setiap Recipe mendokumentasikan ontologi kunci override dalam komentar header-nya, sehingga Operator yang menulis Release untuk kombinasi Component × Recipe tertentu mengetahui pengaturan apa saja yang disediakan Recipe tersebut.

Fragmen Release yang menggunakan overrides:

components:
main-db:
infra:
compute: { cpu: "2", memory: 8Gi }
storage: { size: 40Gi, type: balanced-csi }
overrides:
nodeSelector:
kubernetes.io/hostname: cluster1-worker1
service_type: LoadBalancer
metrics:
enabled: true
image:
repository: bitnamilegacy/mysqld-exporter

Developer tidak pernah melihat overrides — bidang ini berada di Release, yang merupakan domain Operator.

infra.source_version

Bidang source milik Recipe mereferensikan artefak upstream pada versi tertentu (chart Helm 25.0.8, modul Terraform 4.2.0, tag image OCI). Menuliskan versi secara tetap di dalam Recipe memaksa pengelola katalog menerbitkan Recipe baru pada setiap kenaikan versi upstream yang kompatibel. Skema Component menyediakan override opsional:

infra:
source_version:
type: string
description: |
Source artifact version. A Recipe versions its artifact from this key
where its source resolution reads it, and is unaffected where it does not.
Changing from the version a Recipe was authored against does not
guarantee value mapping compatibility.

Recipe membacanya melalui helper optional dalam blok source-nya, sehingga pin yang tidak ada akan jatuh ke versi yang menjadi dasar penulisan Recipe:

source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "{{ optional .infra `source_version` `25.0.8` }}"

String source milik Recipe (dan sub-bidang bernilai string dari map source: terstruktur) dievaluasi sebagai templat Go. Koordinat jarak jauh — seperti version di atas — dievaluasi ketika aggrega pull mematok artefak, terhadap .values, .infra, dan .locals tanpa root .context; source yang menyebut path di dalam workspace dievaluasi saat entitas dirender, terhadap konteks mandiri yang sama dengan locals milik Recipe — .context.instance_id, .values, .infra, dan seluruh .locals node yang telah di-resolve. Pada keduanya, .context.inject, .context.uses, dan .provides dilarang. Keberadaan .infra dalam konteks tersebut yang membuat override di atas berfungsi, dan .locals memungkinkan Recipe menghitung fragmen source sekali lalu membacanya kembali di sini. Templat source tidak pernah membaca provides milik node-nya sendiri: pilar tersebut bukan bagian dari konteks, dan templat yang mencoba mengaksesnya akan menghentikan build — ini adalah sifat tetap dari permukaan tersebut, bukan kekurangan yang menunggu pengerjaan selanjutnya. Lihat Template Expansion Matrix baris #5 untuk aturan ketersediaan lengkap. Mengubah infra.source_version dari nilai default Recipe tidak menjamin bahwa valuesMapping milik Recipe kompatibel secara wire dengan versi upstream yang baru; description pada deklarasi source_version di skema Component memuat peringatan tersebut.

infra.ha.*

Bidang ketersediaan tinggi menggunakan kosakata maksud, bukan kosakata mekanisme:

infra:
ha:
enabled: { type: boolean, default: false }
read_replicas: { type: integer, min: 0, default: 0 }

infra.ha.enabled berarti “jadikan Component ini sangat tersedia,” dan infra.ha.read_replicas berarti “Saya menginginkan N salinan hanya-baca.” Setiap Recipe menentukan menjadi apa maksud tersebut pada provider-nya. Recipes pustaka standar untuk core/datastore/mariadb, dengan nama yang dipakai Manifest untuk memetakannya:

Recipeha.enabled: true dipetakan keha.read_replicas: N dipetakan ke
helm/mariadb (StatefulSet pada image mariadb resmi)menjalankan satu server, sehingga build berhenti dengan menyebut kuncinyamenjalankan satu server, sehingga N di atas 0 menghentikan build
helm/mariadb-cluster (custom resource MariaDB yang direkonsiliasi oleh controller mariadb-operator)mengaktifkan failover otomatis (replication.primary.autoFailover: true); failover dilakukan ke replika baca, sehingga N bernilai 0 menghentikan buildmenyetel spec.replicas ke N + 1 dan mengaktifkan replikasi; provides.host menjadi Service <name>-primary
terraform/mariadb-rds (AWS RDS)menetapkan multi_az = true pada aws_db_instance primermembuat N sumber daya read-replica aws_db_instance terpisah
terraform/mariadb-rds-module, terraform/mariadb-rds-terraform-aws-modules (AWS RDS melalui modul)meneruskan multi_az = true ke modulmenyediakan satu instans, sehingga N di atas 0 menghentikan build
cloudformation/mariadb-rds (AWS RDS)menetapkan MultiAZ: true pada AWS::RDS::DBInstancemenyediakan satu instans, sehingga N di atas 0 menghentikan build
compose/mariadb (kontainer pengembangan lokal)menjalankan satu server, sehingga build berhenti dengan menyebut kuncinyamenjalankan satu server, sehingga N di atas 0 menghentikan build

Kosakata mekanisme (infra.primary.replicas) terasa wajar untuk satu provider (pod Kubernetes adalah replika dari StatefulSet) tetapi menjadi kesalahan kategori di tempat lain — RDS tidak memiliki konsep “replicas” pada primer, CloudFormation mencerminkan RDS, dan Compose sama sekali tidak memiliki abstraksi replika horizontal. Kosakata maksud dapat diterjemahkan: setiap provider memiliki suatu konsep “jadikan basis data ini sangat tersedia” dan suatu konsep “Saya menginginkan N salinan hanya-baca,” dan Recipe membawa terjemahan per provider. Jika sebuah realisasi tidak memiliki mekanisme seperti itu, Recipe-nya dapat menghentikan build dengan menyebut kuncinya, seperti yang dilakukan helm/mariadb dan compose/mariadb untuk kedua kunci dan Recipes RDS satu instans untuk replika baca.

infra.ha.read_replicas: 0 adalah default; dengan kedua kunci pada nilai default-nya, helm/mariadb-cluster merender MariaDB satu instans tanpa blok replication, bukan replikasi di atas satu instans. compose/mariadb menjalankan satu server pada host Docker lokal, sehingga infra.ha.enabled: true atau infra.ha.read_replicas yang bukan nol menghentikan build dengan menyebut kuncinya, dan pesannya mengarahkan ke helm/mariadb-cluster, yang menyediakan failover dan replika baca.

Pilar provides

provides adalah API publik yang ditulis oleh Recipe — nilai-nilai yang disumbangkan oleh Recipe hasil resolusi sebuah Component kepada pemanggil hilir melalui permukaan .context.uses.<alias>.provides.<provided-name> mereka (atau, bila pemanggil mendeklarasikan allowlist inject: pada edge, melalui pipa .context.inject-nya). Skema Component mendeklarasikan bentuknya (nama kunci beserta tipe); blok provides: milik Recipe yang terikat menyediakan nilainya. Developer yang menulis Aggregate melihat bentuk provides pada halaman Component sebagai kontrak yang dapat diandalkan oleh pemanggil; penulis Recipe memenuhi kontrak tersebut untuk implementasi spesifik yang dibungkusnya.

Pemenuhan ditegakkan sebagai Loud Guardrail: Recipe yang terikat harus menghasilkan setiap kunci provides yang dideklarasikan oleh Component-nya. Jika Recipe yang terikat menghilangkan kunci yang dideklarasikan, build berhenti dan menyebutkan kunci yang hilang, alih-alih diam-diam tidak mengirimkan apa pun kepada pemanggil yang mereferensikannya. Menghasilkan kunci tambahan di luar himpunan yang dideklarasikan diperbolehkan. Hanya keberadaan kunci yang diperiksa — nilai yang dihasilkan adalah string buram yang diteruskan oleh compiler, sehingga tipe yang dideklarasikan tetap merupakan kontrak yang dibaca pemanggil, bukan nilai yang divalidasi compiler.

# Component schema declares the provides contract:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
provides:
host: { type: string }
port: { type: integer }
database: { type: string }
# Recipe fulfills the contract:
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-bitnami
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "25.0.8"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
database: "{{ .values.database_name }}"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

Pemisahan evaluasi provides-lalu-inject. Compiler mengevaluasi templat provides: pada tahap evaluasi provides terhadap konteks templat yang mandiri (.context.instance_id, .context.rendered_name bila provider node melaporkannya, .values, .infra, dan locals: hasil resolusi milik Recipe pada node yang sama) — tidak ada status pemanggil yang terlihat. Locals node diresolusi dalam preambul tahap tersebut, sebelum provides-nya, yang memungkinkan templat provides: membaca .locals. Pada hidrasi inject, yang berjalan berikutnya, compiler menelusuri edge uses: dan meresolusi .context.uses.<alias>.provides.<provided-name> setiap pemanggil terhadap nilai provides yang telah diresolusi. Pemisahan keduanya menjamin resolusi yang asiklik: provides: tidak dapat mereferensikan pemanggil, dan inject: milik pemanggil tidak dapat mereferensikan keluaran provider yang belum diresolusi hingga hidrasi inject berjalan.

Evolusi kontrak. Mengganti nama atau menghapus sebuah field provides merupakan perubahan yang merusak bagi setiap pemanggil yang mengandalkan nama lama. metadata.version milik Component (dan deklarasi implements: milik Recipe) membawa sinyal evolusi kontrak; pemanggil hilir yang dipatok ke versi mayor tertentu melihat bentuk provides yang stabil.

Pengajaran sisi Recipe. Untuk tata bahasa penulisan templat provides:, matriks ketersediaan per templat, serta contoh lengkap perutean lintas namespace dan lintas region, lihat entities/recipe.md “The provides: block” dan architecture/06-data-taxonomy-and-composition.md §3.

Mandat kehadiran: features.aggrega.ai/requiredType.<label>

Sebuah Component dapat menyatakan bahwa setiap instansnya wajib membawa lampiran dari jenis Feature tertentu. Ini adalah mandat kehadiran, dan ditulis sebagai anotasi yang dapat diulang pada metadata Component itu sendiri:

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/payment-processor
version: 1.0.0
labels:
component.aggrega.ai/type: server
annotations:
features.aggrega.ai/requiredType.audit: core/audit-logging
features.aggrega.ai/requiredType.compliance: core/pci-compliance
spec:
schema:
values:
processor_endpoint: { type: string, required: true }

Kuncinya adalah prefiks features.aggrega.ai/requiredType. diikuti label yang Anda pilih; nilainya adalah URI jenis Feature yang harus dibawa oleh setidaknya satu lampiran. Label tersebut menamai persyaratan dalam diagnostik yang dihasilkan oleh mandat yang tidak terpenuhi — audit dan compliance di atas — dan hanya itulah fungsinya. Kunci berlabel adalah cara sebuah Component menyatakan lebih dari satu mandat sekaligus: anotasi adalah peta string datar dan tidak dapat membawa kunci duplikat.

Compiler mengevaluasi setiap mandat terhadap himpunan lampiran akhir instans, setelah kaskade 5-Tier Onion Model melipat setiap cakupan: blok features: tingkat komponen dan tingkat subsistem milik Aggregate, blok features: tingkat batas dan tingkat komponen milik Release, serta lampiran yang dihasilkan oleh ekspansi berbasis anotasi. Salah satu dari semuanya memenuhi mandat — aturan ini menguji apa yang ada, bukan bagaimana ia sampai di sana. Jadi, Component yang mandatnya terpenuhi hanya karena operator menetapkan anotasi pemantauan di Release lolos sama persis seperti Component yang pengembangnya melampirkan Feature secara manual.

Mandat yang tidak dipenuhi oleh lampiran apa pun menghentikan build dengan diagnostik yang menyebutkan instans komponen, label persyaratan, dan jenis yang diwajibkan. Nilai anotasi adalah string buram, sehingga tidak ada yang memvalidasi bentuknya sebelum compiler membacanya; karena itu, nilai yang bukan URI jenis Feature, atau kunci tanpa label setelah prefiks, berhenti dengan diagnostik terpisah yang menyatakan bahwa deklarasinya salah bentuk. Keduanya sengaja dibedakan: deklarasi yang rusak diperbaiki di entitas katalog, sedangkan persyaratan yang tidak terpenuhi diselesaikan dengan melampirkan Feature — dan salah ketik tidak boleh terbaca sebagai persyaratan yang terpenuhi.

Kedua diagnostik didokumentasikan di errors/fatal-halts.md “Required feature not attached (Fitur yang diwajibkan tidak terlampir)”.

Mandat bukanlah slot. Kedua permukaan ini menjawab pertanyaan yang berbeda dan perbedaannya bukan sekadar kosmetik:

Slot featuresSchemamandat kehadiran
Menyatakantitik pengikatan bernamabatasan atas apa yang harus ada
Nama dapat didereferensiya — from: <slot> dan .features.<slot>.provides.*tidak — label hanya menamai persyaratan, tidak lebih
Kardinalitastepat satu pengisian per slotsetidaknya satu lampiran dari jenis tersebut
Membatasi pengisianselector, inject, sensitivetidak ada selain jenisnya
Dipenuhi oleh lampiran bebastidak — slot diisi berdasarkan namaya — pada cakupan apa pun, dengan nama apa pun
Ketika tuntutan tidak terpenuhiberhenti ketika required: true dan tidak ada yang mengikat nama slotberhenti ketika tidak ada lampiran yang membawa jenis tersebut

Kedua tuntutan diperiksa terhadap masukan yang sama — himpunan lampiran akhir instans — dan keduanya berhenti dengan diagnostiknya sendiri, karena keduanya mengajukan pertanyaan berbeda: apakah satu titik pengikatan bernama telah terikat, dibandingkan apakah ada lampiran yang membawa jenis bernama. Tidak satu pun menggantikan yang lain.

Gunakan slot ketika Recipe perlu membaca apa yang dilampirkan. Gunakan mandat ketika kontrak Component menuntut suatu kapabilitas ada dan tidak peduli instans mana yang menyediakannya. Component pemrosesan pembayaran yang mewajibkan core/audit-logging mendapatkan pencatatan audit di setiap deployment, terlepas dari apakah pengembang ingat melampirkannya; Component yang patuh PCI yang mewajibkan core/pci-compliance tidak dapat dirilis tanpa Feature kepatuhan terlampir di suatu tempat dalam deployment.

Pewarisan. Mandat yang dideklarasikan pada Component dasar diwarisi oleh setiap Component yang melakukan extends: terhadapnya, karena anotasi metadata digabungkan sepanjang rantai extends dengan turunan yang menang per kunci. Karena itu, turunan dapat mengarahkan ulang mandat yang diwarisi dengan mendeklarasikan ulang label yang sama dengan jenis berbeda, atau menambahkan mandatnya sendiri dengan label baru; turunan tidak dapat menghapus mandat yang dideklarasikan oleh dasarnya.

Soket topologi: usesSchema

Sebuah Component dapat mendeklarasikan soket topologis melalui blok usesSchema: — sebuah map YAML deklaratif yang sejajar dengan featuresSchema. Setiap entri menamai soket yang melaluinya Component menerima dependensi lintas komponen dan mengatur bentuk Component mana yang boleh dihubungkan developer ke soket tersebut. Compiler secara otomatis menghasilkan aturan validasi JSON Schema 2020-12 dari soket yang dideklarasikan dan menyatukannya dengan schema: milik Component selama resolusi Component; developer tidak menulis sendiri pilar uses: di dalam schema:, karena strukturnya berasal dari usesSchema.

# Component declares the sockets it accepts:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/ai-agent/orchestrator
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
primary_datastore:
required: true
selector: "datastore.aggrega.ai/engine=vector"
inject: [env]
cache:
required: false
selector: "datastore.aggrega.ai/engine=kv"
inject: [env, file]
log_destination:
required: false
selector: "component.aggrega.ai/category=messaging"
inject: []
# Aggregate fragment — developer wires the sockets:
components:
agent:
type: core/ai-agent/orchestrator
uses:
primary_datastore:
main: { target: vector-db-instance }
log_destination:
audit: { target: audit-sink }

Bentuk penghubungan — sebuah soket menerima satu atau banyak target. Contoh di atas menghubungkan setiap soket ke satu target, tetapi sebuah soket dapat menyebar ke beberapa target. Nilai soket ditulis dalam salah satu dari dua bentuk:

uses:
# Compact form — a list of target names. Each entry produces an edge
# whose alias equals its target. Use it for the single-target case, and
# when one socket connects to several peers of the same shape.
shards: [orders-db, customers-db, inventory-db]
# Verbose form — an alias-keyed map. Each alias maps to an entry object
# carrying its own `target:`, and may carry its own inject directives.
# Use when the connections need distinct names or per-edge inject.
databases:
primary: { target: orders-db, inject: { env: [{ in: DB_URL, from: url }] } }
replica: { target: orders-db-ro, inject: { env: [{ in: DB_REPLICA_URL, from: url }] } }

Sebuah alias selalu dipetakan ke objek entri, tidak pernah ke nama target polos: databases: { primary: orders-db } ditolak saat dimuat, demikian pula objek entri yang menghilangkan target:. Untuk menghubungkan satu target tanpa perlu membuat alias, gunakan bentuk ringkas — primary_datastore: [vector-db-instance] — yang menamai target sekali dan menurunkan alias darinya.

Setiap entri — elemen list atau alias map — menjadi satu edge, yang dipertahankan sesuai urutan penulisan. selector: milik soket berlaku untuk setiap target yang dihubungkan melaluinya (setiap edge diperiksa jenisnya secara independen selama analisis statis), dan required: true berarti setidaknya satu target harus dihubungkan.

Semantik field:

FieldJenisDefaultArti
requiredboolfalseJika true, developer harus menghubungkan setidaknya satu dependensi ke soket ini. Jika false, soket bersifat opsional.
selectorstring—Selektor label, dalam tata bahasa yang digunakan appliesTo pada Feature, yang harus dipenuhi oleh target setiap edge yang dihubungkan melalui soket ini. Selektor dibaca sebagai string yang ditulis di sini dan dievaluasi terhadap label target selama analisis statis: target yang labelnya tidak memenuhinya menghentikan build, demikian pula selektor yang ditolak oleh tata bahasa, dengan menyebutkan persyaratan yang tidak dapat dibaca. Selektor kosong tidak memberikan batasan apa pun pada target.
injectstring[]—Allowlist mekanisme pengiriman inject yang diizinkan (sejajar dengan featuresSchema[].inject). Jika tidak ada, atau [] (kosong), berarti blackbox — tidak ada blok inject: yang diizinkan pada entri uses: milik developer; Recipe mengendalikan pengiriman. [env, file, arg] (tidak kosong) berarti transparan — developer dapat menentukan mekanisme mana yang mengirimkan nilai provides dependensi. Ditegakkan: lihat “Tempat allowlist inject sebuah soket ditegakkan” di bawah.
valueSchemaobject—Kontrak per-edge opsional untuk values yang ditulis developer pada edge yang dihubungkan melalui soket ini (ditulis di Aggregate). JSON Schema 2020-12 dalam bentuk penulisan yang sama dengan schema:. Jika dihilangkan, soket tidak mendeklarasikan kontrak values.
infraSchemaobject—Kontrak per-edge opsional untuk infra yang ditulis operator pada edge yang dihubungkan melalui soket ini (ditulis di Release). Bentuk penulisan sama dengan valueSchema. Jika dihilangkan, soket tidak mendeklarasikan kontrak infra.
featuresSchemamap—Slot attachment yang dapat diisi oleh setiap koneksi yang dihubungkan melalui soket ini, dengan kunci nama slot, dan setiap slot menerima kunci yang sama dengan slot tingkat Component. Jika dihilangkan, koneksi melalui soket ini tidak membawa attachment. Lihat “Slot yang diisi setiap koneksi” di bawah.

Tempat allowlist inject sebuah soket ditegakkan. Allowlist adalah pernyataan soket tentang apakah konsumen boleh memilih bentuk pengiriman sama sekali, dan jika boleh, bentuk yang mana — sehingga allowlist diperiksa terhadap setiap edge uses: yang dihubungkan melalui soket, setelah edge dan deklarasi soket sama-sama tersedia. Dua penolakan mengikuti dari satu aturan, dan keduanya menghentikan build:

  • Edge yang menentukan mekanisme yang tidak tercantum dalam allowlist akan dihentikan, dengan menyebutkan soket, mekanisme yang melanggar, dan apa yang diizinkan soket. Semua mekanisme yang melanggar pada edge dilaporkan bersama.
  • Edge yang menentukan pengiriman apa pun melalui soket yang allowlist-nya tidak ada atau kosong juga dihentikan. Itulah deklarasi blackbox yang menjalankan tugasnya: deklarasi itu menyatakan “Recipe mengirimkan ini secara internal; jangan menentukan pengiriman,” dan allowlist kosong tidak mengizinkan apa pun, bukan mengizinkan semuanya.

Soket dibaca pada entitas mana pun yang mendeklarasikannya, yang tidak selalu merupakan komponen tempat edge berada: edge yang ditulis pada uses: milik attachment Feature diresolusi terhadap usesSchema milik Feature yang dilampirkan, dan setiap edge lainnya — yang ditulis di Aggregate, dihubungkan dari Release, atau dicapai melalui sub-aggregate — terhadap milik Component yang mengonsumsi. Soket yang diwarisi melalui extends dibaca persis seperti soket yang ditulis sendiri oleh entitas tersebut.

Edge yang tidak menentukan apa pun tidak terpengaruh oleh kedua penolakan tersebut, apa pun yang dideklarasikan soket: membaca nilai dependensi dari .context.uses.<alias>.provides.<name> di Recipe yang mengonsumsi tidak memerlukan blok inject: dan selalu tersedia. Lihat errors/fatal-halts.md untuk kedua diagnostik.

Kontrak koneksi per-edge — valueSchema dan infraSchema. Selain mengatur Components mana yang boleh dihubungkan ke soket, sebuah soket dapat mendeklarasikan konfigurasi apa yang dibawa setiap koneksi. Dua skema opsional per soket memvalidasi konfigurasi lingkup koneksi pada setiap edge yang dihubungkan melalui soket:

  • valueSchema adalah kontrak untuk blok values yang ditulis developer pada edge uses — penyetelan per koneksi yang dinyatakan developer di Aggregate (misalnya, ukuran pool koneksi atau mode klien).
  • infraSchema adalah kontrak untuk blok infra yang ditulis operator pada edge uses — penentuan ukuran operasional per koneksi yang dinyatakan operator di Release.

Keduanya menerima JSON Schema 2020-12 dalam bentuk konten yang sama dengan field schema: — bentuk ringkas inline, YAML JSON Schema inline, atau $ref: lintas dokumen ke entri SchemaLibrary. Keduanya adalah kontrak per-edge yang divalidasi terhadap konfigurasi setiap edge secara independen; keduanya tidak digabungkan ke dalam skema values milik Component yang mengonsumsi. Soket yang menghilangkan skema per-edge untuk suatu pilar tidak mendeklarasikan kontrak di sana, dan konfigurasi apa pun yang ditulis untuk pilar tersebut tidak divalidasi. Konfigurasi per-edge divalidasi secara tertutup, dan validasi memperhitungkan default di kedua pilar: kunci yang diberi default: oleh skema dianggap telah diberikan meskipun penulis menghilangkannya.

default: yang dideklarasikan juga diwujudkan, di kedua pilar. Kunci yang dihilangkan penulis mencapai konteks render Recipe yang mengonsumsi dengan membawa default yang dideklarasikan, persis seperti kunci value atau infra komponen yang dihilangkan — sehingga mendeklarasikan default pada soket sudah cukup, dan template Recipe tidak memerlukan ekspresi fallback untuknya. Nilai yang ditulis selalu menang atas default yang dideklarasikan, dan nilai itu hanya mengisi kunci yang diberikannya: edge yang menulis satu kunci dari kontrak soket tetap menerima default yang dideklarasikan untuk kunci lain dalam kontrak tersebut. Default melekat pada edge, sehingga soket yang tidak dihubungkan tidak memberikan kontribusi apa pun.

spec:
usesSchema:
databases:
required: true
selector: "datastore.aggrega.ai/engine=relational"
inject: [env]
valueSchema: # developer per-edge values, authored in the Aggregate
pool_size: { type: integer, minimum: 1, maximum: 100, default: 10 }
tls_mode: { type: string, enum: [disable, require, verify-full], default: require }
infraSchema: # operator per-edge infra, authored in the Release
storage_class: { type: string, default: standard }

Dengan soket tersebut dideklarasikan, edge yang Aggregate-nya menghilangkan pool_size merender 10, dan edge yang Release-nya menghilangkan storage_class merender standard. Penulisan menang per kunci, di dalam pilarnya sendiri: Aggregate yang menetapkan pool_size: 42 merender 42 sementara tls_mode tetap terisi menjadi require, dan Release yang menetapkan storage_class: gp3 merender gp3 tanpa mengganggu kunci developer mana pun.

Recipe untuk Component yang mengonsumsi membaca konfigurasi per-edge yang telah diresolusi dari pipa topologi yang diperkaya di .context.uses.<alias>.values.<key> dan .context.uses.<alias>.infra.<key> — lihat vocabulary/topology-triad.md.

Slot yang diisi setiap koneksi — featuresSchema milik soket. Sebuah soket juga dapat mendeklarasikan slot attachment, dan kemudian setiap koneksi yang dihubungkan melaluinya dapat membawa attachment-nya sendiri di masing-masing slot: gateway yang menjangkau beberapa model menyimpan kredensial berbeda untuk masing-masing, karena kredensial berada pada koneksi, bukan pada gateway.

spec:
usesSchema:
models:
selector: "component.aggrega.ai/category=ai-model"
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: The credential the consumer presents to the component this connection reaches.

Sebuah koneksi mengisi slot dengan membawa lampiran di bawah nama slot tersebut dalam features: miliknya sendiri — pada entri koneksi Aggregate (Aggregate) atau pada entri koneksi Release (Release) — dan lampiran itu menjadi salah satu lampiran komponen konsumen, dengan nama <alias>.<slot>.

Apa yang dilakukan deklarasi ini, secara tepat:

  • Nama slot merupakan himpunan tertutup. Berbeda dengan featuresSchema milik Component itu sendiri, yang menerima lampiran bebas dengan nama apa pun, slot sebuah soket adalah satu-satunya nama yang boleh dibawa oleh koneksi melalui soket tersebut: nama lain apa pun menghentikan build saat build dimuat, dan soket yang tidak mendeklarasikan featuresSchema tidak menerima lampiran apa pun pada koneksinya. Soket ad-hoc — soket yang tidak dideklarasikan oleh usesSchema ini — tidak mendeklarasikan slot, sehingga koneksinya juga tidak membawa lampiran. Setiap koneksi mengisi slotnya sendiri: lampiran pada cakupan yang lebih luas tidak pernah menurun ke sebuah koneksi, dan kunci Release yang menuliskan nama gabungan lampiran koneksi akan menghentikan build.
  • Kunci lainnya mengikat setiap koneksi pada slot. Slot di sini menerima kunci yang sama dengan slot tingkat Component — required, selector, inject, sensitive, description — dan setiap koneksi diikat padanya secara tersendiri. selector dicocokkan dengan label Feature yang digunakan koneksi untuk mengisi slot, dan isian yang tidak diterimanya menghentikan build, dengan posisi pada entri koneksi tersebut di dokumen yang menuliskan isian itu. required: true wajib dipenuhi oleh setiap koneksi yang dihubungkan melalui soket: koneksi yang membiarkan slot kosong menghentikan build, dengan menyebut koneksi tersebut, sementara koneksi di sebelahnya yang mengisi slot tetap lolos. sensitive dibaca persis seperti pada slot tingkat Component: lampiran yang mengisi slot ditandai sensitif dalam graf build dan dalam aggrega inspect. Pada koneksi, seperti pada komponen, nilai lampiran mana yang disembunyikan sebagai sensitif ditentukan semata-mata oleh skema Feature yang dilampirkan. inject mengikat entri Workload yang mengirimkan materi slot: lampiran koneksi tidak membawa blok inject: sendiri — tidak ada dokumen yang menerimanya pada entri koneksi — sehingga Workload mengirimkannya dengan menyebut koneksi di samping slot, dan entri tersebut diikat pada allowlist slot soket persis seperti entri yang menyebut slot tingkat Component diikat pada allowlist slot tersebut.

usesSchema milik Feature tidak menerima featuresSchema: koneksi yang dibuat oleh Feature tidak membawa lampiran, dan Feature yang mendeklarasikan slot pada soket ditolak saat dimuat. Kredensial yang dibutuhkan koneksi semacam itu merupakan slot dalam featuresSchema milik Feature itu sendiri.

Pembuatan skema dari usesSchema. Compiler membuat fragmen JSON Schema 2020-12 dasar dari soket yang dideklarasikan dan menggabungkannya dengan deklarasi schema: pengguna — pola yang sama dengan yang digunakan featuresSchema. Skema yang dihasilkan tidak pernah ditulis ke disk; skema itu hanya ada di memori selama tahap validasi Component. Map uses: milik developer dalam Aggregate divalidasi terhadap skema gabungan; selector: per soket dievaluasi terhadap label Component kandidat selama analisis statis sebagai pemeriksaan keamanan tipe lintas node.

Semantik selector — mekanisme Split Schema. usesSchema[].selector: adalah hal yang membuat topologi Aggrega lebih dari sekadar pengiriman string tanpa tipe. Soket yang mendeklarasikan selector: "datastore.aggrega.ai/engine=vector" hanya menerima penghubungan ke Components yang berlabel pasangan kunci-nilai yang cocok; agen yang mencoba menghubungkan soket primary_datastore miliknya ke Component relational akan gagal di Static Analyzer dengan diagnostik pelanggaran selector yang jelas. Selector adalah string label-selector bergaya Kubernetes — persyaratan yang digabungkan dengan koma (AND) atas bentuk =, !=, in (...), notin (...), kunci tunggal, dan !key — tata bahasa yang sama dengan yang digunakan appliesTo pada Feature; lihat vocabulary/modifier-system.md untuk tata bahasanya dan architecture/13-catalog-and-registry.md §2 “Kubernetes-Style Selectors” untuk semantik mesinnya. Persyaratan di luar bentuk-bentuk tersebut ditolak, bukan dibaca sebagai selector lain: persyaratan kosong (koma di awal, di akhir, atau ganda), kunci yang mengandung spasi atau salah satu dari =, !, (, ) dan koma, atau himpunan tanpa tanda kurung penutup menghentikan setiap build yang menghubungkan edge melalui soket tersebut, dengan menyebut persyaratannya. Jadi, soket yang dimaksudkan untuk mengecualikan frontend ditulis selector: "tier!=frontend"; "!tier=frontend" ditolak, karena ! hanya menyebut kunci label dan tidak lebih.

Soket ad-hoc — apa yang diperoleh dengan mendeklarasikan soket, dan apa yang dapat dilakukan penulis tanpanya. Penulis Aggregate dapat menulis entri uses: pada komponennya sendiri dengan nama soket yang tidak dideklarasikan oleh usesSchema ini, termasuk pada Component yang sama sekali tidak mendeklarasikan usesSchema. Edge tetap dibuat. Ketiadaan keterangan katalog tentang sebuah soket berarti koneksi tersebut tidak diantisipasi, bukan berarti dilarang, dan developer adalah pemilik topologi aplikasi.

Yang dilepaskan oleh soket ad-hoc semacam itu adalah tepat apa yang disediakan soket yang dideklarasikan, karena semuanya berada dalam entri usesSchema: tidak ada selector, sehingga tidak ada yang membatasi komponen mana yang dapat dicapai edge dan pemeriksaan keamanan tipe lintas node tidak memiliki apa pun untuk dievaluasi; tidak ada allowlist inject:; tidak ada valueSchema per edge, sehingga values: per edge tidak memiliki kontrak untuk diperiksa dan tidak ada default terdeklarasi untuk diwarisi. Soket ini juga melepaskan infraSchema, meskipun kontrak itu memang tidak dapat dicapai pada soket semacam ini: infra per edge ditulis pada entri edge Release, dan entri Release hanya dapat menyebut soket yang dideklarasikan oleh Component konsumen. Yang tidak berubah adalah apa yang dapat dibawa edge: from: pada setiap entri inject tetap harus menyebut kunci yang dideklarasikan oleh schema.provides milik Component target, dan target tetap harus ada — keduanya menghentikan build seperti pada soket yang dideklarasikan.

Bacalah “tidak ada allowlist inject:” sebagai ketiadaan batasan, bukan sebagai deklarasi blackbox, karena keduanya tampak serupa tetapi berperilaku berlawanan. Edge melalui soket ad-hoc dapat menentukan pengiriman secara bebas: tidak ada allowlist yang dapat dilanggar oleh suatu mekanisme, dan tidak ada entitas yang berjanji menangani nilai secara internal. Penolakan blackbox di atas berlaku untuk soket yang memang dideklarasikan entitas dan dibiarkan tanpa allowlist inject: — penghilangan itu merupakan pernyataan tentang koneksi yang diantisipasi entitas, sedangkan soket ad-hoc tidak membuat pernyataan semacam itu.

Pengiriman menempuh jalur yang sama, dan artefak yang dirender tidak mencatat perbedaan. Blok inject pada edge ad-hoc diselesaikan dan dikirimkan persis seperti pada soket yang dideklarasikan: setiap kunci from: dibaca dari provides target yang telah dievaluasi dan masuk ke konteks injeksi node konsumen di bawah kunci pengiriman yang dipilih penulis, lalu mencapai artefak yang dirender dari sana. Hanya ada satu jalur pengiriman dan tidak ada bagian darinya yang bercabang berdasarkan apakah soket dideklarasikan. Yang dapat ditambahkan soket yang dideklarasikan adalah konten — default per edge yang diisi oleh valueSchema atau infraSchema miliknya — sehingga apabila soket yang dideklarasikan tidak membawa kontrak semacam itu, edge yang sama dirender identik pada kedua jenis soket. Deklarasi merupakan fakta tentang koneksi, bukan masukan bagi apa yang dirender.

values: per edge pada soket ad-hoc diterima dan mencapai Recipe konsumen di .context.uses.<alias>.values, tanpa validasi: tanpa valueSchema sebagai acuan, tidak ada kunci yang diperiksa dan tidak ada yang ditolak. Hal ini tidak khas soket ad-hoc — soket yang dideklarasikan tetapi tidak menuliskan kontrak untuk pilar tersebut memperlakukan konfigurasi per edge-nya dengan cara yang sama. Yang diubah oleh soket ad-hoc adalah bahwa kontrak tidak dapat ditambahkan tanpa mendeklarasikan soket. .context.uses.<alias>.infra kosong pada edge semacam itu, karena permukaan yang menyediakan infra per edge tidak dapat menyebut soket yang tidak dideklarasikan.

Setiap edge dalam graf yang dihasilkan mencatat jenis mana dari keduanya, sehingga konsumen tidak pernah perlu menyimpulkannya, dan organisasi yang ingin setiap koneksi melewati socket yang dideklarasikan dapat mewajibkan hal itu sebagai kebijakan tata kelola. Mendeklarasikan socket di sini tetap merupakan jalur yang lebih baik dan itulah yang dilakukan katalog pustaka standar: socket yang dideklarasikan membawa selector yang membatasi komponen mana yang dapat dicapai edge, allowlist inject:, kontrak per-edge dengan default-nya sendiri, dan deskripsi — pernyataan yang dapat ditinjau tentang koneksi yang diantisipasi, yang diberi versi bersama entitas yang membuatnya. Bentuk ad-hoc adalah jalan keluar, bukan default baru. Dua permukaan sengaja tidak dibuka dengan cara ini — uses pada lampiran Feature hanya dapat menyebut socket yang dideklarasikan oleh Feature yang dilampirkan, dan uses per-edge pada Release hanya dapat menyebut socket yang dideklarasikan oleh Component yang mengonsumsi.

Contoh lengkap examples/adhoc-uses-socket/ membangun kedua jenis edge pada satu konsumen dan menampilkan kedua nilai yang dikirimkan berdampingan dalam output yang dirender, bersama dengan penghentian yang ditimbulkan oleh kunci from: yang tidak dideklarasikan.

Salah ketik nama socket muncul sebagai peringatan, bukan penghentian. Karena nama socket yang tidak dideklarasikan itu sah, nama socket yang salah eja menjadi koneksi ad-hoc tersendiri alih-alih menghubungkan socket yang dimaksud penulis — dan build tetap hijau sementara tidak ada yang mengalir melaluinya. Compiler melaporkan nama socket yang berjarak satu suntingan dari nama yang dideklarasikan usesSchema ini sebagai peringatan yang menyebut kedua ejaan — lihat errors/warnings.md “Uses-socket near-miss lint”. Peringatan ini tidak pernah mengubah putusan build; compiler tidak mengawasi nama yang diberikan penulis pada socket.

Hubungan usesSchema dan featuresSchema. Keduanya adalah tabel deklaratif dan keduanya membawa allowlist inject: dengan semantik yang identik, tetapi socket dan slot adalah hal yang berbeda dan tidak dapat dipertukarkan. usesSchema mengatur edge lintas komponen — graf topologi — dengan mendeklarasikan socket mana yang membawa kontrak. featuresSchema mengatur slot lampiran, dan slot adalah titik pengikatan bernama, bukan enumerasi: lampiran dengan nama yang tidak dideklarasikan slot mana pun sah pada blok milik komponen itu sendiri. (Slot yang dideklarasikan socket untuk koneksinya adalah satu-satunya himpunan tertutup, sebagaimana dinyatakan “Slots each connection fills” di atas.) Kedua permukaan telah menyatu pada poin itu — entri uses: milik komponen sendiri dengan nama socket yang tidak dideklarasikan juga sah — tetapi keduanya tetap berbeda: slot yang tidak dideklarasikan adalah lampiran bebas pada Component yang slot-slot terdeklarasinya tidak terpengaruh, sedangkan socket yang tidak dideklarasikan adalah edge tanpa selector dan tanpa kontrak per-edge. Banyak Components mendeklarasikan keduanya; kedua tabel tersusun secara independen.

Slot lampiran: featuresSchema

Sebuah Component dapat mendeklarasikan slot lampiran melalui blok featuresSchema. Setiap slot menamai titik pengikatan tempat Component mengharapkan sebuah Feature dilampirkan — kata sandi root, kunci API, token autentikasi, pengikatan identitas — dan membatasi Feature mana yang dapat mengikatnya serta bagaimana materi pengisinya dapat dikirimkan.

Bagian ini membahas slot milik Component itu sendiri. Slot yang dideklarasikan sebuah soket untuk setiap koneksi justru merupakan himpunan tertutup — lihat “Slots each connection fills” di bawah Topology Sockets.

Mendeklarasikan slot tidak menutup permukaan lampiran. Penulis dapat melampirkan Feature dengan nama yang tidak dideklarasikan oleh slot mana pun, dan lampiran itu adalah lampiran bebas: sepenuhnya sah, hanya saja tidak terikat pada slot yang dideklarasikan. Keterbukaan inilah yang memungkinkan satu entitas katalog melayani dua bentuk deployment yang berbeda tanpa fork katalog:

  • Per konsumen. Setiap instans mengisi slot dengan Feature miliknya sendiri, sehingga setiap konsumen mendapatkan kredensial hasil render miliknya sendiri.
  • Bersama. Tidak ada instans yang mengisi slot; sebagai gantinya satu kredensial dilampirkan sekali pada cakupan yang lebih luas (sebuah subsistem, atau batas Release) dan diturunkan ke setiap komponen di bawahnya, sehingga setiap konsumen diisi dari satu deklarasi itu. Apa yang dirender mengikuti realisasinya: satu Secret per konsumen, masing-masing membawa materi yang sama, pada realisasi yang merender Secret; tidak ada sama sekali pada realisasi yang mengarahkan setiap konsumen ke Secret yang sudah ada.

Penulis memilih di antara keduanya melalui apa yang dilampirkannya. Entitas katalognya sama dalam kedua kasus.

Satu bentuk pada permukaan terbuka itu menghentikan build: pengisi yang ditulis pada komponen dengan nama lain. Ketika lampiran yang ditulis pada komponen itu sendiri — pada blok features: miliknya di Aggregate, atau pada entri Release untuk komponen tersebut — membawa nama yang tidak dideklarasikan oleh slot mana pun, dan Feature-nya memenuhi selector dari slot yang tidak diikat apa pun pada komponen itu setelah semua cakupan digabungkan, build berhenti. Itulah bentuk yang diambil pengisi yang dimaksudkan untuk slot ketika ditulis dengan nama yang salah: jika dibiarkan, ia akan menjadi lampiran bebas sementara slot tetap kosong, dan slot opsional yang kosong tetap lolos build tanpa mengirimkan apa pun. Pesannya menyebutkan lampiran, komponen, Feature, dan setiap slot kosong yang cocok dengan Feature itu, dan solusinya adalah melampirkannya dengan nama slot tersebut. Ini berlaku untuk setiap Feature, bukan hanya kredensial. Segala hal lain pada permukaan ini tetap bebas: lampiran yang Feature-nya tidak cocok dengan slot mana pun yang dideklarasikan, lampiran tambahan setelah setiap slot yang cocok dengannya sudah terikat, dan lampiran yang diwarisi komponen dari subsistem atau batas Release — sehingga bentuk bersama di atas tidak terpengaruh. Slot yang tidak mendeklarasikan selector tidak menyatakan apa pun tentang Feature yang ditujunya, sehingga tidak ada lampiran yang dikaitkan dengannya dengan cara ini. Penghentian ini dijelaskan di errors/fatal-halts.md pada “An attachment written under another name fits a slot its component leaves empty (Lampiran yang ditulis dengan nama lain cocok dengan slot yang dibiarkan kosong oleh komponennya)”.

Kedua bentuk dapat dikomposisikan, dan yang lebih dekat menang. Penulis dapat melakukan keduanya sekaligus: melampirkan Feature pada cakupan yang lebih luas agar mencapai setiap komponen di bawah cakupan itu, dan mengisi slot pada satu komponen yang membutuhkan sesuatu yang berbeda. Pengisi pada cakupan komponen menang — per field, sehingga ia cukup menyatakan ulang field yang diubahnya dan sisanya tetap berasal dari lampiran yang lebih luas. Komponen saudara yang tidak mengisi slot tetap mempertahankan lampiran yang lebih luas tanpa perubahan. Aturan prioritas lengkapnya, termasuk interaksinya dengan lampiran berbasis anotasi dan dengan Aggregates yang dikomposisikan, ada di vocabulary/labels-and-annotations.md “Attachment precedence”.

Definisi skema pada Component:

spec:
featuresSchema:
root_password:
inject: []
description: Root database password. Recipe controls delivery (Black-Box).
user_password:
inject: [env, file]
description: Application user password, auto-generated if omitted.
replication_password:
inject: []
description: Replication password for HA setups.

Semantik field:

FieldJenisDefaultArti
requiredboolfalseMenyatakan bahwa slot harus berakhir dalam keadaan terikat. Build berhenti ketika tidak ada yang mengikat nama slot pada instans Component ini, diperiksa terhadap himpunan lampiran yang dimiliki instans setelah seluruh kaskade lampiran — sehingga lampiran yang dideklarasikan pada cakupan yang diwarisi instans memenuhi slot persis seperti pengisi yang ditulis pada instans itu sendiri. Diagnostiknya menyebutkan komponen dan slotnya.
injectstring[]—Daftar izin mekanisme pengiriman inject yang diperbolehkan. [] (kosong) berarti blackbox — Recipe mengendalikan pengiriman secara internal dan materinya tidak pernah dikirimkan ke workload. [env, file] berarti transparan — materi pengisi dapat dikirimkan melalui mekanisme yang tercantum. Semantiknya sama dengan usesSchema[].inject.
descriptionstring—Dokumentasi untuk manusia, ditampilkan oleh IDE dan hub.
selectorstring—Selector label opsional bergaya Kubernetes yang membatasi Feature mana yang dapat mengisi slot ini — padanan slot untuk selector pada soket usesSchema, dengan tata bahasa yang sama dan mesin pencocokan label native yang sama. Dievaluasi terhadap label milik Feature yang dilampirkan selama analisis statis; pengisi yang labelnya tidak memenuhinya akan menghentikan build, demikian pula selector yang ditolak oleh tata bahasa, dengan menyebutkan persyaratan yang tidak dapat dibacanya. Hilangkan untuk tidak memberikan batasan pada pengisi.
sensitiveboolfalseMenyatakan bahwa apa pun yang mengikat slot ini menangani materi rahasia. Ini adalah pernyataan tentang titik pengikatan, bukan tentang pengisi tertentu; lihat “Declaring a slot sensitive” di bawah.

Slot membatasi pengisi mana yang dapat mengikatnya, bukan apa yang dikonfigurasi oleh pengisi. Secara sengaja tidak ada kontrak values atau infra di tingkat slot: schema: milik Feature yang dilampirkan memiliki pilar-pilar tersebut, sehingga setiap kontrak memiliki tepat satu tempat.

selector slot adalah cara Component mempersempit Feature mana yang dapat mengisi slot — misalnya menjadi Feature kredensial khusus provider (feature.aggrega.ai/kind=secret, provider=helm) — tanpa menyebutkan FeatureRecipe, persis seperti selector soket usesSchema mempersempit target edge dependensi. Kompiler mengevaluasi selector terhadap label Feature yang dilampirkan dan tidak ada yang lain: ia membaca label yang dibawa pengisi, dan melaporkan apakah selector menerimanya. Label mana yang bermakna untuk diwajibkan adalah pilihan dalam penulisan katalog, bukan aturan yang diberlakukan kompiler.

Salah ketik nama slot muncul sebagai peringatan, bukan penghentian. Karena nama lampiran yang tidak dideklarasikan itu sah, nama slot yang salah eja menjadi lampiran bebas alih-alih mengisi slot yang dimaksud penulis. Kompiler melaporkan nama lampiran yang berjarak satu suntingan dari nama slot yang dideklarasikan sebagai peringatan yang menyebutkan kedua ejaan — lihat errors/warnings.md “Attachment-slot near-miss lint”. Peringatan ini tidak pernah mengubah putusan build; kompiler tidak mengawasi nama yang diberikan penulis pada lampiran. Nama yang berjarak satu suntingan dari slot yang selector-nya dipenuhi oleh Feature lampiran tidak memicu peringatan: jika slot itu akhirnya kosong, penghentian yang dijelaskan di atas melaporkan lampiran tersebut, dan jika sesuatu yang lain mengikat slot, lampiran itu merupakan lampiran tambahan biasa.

Mendeklarasikan slot sebagai sensitif

sensitive: true pada sebuah slot menyatakan tuntutan konsumen itu sendiri: apa pun yang mengikat titik ini menangani materi rahasia.

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: "Optional database password credential."

Ini adalah informasi yang benar-benar berbeda dari sensitive: true pada leaf skema, bukan duplikat untuk kemudahan, dan katalog pustaka standar membutuhkan keduanya. Kredensial yang dapat direferensikan menerbitkan provides.name dan provides.key — lokator sumber daya dan kunci data di dalamnya — dan keduanya tidak sensitif: nama Secret Kubernetes bersifat publik, demikian pula kunci di dalamnya. Namun slot yang diisi kredensial tersebut jelas menangani materi rahasia. Sebuah leaf menyatakan datum ini adalah materi rahasia; sebuah slot menyatakan titik pengikatan ini menangani materi rahasia; kedua klaim tersebut mengenai hal yang berbeda dan dapat berlaku secara independen.

Konsekuensi praktisnya adalah tuntutan tersebut melekat pada titik pengikatan, bukan pada pengisinya. Sebuah Feature yang sama sekali tidak mendeklarasikan leaf sensitif — karena mesin target memiliki kredensial tersebut dan penulis tidak menulis apa pun — tetap mengikat slot sensitif sebagai lampiran sensitif, karena slot menyatakan demikian. Kebalikannya juga berlaku: pengisi yang mendeklarasikan leaf sensitif adalah lampiran sensitif bahkan ketika mengikat slot yang tidak membuat deklarasi semacam itu, atau ketika merupakan lampiran bebas yang tidak mengikat slot apa pun.

Deklarasi ini mengikuti kaskade lampiran, bukan satu blok tertulis tertentu. Tuntutan sebuah slot berlaku untuk pengisi mana pun yang akhirnya terikat setelah setiap cakupan digabungkan, sehingga pengisi tingkat komponen yang menggantikan pengisi yang lebih luas mewarisi tuntutan tersebut tanpa perubahan.

sensitive pada sebuah slot memiliki batas yang sama dengan kata kunci tingkat leaf — ia memberi anotasi, tetapi tidak mengenkripsi, memvalidasi, menolak, memaksakan mekanisme pengiriman, atau mengubah byte yang dirender. Pernyataan lengkapnya ada di vocabulary/compact-form-authoring.md “What the keyword does not do”.

sensitive dan compliance.aggrega.ai/data-class adalah dua sumbu yang berbeda, didokumentasikan berdampingan dan tidak pernah dicampuradukkan. sensitive adalah boolean pada satu leaf atau satu slot: datum ini, atau titik pengikatan ini, menangani materi rahasia. compliance.aggrega.ai/data-class adalah label bertingkat pada seluruh node — public, internal, restricted — yang memberi data yang dipegang sebuah komponen identitas tata kelola. Yang satu per datum dan biner, yang lain per node dan berurutan; tidak ada yang menggantikan yang lain, dan sebuah entitas dapat membawa keduanya. Label tersebut dibahas di vocabulary/labels-and-annotations.md dan architecture/08-credential-model.md “Data governance around credentials”.

Proyeksi skema dari featuresSchema

Slot yang dideklarasikan diproyeksikan menjadi fragmen JSON Schema 2020-12 yang menggambarkan bentuk blok lampiran. Dua jenis pengisi divalidasi terhadapnya: blok lampiran dari komponen yang dikontribusikan oleh modul yang diimpor, setelah komposisi yang mengimpornya dibangun, dan lampiran yang dideklarasikan pada cakupan yang lebih luas, terhadap slot pada setiap komponen yang dijangkaunya. Blok lampiran dari komponen yang dideklarasikan oleh Aggregate itu sendiri justru diukur oleh skema dokumen Aggregate dan oleh daftar izin inject milik slot (lihat di bawah), dan fragmen tersebut dibentuk sedemikian rupa sehingga keduanya mencapai putusan yang sama atas pengisi apa pun. Proyeksi ini tidak pernah menyentuh disk; ia hanya ada di memori, dan schema: sebuah Component tidak perlu menulis pilar lampiran secara manual.

Input featuresSchema:

featuresSchema:
root_password:
inject: []
user_password:
inject: [env, file]

Fragmen hasil proyeksi (di memori; representasi bentuk ringkas):

# The OUTER object is open: an attachment under a name no slot declares is
# admitted, because a free attachment is legal authoring.
root_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
# inject admits only an empty block — inject: [] means the Recipe controls
# delivery, so a fill may name no mechanism
inject: {}
user_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
inject:
env: { type: array }
file: { type: array }
# arg is absent — not in the inject allowlist

Kedua tingkat kedalaman ini independen. Objek luar bersifat terbuka, sehingga slot yang dideklarasikan tidak pernah melarang lampiran yang tidak didaftarkan entitas. Fragmen milik setiap slot yang dideklarasikan bersifat tertutup, sehingga pengisi yang memang mengikat slot yang dideklarasikan tetap dibatasi pada bentuk slot tersebut.

Fragmen ini hanya menggambarkan BENTUK. Fragmen ini tidak memuat pernyataan tentang slot mana yang harus terikat, karena slot bertanda required dapat diikat oleh lampiran yang mengalir dari cakupan yang lebih luas — yang membuat blok yang digambarkan fragmen ini kosong. Oleh karena itu, persyaratan diperiksa terhadap himpunan lampiran yang akhirnya dimiliki sebuah komponen, bukan terhadap apa yang dideklarasikan satu blok tertentu, dan kedua pertanyaan itu tidak pernah saling bertentangan karena hanya satu di antaranya yang pernah diajukan pada blok yang ditulis.

Kunci yang diizinkan mencerminkan kunci yang dapat dibawa sebuah lampiran di mana pun, sehingga kunci yang sah pada lampiran bebas tetap sah pada pengisi slot. Setiap mekanisme pengiriman dalam daftar izin adalah daftar entri pengiriman — bentuk yang sama yang diambil inject: di mana pun; slot membatasi NAMA mekanisme mana yang boleh muncul, bukan bentuk sebuah entri.

Tempat daftar izin inject ditegakkan

Daftar izin ini mengikat kedua sisi slot, pada dua langkah yang berbeda.

Terhadap Workload milik Recipe, pada langkah render: sebuah Workload yang mereferensikan slot melalui entri lampiran kontainernya harus menyebut slot yang dideklarasikan entitas, dan harus memilih mekanisme pengiriman yang diizinkan daftar izin inject slot tersebut; referensi ke slot blackbox (inject: []), ke mekanisme di luar daftar izin, atau ke slot yang tidak pernah dideklarasikan entitas akan menghentikan build. Diagnostiknya menyebut Recipe, path kontainer, dan slot yang bermasalah, serta diklasifikasikan sebagai kesalahan katalog — Recipe-lah yang salah.

Terhadap lampiran milik Aggregate itu sendiri, saat lampirannya di-resolve dan sebelum rendering apa pun: blok inject: pada pengisi yang mengikat slot yang dideklarasikan hanya boleh menyebut mekanisme yang diizinkan daftar izin slot tersebut, dan slot blackbox tidak mengizinkan satu pun — daftar izinnya yang kosong menyatakan “Recipe mengirimkan ini secara internal; jangan menentukan pengiriman,” dan menulis pengiriman untuknya akan menghentikan build. Diagnostiknya diposisikan pada lampiran dan menyebut slot serta mekanisme yang bermasalah, beserta mekanisme yang diizinkan slot jika ada; diagnostik ini diklasifikasikan sebagai kesalahan pengembang, karena Aggregate-lah yang salah. Blok inject: {} yang kosong tidak menyebut mekanisme apa pun, sehingga tidak menentukan pengiriman apa pun dan diterima pada setiap slot, termasuk slot blackbox — baik pada komponen yang dideklarasikan Aggregate, pada komponen yang dikontribusikan modul yang diimpor, maupun pada lampiran yang dideklarasikan pada cakupan yang lebih luas. Lampiran bebas — yang berada di bawah nama yang tidak dideklarasikan slot mana pun — tidak memiliki batasan semacam itu, karena daftar izin milik slot, bukan milik blok.

Alur menyeluruh melalui pipeline kompilasi — bagaimana lampiran Aggregate terhubung ke Feature kredensial (seperti core/secret-value) lalu ke FeatureRecipe khusus penyedia yang mengirimkan kredensial ke workload yang berjalan — diuraikan dalam examples/05-credential-features.

Kunci yang disajikan pemanggil dan kunci yang diverifikasi server

Ketika satu komponen memanggil komponen lain yang memeriksa kunci, setiap ujung memegang kunci di sisinya sendiri, dalam slot yang dideklarasikannya sendiri. Ini adalah konvensi yang diikuti katalog pustaka standar; kompilator tidak memberlakukan satu pun darinya — kompilator memeriksa slot setiap komponen terhadap lampiran komponen itu sendiri, meneruskan string-nya, dan tidak pernah membandingkan apa yang dipegang satu komponen dengan apa yang dipegang komponen lain.

  • Kunci yang disajikan pemanggil adalah milik pemanggil. Kunci tersebut berada dalam slot yang dideklarasikan soket pemanggil untuk setiap koneksi — lihat “Slots each connection fills” di atas — sehingga pemanggil yang menjangkau beberapa target memegang satu kunci untuk masing-masing target. Soket model milik core/ai-agent/crewai mendeklarasikan slot tersebut sebagai credential, dan Recipes-nya mengirimkan apa pun yang mengisinya sebagai OPENAI_API_KEY. Soket models milik core/gateway/litellm, core/gateway/kong, dan core/gateway/apisix juga mendeklarasikannya, dan Recipes-nya mengirimkan kunci setiap koneksi dalam variabelnya sendiri, yang dinamai menurut alias koneksi tersebut, sehingga setiap model yang dilayani gateway memegang kuncinya sendiri. Sebaliknya, kunci yang dideklarasikan sebuah Component dalam slotnya sendiri adalah satu kunci untuk setiap koneksi yang dibuatnya.
  • Kunci yang diverifikasi server adalah slot milik server itu sendiri. core/ai-model/vllm, core/ai-model/tei, dan core/ai-model/tgi masing-masing mendeklarasikan api_key opsional, dan setiap Recipes-nya mengirimkan apa pun yang mengisinya sebagai variabel tempat server membaca kuncinya. Model dan gateway LiteLLM mendeklarasikan api_key untuk kunci yang oleh LiteLLM disebut master key.
  • Tidak ada ujung yang melihat lampiran ujung lainnya. Lampiran pada sebuah koneksi adalah salah satu lampiran pemanggil dan hanya mencapai render pemanggil, dan keluaran render server tetap sama apa pun yang dibawa koneksi yang menjangkaunya. Slot yang ditandai required menjadi kewajiban komponen yang mendeklarasikannya, tidak pernah kewajiban komponen yang terhubung dengannya, dan mengisi slot di satu ujung tidak mengisi apa pun di ujung lainnya — sehingga mendeklarasikan kunci di kedua ujung adalah batas minimum, bukan duplikasi.
  • Kedua ujung membaca satu parameter, sehingga kunci yang disajikan pemanggil dan kunci yang diverifikasi server tidak dapat ditulis berbeda.
# Aggregate fragment — one parameter feeds both ends
spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
agent:
type: core/ai-agent/crewai
# values (role, goal, backstory, …) elided
uses:
model:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

Server yang memeriksa satu kunci tidak dapat membedakan para pemanggilnya: vLLM, TEI, dan TGI masing-masing memeriksa satu kunci, sehingga setiap pemanggil menyajikan kunci yang sama berapa pun banyaknya koneksi yang menjangkau server. Apakah kedua ujung mereferensikan satu secret atau masing-masing memegang secret sendiri ditentukan oleh tempat setiap provider me-resolve secret melalui referensi, dan Manifest memilih realisasi setiap ujung — Credential Model membahas kedua kasus tersebut.

Kredensial yang dipegang komponen untuk dirinya sendiri — misalnya kunci yang digunakannya untuk menandatangani sesinya sendiri — adalah slot dari featuresSchema: miliknya sendiri seperti slot lainnya. Kata sandi yang disajikannya ke datastore yang dijangkaunya melalui salah satu soketnya adalah kunci pemanggil di atas, sehingga kata sandi itu berada pada koneksi tersebut sebagai credential: soket backend milik core/gateway/kong mendeklarasikannya, dan Recipes workload-synthesis-nya mengirimkannya sebagai KONG_PG_PASSWORD, dan soket cache_store milik core/gateway/litellm mendeklarasikannya untuk kata sandi yang disajikan semantic cache-nya ke store, yang dikirimkan sebagai REDIS_PASSWORD. Ketika satu koneksi menyajikan sepasang nilai — pengenal access key dan secret-nya — bagian secret adalah credential dan bagian pengenal adalah credential_id, seperti pada soket store milik core/ai-agent/agenta-api.

Self-inject: spec.inject

Sebuah Component dapat mendeklarasikan array spec.inject: tingkat atas yang menjadi daftar izin mekanisme pengiriman self-inject. Jika ada, developer dapat menggunakan blok inject: pada tingkat komponen di Aggregate untuk menyuntikkan kunci values: atau provides: milik Component itu sendiri langsung ke jalur pengirimannya sendiri (variabel lingkungan container-nya, file yang di-mount, atau argumen proses). Jika spec.inject: tidak ada atau kosong, self-inject tingkat komponen dilarang — Recipe mengendalikan semua pengkabelan internal, sesuai dengan pola Black-Box yang diterapkan usesSchema[].inject: [] dan featuresSchema[].inject: [] masing-masing pada pengiriman lintas komponen dan pengiriman kredensial.

# Component declares its self-inject allowlist:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/web-server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
inject: [env, file]
schema:
values:
log_level: { type: string, default: info }
tls_enabled: { type: boolean, default: false }
provides:
health_endpoint: { type: string }
# Aggregate fragment — developer dictates self-inject delivery:
components:
api:
type: core/web-server
values:
log_level: debug
tls_enabled: true
inject:
env:
- in: LOG_LEVEL
value: '{{"{{"}} .values.log_level }}'
- in: TLS_ENABLED
value: '{{"{{"}} .values.tls_enabled }}'
file:
- in: /etc/web/health-probe
from: health_endpoint

Setiap templat value: diawali dengan {{"{{"}}, bukan {{. Seluruh teks Aggregate dibaca sekali sebagai templat, untuk interpolasi parameter, sebelum resolusi self-inject berjalan, dan pada saat itu .values belum ada; escape tersebut mengembalikan {{ agar dievaluasi oleh resolusi self-inject. Lihat Teks yang membawa kurung kurawal gandanya sendiri.

Semantik field. spec.inject: adalah array nama mekanisme. Tiga nilai didefinisikan:

  • env — variabel lingkungan di dalam container.
  • file — path file yang di-mount.
  • arg — argumen baris perintah proses.

Semantiknya mencerminkan usesSchema[].inject dan featuresSchema[].inject secara persis — kosakata yang sama, pola Black-Box yang sama jika dihilangkan, bentuk penulisan yang sama di sisi Aggregate. Perbedaannya terletak pada sumbernya: usesSchema[].inject mengatur bagaimana provides dari dependensi lintas komponen mengalir ke jalur pengiriman konsumen; featuresSchema[].inject mengatur bagaimana kredensial mencapai container; spec.inject mengatur bagaimana values dan provides milik Component itu sendiri mencapai container milik Component itu sendiri.

Disiplin penulisan. Component core/web-server yang mendeklarasikan spec.inject: [env, file] memilih pengiriman transparan — penulis Aggregate menentukan nama variabel lingkungan mana yang membawa nilai mana. Component yang mendeklarasikan spec.inject: [] (atau menghilangkan field tersebut) menjaga pengiriman tetap tertutup — valuesMapping: milik Recipe menentukan field mana yang mengalir ke variabel container mana, dan developer tidak dapat menimpanya di Aggregate. Pola Black-Box cocok untuk Components kontrak yang stabil (Component core/postgres-db yang Recipe-nya tahu cara menghubungkan kata sandi DB ke variabel lingkungan POSTGRES_PASSWORD); pola transparan cocok untuk Components ketika maksud developer memang menyebutkan detail pengiriman (sebuah core/web-server yang aplikasinya membaca LOG_LEVEL dari nama variabel nonstandar yang ingin disesuaikan oleh developer).

Mode kesalahan. Aggregate milik developer yang menggunakan blok inject: pada Component yang spec.inject:-nya tidak ada atau kosong menghentikan build saat pemuatan workspace (“Self-inject on a component without an allowlist (Self-inject pada komponen tanpa daftar izin)”). Blok inject: yang menggunakan mekanisme yang tidak ada dalam daftar izin berhenti dengan kondisi yang sama, dengan menyebut mekanisme tersebut dan mekanisme yang diizinkan daftar (“Self-inject mechanism not in the component’s allowlist (Mekanisme self-inject tidak ada dalam daftar izin komponen)”). Tabrakan kunci pengiriman antara self-inject, inject lintas komponen, dan inject kredensial juga menghentikan build (“Duplicate delivery key across inject sources (Kunci pengiriman duplikat di antara sumber inject)”). Lihat errors/fatal-halts.md untuk bentuk pesan per kesalahan.

Penulisan katalog: memperluas Components dasar

Platform Architect menggunakan kata kunci extends untuk menumpuk antarmuka khusus di atas baseline korporat atau komunitas. Perluasan menyusun struktur dan mewarisi pilar data secara utuh. Compiler menelusuri rantai dari dasar ke bawah; kedua bagian itu berperilaku berbeda, dan perbedaan tersebut adalah keseluruhan model penulisan.

Apa yang disusun oleh perluasan. Permukaan-permukaan ini digabungkan di sepanjang rantai, dengan Component yang memperluas menang per kunci dan daftar digabungkan dengan dasar terlebih dahulu tanpa duplikat:

PermukaanCara penyusunannya
metadata.labelsdigabungkan per kunci; nilai Component yang memperluas menang pada kunci yang sama
metadata.annotationsdigabungkan per kunci, dengan prioritas yang sama — itulah sebabnya mandat kehadiran milik dasar menjangkau setiap Component yang memperluasnya
spec.featuresSchemaslot lampiran digabungkan (union); slot yang dideklarasikan ulang oleh Component yang memperluas menggantikan entri dasar dengan nama tersebut
spec.usesSchemasoket topologi digabungkan (union), dengan aturan penggantian per nama yang sama
spec.injectkedua allowlist self-inject digabungkan, entri dasar terlebih dahulu, duplikat dibuang
spec.assertionsaturan bernama terakumulasi, aturan dasar terlebih dahulu — dan hanya permukaan ini yang tidak mengizinkan penggantian per nama; lihat “Pewarisan asersi bersifat aditif” di bawah

Soket yang ditambahkan oleh Component yang memperluas dapat membawa valueSchema dan infraSchema per sisi miliknya sendiri; keduanya adalah kontrak pada sisi-sisi soket tersebut, bukan tambahan pada pilar milik Component itu sendiri.

Sisa metadata: tetap pada dokumen yang mendeklarasikannya. labels dan annotations adalah satu-satunya metadata yang diturunkan di sepanjang rantai. name, version, description, maintainers, license, repository, home, dan keywords adalah milik Component yang memperluas itu sendiri, dibaca persis seperti yang ditulisnya — Component yang menghilangkan description: tidak memiliki deskripsi alih-alih meminjam milik dasarnya. Identitas dan asal-usul adalah milik dokumen yang sedang Anda baca, sehingga pembungkus tidak pernah tertukar dengan hal yang dibungkusnya.

Apa yang diwarisi utuh oleh perluasan. Ketiga pilar data — values, infra, provides — tidak disusun. Component yang memperluas tidak menulis konten pilar: ia menulis penanda literal schema: inherited dan menerima blok schema: milik dasarnya persis seperti yang ditulis oleh dasar tersebut. Di sepanjang rantai dengan kedalaman berapa pun, setiap Component di dalamnya membawa blok milik akar rantai tanpa perubahan, sehingga aggrega inspect --resolved pada daun menampilkan pilar yang sama dengan akar.

Skema Component yang dipublikasikan menetapkan mana dari tiga kemungkinan hasil yang sah, dan menolak dua lainnya saat dokumen dimuat — dengan diagnostik yang berbeda untuk masing-masing, karena keduanya adalah kesalahan yang berbeda:

  • extends: dengan konten pilar di bawah schema: ditolak. Kontrak Component adalah kontrak milik dasarnya; kontrak kedua yang berbeda tidak memiliki tempat.
  • extends: dengan schema: dihilangkan sepenuhnya ditolak. Penghilangan akan membuat pembaca tidak dapat membedakan blok pilar yang diwarisi dari blok yang terlupakan.
  • schema: inherited tanpa extends: ditolak. Penanda tersebut menyebutkan asal pilar, dan Component ini tidak memiliki dasar untuk mengambilnya.

Component yang memperluas tidak dapat membentuk ulang himpunan kunci. Ia tidak mendeklarasikan kunci pilar, sehingga tidak dapat menyembunyikan, membuang, atau mengubah tipe kunci yang dideklarasikan dasarnya, dan tidak menambahkan kunci miliknya sendiri. Kunci pilar baru ditempatkan pada Component yang kontraknya memilikinya. Apa pun yang diekspos dasar, semua yang memperluasnya mengekspos hal yang sama persis.

Spesialisasi diperketat melalui assertions:. Ketika spesialisasi harus menerima lebih sedikit daripada pilar dasarnya — rentang numerik yang lebih sempit, subset dari enum: yang diwarisi — hal itu dinyatakan dalam blok assertions: miliknya sendiri: aturan di sana menolak nilai yang diterima oleh skema yang diwarisi. Di permukaan itulah pengetatan dilakukan; lihat “Blok assertions:” di bawah.

Dua paragraf terakhir itu adalah satu aturan, dan masing-masing bagian saja menyesatkan: penyempitan himpunan kunci tidak mungkin, pengetatan batasan mungkin. Jika hanya mengambil yang pertama, Anda menyimpulkan bahwa spesialisasi tidak dapat membatasi apa pun; jika hanya mengambil yang kedua, Anda menyimpulkan bahwa spesialisasi dapat membentuk ulang kontrak. Keduanya tidak benar — himpunan kunci ditetapkan oleh dasar, dan nilai yang diterima di dalamnya dapat dipersempit dengan predikat.

Pewarisan asersi bersifat aditif, dan akumulasinya dimulai dari akar. Instans dari Component yang memperluas diperiksa terhadap setiap aturan yang dideklarasikan rantainya serta aturan yang dideklarasikan Component itu sendiri, dengan aturan yang diwarisi dievaluasi terlebih dahulu. Di sepanjang rantai dengan kedalaman berapa pun, aturan terakumulasi dari akar rantai ke bawah, sehingga ketika suatu instans akan gagal pada lebih dari satu aturan, aturan yang dideklarasikan paling atas dalam rantailah yang dilaporkan — kontrak yang paling mendasar menjawab lebih dahulu.

Karena pewarisan menambahkan alih-alih menggantikan, Component yang memperluas tidak boleh menggunakan ulang nama aturan yang diwarisi untuk mendeklarasikan aturan yang berbeda: hal itu ditolak saat rantai extends diselesaikan terhadap katalog, dengan diagnostik yang menyebutkan kedua Components dan nama yang sama tersebut. Pemeriksaan ini memerlukan Component dasar, sehingga dilaporkan saat katalog divalidasi atau saat build menyelesaikan rantai — validasi dokumen yang memperluas secara tersendiri tidak dapat melihatnya. Nama aturan adalah pengenal yang stabil, sehingga membuang aturan dasar maupun mengganti namanya secara diam-diam bukanlah pilihan, dan perbaikannya adalah mengganti nama di Component yang memperluas. Menyatakan ulang aturan yang diwarisi secara identik byte demi byte di bawah namanya sendiri diterima sebagai no-op.

aggrega pull mengambil basis. Basis adalah dependensi dari setiap Release yang menjangkau Component yang memperluasnya, baik ada maupun tidak ada hal lain yang menyebutkannya. aggrega pull mengikuti setiap extends: hingga ujung rantai, mengambil dari registry basis yang tidak dimuat oleh direktori katalog mana pun, dan mencatat setiap basis di lockfile Release, dirujuk dari spec.extends milik Component yang menyebutkannya; build membaca basis dari sana. Jadi, Manifest hanya memetakan tipe milik wrapper itu sendiri dan tidak lebih — basis memerlukan baris pemetaannya sendiri hanya jika sebuah Aggregate juga mendeklarasikan instans basis tersebut. aggrega validate atas seluruh katalog membaca basis dengan cara yang sama, sehingga basis yang dipublikasikan ke registry ditolak di sana, dengan menyebutkan aggrega pull, hingga sebuah pull mengambilnya.

Lihat architecture/13-catalog-and-registry.md §3 untuk format konten skema.

Contoh A: Component dasar (baseline korporat) Platform Architect mendefinisikan server enterprise dasar. Dasar ini menetapkan label primitif cloud operasional yang diwajibkan dan menetapkan batasan keamanan dalam skema. Karena blok pilar diwarisi tanpa perubahan, setiap batasan di sini menjangkau setiap Component yang memperluasnya persis seperti yang ditulis.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/base-enterprise-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
inject: [env]
schema:
values:
# The corporate baseline constraint. Every Component extending this base
# receives this leaf verbatim; none of them can restate or loosen it.
tls_enabled: { type: boolean, enum: [true], default: true }
# An open range at the baseline. A specialization that needs a tighter
# bound expresses it as an assertion, not as a redeclared schema leaf.
timeout_ms: { type: integer, default: 5000 }
assertions:
# A baseline invariant. It is evaluated for instances of this Component AND
# for instances of every Component extending it, under this same name.
audit-window-is-observable: |
{{- if lt (int .values.timeout_ms) 100 -}}
{{- fail "the corporate baseline needs timeout_ms of at least 100 so requests are observable" -}}
{{- end -}}

Contoh B: Component yang memperluas (menspesialisasikan baseline) Sebuah gateway dispesialisasikan dari baseline tersebut. Gateway ini mengambil pilar dasar secara utuh, menambahkan struktur miliknya sendiri — sebuah label, sebuah mekanisme self-inject, sebuah soket topologi dengan slot lampiran di atasnya — dan memperketat timeout yang diwarisi melalui sebuah asersi. Gateway ini tidak menyatakan ulang aturan audit-window-is-observable milik baseline: aturan itu diwarisi dan dievaluasi terlebih dahulu, sehingga instans gateway ini harus memenuhi kedua batas — minimal 100 dan maksimal 2000.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/gateway/kong
version: 1.0.0
labels:
# Every Component declares the reserved base-ontology key, including one
# that extends: the envelope requires it on the document itself.
component.aggrega.ai/type: "server"
api.aggrega.ai/protocol: "http" # merged with the base's labels
spec:
extends: core/base-enterprise-server
schema: inherited # values, infra and provides are the base's, verbatim
inject: [file] # concatenates with the base's [env] -> [env, file]
usesSchema: # a socket of its own; the base declared none
backend:
required: true
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]
featuresSchema: # a slot each connection through it fills
credential:
sensitive: true
inject: [env]
description: Password the gateway presents to the configuration backend this connection reaches.
assertions:
# The tightening. The inherited schema admits any integer for timeout_ms;
# this gateway admits only 2000 or less, so the rule rejects a value the
# inherited pillar block would accept.
timeout-within-gateway-budget: |
{{- if gt (int .values.timeout_ms) 2000 -}}
{{- fail "the gateway must answer within 2000ms: set timeout_ms to 2000 or less" -}}
{{- end -}}

Untuk Recipe yang mengimplementasikan antarmuka core/gateway/kong ini terhadap chart Helm fisik, lihat entities/recipe Contoh C (kong-gateway).

Blok assertions:

Component.spec.assertions: adalah map opsional berisi aturan bernama yang menyatakan invarian arsitektural dari kontrak Component — aturan lintas-field yang harus dipenuhi oleh penulisan pengembang, terlepas dari Recipe mana yang terikat pada Component tersebut. Setiap kunci adalah pengenal aturan yang muncul dalam pesan kegagalan; setiap nilai adalah isi templat Go. Kompiler mengevaluasinya per instans setelah validasi skema dan sebelum pengikatan Recipe, sesuai urutan penulisannya, dan aturan pertama yang gagal menghentikan build dengan pesan galat milik aturan itu sendiri sesuai kontrak Loud Guardrails.

spec:
assertions:
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt (int .values.secondary.replicaCount) 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}

Aturan di atas adalah properti dari kontrak Component — Recipe apa pun yang terikat (chart Bitnami, alternatif buatan sendiri, implementasi di masa depan), mode replikasi memerlukan setidaknya dua replika sekunder.

assertions: adalah tempat Component turunan memperketat batasan. Component yang melakukan extends: terhadap suatu basis mewarisi blok pilar basis apa adanya dan tidak mendeklarasikan konten pilar sendiri, sehingga spesialisasi yang harus menerima lebih sedikit daripada skema warisan menyatakan pembatasannya di sini sebagai predikat, bukan sebagai daun skema yang dipersempit — sebuah aturan yang menolak nilai yang diterima oleh pilar warisan. Pasangan contoh lengkap, beserta perilaku pewarisan secara utuh, ada di “Catalog Authoring: Extending Base Components” di atas: aturan terakumulasi di sepanjang rantai mulai dari akar, dan penggunaan ulang nama aturan warisan untuk aturan yang berbeda ditolak alih-alih dibiarkan menggantikannya.

Kompiler tidak memeriksa apakah dua aturan dapat dipenuhi sekaligus. Aturan adalah predikat templat, bukan batasan yang dinalar oleh kompiler, sehingga sepasang aturan yang tidak dapat dipenuhi bersamaan oleh nilai apa pun — basis yang menuntut minimal 100 dan spesialisasi yang menuntut maksimal 50 — tidak menghasilkan peringatan saat katalog dimuat. Hal ini muncul dengan cara biasa: sebuah instans ditulis, build berhenti pada aturan mana pun dari keduanya yang terpicu lebih dulu, dan pesan aturan itulah yang dibaca penulis. Jangan berharap kontradiksi dilaporkan di awal; periksa pengetatan sebuah spesialisasi terhadap apa yang sudah dituntut basisnya.

Gunakan assertions: untuk aturan lintas-field yang sesungguhnya. Batasan per-field (rentang, pola, enum) ditempatkan dalam kata kunci schema:; predikat kustom per-field ditempatkan dalam validate: pada bentuk ringkas; bentuk kondisional (apakah batasan suatu subpohon berlaku) ditempatkan dalam when:. Untuk tata bahasa penulisan lengkap — field konteks templat, konvensi pesan {{ fail }}, fase evaluasi, dan contoh yang mencakup peran Component dan Recipe — lihat templates/assertions-block.md.