extends dan implements
Pewarisan melalui extends
Entitas katalog (Component, Feature) mendukung pewarisan tunggal melalui kata kunci extends, yang memungkinkan Platform Architect membangun entitas yang terspesialisasi di atas basis bersama. Deep-merge amplop YAML berlaku sama untuk kedua jenis: metadata, label, dan tabel struktural deklaratif pada entitas yang memperluas menimpa kunci yang cocok di basis, dan map bersarang diproses secara rekursif. Kedua jenis tersebut berbeda dalam hal pilar data.
Halaman ini membahas jenis katalog, dan jenis tersebut bukan satu-satunya jenis yang mendeklarasikan extends. Release dan Manifest juga mendeklarasikannya, dan keduanya adalah dokumen sisi deployment yang ditulis berdampingan, bukan entitas yang diindeks katalog — sehingga referensinya menamai file, bukan entitas katalog, dan yang digabungkan adalah permukaan penulisan, bukan skema. Untuk keduanya, lihat entities/release.md dan entities/manifest.md.
extends pada Component menyusun struktur dan mewarisi pilar secara utuh
Untuk Component, extends menyusun metadata.labels, metadata.annotations, spec.featuresSchema (slot lampiran), spec.usesSchema (soket topologi) dan spec.inject (allowlist self-inject, yang entrinya digabungkan dengan basis lebih dahulu tanpa duplikat). Ketiga pilar data — values, infra, provides — tidak disusun. Component yang memperluas tidak menulis konten pilar: Component tersebut menulis penanda literal schema: inherited dan menerima blok schema: milik basis persis seperti yang ditulis basis, pada setiap kedalaman rantai.
Skema Component yang dipublikasikan menjadikan penanda tersebut wajib sekaligus eksklusif, dan menolak setiap penyimpangan darinya saat dokumen dimuat, dengan diagnostiknya sendiri untuk masing-masing: konten pilar yang ditulis di bawah schema: pada Component yang mendeklarasikan extends:; schema: yang dihilangkan sepenuhnya di sana; dan schema: inherited pada Component yang tidak mendeklarasikan extends:.
Dua konsekuensi muncul, dan keduanya menarik ke arah yang berlawanan:
- Himpunan kunci ditetapkan oleh basis. Component yang memperluas tidak mendeklarasikan kunci pilar, sehingga tidak dapat menyembunyikan, menghapus, atau mengubah tipe kunci yang dideklarasikan basis, dan tidak menambahkan kuncinya sendiri. Instans basis dan instans dari apa pun yang memperluasnya divalidasi terhadap kontrak pilar yang sama.
- Pengetatan dipindahkan ke
assertions:. Spesialisasi yang harus menerima lebih sedikit daripada pilar yang diwarisi menyatakannya sebagai predikat pada dirinya sendiri, bukan sebagai leaf skema yang dipersempit. Jika basiscore/base-servermendeklarasikantls_enabled: { type: boolean, default: true }, spesialisasi yang mewajibkan TLS tanpa syarat menulis:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/tls-only-server version: 1.0.0 labels: component.aggrega.ai/type: "server"spec: extends: core/base-server schema: inherited # values, infra and provides are the base's, verbatim assertions: tls-is-mandatory: | {{- if not .values.tls_enabled -}} {{- fail "this component requires tls_enabled: true" -}} {{- end -}}Aturan tersebut menolak nilai yang diterima oleh blok pilar yang diwarisi, dan itulah tepatnya makna pengetatan di sini. Arah sebaliknya sama sekali tidak dapat dinyatakan: spesialisasi tidak dapat melonggarkan batasan yang diwarisi, karena tidak dapat menyatakan ulang leaf yang membawanya. Lihat entities/component.md “Catalog Authoring: Extending Base Components” untuk tabel komposisi lengkap dan contoh pasangan basis dan ekstensi.
extends pada Feature menyusun pilarnya
Untuk Feature, schema: milik turunan disusun dengan milik basis berdasarkan semantik komposisi JSON Schema 2020-12, menghasilkan satu skema gabungan yang menjadi dasar validasi instans yang ditulis. Features kredensial — yang berlabel feature.aggrega.ai/kind: secret — menggunakan ini untuk membangun di atas basis bersama: Feature kredensial turunan memperluas induk untuk mewarisi skema kueri vault-nya sambil mempersempit batasan.
Compiler tidak mengambil sikap terhadap arah perubahan tersebut. Komposisi bersifat struktural, sehingga batasan turunan yang memperlebar batasan basis tetap tersusun tanpa menghentikan build dan muncul sebagai peringatan. Tidak ada yang menolaknya: batasan basis Feature adalah harapan bersama yang dijaga oleh para penulis katalog melalui review, bukan kontrak yang diawasi platform.
Pengikatan antarmuka melalui implements
Recipes dan FeatureRecipes terikat ke antarmuka Component atau Feature melalui kata kunci implements: di bagian atas spec mereka. Pengikatan ini menyatakan antarmuka katalog mana yang implementasi konkretnya adalah Recipe / FeatureRecipe ini, dan mendukung tiga bentuk pencocokan versi:
- Tepat —
implements: core/api-server:1.0.0— mencocokkan satu versi spesifik dari tipe Component. - Rentang kompatibel mayor —
implements: core/api-server:^1.0.0— mencocokkan versi apa pun yang memenuhi>=1.0.0, <2.0.0(kompatibel mayor menurut SemVer). Digunakan ketika sebuah Recipe mendukung rentang yang kompatibel, bukan satu versi yang dipatok. - Tanpa versi —
implements: core/api-server— mencocokkan versi apa pun dari tipe Component. Digunakan ketika sebuah Recipe melayani setiap versi tipe tersebut.
implements: tidak pernah memilih Recipe: yang memilih adalah pemetaan Manifest. Yang digerakkan oleh deklarasi ini adalah pemeriksaan konsistensi pada setiap entri pemetaan — versi tipe yang dipetakan harus memenuhi implements: milik Recipe yang dipetakan dalam salah satu dari tiga bentuk, atau Recipe tersebut harus mengimplementasikan basis yang diperluas tipe itu — serta daftar kandidat yang ditawarkan diagnostik tanpa-pemetaan dan pelengkapan editor. Entri pemetaan yang implements: milik Recipe-nya tidak cocok dengan tipe yang dipetakan maupun basis mana pun darinya menghentikan build, dengan menyebut pemetaan, Recipe, dan nilai implements:-nya. Ketika kunci components.type menjangkau instans komponen pada versi yang tidak disebut oleh kunci tersebut — setiap instans, untuk kunci yang ditulis tanpa versi — pemeriksaan dilakukan lagi dengan tipe instans itu sendiri, pada versi yang dikompilasi build, dan Recipe yang tidak memenuhinya menghentikan build dengan cara yang sama, dengan menyebut instansnya.
Pengikatan implements: adalah mekanisme yang membuat “tipe Component yang sama, Recipes berbeda untuk provider berbeda” berfungsi: sebuah Component core/postgres dapat memiliki satu Recipe yang mengimplementasikannya untuk provider helm dan Recipe lain yang mengimplementasikannya untuk provider compose. Setiap Recipe mendeklarasikan nilai implements: yang sama, dan Manifest yang digunakan sebuah Release untuk build memetakan tipe tersebut ke Recipe yang diinginkannya.
Recipe yang ditulis terhadap sebuah basis melayani semua yang memperluasnya
implements: menyebut sebuah basis, dan Recipe yang menyebutnya adalah implementasi konkret untuk setiap Component yang memperluas basis tersebut, pada kedalaman rantai mana pun. Jadi spesialisasi yang dibangun dengan extends tidak memerlukan Recipe sendiri — inilah yang membuat pembungkus yang dipublikasikan murah untuk dikonsumsi: tim yang memublikasikannya menulis sebuah Component, dan tim yang men-deploy-nya menggunakan kembali Recipes milik basis pada setiap target.
Dua fakta berlaku sekaligus di sini, dan keduanya terpisah. Pembaca yang meleburkan keduanya menjadi “spesialisasi tidak memerlukan apa pun” akan menulis Manifest yang gagal, karena alasan yang akan ia cari di berkas yang salah:
- Recipe cocok. Pemeriksaan konsistensi antara kunci tipe pada pemetaan Manifest dan
implements:milik Recipe yang dipetakan menerima pemetaan tersebut ketika Recipe mengimplementasikan tipe yang dipetakan itu sendiri atau basis mana pun yang diperluas oleh tipe tersebut. Ketiga bentuk versi di atas berlaku untuk basis persis seperti berlaku untuk tipe itu sendiri: Recipe yang mendeklarasikanimplements: core/base-server:^1.0.0memenuhi spesialisasi yang basisnya berversi1.4.0, dan tidak memenuhi spesialisasi yang basisnya2.0.0. - Manifest tetap memetakan tipe milik spesialisasi itu sendiri. Pemilihan Recipe dilakukan berdasarkan kunci pemetaan yang tepat. Sebuah instans
enterprise/labelled-servermemerlukan entrimappings.components.typesendiri; ia tidak mewarisi entri yang ditulis untukcore/base-server. Spesialisasi tanpa entri sendiri akan berhenti dengan diagnostik instans tak terpetakan bahkan ketika basisnya sudah dipetakan.
Dengan demikian, biaya penulisan sebuah spesialisasi adalah satu baris Manifest dan tanpa Recipe baru:
# The wrapper extends core/base-server and authors no pillars.# core/helm/base-server declares: implements: core/base-serverspec: mappings: components: type: enterprise/labelled-server:1.0.0: core/helm/base-server:1.0.0Ketika rantai extends dari tipe yang dipetakan tidak dapat ditelusuri — rantai tersebut membentuk perulangan, atau basis yang disebutnya tidak ada di katalog — build berhenti pada kesalahan rantai tersebut alih-alih pada pemetaan, karena sebuah pemetaan tidak dapat dinilai sebelum rantai yang menjadi dasarnya teresolusi. Pemeriksaan ini menelusuri rantai hanya melalui Components yang sudah ada di mesin ini — yang berada di direktori katalog, dan yang disimpan cache artefak lokal di bawah patokan lockfile — dan tidak pernah menanyakan registry, sehingga basis yang hanya disimpan oleh registry dianggap tidak ada di sini. Mengambilnya adalah tugas aggrega pull: basis merupakan dependensi bagi semua yang memperluasnya, sehingga pull mengikuti setiap rantai extends: yang dijangkau Release, mengambil setiap basis yang tidak disimpan oleh direktori katalog mana pun, dan mematoknya di lockfile, tempat build berikutnya menemukannya. Manifest tidak memerlukan baris untuk basis itu sendiri kecuali sebuah Aggregate juga mendeklarasikan instans basis tersebut.
Saran Recipe tetap lebih sempit daripada aturan pencocokan ini. Daftar kandidat yang dicetak oleh diagnostik tanpa-pemetaan, dan urutan yang diterapkan pelengkapan editor pada nilai pemetaan, menyebut recipe yang mengimplementasikan tipe yang diminta itu sendiri; keduanya tidak meluas ke recipe yang mengimplementasikan salah satu basisnya.
Untuk panduan menyeluruh yang dapat dijalankan — pembungkus yang dipublikasikan di katalog, satu baris Manifest yang mengonsumsinya, Recipe milik basis yang membentuk keluaran hasil render, dan penghentian yang dihasilkan oleh instans pembungkus tanpa pemetaan sendiri — lihat contoh examples/extends-wrapper/.
Konsumsi versi lintas entitas
Setiap jenis entitas Aggrega — Component, Feature, Aggregate, Recipe, FeatureRecipe, Manifest, Release, Plugin, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary — memiliki field wajib metadata.version yang divalidasi terhadap regex SemVer yang sama (MAJOR.MINOR.PATCH menurut architecture/02-ecosystem-philosophy.md). Versi seragam dalam bentuk; konsumsi versi berbeda menurut jenis entitas. Sebagian versi berperan aktif dalam resolusi; sebagian lainnya adalah provenans deskriptif yang tidak dicocokkan oleh compiler. Tabel di bawah mencakup jenis non-pustaka, menyebutkan apa yang dilakukan compiler terhadap field versi setiap entitas, dan menggunakan taksonomi status empat label dari 10-status.md untuk mengklasifikasikan setiap rezim konsumsi. Empat jenis pustaka berada di luar tabel karena rezimnya seragam dan berbeda: konsumen merujuk pustaka dengan nama polos, dapat menyatakan batas bawah versi minimum :<version> yang opsional, dan lockfile per Release memiliki versi yang telah diresolusi beserta digest kontennya.
| Entitas | Rezim konsumsi | Status |
|---|---|---|
| Component | Resolusi referensi tipe; pencocokan implements: Recipe | available — bentuk eksak, rentang caret (^MAJOR.MINOR.PATCH), dan tanpa versi pada keduanya (lihat Resolusi versi dan Status → Pencocokan versi) |
| Feature | Resolusi referensi lampiran; pencocokan implements: FeatureRecipe | Sama seperti Component |
| Recipe | Resolusi tingkat pemetaan Manifest | available — bentuk eksak, rentang caret, dan tanpa versi dalam nilai pemetaan, masing-masing memilih versi tertinggi yang memenuhi |
| FeatureRecipe | Resolusi tingkat pemetaan Manifest | Sama seperti Recipe |
| Aggregate | Resolusi referensi induk aggregates[].type | available — bentuk eksak, rentang caret, dan tanpa versi, masing-masing memilih versi tertinggi yang memenuhi (lihat Resolusi versi) |
| Plugin | Dispatch Provider melalui recipe.spec.capability → spec.provider.capabilities | available — capability polos memilih provider, dan pin padanya (helm:<version>, helm:^<version>) memilih versi plugin mana yang melakukan render; identitas plugin adalah referensi oci://<repository> tanpa digest ditambah metadata.version, dan digest konten dicatat dalam lockfile release yang menjadi acuan build untuk memverifikasi byte yang diambil |
| Manifest | Provenans grafik IR (manifest_version) | available (hanya dibaca untuk provenans; tidak berperan dalam dispatch resolusi) |
| Release | Provenans grafik IR (release_version) + metadata template (.metadata.release_version) | Sama seperti Manifest |
Rezim resolusi katalog (Component, Feature, Aggregate, Plugin). Referensi ke salah satu jenis ini — type sebuah komponen, type sebuah lampiran fitur, aggregates[].type sebuah impor sub-aggregate, plugin sebuah langkah pipeline — diresolusi dengan aturan yang dijelaskan dalam Resolusi versi: referensi eksak, rentang caret, atau tanpa versi memilih versi tertinggi yang memenuhi di antara versi yang dimiliki katalog, dan pull, build, validate, editor, serta alat untuk asisten menerapkan satu aturan yang sama itu. Untuk Component atau Feature, pencocokan implements: membaca tiga bentuk yang sama dari arah sebaliknya — versi tipe konkret terhadap bentuk yang dideklarasikan sebuah Recipe atau FeatureRecipe — sebagai pemeriksaan konsistensi yang dijelaskan di bawah, bukan sebagai pemilihan. Dispatch Provider-rendering-plugin menggunakan bentuk yang lebih sederhana: dispatch ini mencari recipe.spec.capability polos terhadap spec.provider.capabilities milik plugin provider-rendering berdasarkan nama, dan pin versi yang ditulis pada capability memilih versi plugin mana yang melakukan render, serta berhenti jika tidak ada versi yang memenuhinya.
Resolusi tingkat pemetaan Manifest. Mekanisme resolusi mappings.{components,features} yang datar pada Manifest (dengan tingkat name dan type, nama menang atas tipe, dan tipe berversi menang atas tipe tanpa versi) didokumentasikan di entities/manifest.md. Resolver mengonsumsi pemetaan tersebut: pemilihan Recipe dan FeatureRecipe adalah pencarian langsung nilai pemetaan terhadap lockfile dan katalog, dan komponen atau lampiran yang tipenya tidak memiliki pemetaan menghentikan build. spec.implements tidak memilih Recipe — ini adalah pemeriksaan konsistensi saat pemuatan terhadap pemetaan yang sudah ditulis penulis, serta sumber daftar kandidat yang ditawarkan diagnostik tanpa pemetaan dan pelengkapan editor. Dispatch kapabilitas kemudian mengalir dari field spec.capability milik Recipe yang telah diresolusi, bukan dari bentuk struktural Manifest.
Rezim provenans deskriptif (Manifest, Release). metadata.version Manifest dan metadata.version Release dibaca ketika compiler mengisi provenans, dan muncul di blok provenans grafik IR sebagai manifest_version dan release_version; tidak ada label pada keluaran yang dirender yang membawa salah satunya. Template juga melihat versi Release yang diekspos sebagai .metadata.release_version. Tidak satu pun versi ini dicocokkan dengan versi entitas lain untuk dispatch resolusi; keduanya murni provenans.
Membaca tabel. Klasifikasi empat label membedakan “field versi diterima oleh skema dan ada pada entitas” (selalu benar — regex SemVer yang seragam) dari “compiler mencocokkan versi ini selama resolusi” (berbeda per entitas).
Penyaluran lintas pilar schema-bridge: menjembatani intensi ke infrastruktur
Aggrega menerapkan Pemisahan Kepentingan yang tegas antara Domain 1 dan Domain 4: Developer menulis logika kognitif di blok values, sedangkan Operator menentukan ukuran fisik di blok infra. Skema Aggregate.yaml menegakkan satu konsekuensi konkret: kata kunci infra tidak ada pada instans komponen Aggregate maupun pada lampiran features milik instans tersebut dan, dikombinasikan dengan additionalProperties: false, ditolak oleh validasi skema. Developer sebaiknya tidak menentukan ukuran fisik di dalam Developer Intent; bila suatu nilai spesifik sesuai dengan kasus aplikasi (misalnya port yang di-hardcode atau angka CPU tertentu), Architect dapat mengeksposnya secara eksplisit dalam deklarasi schema: milik Component dan nilainya mengalir melalui values.
Untuk kasus ketika suatu batasan infrastruktur spesifik merupakan bagian intrinsik dari kontrak sebuah komponen — basis data trading ber-throughput tinggi yang harus memiliki 10.000 IOPS terprovisi, workload ML yang harus berjalan pada tepat 4 GPU — Platform Architect mengekspos batasan tersebut melalui Component yang dibuat khusus menggunakan pola penyaluran lintas pilar schema-bridge.
Pola schema-bridge untuk komponen yang sadar infrastruktur.
Component mengekspos pengaturan infrastruktur spesifik di dalam blok values milik developer melalui deklarasi schema:-nya, dan templat valuesMapping: milik Recipe yang terikat menyalurkan nilai tersebut ke keluaran berbentuk infra: yang dirender. Hasilnya adalah jembatan bertipe antara intensi kognitif dan ukuran fisik: developer menentukan batasan perangkat keras melalui bidang yang tervalidasi, dan batasan itu mengalir ke Ops tanpa salah satu pihak menulis kode infrastruktur mentah. Pengaturan tersebut adalah kunci pilar, sehingga dideklarasikan pada Component yang kontraknya memilikinya — Component yang melakukan extends: terhadap sebuah basis tidak mendeklarasikan kunci pilar dan karena itu tidak dapat memperkenalkan kunci baru.
# Domain 2: The Platform Catalog (the schema-bridge Component)apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/high-perf-postgres version: 1.0.0 labels: component.aggrega.ai/type: "stateful-server"spec: schema: values: # Expose the dial safely to the Developer with a typed contract. required_iops: { type: integer, min: 1000, max: 100000, required: true } infra: # Operator-owned sizing the Recipe below reads alongside the dial. storage: { size: { type: string, default: 100Gi } } compute: { instance_class: { type: string, default: db.m5.large } }# Domain 2: The Platform Catalog (the Recipe pipes the dial into provider infra)apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-rds-high-perf-postgres version: 1.0.0spec: implements: core/high-perf-postgres:^1.0.0 capability: terraform source: ./modules/rds valuesMapping: | # The Recipe pipes the developer's values.required_iops into the provider's infra-side knob. iops: {{ .values.required_iops }} allocated_storage: "{{ .infra.storage.size }}" instance_class: "{{ .infra.compute.instance_class }}"# Domain 1: The Developer Intent (remains capability-agnostic)components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: 10000 # Developer dictates the hardware constraint safelyPenskalaan multi-lingkungan (persyaratan pengangkatan parameter).
Untuk menskalakan batasan perangkat keras ini di seluruh lingkungan GitOps (Dev vs. Prod) tanpa mengubah Aggregate.yaml milik developer, developer mengangkat nilai tersebut ke kontrak parameters yang bertipe. Ops memenuhi persyaratan IOPS spesifik melalui berkas Release khusus lingkungan. Urutan eksekusi compiler melindungi alur ini: validasi kontrak parameter berjalan saat resolusi; interpolasi menyelesaikan parameter ke dalam string values: di sekitarnya; templat valuesMapping: milik Recipe menyalurkan nilai yang telah diselesaikan ke keluaran yang dirender.
1. Developer Intent (mengabstraksikan pengaturan).
Developer tahu bahwa mereka perlu mengendalikan IOPS, tetapi mereka mengabstraksikan angka eksplisitnya ke tingkat lingkungan melalui kontrak parameters yang bertipe.
spec: parameters: env_iops: type: integer min: 1000 max: 100000 description: Provisioned IOPS for the trading-db instance components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: {{ .parameters.env_iops }} # Hoisted to the environment2. Releases GitOps (pemenuhan oleh Ops).
Ops memenuhi kontrak parameters dalam berkas Release khusus lingkungan. Kontrak bertipe memvalidasi setiap nilai yang diberikan Release sebelum interpolasi berjalan.
- Lingkungan Dev (
release-dev.yaml):env_iops: 1000 - Lingkungan Prod (
release-prod.yaml):env_iops: 25000
Urutan kompilasi. Mekanisme ini dilindungi oleh urutan eksekusi compiler yang ketat saat resolusi:
- Validasi kontrak parameter. Setiap nilai parameter yang diberikan Release divalidasi terhadap deklarasi
parameters:bertipe milik Aggregate. Nilai Prod25000lolos validasi (dalammin: 1000, max: 100000); nilai500akan menghentikan proses dengan galat yang jelas. - Interpolasi. Compiler membaca nilai parameter
ReleaseProd dan menginterpolasikan25000ke dalam string YAMLAggregatepadavalues.required_iops. Peta parameter hasil penggabungan tetap hidup selama rendering sehingga permukaan templat path dapat membaca.parameters.<slot>secara langsung; permukaan templat nilai menggunakan literal pascainterpolasi yang sudah ditulis ke blokvalues:milik Aggregate. Peta tersebut tetap dapat dibaca hingga setiap fase render selesai, dan hanya dapat dijangkau dari kompilasi tempat peta itu diselesaikan. - Validasi skema. Deklarasi
schema:milik Component memvalidasi kamusvalues:yang dihasilkan;values.required_iops: 25000memenuhimin: 1000, max: 100000pada skema. - Rendering valuesMapping Recipe. Templat
valuesMapping:milik Recipe yang terikat menyalurkanvalues.required_iopske keluaran berbentukinframilik provider (iops: 25000). Plugin provider Wasm menghasilkan konfigurasi basis data fisik yang tepat. Developer mendapatkan kendali perangkat keras yang eksplisit, Ops mendapatkan penskalaan khusus lingkungan, danAggregatetetap agnostik terhadap kapabilitas.