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

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).

FieldJenisTujuanKonsumen
descriptionstringRingkasan entitas yang dapat dibaca manusiaKartu hover editor (aggrega serve); alat describe yang dipanggil asisten (aggrega mcp); anotasi yang dapat dicari pada artefak yang dipublikasikan (aggrega push); aggrega inspect
maintainersarray objekPemilik entitas (nama, email, url)catalog_metadata per node dalam IR, pada node Component
licensestringKepatuhan hukum (biasanya pengenal SPDX)catalog_metadata per node dalam IR, pada node Component
repositorystring (URL)Repositori Git tempat sumber beradacatalog_metadata per node dalam IR, pada node Component — tidak ada yang lain yang membacanya
homestring (URL)URL dokumentasi / wikicatalog_metadata per node dalam IR, pada node Component — tidak ada yang lain yang membacanya
keywordsarray stringTag penemuancatalog_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:

  • description adalah satu-satunya field dengan lebih dari satu pembaca. aggrega serve merendernya ke dalam kartu hover untuk Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, dan keempat jenis pustaka (SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) — tidak untuk Plugin atau Release. Alat describe yang disediakan aggrega mcp mengembalikannya untuk entitas jenis apa pun. aggrega push membubuhkannya ke artefak yang dipublikasikan sebagai anotasi yang dapat dicari. aggrega inspect mencetaknya di bawah header entitas untuk setiap jenis, dan tidak mencetak field permukaan publikasi lainnya.
  • repository, home, dan keywords divalidasi 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.

JenisLokasinyaDitulis olehTujuan
Deskripsi envelopemetadata.description pada setiap entitasPenerbit katalogRingkasan entitas secara keseluruhan, ditampilkan pada kartu hover editor dan dicapkan ke artefak yang diterbitkan
Deskripsi instansField description di samping deklarasi per instans (misalnya, featuresSchema.<slot>.description, usesSchema.<socket>.description)Penulis skemaDeskripsi per slot / per socket / per port, bagi penulis entitas konsumen yang membaca deklarasi tersebut
Deskripsi fieldAnotasi description: JSON Schema 2020-12 di dalam konten schema: / featuresSchema: / usesSchema: (bentuk ringkas atau YAML JSON Schema lengkap)Penulis skemaDokumentasi 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.description satu kali untuk entitas Component itu sendiri.
  • Tetapkan featuresSchema.admin_password.description satu kali untuk setiap slot kredensial yang dideklarasikan Component.
  • Tetapkan anotasi description: per field di dalam blok schema: — 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.schema dan dipotong hingga baris-baris awalnya, sehingga deskripsi yang berada lebih dalam di blok tersebut — atau yang berada di dalam featuresSchema: atau usesSchema: — tidak muncul di sana.
  • Deskripsi instans — dideklarasikan dan dibawa bersama entitas; tidak ada permukaan bawaan yang merendernya secara tersendiri. aggrega inspect mencantumkan 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):

EntitasBidang wajib tambahanAlasan
Componentmetadata.labels.component.aggrega.ai/typePersyaratan 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
Recipespec.capability, spec.implementsCapability menjadi gerbang bagi dispatch provider; implements menjadi gerbang bagi pengikatan Component
FeatureRecipespec.capability, spec.implementsSama seperti Recipe
Pluginmetadata.pluginType, spec.abiVersionTipe 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
Manifestspec.mappingsTingkatan pemetaan adalah satu-satunya tujuan Manifest
Releasespec.aggregate, spec.manifest (Release yang mendeklarasikan extends tidak menulis aggregate dan boleh menghilangkan manifest); metadata.environmentDua 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 — persyaratan metadata.labels.component.aggrega.ai/type pada Component serta deklarasi schema / usesSchema / featuresSchema.
  • entities/release.md — field metadata.environment pada 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 menjalankan aggrega 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.