Manifest
Peran konseptual entitas Manifest (Domain 4 — tabel pemetaan yang mengikat antarmuka abstrak ke Recipes konkret) dijelaskan di architecture/04-entity-taxonomy.md. Halaman ini membahas permukaan penulisan Manifest: bagaimana Manifest berdampingan dengan Release, bentuk pemetaan URI datar, komposisi melalui extends, aturan singkatan URI, pengikatan Feature berbasis anotasi, dan prefiks aggrega.ai/ yang dicadangkan oleh platform.
Manifest vs. Release: pemisahan tanggung jawab
Manifest dan Release memikul tanggung jawab yang tidak saling tumpang tindih:
- Manifest menentukan Recipe mana yang merealisasikan setiap jenis katalog, dan melalui
spec.capabilitymilik Recipe tersebut, provider (misalnya Helm, Helm-chart, Compose) yang me-render-nya. Manifest adalah tabel pemetaan — catatan per proyek yang di-commit ke Git tentang Recipe konkret mana yang mengimplementasikan setiap antarmuka abstrak; versi dan digest yang diwajibkan build bagi Recipes tersebut dipatok secara terpisah, dalam lockfile setiap Release. - Release menentukan tujuan (misalnya folder keluaran fisik untuk pembuatan artefak GitOps). Release adalah perute deployment — deskripsi per lingkungan tentang tempat artefak hasil kompilasi ditempatkan.
Skema Release tidak memuat field provider pada tingkat penyarangan mana pun; dispatch provider sepenuhnya menjadi milik Manifest.
Jalur kompilasi. Ketika pengguna menjalankan aggrega build --release release.yaml, kompiler menyelesaikan artefak fisik dengan menggabungkan kedua sumber:
- Baca tujuan. Kompiler memindai batas-batas (boundaries) Release — misalnya, boundary
ovh-cluster-3berisi komponenuser-db(tipe:core/postgres:1.0.0). - Pindai Manifest. Kompiler membuka Manifest yang dirujuk Release melalui field
manifest:miliknya. - Pencarian dua tingkat. Kompiler terlebih dahulu memeriksa tingkat
nameuntuk"user-db". Jika tidak ditemukan, kompiler memeriksa tingkattypeuntuk"core/postgres:1.0.0"(berversi), lalu"core/postgres"(tanpa versi). - Selesaikan Recipe. Nilai entri yang cocok adalah URI Recipe; Recipe yang dirujuknya mendeklarasikan di
spec.capabilityprovider mana yang merendernya. - Pembuatan keluaran. Kini kompiler mengetahui folder target (
dist/boundaries/ovh-cluster-3/), provider (rendering Helm melalui Wasm), dan artefak (kode sumber Recipe). Batas-batas GitOps ahead-of-time dihormati dari ujung ke ujung.
Pemetaan URI datar
Blok mappings: pada Manifest adalah peta datar dari URI tipe komponen ke URI Recipe (dan dari URI tipe fitur ke URI FeatureRecipe). Pemetaan ini agnostik terhadap kapabilitas pada tingkat Manifest; penentuan kapabilitas berasal dari field spec.capability milik setiap Recipe yang telah di-resolve pada waktu render, bukan dari bentuk struktural Manifest. Blok ini mengatur pemetaan di bawah dua kunci tingkat atas:
components.typememetakan URI tipe komponen ke URI Recipe. Setiap instans komponen dari tipe yang dideklarasikan di-resolve ke Recipe yang ditentukan. Pemetaan ini satu-ke-satu per tipe komponen. Kunci yang tidak menyebut tipe persis suatu instans tetap menjangkaunya melalui basis tipe tersebut, bila tidak ada kunci yang menyebut tipe persis itu dan tidak ada kunci lain yang ditulis untuk basis yang sama — sehingga kunci yang ditulis tanpa versi (core/postgres), atau kunci yang menyebut versi lain (core/postgres:1.0.0), dapat menjangkau instanscore/postgres:2.0.0— tetapi Recipe yang disebutnya harus mengimplementasikan versi milik setiap instans tersebut: instanscore/postgres:2.0.0yang dijangkau dengan cara itu dan dipetakan ke Recipe yang mendeklarasikanimplements: core/postgres:1.0.0menghentikan build. Petakan instans seperti itu dengan kunci yang menyebut versinya (core/postgres:2.0.0) ke Recipe yang mengimplementasikannya.features.typememetakan URI tipe fitur ke URI FeatureRecipe. Setiap lampiran Feature dengan tipe yang dideklarasikan di-resolve ke FeatureRecipe yang ditentukan. Features kredensial (berlabelfeature.aggrega.ai/kind: secret) berada di petafeatures.typeyang sama dengan Features operasional — model entitas Feature yang terpadu.
Setiap blok juga menerima tingkat name di samping type, yang memetakan nama instans tertentu ke URI Recipe (atau FeatureRecipe). Tingkat nama didahulukan atas tingkat tipe: instans yang disebut dalam components.name di-resolve ke Recipe tersebut, sedangkan setiap instans lain dengan tipe yang sama di-resolve melalui components.type. Hal ini menyatakan penimpaan per instans — dua instans dari satu tipe komponen dapat di-deploy melalui dua Recipes yang berbeda (misalnya, sebagian besar instans basis data menggunakan Recipe yang dipetakan secara massal sementara satu instans dipatok ke implementasi fisik yang berbeda), tanpa melakukan fork pada tipe komponen atau menduplikasi Manifest. Penimpaan ini berlaku seragam: instans yang dinamai dirender melalui Recipe penimpa sekaligus mematok sumbernya dari Recipe tersebut. features.name adalah tingkat simetris untuk lampiran Feature, dengan kunci berupa nama lampiran itu sendiri — kunci tempat lampiran ditulis dalam features: milik komponen — dan tidak pernah nama komponen tempat lampiran itu dipasang. Contoh penimpaan recipe per instans menelusuri kasus minimal dua instans dari awal hingga akhir.
Lampiran yang dibawa oleh sebuah koneksi diberi kunci berupa nama yang dimilikinya pada komponen konsumen: <alias>.<slot>, yaitu alias tempat koneksi ditulis, sebuah titik, dan slot yang diisi lampiran tersebut (lihat entri koneksi pada Aggregate). Dengan demikian, kredensial satu koneksi dapat direalisasikan secara berbeda dari setiap lampiran lain dengan tipe yang sama:
spec: mappings: features: type: core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0 name: # The credential the "gpt" connection carries in its "credential" slot. gpt.credential: helm/k8s-external-secret:1.0.0Entri ini dipatok dan diverifikasi seperti entri tingkat nama lainnya, sebagaimana dijelaskan paragraf berikut. Feature yang disebut oleh lampiran juga dipatok dan diverifikasi, persis seperti Feature dari lampiran yang ditulis pada komponen itu sendiri, di bawah entri koneksi yang ditulis pembuatnya — lihat Lockfile.
Kunci name harus menyebut sesuatu yang dimiliki build. Tingkat ini dicocokkan berdasarkan nama persis, sehingga kunci components.name yang bukan instans komponen dalam build, atau kunci features.name yang bukan lampiran di dalamnya — paling sering nama komponen tempat lampiran berada, yang ditulis di posisi nama lampiran itu sendiri — tidak akan dirujuk oleh apa pun, dan instans yang dimaksudkannya akan diam-diam di-resolve melalui tingkat type. Sebagai gantinya, build berhenti pada kunci seperti itu, sebelum apa pun di-render, dengan menyebut Manifest, kunci tersebut, nama-nama sejenis yang memang dimiliki build, dan nama yang mungkin Anda maksud — lihat A Manifest name mapping names nothing in the build (Pemetaan Manifest tidak menyebut apa pun dalam build).
Realisasi yang diikat berdasarkan nama dipatok dan diverifikasi seperti realisasi yang diikat berdasarkan tipe. aggrega pull memperoleh setiap Recipe dan FeatureRecipe yang diikat oleh kedua tingkat — dari direktori katalog, cache, atau registry — dan mencatat masing-masing dalam lockfile Release beserta versi yang di-resolve dan digest kontennya, di bawah entri pemetaan yang mengikatnya: manifest.spec.mappings.components.name.<instance> untuk entri tingkat nama, di samping manifest.spec.mappings.components.type.<type> untuk entri tingkat tipe. aggrega build menahan setiap realisasi tersebut pada patokannya. Lockfile yang tidak mencatat baris untuk realisasi yang diikat Manifest menghentikan build karena kedaluwarsa, dengan menyebut realisasi dan entri yang mengikatnya; realisasi yang kontennya berubah sejak pull menghentikannya dengan cara yang sama, dengan menyebut kedua digest. Dalam kedua kasus, aggrega pull --release <release> mencatat realisasi sebagaimana keadaannya sekarang. Seperti entri type, entri name dipatok baik Release mendeklarasikan instans dengan nama tersebut maupun tidak, sehingga entri name yang menyebut Recipe yang tidak dimiliki katalog atau registry mana pun menghentikan pull; entri name yang tidak menyebut instans apa pun yang dimiliki build juga dipatok, dan menghentikan build seperti dijelaskan paragraf di atas.
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: production-manifest version: 1.0.0spec: mappings: components: type: # Component-type → Recipe URI. A Recipe URI is at most two segments: an # optional leading capability, then the recipe name. The bare one-segment # form (last line) is the common case. core/datastore/postgres: helm/postgres:1.2.0 core/api-server: helm/api-helm:0.5.0 core/python-worker: standard-python-worker:2.0.0
features: type: # Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones. core/data-masking: helm/data-masking-litellm:1.0.0 core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0Penentuan kapabilitas pada waktu render. Entri Manifest mengikat tipe komponen ke URI Recipe. URI Recipe membawa paling banyak dua segmen — kapabilitas di depan yang opsional, lalu nama recipe — ditambah :version opsional; resolver memisah hanya pada / pertama, sehingga referensi dengan segmen ketiga tidak menyebut recipe apa pun dan menghentikan resolusi. Pada waktu render, resolver memuat Recipe melalui pencarian URI langsung terhadap lockfile dan katalog, dan field spec.capability setiap Recipe menentukan pengelompokan dispatch per-(path, kapabilitas). Bentuk struktural Manifest tetap datar, berapa pun banyaknya provider yang didukung katalog yang lebih luas.
Pencarian URI langsung
Nilai pemetaan Manifest adalah URI Recipe. Compiler me-resolve URI secara langsung terhadap lockfile dan katalog, lalu mengembalikan Recipe yang cocok. Compiler tidak mengiterasi deklarasi spec.implements untuk mencari Recipe yang “mengimplementasikan” suatu tipe komponen. Setiap entri Manifest mengikat tipe komponen yang ditulis pengembang ke URI Recipe tertentu; pilihannya eksplisit dan tidak ambigu dalam konten Manifest.
spec.implements adalah pemeriksaan konsistensi atas tabel pemetaan. Nilai spec.implements milik Recipe yang di-resolve HARUS cocok dengan kunci tipe komponen Manifest untuk entri pemetaan tersebut — atau dengan basis yang di-extends oleh kunci itu, pada kedalaman rantai berapa pun, karena Recipe yang ditulis untuk sebuah basis mengimplementasikan semua yang memperluasnya. Nilai yang tidak cocok dengan keduanya menghasilkan OPS_ERROR dengan diagnostik jelas yang menyebut entri Manifest, Recipe yang di-resolve, dan nilai spec.implements yang bertentangan. Pemeriksaan dijalankan sekali per entri pemetaan Manifest, atas Manifest yang telah dikomposisikan dan sebelum Recipe mana pun di-resolve — statis, deterministik, dan tidak menelusuri apa pun di luar rantai extends milik tipe yang dipetakan. Kunci components.type yang mencapai instans komponen pada versi yang tidak disebutnya dinilai sekali lagi untuk instans tersebut dengan cara yang sama, dengan tipe milik instans itu sendiri, pada versi yang digunakan build untuk mengompilasinya, menempati posisi kunci tersebut, sebagaimana dijelaskan di Pemetaan URI datar. Lihat ../vocabulary/inheritance-and-interface.md untuk apa yang dilakukan dan tidak dilakukan Recipe milik basis bagi sebuah spesialisasi.
Setiap perintah yang membaca dependensi Release menjalankannya, dan masing-masing memutuskan sendiri arti sebuah temuan: aggrega build dan aggrega pull berhenti, karena keduanya menghasilkan sesuatu yang akan Anda gunakan selanjutnya, sedangkan aggrega validate dan aggrega lint melaporkannya bersama temuan lainnya dan keluar dengan kode bukan nol, dan editor menerbitkannya sebagai salah satu diagnostik di antara yang lain. aggrega lint adalah pengecualian untuk penilaian sebuah instans: perintah ini menilai entri pemetaan, bukan instans yang dicapainya, sehingga tidak melaporkannya, sedangkan aggrega build, aggrega pull, dan aggrega validate --release melaporkannya. Lihat ../errors/fatal-halts.md untuk diagnostik tersebut dan cara memperbaikinya.
Pemeriksaan konsistensi adalah satu-satunya permukaan pemetaan yang membaca rantai extends. Pemilihan Recipe tetap persis pada kunci pemetaan: tipe komponen yang memperluas basis yang dipetakan tetap memerlukan entrinya sendiri di sini, dan tidak mendapatkan entri melalui pewarisan.
spec.implements juga menyarankan kandidat. Instans yang tipenya tidak memiliki pemetaan Manifest menghentikan build dengan OPS_ERROR yang mencantumkan recipe-recipe yang spec.implements-nya mampu mengimplementasikan tipe tersebut sebagai kandidat patokan; pelengkapan editor pada nilai pemetaan mengurutkan recipe yang cocok tersebut di urutan pertama. Kedua permukaan membaca spec.implements terhadap tipe yang diminta itu sendiri, sehingga recipe yang mengimplementasikan salah satu basis tipe tersebut tidak ditawarkan sebagai kandidat meskipun pemetaannya akan dinilai konsisten. Dengan demikian, spec.implements mendeklarasikan apa yang dapat diimplementasikan sebuah recipe dan menjadi masukan bagi pilihan manusia — dalam pemeriksaan konsistensi, diagnostik tanpa pemetaan, dan pelengkapan — tetapi tidak pernah me-resolve sebuah build. Pemetaan Manifest adalah pilihan deployment eksplisit pengguna, yang dipatok dalam lockfile demi reprodusibilitas; katalog tidak pernah memilih deployment atas nama pengguna.
Tiga bentuk untuk segmen versi URI
Sebuah URI Recipe dalam Manifest dapat membawa versi dalam salah satu dari tiga bentuk:
- Persis —
helm/postgres:1.2.0. Lockfile harus mem-pin tepat versi ini; pada resolusi lockfile pertama, resolver mem-pin versi ini; jika katalog atau registry tidak berisi versi ini pada saat resolusi, pemuatan workspace berhenti dengan galat. - Rentang —
helm/postgres:^1.2.0. Rentang semver dengan aturan MVS standar; pada resolusi lockfile pertama, resolver mem-pin versi tertinggi yang tersedia yang memenuhi rentang tersebut. - Tanpa versi —
helm/postgres. Tanpa sufiks:version; pada resolusi lockfile pertama, resolver mem-pin versi terbaru yang tersedia.
Build berikutnya menggunakan versi yang di-pin di lockfile, apa pun bentuk yang diketik pengguna. Resolusi ulang ke versi yang lebih baru memerlukan tindakan eksplisit dari pengguna — aggrega pull --upgrade --release <release> <uri> meresolusi ulang satu dependensi sambil mempertahankan setiap pin lainnya, atau aggrega pull --upgrade --release <release> meresolusi ulang semuanya — lockfile adalah sumber kebenaran untuk build; bentuk yang diketik pengguna adalah cara pengguna menyatakan batasan versi pada saat penulisan.
Referensi yang dikualifikasi kapabilitas
Identitas Recipe dalam katalog bercakupan kapabilitas: dua recipe dapat berbagi metadata.name dan versi yang sama sambil mendeklarasikan nilai spec.capability yang berbeda. Identitas registry adalah recipe/{capability}/{name}:{version}, yang diturunkan dari kind recipe, spec.capability-nya tanpa pin versi apa pun yang dibawanya, dan namanya; pohon katalog pustaka standar mencerminkan koordinat tersebut di recipe/{capability}/{name}/ berdasarkan konvensi. Nilai pemetaan Manifest menyebut recipe dengan salah satu dari dua tingkat presisi:
- Polos —
mariadb:1.0.0. Teresolusi bila tepat satu recipe dalam katalog membawa nama tersebut; bentuk yang paling umum dalam praktik. - Dikualifikasi kapabilitas —
compose/mariadb:1.0.0. Segmen sebelum/pertama menyebutspec.capabilitymilik recipe, tanpa pin versinya — pin yang ditulis ke dalam referensi ditolak (E0095). Diperlukan bila lebih dari satu recipe memiliki nama yang sama: referensi polos yang cocok dengan dua recipe bersifat ambigu dan berhenti secara jelas pada saat resolusi alih-alih diam-diam memilih salah satunya.
Sebuah URI Recipe tidak memiliki posisi lebih lanjut. Resolver memisahkan hanya pada / pertama, sehingga compose/mariadb menyebut kapabilitas compose dan recipe mariadb, dan referensi tiga segmen tidak cocok dengan recipe mana pun pada presisi mana pun.
Bentuk segmen versi di atas berlaku untuk kedua bentuk tersebut.
Entitas yang dipublikasikan di registry dalam pemetaan
Entitas yang dikonsumsi dari registry alih-alih dari katalog lokal direferensikan dengan identitas yang persis sama dengan yang digunakan entitas lokal: referensi tidak membawa host registry maupun segmen kind entitas. Resolver menyediakan keduanya — host dari registry default yang dikonfigurasi workspace, segmen kind dari letak referensi dalam skema — sesuai aturan Context-Aware Shorthand URIs di bawah. Bila baik direktori katalog lokal maupun cache tidak menyimpan salinan, aggrega pull — atau build yang dijalankan dengan --auto-pull — mengambil entitas dari lokasi turunan, menyimpannya di cache, dan mem-pin versi yang teresolusi serta digest kontennya di lockfile; build berikutnya mengonsumsi cache tanpa akses jaringan.
# Aggregate fragment — a registry-published Component as the type:components: db: type: core/datastore/mariadb:1.0.0Karena host dan segmen kind entitas diturunkan alih-alih
ditulis, menuliskan salah satunya ke dalam referensi tidak menunjuk
entitas yang dipublikasikan — hal itu menghasilkan identitas yang tidak dimiliki entri katalog mana pun. Referensi
Component atau Feature adalah metadata.name-nya apa adanya ditambah
:version opsional, baik entitas teresolusi dari katalog lokal,
dari cache, maupun dari registry. Workspace yang mengonsumsi registry
privat menyebut host tersebut dalam konfigurasinya sendiri alih-alih dalam setiap
referensi.
Pemeriksaan kelengkapan
Setelah semua pemetaan teresolusi, compiler memverifikasi bahwa setiap instans component dan attachment (Feature kredensial adalah attachment seperti yang lain) dalam Aggregate milik developer memiliki Recipe atau FeatureRecipe yang teresolusi. Entitas yang tidak terpetakan menyebabkan penghentian fatal dengan diagnostik eksplisit yang mencantumkan setiap entitas yang hilang dan menyarankan kunci components.type atau features.type mana yang perlu ditambahkan untuk menutup kekurangan tersebut.
Anchor YAML untuk manifest DRY
Untuk menghindari pembengkakan YAML pada kumpulan pemetaan yang besar, Manifest mendukung blok defs: opsional untuk anchor YAML standar (& dan *):
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: global-base-manifest version: 1.0.0defs: - &python_worker_recipe "helm/standard-python-worker:2.0.0"spec: mappings: components: type: core/python-worker: *python_worker_recipe core/postgres: helm/postgres:1.2.0Negosiasi Feature
Handshake kapabilitas menggunakan pemetaan URI datar yang sama:
- Developer melampirkan
core/data-maskingke sebuah component dalam Aggregate, dengan nama tersendiri di mapfeatures:milik component tersebut. - Compiler mencari
core/data-maskingdi mapfeatures.typemilik Manifest. - Jika pencarian teresolusi ke URI FeatureRecipe (misalnya
helm/data-masking-litellm:1.0.0), kapabilitas tersebut ada dan pipeline FeatureRecipe dieksekusi dalam urutan yang ditentukan. - Jika
features.typetidak berisi entri yang cocok, compiler menghentikan build dan mencantumkan Feature yang tidak terpetakan.
Manifest juga menerima blok features.annotations — permukaan penulisan paralel yang memungkinkan Release atau subsistem Aggregate melampirkan Features berdasarkan kunci anotasi alih-alih melalui deklarasi per component. Bentuk binding, partisi side-vs-pillar yang mengatur permukaan penulisan mana yang menggunakan jalur routing mana, disiplin bahwa attachment eksplisit yang menang, serta aturan default skema dijelaskan di bagian khusus Annotation-Driven Feature Bindings lebih lanjut di bawah.
Komposisi melalui extends
Sebuah Manifest dapat mendeklarasikan satu referensi extends: yang menamai Manifest dasar yang mappings-nya diwarisinya. Referensi tersebut bukan URI dan tidak pernah diselesaikan melalui katalog: sebuah Manifest berada di sisi deployment, ditulis di samping Release alih-alih dipublikasikan, sehingga nilainya adalah path relatif ke sebuah file Manifest — ./base-manifest.yaml — atau metadata.name polos dari sebuah Manifest yang berada di direktori Release itu sendiri. Path relatif harus mengarah ke Manifest di dalam workspace — atau, jika Release dinamai di luar workspace (di baris perintah, atau oleh konfigurasi workspace), di dalam direktori yang memuat Release tersebut, dan untuk Manifest yang Anda namai sendiri di baris perintah di luar workspace, di dalam direktori yang memuat Manifest tersebut: path yang naik keluar, atau yang dibawa keluar oleh tautan simbolis, ditolak sebelum file yang dinamainya dibaca (lihat errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Referensi ke file lain mengarah keluar dari direktori tempat ia harus tetap berada)”). Pemetaan turunan menimpa pemetaan dasar saat terjadi tabrakan kunci, sehingga mendukung pola overlay lingkungan (paritas staging/prod dengan perbedaan per lingkungan yang presisi) dan pola pengembangan lokal tanpa penulisan salinan penuh.
Semantik penggabungan. Ketika sebuah Manifest lokal memperluas Manifest dasar, compiler melakukan penggantian kunci dangkal per tingkat — kamus type dan name digabungkan secara independen, tidak digabungkan secara mendalam — yang menjamin pencarian kamus O(1) dan menjaga perilaku pewarisan tetap dapat diprediksi. Di dalam setiap tingkat, kunci turunan menimpa kunci induk.
Pola jembatan pengembangan lokal. Penggunaan umum extends adalah menukar FeatureRecipe kredensial untuk pembuatan prototipe lokal tanpa menyentuh Aggregate. Di produksi, Manifest dasar memetakan Feature kredensial core/aws-secrets-manager ke FeatureRecipe produksi di bawah tingkat features.type. Untuk pembuatan prototipe lokal, tim platform menyediakan local-manifest yang memperluas Manifest dasar dan secara presisi menimpa pemetaan Feature kredensial agar menggunakan host-env-injector — sebuah FeatureRecipe lokal yang mengirimkan kredensial ke dalam file Compose sebagai referensi variabel seperti ${SECRET_NAME}, yang disubstitusi oleh Docker Compose dari lingkungan shell atau file .env saat stack dijalankan. Developer mendapatkan alur kerja lokal standar, dan Aggregate tetap agnostik terhadap kapabilitas untuk produksi.
URI singkat yang sadar konteks
Compiler Aggrega menggunakan Inferensi Sadar Konteks saat meresolusi URI OCI di dalam Manifests. Jika seorang engineer menghilangkan Fully Qualified Domain Name (FQDN) dan tipe entitas arsitektural, compiler secara otomatis beralih ke registry default (dikonfigurasi di .aggrega-config.yaml) dan menyimpulkan tipe entitas berdasarkan lokasi string tersebut di dalam skema.
Aturan inferensi:
- Domain default: Setiap URI tanpa domain (misalnya,
python-worker-helm:1.0) diberi prefiksdefault_registryyang dikonfigurasi (default:hub.aggrega.ai/). - Ekspansi entitas kontekstual: Compiler menambahkan path entitas yang benar berdasarkan kamus skema yang ketat:
- String di bawah
Aggregate.spec.components[].typediekspansi menjadi/component/. - String di bawah
Aggregate.spec.aggregates[].typediekspansi menjadi/aggregate/. - String di bawah
Manifest.spec.mappings.components.typeatauManifest.spec.mappings.components.namediekspansi menjadi/recipe/. - String di bawah
Manifest.spec.mappings.features.typeatauManifest.spec.mappings.features.namediekspansi menjadi/featurerecipe/. Ini mencakup Features kredensial (berlabelfeature.aggrega.ai/kind: secret) — Features tersebut menggunakan path FeatureRecipe yang sama. - String yang ditetapkan pada
pipeline[].plugindiekspansi menjadi/plugin/.
- String di bawah
- Prioritas tiga tingkat: Sebelum menerapkan inferensi OCI, compiler mencari di direktori katalog workspace dan cache artefak (tingkat workspace dan cache) sebagaimana didefinisikan dalam Model Resolusi Entitas Tiga Tingkat. Inferensi OCI hanya berlaku ketika entitas mencapai tingkat registry. Kunci atau nilai pemetaan tidak pernah dibaca sebagai path file: Recipe atau FeatureRecipe yang ditulis secara lokal berada di direktori katalog —
catalog/di root workspace, atau salah satu yang dicantumkanworkspace.catalog_dirs— dan disebut melalui referensinya.
Bentuk singkat dalam praktik:
# Capability-qualified — required when two recipes share the name "postgres":"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:"core/postgres": "postgres:2.0"# Found in a local catalog directory or the cache; failing both, `aggrega pull`# (or a build run with --auto-pull) fetches it from the registry location derived# from the configured default registry and the Recipe kind.# A private registry is named in workspace configuration, not in the reference.Tanpa prefiks ops/. Nama Recipe tidak membawa prefiks ops/ — direktori tipe entitas recipe/ dalam taksonomi OCI sudah mengidentifikasi domainnya, dan Recipes dikirim di bawah recipe/{capability}/{name} tanpa prefiks tambahan. Manifests mereferensikan Recipes dengan {capability}/{name}, atau dengan nama polos untuk inferensi sadar konteks. Lihat architecture/13-catalog-and-registry.md §6 untuk taksonomi OCI selengkapnya.
Pengikatan Feature berbasis anotasi
Blok features.annotations pada Manifest mendeklarasikan pengikatan antara kunci anotasi dan tipe Feature beserta jalur perutean yang dilalui nilai anotasi untuk setiap pengikatan. Pengikatan ini adalah permukaan penulisan untuk memadatkan lampiran Feature per komponen yang berulang — pola di mana puluhan komponen dalam satu batas masing-masing membawa blok features: yang identik — menjadi deklarasi anotasi tunggal pada batas Release atau subsistem Aggregate.
Bentuk skema:
spec: mappings: features: type: core/rewrite-host: helm/rewrite-host-helm:1.0.0 core/db-pool: helm/db-pool-helm:1.0.0
annotations: feature.aggrega.ai/rewrite-host: feature: core/rewrite-host maps: infra: - upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool: feature: core/db-pool maps: values: - pool # Aggregate-side: routes annotation value into values.poolSebuah pengikatan membawa field feature yang menamai tipe Feature target dan blok maps yang mengelompokkan rute subkunci berjalur titik menurut pilar target. Field feature mereferensikan tipe Feature yang juga harus muncul di bagian saudara features.type (tempat pengikatan versi FeatureRecipe berada). Blok maps mendeklarasikan dua daftar berkunci pilar — maps.infra dan maps.values — yang masing-masing membawa string berjalur titik yang menunjuk ke properti spec.schema.<pillar>.<path> milik Feature target. Sebuah pengikatan harus mendeklarasikan setidaknya satu jalur di kedua daftar tersebut (JSON Schema menerapkan minProperties: 1 pada maps).
Polimorfisme Provider untuk kunci anotasi yang sama — misalnya, feature.aggrega.ai/rewrite-host terikat ke core/k8s-dns-resolver dalam deployment Kubernetes tetapi ke core/compose-bridge dalam deployment Compose lokal — dinyatakan dengan memilih tipe Feature yang berbeda di Manifests yang berbeda; setiap Manifest mengikat anotasi ke satu Feature, dan FeatureRecipe milik Feature yang dipilih membawa implementasi khusus provider.
Partisi sisi-vs-pilar. Invarian Aggregate-as-Authoring-Surface membatasi setiap sisi penulisan pada jalur perutean satu pilar. Anotasi sisi Aggregate hanya dirutekan melalui jalur maps.values; anotasi sisi Release hanya dirutekan melalui jalur maps.infra. Pengikatan yang mendeklarasikan jalur di kedua pilar mendukung komposisi lintas sisi: anotasi sisi Aggregate memicu subset pilar values; anotasi sisi Release terhadap kunci yang sama memicu subset pilar infra; kedua kontribusi tersusun menjadi satu lampiran Feature per pasangan (Component, Feature) dengan kedua pilar terisi. Ketidakcocokan sisi-vs-pilar — misalnya, anotasi sisi Aggregate terhadap pengikatan yang hanya mendeklarasikan maps.infra — menghentikan build dengan diagnostik yang jelas yang menyebutkan kunci anotasi, pilar yang dirutekan, sisi penulisan, dan lokasi sumber, yang dicatat di bawah domain dokumen tempat nilai anotasi ditulis.
Validasi target jalur. Saat pemuatan katalog, compiler memverifikasi bahwa setiap jalur bertitik yang dideklarasikan di bawah maps.infra dan maps.values sesuai dengan properti yang benar-benar dideklarasikan oleh spec.schema.<pillar> milik Feature target. Pengikatan yang merutekan ke jalur yang tidak tercantum dalam skema Feature menghentikan pemuatan katalog dengan OPS_ERROR yang jelas, yang menyebutkan pengikatan, Feature target, serta pilar dan jalur yang dilaluinya. Bentuk skema yang lolos dari penelusuran properti sederhana ($ref, patternProperties, komposisi oneOf / anyOf / allOf) mengakhiri pemeriksaan statis pada cabang tersebut dan membiarkan validasi skema hilir menangkap ketidakcocokan apa pun.
Bentuk nilai anotasi. Sebuah pengikatan menerima nilai anotasi dalam tiga bentuk. Skalar — satu nilai YAML (string, angka, boolean). Skalar yang dipasangkan dengan pengikatan yang mendeklarasikan tepat satu jalur di kedua pilar merutekan nilai ke jalur tunggal tersebut; skalar yang dipasangkan dengan pengikatan yang mendeklarasikan lebih dari satu jalur merupakan perutean ambigu dan menghentikan build dengan diagnostik yang jelas, yang dicatat di bawah domain dokumen tempat nilai anotasi ditulis. Terstruktur — map YAML yang setiap subkunci tingkat atasnya cocok dengan entri jalur bertitik di bawah maps.infra atau maps.values; setiap subkunci dirutekan ke pilar yang dideklarasikannya secara independen, dan partisi sisi-vs-pilar berlaku per subkunci. YAML null eksplisit — menolak pengikatan yang diwarisi pada cakupan kaskade (dengan null per subkunci di dalam nilai terstruktur menolak subkunci individual sementara subkunci saudaranya tetap berlaku). Untuk panduan penulisan kanonis tentang nilai terstruktur — penggabungan kaskade per subkunci, komposisi lintas sisi, validasi tipe per subkunci, disiplin default longgar untuk field skema tanpa type yang dideklarasikan — lihat providers/well-known-annotations.md §“Structured annotation values”.
Lampiran eksplisit menang saat terjadi tabrakan kunci. Ketika komponen Release atau komponen Aggregate membawa entri features: eksplisit sekaligus anotasi yang diekspansi ke kunci Feature yang sama, entri eksplisit dipertahankan dan ekspansi anotasi untuk kunci tersebut pada komponen itu tidak berpengaruh. Lampiran sintetis tidak pernah menimpa instans Feature yang dideklarasikan penulis. Dengan demikian, penulis dapat menggunakan ekspansi anotasi untuk sebagian besar komponen dan secara terarah menimpa komponen individual dengan menulis entri features: eksplisit dengan kunci yang sama — entri eksplisit membawa kustomisasi per komponen, sedangkan anotasi mengalir ke setiap komponen lain tanpa perubahan.
Eksplisit menang per daun pada komposisi lintas sisi. Ketika lampiran eksplisit dan kontribusi anotasi sama-sama mengisi instans Feature yang sama tetapi menulis ke daun yang berbeda, kedua kontribusi tetap berlaku dan Feature yang dihasilkan membawa kedua daun dengan provenans per daun yang mencatat sumber setiap daun. Ketika lampiran eksplisit dan kontribusi anotasi menargetkan daun yang sama dalam pilar yang sama, kontribusi eksplisit menang dan IR mencatat provenans anotasi yang ditekan sebagai penanda override pada daun tersebut. Pemuatan katalog menampilkan override ini saat build melalui peringatan lint bersifat anjuran yang menyebutkan kunci anotasi yang ditekan + sumbernya.
Default skema saat ekspansi. Lampiran Feature sintetis yang dihasilkan oleh ekspansi anotasi hanya membawa daun yang diisi nilai anotasi melalui jalur yang dideklarasikan pengikatan. Default skema yang dideklarasikan pada spec.schema milik Feature target tidak digabungkan ke dalam lampiran sintetis saat ekspansi. Materialisasi nilai default merupakan tanggung jawab lapisan rendering FeatureRecipe, yang diterapkan secara seragam pada lampiran eksplisit dan sintetis sehingga kedua jalur menghasilkan keluaran hilir yang sama untuk konfigurasi efektif yang sama.
Pemisahan namespace anotasi:
| Prefiks | Pemilik | Tujuan |
|---|---|---|
aggrega.ai/ | Hanya platform Aggrega | Anotasi native platform yang dibaca langsung oleh provider (misalnya, aggrega.ai/namespace). |
feature.aggrega.ai/ | Pustaka standar resmi | Pintasan anotasi Feature yang diikat dalam Manifest. |
{any-other-domain}/ | Perusahaan / komunitas | Pintasan anotasi Feature kustom. |
Reservasi prefiks aggrega.ai/
Binding features.annotations pada Manifest tidak dapat menggunakan prefiks aggrega.ai/ tanpa sub-prefiks — prefiks tersebut dicadangkan untuk anotasi bawaan platform yang dihasilkan oleh kompiler (label OTel/provenans, dan sebagainya). Sub-prefiks bercakupan (component.aggrega.ai/*, compliance.aggrega.ai/*, acme.aggrega.ai/* milik perusahaan) tetap tersedia untuk penulisan oleh pengguna. Lihat providers/well-known-annotations untuk kumpulan anotasi yang dicadangkan oleh platform.