Permukaan publikasi
Setiap YAML katalog Aggrega membawa sekumpulan field metadata yang seragam yang mendeskripsikan entitas untuk distribusi katalog: siapa yang memeliharanya, lisensi apa yang menyertainya, di mana sumbernya berada, dan kata kunci apa yang memunculkannya untuk penemuan. Bersama-sama, field ini membentuk permukaan publikasi — kosakata metadata yang diandalkan oleh penerbit katalog dan konsumen tooling, berbeda dari mekanisme metadata.labels / metadata.annotations di sisi konten yang didokumentasikan di labels-and-annotations.md.
Halaman ini mendokumentasikan field permukaan publikasi, inventaris field deskripsi di seluruh korpus (deskripsi tingkat envelope vs instans vs field), tujuan penggunaan field maintainer beserta konsumennya yang telah diverifikasi, serta asimetri field wajib per entitas (field mana yang diwajibkan setiap entitas saat ini dan di mana asimetri tersebut disengaja).
Field permukaan publikasi
Field berikut muncul pada setiap entitas Domain 2 (Component, Feature) dan Domain 3 (Recipe, FeatureRecipe, Plugin), serta pada Aggregate sebagai modul yang dapat digunakan ulang. Field ini juga muncul pada Manifest dan Release, dengan semantik yang lebih terbatas (atribusi workspace, bukan publikasi katalog).
| Field | Jenis | Tujuan | Konsumen |
|---|---|---|---|
description | string | Ringkasan entitas yang dapat dibaca manusia | Kartu hover editor (aggrega serve); alat describe yang dipanggil asisten (aggrega mcp); anotasi yang dapat dicari pada artefak yang dipublikasikan (aggrega push); aggrega inspect |
maintainers | array objek | Pemilik entitas (nama, email, url) | catalog_metadata per node dalam IR, pada node Component |
license | string | Kepatuhan hukum (biasanya pengenal SPDX) | catalog_metadata per node dalam IR, pada node Component |
repository | string (URL) | Repositori Git tempat sumber berada | catalog_metadata per node dalam IR, pada node Component — tidak ada yang lain yang membacanya |
home | string (URL) | URL dokumentasi / wiki | catalog_metadata per node dalam IR, pada node Component — tidak ada yang lain yang membacanya |
keywords | array string | Tag penemuan | catalog_metadata per node dalam IR, pada node Component — tidak ada indeks pencarian yang mengonsumsinya |
Keenam field bersifat opsional pada setiap entitas yang memuatnya. Penulis katalog yang menghilangkan seluruh rangkaian field ini tetap menghasilkan YAML yang valid — permukaan publikasi ditujukan untuk entitas yang akan didistribusikan melalui katalog; entitas untuk penggunaan internal dapat menghilangkannya tanpa konsekuensi.
Kolom Konsumen bersifat lengkap untuk apa yang dirilis saat ini, dan dua konsekuensinya layak dinyatakan secara gamblang, karena keduanya mengubah apa yang layak ditulis:
descriptionadalah satu-satunya field dengan lebih dari satu pembaca.aggrega servemerendernya ke dalam kartu hover untuk Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, dan keempat jenis pustaka (SchemaLibrary,MappingLibrary,WorkloadLibrary,ArtifactLibrary) — tidak untuk Plugin atau Release. Alatdescribeyang disediakanaggrega mcpmengembalikannya untuk entitas jenis apa pun.aggrega pushmembubuhkannya ke artefak yang dipublikasikan sebagai anotasi yang dapat dicari.aggrega inspectmencetaknya di bawah header entitas untuk setiap jenis, dan tidak mencetak field permukaan publikasi lainnya.repository,home, dankeywordsdivalidasi dan dibawa, dan tidak ada yang membacanya di luar IR. Tidak ada permukaan daftar, situs katalog, atau indeks pencarian yang mengonsumsinya. Menulisnya merekam provenans yang ikut bersama entitas dan dapat dibaca dari keluaran IR serta dari kebijakan tata kelola; hal itu tidak membuat entitas dapat ditemukan di mana pun.
Deprekasi bukan field permukaan publikasi. Sebuah entitas didepresiasi dengan merekam penanda terhadapnya di registri setelah publikasi — penanda bertanda tangan yang memuat tingkat keparahan (warning, error, atau retracted), alasan, dan pengganti, yang diverifikasi saat pull. Setiap permukaan yang membaca lockfile kemudian melaporkannya; build.halt_on_deprecated_severity hanya menentukan apakah penanda itu juga menghentikan build. Penanda tidak pernah ditulis pada YAML entitas itu sendiri, dan alasannya bersifat struktural: artefak yang dipublikasikan tidak dapat diubah, sehingga flag yang dibekukan di dalamnya saat publikasi tidak akan pernah dapat menyatakan keputusan yang diambil kemudian. Pemberitahuan deprekasi yang dicetak aggrega inspect untuk entitas katalog berasal dari penanda tersebut, untuk setiap jenis yang di-resolve berdasarkan nama.
Konsumsi IR — catalog_metadata per node
Compiler membawa field permukaan publikasi dari setiap Component ke dalam blok catalog_metadata milik node tersebut, yang terlihat dalam graf IR yang dikembalikan oleh sebuah eksekusi (aggrega inspect <release> --ir-graph). Blok ini memuat maintainers, license, repository, home, dan keywords — lima field yang dibawa IR; description tidak termasuk di antaranya. Tooling yang dibangun berdasarkan kontrak graf IR membaca metadata dari sana alih-alih membaca ulang YAML katalog.
Hanya node Component. Blok ini diisi dengan mencari tipe komponen node di katalog sebagai Component, sehingga permukaan publikasi milik Feature, Recipe, FeatureRecipe, atau Plugin tidak pernah mencapai IR — entitas tersebut memuat field-field itu, dan field-field itu tervalidasi, tetapi tidak ada node IR yang dihasilkan darinya.
catalog_metadata dihilangkan sepenuhnya dari JSON IR ketika setiap field permukaan publikasi pada Component sumber kosong atau bernilai nol: blok tersebut dihilangkan alih-alih dikeluarkan dengan nilai kosong. Dengan demikian, input yang sama menghasilkan keluaran ringkas yang sama, sehingga diff IR tetap stabil di setiap eksekusi.
Kebijakan tata kelola dapat membaca blok ini. Plugin yang dipasang di bawah plugins.governance dalam peran ir-verdict menerima seluruh graf IR, node demi node, termasuk catalog_metadata setiap node Component — sehingga kebijakan dapat menerima atau menolak build berdasarkan license, repository, home, keywords, atau maintainers milik sebuah node. Jangkauan itu khusus untuk soket tata kelola: plugin perenderan milik penyedia menerima proyeksi per node yang terbatas yang tidak mencakup catalog_metadata, sehingga plugin perenderan tidak dapat membaca field-field ini.
Tiga jenis deskripsi
Field description muncul secara seragam pada envelope, tetapi korpus juga memuat string bergaya deskripsi di dalam deklarasi skema (deskripsi per field) dan di dalam badan pilar (deskripsi per instans). Tiga jenis deskripsi yang berbeda hidup berdampingan; tabel di bawah ini membedakannya.
| Jenis | Lokasinya | Ditulis oleh | Tujuan |
|---|---|---|---|
| Deskripsi envelope | metadata.description pada setiap entitas | Penerbit katalog | Ringkasan entitas secara keseluruhan, ditampilkan pada kartu hover editor dan dicapkan ke artefak yang diterbitkan |
| Deskripsi instans | Field description di samping deklarasi per instans (misalnya, featuresSchema.<slot>.description, usesSchema.<socket>.description) | Penulis skema | Deskripsi per slot / per socket / per port, bagi penulis entitas konsumen yang membaca deklarasi tersebut |
| Deskripsi field | Anotasi description: JSON Schema 2020-12 di dalam konten schema: / featuresSchema: / usesSchema: (bentuk ringkas atau YAML JSON Schema lengkap) | Penulis skema | Dokumentasi per field yang menyertai skema |
Ketiga jenis ini sama-sama memakai kata “description”, tetapi berada pada tingkat struktural yang berbeda. Deskripsi envelope berlaku untuk entitas secara keseluruhan; deskripsi instans berlaku untuk deklarasi di dalam slot skema; deskripsi field berlaku untuk nilai tertentu di dalam skema bertipe. Penulis yang menulis sebuah Component:
- Tetapkan
metadata.descriptionsatu kali untuk entitas Component itu sendiri. - Tetapkan
featuresSchema.admin_password.descriptionsatu kali untuk setiap slot kredensial yang dideklarasikan Component. - Tetapkan anotasi
description:per field di dalam blokschema:— dalam bentuk ringkas (port: { type: integer, description: "..." }) atau dalam YAML JSON Schema lengkap — untuk mendokumentasikan setiap field bagi siapa pun yang membaca skema Component tersebut.
Ketiga jenis ini tidak saling menurun dan tidak saling bertabrakan, dan masing-masing mencapai permukaan yang berbeda — atau tidak mencapai permukaan mana pun:
- Deskripsi envelope — kartu hover editor, anotasi artefak terbitan yang dapat dicari, dan
aggrega inspect, sesuai kolom Konsumen di atas. - Deskripsi field — muncul apa adanya dalam cuplikan skema yang dirender oleh kartu hover sebuah Component atau Feature. Cuplikan tersebut hanya mencakup
spec.schemadan dipotong hingga baris-baris awalnya, sehingga deskripsi yang berada lebih dalam di blok tersebut — atau yang berada di dalamfeaturesSchema:atauusesSchema:— tidak muncul di sana. - Deskripsi instans — dideklarasikan dan dibawa bersama entitas; tidak ada permukaan bawaan yang merendernya secara tersendiri.
aggrega inspectmencantumkan socket dan slot fitur sebuah Component tanpa deskripsinya.
Maksud field maintainer
Field maintainers memuat array objek, masing-masing dengan name, email, dan url. Maksud dan konsumen yang terverifikasi:
Maksud (informasional + provenans IR). Field ini bersifat informasional untuk publikasi katalog: maksud arsitekturalnya adalah “siapa yang bertanggung jawab atas entitas katalog ini” — sinyal kepemilikan yang ikut serta dengan entitas. Tidak ada permukaan yang menyajikannya sebagai daftar kontak, dan tidak ada pemeriksaan bawaan yang membandingkannya dengan apa pun.
Konsumen terverifikasi (catalog_metadata per node). Compiler membawa metadata.maintainers dari setiap Component ke dalam catalog_metadata.maintainers milik node tersebut di IR, yang terlihat dalam graf yang dikembalikan oleh aggrega inspect <release> --ir-graph apabila Component sumber mendeklarasikannya. Itulah satu-satunya pembaca field ini. Kebijakan tata kelola yang dipasang di bawah plugins.governance dalam peran ir-verdict melihatnya di sana, sehingga aturan kepemilikan — setiap entitas menyebutkan setidaknya satu maintainer, domain seorang maintainer cocok dengan himpunan yang disetujui — dapat dinyatakan terhadap IR, bukan terhadap YAML katalog. Tidak ada aturan semacam itu yang disertakan; socket tersebut adalah tempat aturan itu dipasang.
Compiler tidak menegakkan atau memvalidasi isi maintainer di luar bentuk struktural JSON Schema (name wajib; email dan url opsional, keduanya string). Apakah maintainer yang tercantum benar-benar memiliki entitas tersebut, apakah email mereka dapat dihubungi, apakah sebuah commit repositori ditandatangani oleh salah satu dari mereka — semua ini adalah urusan tata kelola katalog, dan tidak ada pemeriksaan yang disertakan yang mengevaluasi satu pun di antaranya. Hal-hal tersebut menjadi bagian dari kebijakan tata kelola yang dipasang oleh operator, bukan bagian dari compiler.
Asimetri bidang wajib
Jenis-jenis entitas Aggrega memiliki himpunan bidang wajib yang sedikit berbeda dalam JSON Schema masing-masing. Sebagian besar asimetri disengaja dan mencerminkan peran entitas.
Bidang wajib per entitas (tidak termasuk apiVersion / kind / metadata.name / metadata.version, yang diwajibkan secara seragam oleh setiap entitas):
| Entitas | Bidang wajib tambahan | Alasan |
|---|---|---|
| Component | metadata.labels.component.aggrega.ai/type | Persyaratan label ini menopang pencocokan selektor: anotasi usesSchema x-aggrega-selector: menyaring Components target berdasarkan label ini; tanpa label tersebut, Component ditolak saat dimuat |
| Feature | — | Tidak ada persyaratan label yang dicadangkan; Features diidentifikasi berdasarkan nama + penerbit |
| Recipe | spec.capability, spec.implements | Capability menjadi gerbang bagi dispatch provider; implements menjadi gerbang bagi pengikatan Component |
| FeatureRecipe | spec.capability, spec.implements | Sama seperti Recipe |
| Plugin | metadata.pluginType, spec.abiVersion | Tipe soket yang diimplementasikan plugin (bagian dari blok pengalamatan, yang menyediakan segmen <pluginType> dari koordinat turunan plugin/<pluginType>/<name>) dan versi ABI yang ditargetkannya; lokasi .wasm diturunkan dari identitas tersebut alih-alih ditulis; plugin perender provider (pluginType: provider) juga membawa kontrak terjemahannya di bawah spec.provider |
| Aggregate | — | Aggregate yang tidak mendeklarasikan components, subsystems, maupun aggregates tetap dimuat dan di-build, dan tidak me-render apa pun |
| Manifest | spec.mappings | Tingkatan pemetaan adalah satu-satunya tujuan Manifest |
| Release | spec.aggregate, spec.manifest (Release yang mendeklarasikan extends tidak menulis aggregate dan boleh menghilangkan manifest); metadata.environment | Dua yang pertama menambatkan build ke Aggregate + Manifest tertentu; environment dicap pada keluaran yang di-render sebagai label aggrega.ai/environment |
Persyaratan label Component bersifat menopang
Label component.aggrega.ai/type adalah satu-satunya label yang diwajibkan Aggrega pada entitas mana pun. Persyaratan ini ada karena mekanisme usesSchema dari pustaka standar menyaring kandidat target melalui anotasi x-aggrega-selector: yang membawa string selektor seperti "component.aggrega.ai/type=database" — selektor memeriksa label target untuk menentukan apakah tipenya cocok dengan tipe yang diterima soket. Skema Component menegakkannya: Component yang tidak menyertakan label tersebut ditolak saat dimuat (E0215), dengan menyebutkan kunci yang hilang.
Dengan demikian, persyaratan ini bukan urusan permukaan publikasi (label tersebut bukan untuk penemuan katalog), melainkan urusan topologi: setiap Component membawanya, termasuk Components untuk penggunaan internal yang tidak ditujukan untuk distribusi katalog.
metadata.environment pada Release bersifat wajib
Skema Release mewajibkan metadata.environment, sebuah string yang dicap build pada keluaran yang di-render sebagai label aggrega.ai/environment.
Asimetri lainnya
Asimetri yang tersisa (bidang wajib Recipe vs Component, persyaratan mappings pada Manifest) mencerminkan peran masing-masing entitas. Penulis yang menginginkan kontrak bidang wajib yang seragam di semua jenis entitas tidak akan menemukannya; asimetri ini disengaja sesuai desain yang digerakkan oleh peran.
Rujukan silang
labels-and-annotations.md— mekanisme metadata sisi konten yang melengkapi permukaan publikasi.entities/component.md— persyaratanmetadata.labels.component.aggrega.ai/typepada Component serta deklarasischema/usesSchema/featuresSchema.entities/release.md— fieldmetadata.environmentpada Release dan persyaratannya.10-status.md— status envelope metadata.architecture/02-ecosystem-philosophy.md— Strict API Partitioning dan kerangka desain Enterprise Metadata Suite.architecture/13-catalog-and-registry.md§“Lockfile pinning and artifact immutability” + §“Catalog entity name-shape enforcement” — apa yang ditolak oleh aturan imutabilitas saat publikasi, dan di mana bentuk nama per jenis entitas diperiksa: plugin disiplin publikasi melaporkannya sebagai saran ketika penulis menjalankanaggrega lint, dan baik proses build maupun publikasi tidak memeriksanya.architecture/11-governance-and-compliance.md§“Inheritance and publishing discipline” — aturan tata kelola mana yang menjadi milik plugin disiplin publikasi, dan mana yang justru diselesaikan oleh pewarisan Component yang memperluas secara konstruksi.