Kontrak plugin Wasm
Pipeline kompilasi Aggrega mencakup titik soket yang ditetapkan tempat plugin WebAssembly (Wasm) memperluas perilaku compiler: empat peran soket tata kelola, di antaranya Mutation Gate pada konstruksi topologi dan Validation Gate pada analisis statis; pipeline plugin pascarender untuk langkah FeatureRecipe dan Recipe; soket rendering provider; soket parser; soket importer; dan soket linting di luar jalur utama. Halaman ini mendokumentasikan kontrak plugin Wasm publik: soket apa saja yang ada, apa yang dikonsumsi dan dihasilkan setiap soket, di mana setiap soket berada dalam pipeline kompilasi, dan sandbox tempat setiap plugin dieksekusi.
Halaman ini membahas soket — titik-titik pipeline beserta bentuk input/output-nya. Untuk plugin — entitas Plugin, klaim kapabilitas per ekspor, batas runtime, dan siklus hidup publish→pull→build — lihat panduan pengembang plugin Wasm.
Aggrega menyematkan runtime host Wasm — Extism di atas mesin Wazero — yang memuat dan mengeksekusi plugin di balik firewall kemurnian AOT: host memberikan nol kapabilitas ambien kepada guest — tanpa jaringan, tanpa sistem berkas, tanpa environment, stdio dibuang, serta jam dinding teramati yang dibekukan pada suatu instan yang invarian terhadap build — sehingga plugin tidak dapat merusak jaminan ahead-of-time compiler. Permukaan kapabilitas lengkapnya — aturan modul impor saat pemuatan, penolakan saat instansiasi, dan fungsi host terkurasi — dijelaskan dalam kontrak sandbox di bawah. Para penulis Plugin menargetkan host melalui PDK tiga bahasa (Go, Rust, TypeScript). aggrega lint men-dispatch socket linter — publishing-linter standar — melalui host. aggrega build men-dispatch peran build-time dari socket governance apabila workspace mengonfigurasinya: peran annotation-transform selama resolusi dan peran label-transform saat konstruksi topologi (keduanya membentuk output), ditambah verdict IR saat analisis statis dan verdict render atas artefak yang dirender. Masing-masing tidak melakukan apa pun bila tidak ada plugin yang terpasang pada peran tersebut, sehingga build tanpa konfigurasi governance tidak berubah. aggrega build juga men-dispatch pipeline: FeatureRecipe dan Recipe dalam pipeline plugin yang menutup proses rendering — setiap langkah yang dideklarasikan dijalankan melalui host terhadap himpunan dokumen yang dirender, menerapkan patch RFC 6902 milik langkah tersebut dan menghasilkan efek sampingnya. Lihat Status Bahasa → Fase pipeline kompilasi.
Kontrak sandbox
Setiap socket menjalankan plugin-nya melalui sandbox host yang sama. Sandbox ini memiliki dua lapisan independen — pemeriksaan struktural saat pemuatan dan penolakan kapabilitas saat instansiasi — dan bersama-sama keduanya menentukan apa yang dapat dijangkau sebuah plugin, apa yang tidak, dan apa yang menjadi tanggung jawabnya.
Aturan modul impor (saat pemuatan). Pemuat menelusuri bagian impor biner plugin dan hanya menerima impor fungsi di bawah tiga namespace modul: wasi_snapshot_preview1 (runtime WASI preview-1 yang ditautkan oleh runtime bahasa guest), extism:host/env (ABI runtime Extism — intrinsik memori dan IO milik PDK sendiri), dan extism:host/user (fungsi host terkurasi milik Aggrega). Guest boleh mengimpor nama fungsi apa pun di bawah modul yang diizinkan; impor di bawah modul lain menyebut permukaan yang tidak disediakan host, dan plugin ditolak saat pemuatan dengan diagnostik yang menyebut modul dan impor tersebut. Aturan ini sengaja tidak menyensor nama fungsi WASI satu per satu: runtime bahasa yang ditautkan secara statis mengimpor fungsi sistem berkas dan socket yang tidak pernah dipanggil oleh jalur kode aktifnya — tertarik secara transitif oleh dependensi — dan menyebut sebuah impor tidak memberikan apa pun. Penolakan kapabilitas saat instansiasi, bukan sensor impor, yang menjamin tidak adanya I/O.
Nol kapabilitas ambien (instansiasi). Host menginstansiasi guest dengan perilaku WASI yang nyata dan nol otoritas ambien:
- tanpa sistem berkas — tidak ada direktori yang dibuka sebelumnya, sehingga panggilan sistem berkas gagal di batas panggilan;
- tanpa socket jaringan;
- lingkungan yang kosong;
- stdio yang dibuang — apa pun yang ditulis guest ke stdout atau stderr tidak mencapai stream host;
- jam dinding teramati yang dibekukan, dipatok pada suatu instan yang invarian terhadap build, sehingga guest yang membaca waktu tidak dapat membocorkan waktu build ke dalam output-nya;
- jam monotonik yang nyata dan terus maju — runtime bahasa guest memerlukannya untuk bootstrap, dan waktu monotonik mengukur durasi yang berlalu, bukan instan jam dinding;
- entropi host yang nyata — entropi yang dipatok akan menstabilkan seed hash internal runtime bahasa dan menyamarkan nondeterminisme guest alih-alih membiarkannya muncul sebagai output yang berbeda;
- satu nama program sintetis sebagai argv.
Panggilan I/O yang benar-benar dilakukan guest — membuka berkas, menyambung ke socket — gagal di batas panggilan. Inilah model keamanan berbasis kapabilitas milik WASI sendiri: sandbox menolak kapabilitas alih-alih mengawasi kode.
Input hanya datang melalui payload dan fungsi host terkurasi. Plugin menerima semua yang dirender atau dievaluasinya dalam payload yang dibawa socket-nya — proyeksi graf dan node, nilai, dan konteks render. Encoding yang digunakan payload ditetapkan per socket dan disebutkan di bagian socket tersebut di bawah; setiap tipe payload yang dipublikasikan menyertakan titik masuk encode dan decode untuk encoding socket-nya, sehingga guest cukup memanggil satu fungsi alih-alih memilih parser. Untuk render provider bersumber, payload membawa daftar sumber alih-alih byte sumber: himpunan entri {path, is_dir} yang terurut di bawah akar sumber node, tanpa interpretasi tata letak provider oleh host. Guest menerapkan logika tata letaknya sendiri — memilih satu berkas compose, turun ke akar chart, mensyaratkan Chart.yaml, menyertakan modul secara rekursif — dan membaca kembali tepat bagian yang dipilihnya melalui callback host. Di luar payload, host mengikat himpunan fungsi host terkurasi dengan hak akses minimum, dan memberi plugin tepat fungsi-fungsi yang diimpor binernya:
aggrega_log— satu baris log pada tujuan log host.aggrega_emit_warning— peringatan terstruktur yang dimunculkan host setelah panggilan.aggrega_fetch_external_input— kanal pengambilan input eksternal (di bawah).aggrega_pack_source— callback pemilihan sumber: guest menyebut pilihan{file | dir | tree, path}di bawah akar sumber dan host membaca serta mengemas tepat pilihan itu di bawah sandbox yang me-resolve path di bawah akar dan menolak...aggrega_read_source_file— pembacaan konten satu berkas di bawah sandbox yang sama, untuk pemilihan sumber yang bergantung pada konten.aggrega_parse_source— callback konsumsi produsen: guest menyebut format sintaksis dan menyerahkan byte sumber, lalu host me-resolve parser untuk format itu, menjalankannya, dan mengembalikan pohon kanonis yang dihasilkannya. Inilah cara konsumen memperoleh output produsen melalui host alih-alih memanggil guest produsen sendiri, dan host membatasinya pada satu tingkat — produsen yang dijangkau dengan cara ini dan memanggilnya lagi akan ditolak — sehingga konsumen memanggilnya sekali per sumber dan dapat mengonsumsi banyak sumber secara berurutan.
Host menurunkan himpunan yang diimpor plugin dari biner .wasm-nya, memvalidasinya terhadap allowlist terkurasi, dan memeriksa silang dengan fungsi host yang dideklarasikan oleh describe() milik guest. aggrega plugin sync mencatat himpunan tersebut pada spec.runtime.hostFunctions milik entitas, dan publikasi menolak entitas yang catatannya berbeda dari binernya, sehingga permukaan host setiap plugin terlihat di katalog dan tidak dapat menyimpang dari binernya.
Kegagalan callback membawa kode yang dapat dicocokkan mesin, di bawah hostfunc_error_code. Callback host yang mengembalikan balasan — aggrega_fetch_external_input, aggrega_pack_source, aggrega_read_source_file, dan callback konsumsi produsen aggrega_parse_source — menyampaikan kegagalan secara in-band: amplop balasan membawa pesan yang dapat dibaca manusia dan, di sampingnya, kode opsional yang dapat dicocokkan mesin di bawah hostfunc_error_code, yang diambil dari kosakata tertutup. Pesan adalah prosa bebas untuk manusia; kode adalah identitas stabil yang menjadi dasar percabangan guest tanpa mengurai pesan. Saat berhasil, kode tidak ada; saat gagal, host mengisi keduanya. PDK memunculkan pasangan ini sebagai error bertipe yang teksnya adalah pesan dan yang field kodenya dicocokkan guest dengan konstanta kode yang diekspor ulang oleh bahasanya. Guest menoleransi kode yang tidak ada dan kode yang tidak dikenalinya dengan kembali ke pesan — sehingga pencocokan kode adalah penyempurnaan upaya terbaik di atas pesan yang selalu ada, tidak pernah menggantikannya. Himpunan nilai tertutupnya adalah skema kode error fungsi host.
🔴 Dua kosakata berbeda menamai kegagalan pada batas ini, dan kunci yang Anda baca menunjukkan kosakata mana yang sedang Anda pegang. Mencampuradukkan keduanya adalah satu-satunya kesalahan yang layak disorot di sini, karena nilai dari keduanya adalah string biasa dan baik host maupun guest tidak memeriksa dari himpunan mana nilai itu berasal.
hostfunc_error_code, pada balasan yang dikirim host ke guest. Nilainya adalah anggota katalog tertutup yang ditautkan di atas — daftar tetap yang jarang berubah, yang menamai cara-cara callback host dapat gagal. Karena himpunannya tertutup, guest dapat mencocokkan nilai dengan konstanta bernama yang diekspor ulang oleh kit-nya dan bercabang berdasarkan hasilnya.condition_codedi sampingcondition_short_code, pada output socket yang dikembalikan guest ke host. Keduanya adalah dua pengenal kondisi penghentian yang dimunculkan guest sendiri, dan keduanya berasal dari himpunan kondisi terbuka dan terus bertambah yang didaftarkan compiler, bukan dari katalog.condition_codeadalah kode deskriptif tempat kondisi didaftarkan;condition_short_codeadalah bentuk ringkasnya — hurufEdan empat digit — yang dikutip, dicari, dan ditempelkan pembaca ke dalam laporan. Host mencetak kode pendek di bagian kepala diagnostik dalam kurung siku yang direndernya, sehingga kondisi yang dimunculkan guest dapat dikutip persis seperti kondisi yang dimunculkan compiler. Host tidak menurunkan kedua nilai itu, tetapi memeriksanya: kode pendek yang tidak merujuk ke kondisi apa pun yang dideklarasikan compiler ini, atau merujuk ke kondisi yang nomornya telah dipensiunkan, menghentikan build alih-alih sampai ke pembaca sebagai pengenal yang tidak merujuk ke apa pun.
Kedua pengidentifikasi di sisi guest dilaporkan bersama-sama: guest yang menetapkan salah satunya tetapi tidak yang lain telah menamai kondisi yang tidak dapat diresolusi oleh host, dan host kemudian melaporkan kondisi kegagalan plugin generiknya sendiri sebagai gantinya, dengan pesan yang tetap membawa seluruh kegagalan. Selain itu, condition_code tidak pernah menjadi anggota katalog fungsi host, sehingga membandingkannya dengan konstanta yang diekspor ulang tidak pernah cocok — itulah sebabnya setiap kunci menamai kosakatanya sendiri, bukan kegagalan secara umum.
Slot setiap callback membawa encoding yang ditetapkan, dan setiap slot yang memuat dokumen payload memuatnya dalam bentuk biner. Setiap argumen yang diterima callback host adalah pointer ke memori guest, kecuali level numerik aggrega_log; callback yang mengembalikan balasan juga menjawab dengan pointer. Isi setiap slot tersebut ditetapkan per callback:
| Callback | Slot argumen | Slot balasan |
|---|---|---|
aggrega_log, aggrega_emit_warning | Teks UTF-8 — bukan dokumen payload | tidak ada balasan |
aggrega_fetch_external_input | URL UTF-8 polos — bukan dokumen payload | CBOR kanonis |
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_source | CBOR kanonis (RFC 8949 §4.2.1) | CBOR kanonis |
Tabel ini dibagi berdasarkan isi setiap slot, bukan berdasarkan identitas callback: slot yang memuat dokumen payload membawa CBOR kanonis, dan slot yang memuat string polos — baris log, field diagnostik, URL — membawa teks UTF-8. aggrega_fetch_external_input adalah satu-satunya yang kedua slotnya berbeda: argumennya adalah URL polos, dibaca sebagai teks UTF-8, dan balasannya adalah dokumen payload dalam CBOR kanonis.
Apa yang dilakukan guest pada slot pembawa payload, dan apa yang tidak boleh dilakukannya. 🔴 Slot yang memuat dokumen payload memuat rangkaian byte opak, bukan teks UTF-8 — jadi inilah bentuk yang dideklarasikan guest, bukan hanya byte yang ditaruhnya di sana. Guest yang mengalokasikan permintaan semacam itu sebagai string, atau membaca balasan semacam itu sebagai string, tidak dapat berinteroperasi: konversi teks ke arah mana pun merusak byte biner. Kegagalannya tampak jelas, bukan parsial — permintaan yang tidak dapat didekode host kembali sebagai amplop balasan yang membawa kode request_undecodable, dalam bentuk in-band yang sama dengan kegagalan callback lainnya, sehingga guest melaporkannya alih-alih melanjutkan dengan payload yang baru terbaca separuh. Tipe payload-nya adalah SourcePackRequest dan SourcePackResponse untuk aggrega_pack_source, SourceFileRequest dan SourceFileResponse untuk aggrega_read_source_file, ParseInput dan ParseSourceResponse untuk aggrega_parse_source, serta tipe balasan FetchExternalInputResponse saja untuk aggrega_fetch_external_input, yang URL-nya dialokasikan sebagai teks. Secara konkret, per kit:
- Go — bangun permintaan dengan
EncodeCBOR()dari tipe permintaan, alokasikan denganpdk.AllocateBytes(bukanpdk.AllocateString), dan baca balasan denganReadBytes()pada memori yang dirujuk oleh pointer balasan, ke dalamDecodeCBORdari tipe balasan. URL fetch adalah pengecualian di sisi permintaan, dialokasikan denganpdk.AllocateString; balasannya dibaca seperti yang lain. Deklarasi//go:wasmimporttetap berupa pointer, sehingga tidak ada bagian signature yang menunjukkan bentuknya — bentuk itu terletak pada alokasi dan pembacaan. - Rust — deklarasi
#[host_fn]menyatakan bentuknya secara langsung: masing-masing dari ketiga callback payload berbunyifn <callback>(request: Vec<u8>) -> Vec<u8>;, dan callback fetch berbunyifn aggrega_fetch_external_input(url: String) -> Vec<u8>;. Bangun permintaan denganencode_cbor()dari tipe permintaan dan baca balasan dengandecode_cbor(&raw)dari tipe balasan. - TypeScript — bangun permintaan dengan fungsi
encodeCBOR…dari tipe permintaan, alokasikan denganMemory.fromBuffer(bukanMemory.fromString), dan baca balasan denganreadBytes()ke dalam fungsidecodeCBOR…dari tipe balasan. URL fetch dialokasikan denganMemory.fromString; balasannya dibaca denganreadBytes()seperti yang lain. Seperti pada Go, entrideclare moduletetap berupa pointer.
Guest yang memanggil wrapper PDK tidak memerlukan semua itu. Wrapper — FetchExternalInput, PackSource, ReadSourceFile dan ParseSource, dalam ejaan masing-masing bahasa — melakukan alokasi dan encoding, dan tidak satu pun signature-nya menamai tipe wire, sehingga guest yang menjangkau callback ini melalui kit-nya tidak mengalokasikan maupun mendekode apa pun sendiri; guest yang mendeklarasikan dan memanggil fungsi host sendiri mengalokasikan dan membaca memorinya seperti dijelaskan di atas. Permintaan yang dialokasikan sebagai teks ditolak alih-alih dilayani separuh, dan balasan yang dibaca sebagai teks tidak dapat didekode, sehingga ketidakcocokan antara kedua sisi muncul dengan jelas, bukan diam-diam.
Dua properti yang layak diandalkan. Balasan membawa encoding yang sama, baik berhasil maupun gagal: guest membaca satu slot dan tidak dapat mengetahui sebelum mendekode mana dari keduanya yang dimuatnya, sehingga satu titik masuk dekode membaca keduanya, dan kode error serta pesan yang dijelaskan di atas tiba melaluinya. Selain itu, guest mengisi field bernilai byte dengan tipe field milik kit-nya sendiri — byte slice di Go, string base64 di Rust dan TypeScript — karena konversi ke rangkaian byte mentah yang dibawa encoding biner adalah tugas encoder yang dihasilkan, dilakukan saat keluar dan dibalik saat masuk. Hal itu mencakup byte sumber ParseInput, konten file yang dikembalikan aggrega_read_source_file, konten yang diambil aggrega_fetch_external_input, dan konten setiap file yang dikemas dalam balasan pack-source: byte tersebut melintasi batas sekali, bukan di-encode dua kali, dan tidak ada guest yang meng-base64 apa pun yang akan di-un-base64 oleh encoder. Field content pada balasan read-source-file dan fetch dihilangkan jika kosong, sehingga balasan untuk file kosong atau payload hasil fetch dengan panjang nol sama sekali tidak membawa konten; balasan seperti itu tetap merupakan keberhasilan, karena kegagalan selalu membawa pesan dan kodenya, dan wrapper setiap kit mengembalikan byte kosong untuknya. Tree yang dikembalikan aggrega_parse_source dikirim sebagai rangkaian byte yang memuat dokumen JSON-nya sendiri apa adanya; host tidak membaca maupun membentuk ulangnya. Parser membaca ParseInput yang sama, dalam encoding yang sama, pada export parse miliknya sendiri — lihat socket parser.
Kanonis berarti input yang identik menghasilkan byte yang identik di setiap sisi, yang memungkinkan payload dibandingkan lintas ketiga kit plugin alih-alih hanya di-round-trip, dan itulah sebabnya output build tetap identik secara byte. Tidak diperlukan pustaka CBOR di guest dan tidak ada yang mengurai byte secara manual: setiap tipe payload yang dipublikasikan menyertakan titik masuk encode dan decode yang diperlukan encoding slotnya.
Determinisme adalah tanggung jawab penulis plugin. Host mengonsumsi byte output guest apa adanya dan tidak menjalankan serializer apa pun atasnya, sehingga kontrak yang harus dipegang setiap plugin adalah: input yang identik menghasilkan byte output yang identik. Sandbox menghilangkan sumber nondeterminisme ambien — waktu dinding, environment, status filesystem — tetapi dengan sengaja tidak menutupi sisanya: guest yang meng-encode entropi atau waktu monotonik yang berlalu ke dalam outputnya menghasilkan byte yang jelas berbeda antar-run, alih-alih cacat yang tersembunyi secara stabil.
Kanal fetch input eksternal. aggrega_fetch_external_input adalah satu-satunya kanal resmi untuk konten jarak jauh, dan kanal ini dimediasi host, bukan akses jaringan guest: guest menamai URL, dan host menyajikan byte di bawah disiplin pin input eksternal. URL yang di-pin dalam lockfile Release disajikan dari penyimpanan lokal yang dialamatkan berdasarkan konten dan diverifikasi terhadap digest yang tercatat; URL yang tidak di-pin ditolak dengan diagnostik yang menamai URL tersebut dan langkah yang mem-pin-nya, karena render mengonsumsi closure yang dicatat lockfile-nya dan tidak pernah memperluasnya. Pin ditulis saat dependensi Release diresolusi, yang merupakan satu-satunya saat apa pun di-pin. Panduan pengembang memuat petunjuk penulisan dan disiplin pin secara lengkap.
Map yang mempertahankan urutannya
Beberapa map yang dibawa oleh sebuah payload ditandai sebagai mempertahankan urutan dalam skema socket-nya, karena urutan entrinya merupakan bagian dari apa yang dibawanya: node-node sebuah build, label-label sebuah node, lampiran pada sebuah node, input dan output sebuah langkah pipeline, ruang kunci yang dideklarasikan oleh sebuah provider. Tipe payload yang dipublikasikan menyimpan setiap map semacam itu dalam sebuah wadah yang mempertahankan entrinya sesuai urutan pengisiannya:
| Kit | Wadah |
|---|---|
| Go | aggrega.OrderedMap[V] — nama yang digunakan kit untuk abi.OrderedMap[V] dari paket ABI |
| Rust | OrderedMap<V> dari crate aggrega-abi, diekspor ulang oleh kit |
| TypeScript | Map<string, V> bawaan bahasa itu sendiri |
Wadah Go dan Rust menyediakan operasi sebuah map — mencari sebuah kunci, menetapkannya, menghapusnya, membaca kunci-kuncinya, menelusuri entri secara berurutan, menghitungnya. Menetapkan kunci yang sudah ada di dalam wadah akan mengganti nilainya dan mempertahankan posisinya; kunci baru ditempatkan setelah semua kunci yang sudah ada.
Urutan tetap bertahan pada kedua encoding. Pada encoding biner, map yang ditandai ditulis sebagai daftar entri yang berurutan — setiap entri berupa daftar dua elemen, kunci lalu nilai — sesuai urutan wadah, padahal encoding kanonis biasanya menulis map dengan kunci yang diurutkan. Pada encoding teks, map tersebut berupa objek JSON yang anggotanya ditulis sesuai urutan wadah. Decoder pada kedua encoding menolak map yang mengulang sebuah kunci, dengan menyebutkan kunci tersebut. Map yang tidak ditandai oleh skema tetap menggunakan bentuk map terurut pada encoding biner dan tipe map biasa milik bahasa yang bersangkutan pada tipe yang dipublikasikan.
Tiga konsekuensi bagi guest:
- Urutan adalah output. Karena map yang ditandai ditulis sesuai urutan pengisiannya, guest yang mengisinya dari sumber tanpa urutan tetap — misalnya dengan mengiterasi map bawaan Go — menulis byte yang berbeda di antara beberapa run dengan input yang identik. Isilah dalam urutan yang tetap.
- Urutan hanya bertahan selama map tetap berada di dalam wadahnya. Guest yang mengonversi payload menjadi tipe nilai generik milik bahasanya sendiri akan mendapatkan urutan tipe tersebut:
map[string]anydi Go tidak memiliki urutan, danserde_json::Valuedi Rust menyimpan kunci objek dalam keadaan terurut kecuali crate tersebut di-build dengan fiturpreserve_order. - Di TypeScript, baca dan tulis melalui fungsi yang dihasilkan. Tipe yang menyimpan map yang ditandai men-decode JSON-nya anggota demi anggota, sehingga kunci yang terbaca sebagai indeks array, seperti
"8080", tetap berada di posisinya, sedangkanJSON.parseakan memindahkannya ke awal objek; dan encoder-nya menulis setiapMapsebagai objek, sedangkanJSON.stringifymenulisMapsebagai{}.Object.keysdari sebuahMapjuga kosong: bacalah kunci sebuahMapdengankeys()miliknya sendiri.
Nilai yang ditandai sensitif oleh input
Plugin tidak pernah mengutip, dalam penolakan atau peringatan yang dikembalikannya, nilai yang ditandai sensitif oleh inputnya — melalui kuncinya, atau sebagai bagian dari payload yang ditandai secara keseluruhan. Penolakan adalah error yang dibawa oleh output; peringatan adalah Diagnostic yang dibawa oleh output, apa pun tingkat keparahannya, atau yang dimunculkan melalui aggrega_emit_warning. Host membawa teks tersebut tanpa perubahan di mana pun ia melaporkannya — baris perintah, language server dan daftar masalah editor, alat asisten — dan tidak membaca nilai apa pun darinya, sehingga plugin adalah satu-satunya pihak yang dapat menjauhkan nilai tersebut. Sebutkan kunci, pengaturan, atau posisinya sebagai gantinya: pembaca dapat menemukan nilainya dari situ.
Aturan ini mencakup teks yang ditulis oleh pustaka untuk plugin sama halnya dengan teks yang ditulis oleh plugin sendiri. Mesin templat melaporkan data yang sedang dievaluasinya, validator skema mengutip nilai yang gagal memenuhi pattern, parser mengutip token yang tidak dapat dibacanya. Jika kegagalan semacam itu terjadi pada nilai yang ditandai oleh input, laporkan tanpa nilai tersebut — misalnya, jalankan kembali langkah yang sama dengan setiap nilai yang ditandai diganti dengan placeholder, laporkan kegagalan dari eksekusi itu jika gagal di tempat yang sama, dan jika tidak, nyatakan bahwa teks kegagalan ditahan. Di bawah payload yang ditandai secara keseluruhan, setiap nilai dalam payload tersebut adalah nilai yang ditandai, sedangkan kuncinya — bentuk dokumen — tetap dapat dibaca.
Tempat input menandai kunci atau payload sebagai sensitif, dieja sebagaimana wire menamainya:
| Socket dan export | Tempat penandaan dibaca |
|---|---|
provider render_node dan validate_node_input (RenderNodeInput) | node.sensitive_rendered_keys: setiap kunci menamai entri node.values ketika nilai-nilai tersebut adalah milik Component itu sendiri, dengan kunci berupa leaf yang dideklarasikannya — valuesMapping milik Recipe menulis kunci yang tidak dinamai oleh deklarasi mana pun, sehingga tidak ada satu pun yang ditandai di sini — atau entri map attachments milik container workload yang membaca slot yang dideklarasikan sensitif. node.sensitive_values menandai node.values secara keseluruhan: nilainya true ketika valuesMapping — milik Recipe, atau milik FeatureRecipe dari sebuah attachment — menghasilkan nilai-nilai tersebut dan membaca nilai yang dideklarasikan sensitif oleh penulis. workload_projection.sensitive_workload menandai setiap nilai workload dengan cara yang sama ketika templat workload membaca salah satunya, dan setiap entri artifacts_projection.entries membawa sensitive_content untuk kontennya sendiri, termasuk pesan parser tentang konten tersebut. Setiap entri omits membawa sensitive ketika templat yang menghasilkan kind, name, atau namespace-nya membaca salah satunya, dan dalam hal itu setiap field entri tersebut adalah nilai yang ditandai. Setiap entri node.features membawa penandaan attachment-nya sendiri: sensitive_payload_leaves (leaf values.<path> dan infra.<path> yang dideklarasikan sensitif oleh Feature-nya), sensitive_inject (kunci pengiriman inject yang membaca kunci provides yang dideklarasikan sensitif oleh Feature-nya) dan sensitive (apakah attachment tersebut menangani materi yang dideklarasikan sensitif sama sekali). |
governance ir-verdict (PolicyInput) | graph: sensitive_payload_leaves setiap node, serta sensitive_payload_leaves, sensitive_inject dan sensitive setiap attachment. Setiap nilai yang dinamai oleh penandaan tersebut sudah tiba sebagai penanda tertahan {"aggrega_withheld": "declared"}, sehingga nilai itu sendiri tidak pernah sampai ke plugin. |
Tidak ada input socket lain, dan tidak ada input export provider lain, yang membawa penandaan. Penandaan kunci hanya menamai apa yang digabungkannya secara tepat ke sebuah deklarasi, sehingga ketiadaan kunci tidak pernah berarti suatu nilai aman untuk dikutip: artinya tidak ada deklarasi yang dapat digabungkan ke kunci tersebut. Penandaan payload dibaca dari referensi templat yang menghasilkan payload — referensi yang mencapai nilai yang dideklarasikan, templat yang meneruskan seluruh datanya, atau templat yang tidak dapat di-parse — dan tidak pernah dari nilai, sehingga ketiadaannya berarti templat tersebut tidak membaca nilai yang dideklarasikan sejauh yang ditunjukkan oleh referensinya, atau bahwa tidak ada templat yang menghasilkan payload tersebut; hal ini bukan pernyataan bahwa payload tidak membawa apa pun yang sensitif.
Penempatan socket Wasm dalam pipeline
Pipeline kompilasi mencadangkan titik-titik socket berikut. Label bentuk mengikuti taksonomi empat label dari halaman Status.
| Socket | Penempatan dalam pipeline | Status saat ini |
|---|---|---|
Socket tata kelola, peran annotation-transform | Resolusi (sebelum ekspansi anotasi) | tersedia — dijalankan ketika sebuah workspace memasang plugin annotation-transform; menyisipkan anotasi yang oleh ekspansi diubah menjadi lampiran Feature |
Socket tata kelola, peran label-transform | Konstruksi topologi (Topology Builder) | tersedia — dijalankan ketika sebuah workspace memasang plugin label-transform; memberi tag otomatis pada label node melalui JSON Patch |
Socket tata kelola, peran ir-verdict | Analisis statis (Static Analyzer, atas graf IR) | tersedia — dijalankan ketika sebuah workspace memasang plugin ir-verdict; verdict halt menghentikan build |
Socket tata kelola, peran render-verdict | Rendering (atas artefak yang telah di-render) | tersedia — dijalankan ketika sebuah workspace memasang plugin render-verdict; verdict halt menghentikan build |
Plugin pipeline: FeatureRecipe dan Recipe | Pipeline plugin (mutasi pasca-render) | tersedia — setiap langkah yang dideklarasikan dijalankan terhadap kumpulan dokumen yang telah di-render, menerapkan patch RFC 6902 dan menghasilkan efek samping |
| Plugin rendering Provider (helm, helm-chart, compose, terraform, cloudformation) | Rendering dasar (para provider) | tersedia — setiap provider me-render melalui guest Wasm-nya; rendering hanya melalui Wasm, tanpa fallback renderer di dalam host |
Plugin parser (parse:<format>) | Rendering, untuk kebijakan render-verdict; dan di luar jalur utama, untuk impor | tersedia — dipanggil untuk artefak dalam format yang tidak dibaca secara native oleh kebijakan render-verdict, untuk importer melalui aggrega_parse_source, dan untuk mengenali format impor yang tidak menyebutkannya |
Plugin importer (import:<format>) | Di luar jalur utama (aggrega import) | tersedia — di-dispatch oleh aggrega import, sesi editor, dan alat yang ditujukan untuk asisten |
Plugin linter (linter/publishing) | Di luar pipeline (aggrega lint) | tersedia — publishing-linter disertakan dan dijalankan melalui host via aggrega lint |
Subfase ekspansi Feature berbasis anotasi, bagian dari resolusi, adalah tahap pipeline Go native, bukan socket Wasm. Subfase ini memvalidasi nilai anotasi terhadap spec.schema milik Feature target dan menyisipkan lampiran Feature sintetis pada saat build IR. Lihat vocabulary/labels-and-annotations.md untuk enam permukaan yang memuat anotasi dan label, serta providers/well-known-annotations.md untuk bentuk binding dan panduan penulisannya.
Kontrak bentuk keluaran — yang ada saat ini
Socket tata kelola membawa permukaan kontrak bertipe pada masing-masing dari empat perannya, dan peran tersebut menentukan permukaan yang mana. Pembuat Plugin mengimplementasikan kode sisi guest yang menghasilkan bentuk yang didokumentasikan; host membacanya pada waktu build, sekali per plugin yang dikonfigurasi, ketika sebuah workspace melampirkan plugin pada peran tersebut. Subbagian di bawah ini mengikuti urutan pipeline mengirimkannya.
Peran annotation-transform — keluaran injeksi anotasi
Penempatan pipeline. Resolusi, setelah komponen di-resolve dan sebelum ekspansi Feature berbasis anotasi dijalankan.
Bentuk masukan (host → guest). Sebuah dokumen AnnotationTransformInput yang membawa:
targets— target injeksi: komponen yang telah di-resolve yang boleh dianotasi oleh guest — yang disebutkan langsung oleh sebuah boundary, dan setiap komponen yang dirutekan masuk oleh entri routing di bawahaggregates:milik boundary, baik entri itu menyebutkannya maupun tidak — masing-masing membawaboundary_path,component_name(untuk komponen yang dirutekan, id bertitiknya dalam graf build, sepertimetrics.query), danannotationsyang ditulis Release padanya, sehingga guest dapat memutuskan apa yang akan ditambahkan tanpa menggeser nilai yang ditulis penulis. Setiap nilai anotasi tiba sebagaimana ditulis — string, objek subkunci, ataunulljika komponen memilih keluar dari anotasi yang seharusnya diwarisinya — dan setiap kunci yang dibawa komponen hadir apa pun nilainya. Diurutkan secara deterministik oleh host.binding_keys— kunci anotasi yang binding-nya didaftarkan oleh Manifest, dalam urutan penulis. Injeksi di bawah kunci yang terdaftar selanjutnya diekspansi menjadi lampiran Feature, sehingga guest membaca daftar ini untuk menginjeksi kunci yang akan berlaku. Host tidak mengharuskan injeksi menyebut kunci yang terdaftar: anotasi terinjeksi yang tidak terdaftar berperilaku persis seperti anotasi tanpa binding yang ditulis penulis.sources— file definisi yang dideklarasikan lampiran di bawahwith.sources, masing-masing membawa path nama dasar dan kontennya, diurutkan berdasarkan path.settings— objek pengaturan bebas yang dideklarasikan lampiran di bawahwith.settings, diserahkan ke guest apa adanya.
settings dan sources adalah kanal with yang sama dan agnostik terhadap engine yang dibaca oleh setiap peran lainnya, dan keduanya tidak ada ketika lampiran tidak mendeklarasikannya. Karena keluaran peran ini membentuk build, pengaturan dan konten sumber lampiran dikunci dalam lockfile release saat pull dan direkonstruksi darinya saat build.
Bentuk keluaran (guest → host). Sebuah dokumen AnnotationTransformOutput yang membawa:
injections— anotasi yang akan ditambahkan, secara berurutan. Masing-masing menyebut koordinat target yang sudah ada (boundary_pathdancomponent_name) besertaannotation_keydanannotation_value-nya: string, atau objek subkunci, yang mengisi binding yang merutekan beberapa subkunci sekaligus.
Host hanya menerapkan penambahan anotasi, hanya pada koordinat yang disediakannya, masing-masing dengan nilai yang dapat ditulis penulis pada anotasi itu. Host membaca nilai yang diinjeksi persis seperti membaca nilai yang sama yang ditulis dalam Release — subkunci objek dalam urutan yang ditulis guest — sehingga ekspansi menanganinya sama seperti anotasi yang ditulis penulis. Injeksi yang menyebut koordinat yang tidak dibawa payload, atau membawa null, daftar, angka, boolean, atau objek tanpa subkunci, menghentikan build dengan pesan yang menyebut koordinat dan anotasinya, alih-alih dibuang atau diterapkan secara diam-diam; seluruh output diperiksa sebelum bagian mana pun diterapkan. Pembatasan itulah yang membatasi peran ini: operator yang memasang plugin di sini telah mendeklarasikan injeksi anotasi dan tidak lebih. Jika build kemudian menolak anotasi yang diinjeksi karena cara perutekannya, karena nilai subkunci yang tidak diterima skema Feature yang terikat, atau karena pilar yang tidak boleh digunakan anotasi di sisi Release, pesannya menyebut plugin yang menginjeksinya dan peran tempat plugin itu dipasang.
Encoding wire. Payload dan hasil peran ini dikirim sebagai CBOR kanonis (RFC 8949 §4.2.1), di kedua arah. Guest membaca dan menulisnya melalui titik masuk yang dibawa tipe payload — DecodeCBOR dan EncodeCBOR di Go, decode_cbor dan encode_cbor di Rust, decodeCBORAnnotationTransformInput dan encodeCBORAnnotationTransformOutput di TypeScript — sehingga tidak diperlukan pustaka CBOR dan tidak ada byte yang di-parse secara manual. Di Rust, export menerima dan mengembalikan Vec<u8>; di TypeScript, export membaca Host.inputBytes() dan menulis Host.outputBytes(...). annotations setiap target adalah map yang ditandai skema sebagai menjaga urutan, sehingga dikirim sebagai daftar entri berurutan dalam urutan yang dimiliki target, dan guest membacanya melalui container penjaga urutan milik kit-nya; setiap nilai dikirim sebagai byte JSON-nya, sebagaimana annotation_value sebuah injeksi pada arah sebaliknya. settings dikirim sebagai byte dokumen JSON-nya, yang di-parse guest sebagai JSON untuk melihat isinya. Jawaban yang bukan AnnotationTransformOutput dalam encoding ini — yang ditulis sebagai JSON, atau yang membawa field tingkat atas yang tidak dideklarasikan bentuknya — menghentikan build, dengan menyebut plugin dan export-nya, alih-alih dibaca sebagai daftar injeksi kosong. Ketika dipanggil langsung dengan aggrega plugin run-local --export transform_annotations, guest diberi payload JSON yang ditulis penulis yang telah dikonversi ke encoding ini, dan jawabannya dibaca sebagai bentuk output export tersebut lalu dicetak sebagai JSON — jawaban yang tidak berbentuk demikian ditolak dengan menyebut export-nya, sebagaimana build menolaknya.
Definisi tipe. Tipe wire annotation-transform — AnnotationTransformInput, AnnotationTransformOutput, AnnotationTarget, AnnotationInjection, AnnotationSource — dipublikasikan di ketiga paket ABI, dihasilkan dari satu codec sehingga ketiganya tetap selaras.
Peran label-transform — keluaran JSONPatch
Penempatan pipeline. Konstruksi topologi, setelah graf diratakan dan sebelum graf IR dibangun, sehingga selektor soket dan Feature yang dievaluasi analyzer membaca label yang ditinggalkan peran ini.
Bentuk masukan (host → guest). Dokumen MutatorInput yang memuat:
compilation_context— identitas rilis (release_name,environment).graph— proyeksiMutatorGraphdari node topologi: Component setiap node, versi yang di-resolve, label, danvaluesyang dideklarasikan instansnya.settings— objek pengaturan bebas yang dideklarasikan lampiran di bawahwith.settings, diserahkan ke guest apa adanya.sources— berkas definisi yang dideklarasikan oleh lampiran di bawahwith.sources, masing-masing memuat path nama dasarnya dan kontennya, sehingga mutator dapat digerakkan oleh berkas aturan atau pemetaan yang tersimpan di repositori alih-alih pengaturan inline.
Graf tersebut adalah proyeksi, bukan graf IR: setiap node membawa set label yang telah di-resolve dan nilai yang dideklarasikan instansnya dalam Aggregate, sementara edge dan payload feature tetap berada di dalam compiler. Nilai-nilai itu milik Aggregate sendiri, dengan template yang sudah dievaluasi terhadap parameternya, sehingga nilai yang diangkat ke parameter tiba sebagai nilai yang disediakan Release; nilai default yang dideklarasikan skema Component, dan apa pun yang dikontribusikan Recipe atau Feature, tidak termasuk di dalamnya, dan node yang tidak mendeklarasikan nilai tidak membawa kunci values. Nilai yang dideklarasikan sensitif oleh Component node ditahan persis seperti verdict atas graf menahannya — terbaca sebagai {"aggrega_withheld": "declared"} — sementara setiap nilai saudara yang tidak dijangkau deklarasi apa pun tiba sebagaimana ditulis. Itulah yang memungkinkan konfigurasi yang dideklarasikan developer menentukan sebuah label — misalnya, database yang nilainya mengaktifkan ekstensi vektor dipromosikan ke datastore.aggrega.ai/engine: vector. settings dan sources adalah kanal with yang sama dan agnostik terhadap mesin yang dibaca oleh peran verdict; host meneruskannya dan tidak pernah menafsirkan kontennya. Karena keluaran mutator membentuk build, pengaturan dan konten sumber lampiran dipatok dalam lockfile rilis saat pull dan direkonstruksi darinya saat build, sehingga masukan mutator tidak berubah oleh perubahan pada salah satunya setelah pull hingga pull berikutnya.
Bentuk keluaran (guest → host). Dokumen MutatorOutput yang memuat:
patches— array dokumen JSONPatch opak (RFC 6902) yang diterapkan host hanya pada label node; nilai yang dibawa masukan bersifat hanya-baca.
Setiap patch menunjuk label node tertentu melalui JSON Pointer (RFC 6901); host menerapkan patch sesuai urutan array dan memasukkan kembali set label yang telah dimutasi ke dalam graf IR. Tugas peran label-transform adalah penandaan otomatis perusahaan — menambahkan label kepatuhan / observabilitas / atribusi biaya yang dideklarasikan oleh kebijakan perusahaan tanpa mengubah konten katalog. Permukaan label adalah satu-satunya target yang diizinkan untuk peran ini: patch yang menyentuh field node selain labelnya, menambah atau menghapus node, atau menetapkan nilai label non-string akan menghentikan build alih-alih diserap secara diam-diam. RFC 6901 adalah dasar tata bahasa path untuk setiap permukaan path dokumen di Aggrega — kontrak plugin Wasm di sini, ditambah ekspor .locals *_path, ditambah field skema *Path di bagian lain korpus. Lihat 02-naming-conventions.md “Document-path naming-suffix discipline” untuk deklarasi dasar kanonis dan disiplin sufiks *Path / *_path yang membedakan kedua sisi penulisan.
Encoding wire. Payload dan hasil peran ini berpindah sebagai CBOR kanonis (RFC 8949 §4.2.1), di kedua arah. Kanonis berarti masukan yang identik menghasilkan byte yang identik di setiap sisi, yang memungkinkan payload dibandingkan di antara ketiga kit plugin alih-alih hanya diuji bolak-balik, dan itulah sebabnya keluaran build tetap identik per byte. Guest membaca dan menulisnya melalui titik masuk yang sudah dimiliki tipe payload kitnya — DecodeCBOR dan EncodeCBOR di Go, decode_cbor dan encode_cbor di Rust, decodeCBORMutatorInput dan encodeCBORMutatorOutput di TypeScript — sehingga tidak diperlukan pustaka CBOR dan tidak ada yang mengurai byte secara manual. Di Rust, ekspor menerima dan mengembalikan Vec<u8>; di TypeScript, ekspor membaca Host.inputBytes() dan menulis Host.outputBytes(...). nodes milik graf, labels milik setiap node, dan values milik setiap node adalah map yang ditandai skema sebagai mempertahankan urutan, sehingga ketiganya berpindah sebagai daftar entri berurutan — node dalam urutan yang dipegang build, yaitu urutan penulis, label setiap node dalam urutan yang dibawa node tersebut, dan nilai setiap node dalam urutan yang ditulis Aggregate — dan guest membaca ketiganya melalui kontainer penjaga urutan milik kitnya. Setiap nilai berpindah sebagai byte dokumen JSON-nya: kit Go dan Rust menyerahkannya ke guest sebagai JSON tersebut, untuk diurai sejauh yang diperlukan aturan, dan kit TypeScript sebagai nilai yang sudah diurai.
Ada dua hal yang tidak diubah oleh ini. Array patches tetap JSON: socket membawa setiap dokumen patch apa adanya sebagai konten opak dan tidak ada sisi yang membaca isinya, sehingga bentuk dokumen patch itu sendiri tidak bergantung pada encoding yang dibawa socket-nya. Dan settings serta sources tetap diteruskan apa adanya — settings tiba sebagai byte yang ditulis oleh lampiran, yang diurai guest sebagai JSON jika perlu melihat isinya.
Setiap peran tata kelola lainnya membawa encoding yang sama — peran annotation-transform dan kedua peran verdict masing-masing menyatakannya di bagiannya sendiri — sehingga guest yang melayani lebih dari satu peran menggunakan CBOR kanonis di setiap peran yang dilayaninya, dengan membaca setiap payload melalui titik masuk decode milik tipenya sendiri.
Definisi tipe. Tipe wire mutator — MutatorInput, MutatorOutput, CompilationContext, MutatorGraph, MutatorNode — diterbitkan di ketiga paket ABI (github.com/aggrega-ai/aggrega-abi/go, crate aggrega-abi, dan @aggrega-ai/aggrega-abi), dihasilkan dari satu codec sehingga ketiganya tetap selaras. Host menyusun masukan dan menerapkan patch yang dikembalikan guest.
Peran verdict — keluaran berupa array verdict
Guest kebijakan memeriksa sebuah build dan mengembalikan daftar verdict; host bertindak berdasarkan severity setiap verdict dan tidak pernah menafsirkan kebijakan itu sendiri. Pembahasan lengkapnya — keempat peran, severity, kanal masukan yang disediakan operator, cara menulis kebijakan untuk salah satu dari dua mesin yang disertakan di dalam compiler, cara membungkus mesin kebijakan asing, guest referensi, dan cara operator melampirkan kebijakan — ada di halaman socket tata kelola. Bagian ini mencatat penempatan dalam pipeline dan bentuk wire bertipe.
Penempatan dalam pipeline. Sebuah kebijakan dilampirkan pada tepat satu peran verdict, yang menentukan di mana kebijakan itu dievaluasi:
ir-verdict— dievaluasi saat analisis statis, sebelum rendering dasar. Analyzer menyusun payload pada setiap build.render-verdict— dievaluasi setelah render, atas artefak yang dihasilkan.
Ketika sebuah workspace melampirkan plugin peran verdict, pipeline melakukan marshal payload peran tersebut ke plugin dan membaca kembali verdict-nya.
Bentuk masukan (host → guest). Peran menentukan payload:
PolicyInputuntukir-verdictmembawagraph— graf IR lengkap yang agnostik terhadap kapabilitas (bentuk yang sama dengan yang dihasilkan Topology Builder), dengan setiap node, edge, dan detail lampiran yang dipegang compiler, kecuali bahwa nilai yang dideklarasikan sensitif oleh penulis tiba dalam keadaan ditahan (lihat Nilai yang ditandai sensitif oleh masukan) — sertaprecalculated_paths, jalur routing yang dienumerasi analyzer di sampingnya, sehingga kebijakan dapat menalar keterjangkauan tanpa menelusuri ulang graf. Graf tersebut adalah graf IR berversi, bersumber tunggal dari skemair-v1beta1; bentuk IR tidak rahasia (graf yang sama dengan yang dihasilkanaggrega inspect) dan rahasia di dalamnya berupa pointer, tidak pernah teks biasa.RenderPolicyInputuntukrender-verdictmembawaartifacts— file keluaran hasil render yang diurutkan berdasarkan path, sehingga wire identik byte demi byte di setiap eksekusi dengan masukan identik. Setiap entri membawapathkeluaran artefak dancontenthasil rendernya; entri juga membawaformattempat artefak dirender, bila provider penghasilnya mendeklarasikannya, sertatree, tampilan kanonis hasil parsing dari format yang tidak dibaca guest secara native, yang di-parse host melalui parser yang di-resolve dan diteruskan secara opak. Keduanya tidak ada bila tidak berlaku — format yang dibaca guest secara native (JSON, YAML) dibiarkan tanpa parsing agar guest membacanya daricontent.
Kedua peran juga membawa sources milik lampiran (file definisi kebijakan yang dibaca host saat build dan diserahkan ke guest apa adanya, dengan path berupa nama dasar dan konten opak) serta settings (objek bebas yang diteruskan tanpa diubah). Keduanya tidak ada bila lampiran tidak mendeklarasikannya.
Bentuk keluaran (guest → host). Sebuah dokumen PolicyOutput yang membawa:
results— array entriDiagnostic, masing-masing denganseverity(halt,warn, atauinfo) dan stringmessage. Sebuah verdict juga dapat menetapkancode,rule_id,classification,source_ref,location, dansuggestpada entri yang sama; host menambahkan mana pun dari itu yang dibawa verdict ke verdict yang dirender, pada setiap rute severity.
Hanya verdict yang terpicu yang muncul; evaluasi yang mengizinkan mengembalikan array kosong. Host menelusuri verdict dan memetakan setiap severity ke sebuah tindakan: halt menghentikan build (menampilkan setiap pesan halt), warn menandai verdict dan membiarkan build berlanjut, info mencatatnya tanpa memengaruhi hasil. Sebuah halt menghentikan build melalui gerbang yang sama dengan yang digunakan pelanggaran selector atau appliesTo.
Encoding wire. Payload kedua peran, dan PolicyOutput yang dikembalikan guest pada salah satunya, dikirim sebagai CBOR kanonis (RFC 8949 §4.2.1). Guest membaca dan menulisnya melalui titik masuk yang dibawa tipe payload — DecodeCBOR dan EncodeCBOR di Go, decode_cbor dan encode_cbor di Rust, decodeCBORPolicyInput, decodeCBORRenderPolicyInput, dan encodeCBORPolicyOutput di TypeScript — sehingga tidak diperlukan pustaka CBOR dan tidak ada yang mem-parse byte secara manual. Di Rust setiap export menerima dan mengembalikan Vec<u8>; di TypeScript export membaca Host.inputBytes() dan menulis Host.outputBytes(...). Map graf yang mempertahankan urutan, di antaranya nodes dan labels setiap node, dikirim sebagai daftar entri berurutan sesuai urutan yang dipegang build, dan guest membacanya melalui kontainer penjaga urutan milik kit-nya; urutan yang ditemui kebijakan pada masing-masing mesin kebijakan dijelaskan di halaman socket tata kelola. settings, dan tree hasil parsing sebuah artefak, dikirim sebagai byte dokumen JSON-nya, yang di-parse guest sebagai JSON untuk melihat isinya. Jawaban yang bukan PolicyOutput dalam encoding ini — yang ditulis sebagai JSON, atau yang membawa field tingkat atas yang tidak dideklarasikan bentuknya — menghentikan build, dengan menyebut plugin dan export-nya, alih-alih dibaca sebagai daftar verdict kosong. Bila dipanggil langsung dengan aggrega plugin run-local --export verdict_ir atau --export verdict_render, guest menerima payload JSON yang ditulis penulis dan dikonversi ke encoding ini, dan jawabannya dibaca sebagai bentuk output export tersebut lalu dicetak sebagai JSON — jawaban yang tidak berbentuk demikian ditolak dengan menyebut export-nya, sebagaimana build menolaknya.
Definisi tipe. Tipe wire kebijakan dipublikasikan dalam tiga paket ABI yang sama: PolicyInput (peran ir-verdict), RenderPolicyInput (peran render-verdict), PolicySource yang digunakan bersama, dan PolicyOutput, yang entri results-nya berupa nilai Diagnostic. Severity sebuah diagnostik adalah salah satu dari tiga nilai yang digunakan bersama oleh setiap socket — halt, warn, atau info — dan ketiganya dipublikasikan sebagai konstanta di samping tipe wire dalam masing-masing dari ketiga paket, sehingga guest melapor dari himpunan tertutup yang sama dengan yang digunakan host untuk routing. Guest yang mengembalikan nilai lain menghentikan build, dengan pesan yang menyebut plugin dan nilai yang dikembalikannya: severity yang tidak dapat di-routing adalah cacat plugin yang dilaporkan host, bukan diagnostik yang dibuangnya.
Kontrak bentuk keluaran — pipeline FeatureRecipe dan soket provider
Soket di bawah ini membawa permukaan kontrak bertipe yang di-dispatch oleh kompiler saat build. Langkah pipeline: FeatureRecipe dan Recipe berjalan dalam pipeline plugin atas himpunan dokumen yang telah dirender; soket perenderan provider berjalan pada perenderan dasar; publishing-linter berjalan di luar alur.
Patch RFC 6902 (pipeline plugin)
Langkah pipeline: FeatureRecipe dan Recipe yang berjalan dalam pipeline plugin menghasilkan operasi JSON Patch RFC 6902 terhadap himpunan dokumen yang telah dirender. Host menyerahkan himpunan dokumen berkunci secara utuh kepada setiap langkah; langkah tersebut memilih dokumen yang ditargetkannya berdasarkan konten dan mengembalikan patch yang dialamatkan dengan kunci, yang diterapkan oleh mesin penerap ke dokumen yang dialamatkan — biasanya menambahkan kontainer sidecar, memasang volume secret, atau menulis ulang variabel env. Sebuah langkah juga mengembalikan side_effects (di bawah), diagnostics — setiap entri dalam bentuk Diagnostic bersama yang sama yang digunakan setiap soket untuk melaporkan masalah — dan outputs (di bawah). Dijelaskan di examples/04-secrets.md.
Status saat ini: tersedia. Setiap langkah yang dideklarasikan berjalan selama aggrega build.
Pengodean wire. Masukan sebuah langkah (FRPStepInput) dan jawabannya (FRPStepOutput) dikirim sebagai CBOR kanonis (RFC 8949 §4.2.1), dalam kedua arah. Guest mendekode masukannya dan mengodekan jawabannya melalui titik masuk yang dibawa oleh tipe payload — DecodeCBOR dan EncodeCBOR di Go, decode_cbor dan encode_cbor di Rust (pada tipe yang dipublikasikan crate aggrega-abi), decodeCBORFRPStepInput dan encodeCBORFRPStepOutput di TypeScript — dengan membaca dan menulis byte (Vec<u8> di Rust, Host.inputBytes() dan Host.outputBytes(...) di TypeScript). Tidak diperlukan pustaka CBOR dan tidak ada yang mengurai byte secara manual. Masukan with dari langkah (step_input), outputs yang dikembalikannya, serta himpunan dokumen own dan host adalah map yang ditandai skema sebagai mempertahankan urutan, sehingga dikirim sebagai daftar entri berurutan dalam urutan yang dipegang pipeline, dan guest membaca serta menulisnya melalui kontainer penjaga urutan milik kit-nya — itulah yang memungkinkan keluaran sebuah langkah mencapai .steps.<id>.outputs dalam urutan yang dikembalikan langkah tersebut. tree setiap unit, setiap nilai step_input dan outputs, value sebuah patch, crd sebuah efek samping, dan context render dikirim sebagai byte dari dokumen JSON-nya, yang diurai guest sebagai JSON untuk melihat isinya; bytes sebuah unit dikirim sebagai rangkaian byte mentah yang diisikan oleh dekoder yang dihasilkan ke tipe field milik kit — slice byte di Go, string base64 di Rust dan TypeScript. Setiap diagnostik dikirim dalam bentuk Diagnostic bersama. Jawaban yang bukan FRPStepOutput dalam pengodean ini — yang ditulis sebagai JSON, atau yang membawa field tingkat atas yang tidak dideklarasikan bentuknya — menggagalkan langkah tersebut dengan menyebut fungsi yang dijalankannya, yang menghentikan build kecuali langkah itu optional. Jika dipanggil langsung dengan aggrega plugin run-local --export step, sebuah langkah menerima payload JSON yang ditulis yang dikonversi ke pengodean ini, dan jawabannya dibaca sebagai bentuk output export tersebut lalu dicetak sebagai JSON — jawaban yang tidak berbentuk demikian ditolak dengan menyebut export-nya, sebagaimana build menolaknya.
Efek samping — menghasilkan sumber daya (plugin kredensial dalam pipeline plugin)
Pipeline FeatureRecipe kredensial (Prinsip Plugin Dua Bagian: Fetcher + Injector) menghasilkan sumber daya lengkap di samping patch melalui side_effects sebuah langkah, masing-masing mendeklarasikan salah satu dari dua jenis yang didefinisikan kontrak: emit_crd, dokumen custom resource seperti CRD ExternalSecret atau VaultSecret yang diambil klaster saat runtime, atau emit_file, file yang ditulis. Langkah yang mengembalikan jenis lain apa pun menghentikan build, dengan menyebut node, indeks efek samping, dan jenis yang dideklarasikannya. Langkah Fetcher menghasilkan sumber daya lengkap; langkah Injector mengembalikan patch yang memasang Kubernetes Secret yang dihasilkan. Dijelaskan di examples/04-secrets.md.
Status saat ini: tersedia.
Keluaran langkah (map outputs langkah pipeline:)
Langkah pipeline plugin memublikasikan keluaran bernama yang dikonsumsi langkah-langkah berikutnya melalui {{ .steps.<id>.outputs.<key> }}. Bentuk keluaran ditentukan oleh provider per plugin; keluaran langkah dibatasi pada pipeline yang sama dan hanya terlihat oleh langkah-langkah berikutnya dalam urutan deklarasi. Didokumentasikan di templates/expansion-matrix.md baris 10.
Status saat ini: tersedia.
Provider rendering — soket yang digerakkan oleh guest
Provider adalah guest Wasm. Perenderan hanya melalui Wasm: nama capability: sebuah Recipe diresolusikan ke Plugin perenderan provider (pluginType: provider) yang mencantumkan nama tersebut dalam spec.provider.capabilities-nya dan mengiklankan ekspor render_node, dan guest plugin itulah yang merender node tersebut. Tidak ada perender di dalam host sebagai cadangan; nama provider yang tidak diresolusikan ke Plugin yang melayani menghentikan build pada saat routing. Menambahkan provider standar berarti mengirimkan guest .wasm dan entitas Plugin katalog — host tidak membawa kode per provider.
Kapabilitas yang dilayani provider tidak mengandung titik dua, demikian pula kapabilitas yang dinyatakan kompatibel oleh sebuah langkah pipeline. capability: sebuah Recipe dibaca sebagai kapabilitas hingga titik dua terakhirnya dan pin versi setelahnya — helm:1.0.0 meminta helm pada 1.0.0 — sehingga nama yang mengandung titik dua adalah nama yang tidak dapat diminta oleh Recipe mana pun. Host menolak nama seperti itu dalam capabilities milik describe() untuk guest provider atau pipeline-step saat guest dimuat dan saat entitasnya dihasilkan untuk publikasi, dengan menyebut guest dan nama tersebut. parse:<format> sebuah parser dan import:<format> sebuah importer tetap memiliki titik duanya: keduanya dicari berdasarkan format, tidak pernah melalui capability: sebuah Recipe.
Host adalah router generik. Host membaca laporan diri describe() milik guest — termasuk kontrak perilaku render-nya — dan men-dispatch ekspor guest tanpa memahami format provider apa pun. Kontrak tersebut menggerakkan dispatch sebagai data:
input_kinds(sourced,synthesized,artifacts_standalone) — jenis masukan Recipe mana yang dirender guest; host membatasi jenis masukan sebuah node berdasarkan himpunan ini.boundary_assembly(none|merge|nest) — cara guest menggabungkan keluaran sebuah grup dispatch:mergemengklasifikasikan keluaran per node sebagai fragmen yang digabungkan assembler ke dalam satu artefak,nestmenyarangkan file per node di bawah pembungkus yang dirakit,nonemenulis keluaran setiap node secara langsung.nest_segment(opsional) — untuk assemblynest, direktori tempat subdirektori milik setiap kontributor ditempatkan, ditulis sebagai satu nama direktori; jika tidak ada, subdirektori setiap kontributor berada langsung di posisi dispatch.assembly_name_annotation(opsional) — anotasi boundary yang nilai hasil resolve-nya menamai artefak yang dirakit guest dari sebuah grup dispatch; jika tidak ada, guest menamai assembly-nya hanya dari path dispatch.cross_boundary_linking(opsional) — apakah guest menyambungkan edgeuseslintas boundary melalui exportlink_publishdanlink_resolvemiliknya; guest mendeklarasikannya true tepat ketika ia mengekspor keduanya, dan pemuatan menolak guest yang flag dan export-nya tidak sesuai.artifact_delimiters(opsional) — pasangan delimiter Go-template yang diterapkan guest pada isi artefak.reusable_instance(opsional) — apakah satu instans yang dimuat boleh melayani setiap persilangan build (lihat Determinisme dan penggunaan ulang instans di bawah).omits(opsional) — apakah guest menghormati entri omit yang dibawa render sumber (lihat Mengecualikan unit yang dirender di bawah).boundary_artifacts(opsional) — apakah target guest menerima file yang dikontribusikan sebuah Recipe ke keluaran bersama boundary-nya (lihat Menerima file yang dikontribusikan Recipe ke boundary di bawah).source_ignore(opsional) — file yang tidak pernah dikirimkan ekosistem guest di samping sumber yang direndernya (lihat Mendeklarasikan apa yang tidak pernah dikirimkan ekosistem sebuah sumber di bawah).
Soket ini adalah himpunan ekspor tetap — satu wajib, sisanya opsional dan diiklankan dalam describe():
render_node(wajib) — merender satu node IR menjadi file native provider.assemble_boundary(opsional) — menggabungkan keluaran per node sebuah grup dispatch menjadi satu artefak per path (ada ketikaboundary_assemblybernilaimergeataunest).validate_node_input(opsional) — validasi struktural pra-render atas masukan sebuah node; diagnostikhaltmenghentikan build,warnditampilkan pada hasil build.carve/reassemble(opsional, berpasangan) — codec patch setia-byte milik guest sendiri untuk langkah pipeline pasca-render, hanya digunakan ketika keduanya diiklankan.name_bound(opsional) — guest menilai apakah nama yang diusulkan host sebagai identitas komponen menghasilkan nama yang diterima targetnya, dengan menjawab berupa batasan alih-alih nama miliknya sendiri.rendered_name(opsional) — guest melaporkan nama yang diberikan targetnya kepada sumber daya yang dirender guest untuk sebuah node.link_publish/link_resolve(opsional, berpasangan) — guest menyambungkan edgeuseslintas batas: endpoint yang dikonsumsi menerbitkan sebuah handle, dan endpoint yang mengonsumsi me-resolve-nya ke dalam output rakitannya sendiri.
artifacts: milik Recipe dilebur ke dalam render_node melalui proyeksi artefak pada input: host melakukan pembacaan $import, evaluasi Go-template, dan komputasi key/value provenans, lalu menyerahkan kepada guest setiap entri yang sudah dibaca dan dievaluasi; guest memegang penempatan dan emisi dalam format yang hanya diketahuinya. Didokumentasikan di architecture/13-catalog-and-registry.md.
Input render sumber membawa nilai-nilai node pada node.values, dan node.values_mapped menyatakan asal nilai tersebut: bernilai true jika nilai itu merupakan output dari valuesMapping milik Recipe — atau, untuk render milik attachment itu sendiri, milik FeatureRecipe-nya — dan tidak ada jika nilai itu merupakan nilai milik komponen sendiri yang diteruskan sebagaimana ditulis. Apakah sebuah guest membacanya merupakan kontrak guest itu sendiri. Provider cloudformation mengikat Parameters dari templat bersumber hanya dari nilai yang dihasilkan oleh mapping, karena nilai milik komponen sendiri mungkin ditulis untuk input Recipe yang lain; provider terraform menulis argumen modul bersumber dari nilai yang diterima perakitannya, dan tidak membaca flag tersebut. Nilai-nilai itu dibawa pada setiap node yang dirender dari input assemble_boundary untuk node yang dirender dari sumber — milik komponen, baik dihasilkan oleh mapping maupun tidak, dan milik Feature yang dilampirkan hanya jika dihasilkan oleh valuesMapping dari FeatureRecipe-nya — dan flag yang sama dibawa di sampingnya dan hanya di tempat nilai itu dibawa, sehingga assembler membaca jawaban yang sama dengan render milik node itu sendiri; provider cloudformation membacanya di sana untuk mengetahui parameter mana yang diisi oleh binding sebuah node, dan menolak referensi ke parameter tersebut dari tempat lain mana pun dalam stack, termasuk host dari Feature yang dilampirkan. Flag ini mencatat bagaimana nilai dihasilkan dan tidak pernah diturunkan dari key atau nilai.
Encoding wire. Setiap export dari socket ini menerima input dan mengembalikan output sebagai canonical CBOR (RFC 8949 §4.2.1), di kedua arah. Guest mendekode input dan mengenkode output melalui entry point yang sudah dibawa oleh tipe payload — DecodeCBOR dan EncodeCBOR di Go, decode_cbor dan encode_cbor di Rust, dan di TypeScript fungsi decodeCBOR dan encodeCBOR dari setiap tipe, seperti decodeCBORRenderNodeInput dan encodeCBORRenderNodeOutput — dengan membaca dan menulis byte (Vec<u8> di Rust, Host.inputBytes() dan Host.outputBytes(...) di TypeScript). Tidak diperlukan pustaka CBOR dan tidak ada yang mem-parse byte secara manual. content dari file yang dirender, dan setiap field byte lainnya, dikirim sebagai deretan byte mentah yang diisikan oleh dekoder yang dihasilkan ke dalam tipe field milik kit: byte slice di Go, string base64 di Rust dan TypeScript. Map yang ditandai skema sebagai mempertahankan urutan — di antaranya values, features dan uses milik node, derived_keys milik balasan, dan values milik kontributor perakitan — dikirim sebagai daftar entri berurutan dalam urutan yang dipegang build, dan guest membacanya melalui kontainer penjaga urutan milik kitnya. Setiap nilai dari values milik node dikirim sebagai byte dokumen JSON-nya sendiri, sehingga key di dalam sebuah nilai mempertahankan urutan penulisannya; demikian pula setiap entri attachment dari features, konteks render, workload yang di-parse, setiap edge yang diperkaya, setiap unit yang dipotong dan setiap operasi patch, dan guest mem-parse-nya sebagai JSON untuk melihat isinya. Setiap diagnostik dikirim dalam bentuk Diagnostic bersama. Jawaban yang bukan bentuk output export-nya dalam encoding ini — yang ditulis sebagai JSON, atau yang membawa field tingkat atas yang tidak dideklarasikan bentuk tersebut — menghentikan build, dengan menyebutkan export yang dipanggil. Contoh payload di halaman ini ditulis sebagai JSON agar mudah dibaca. Jika dipanggil langsung dengan aggrega plugin run-local --export render_node, atau dengan export lain dari socket ini, guest diberi payload JSON yang ditulis, yang telah dikonversi ke encoding ini, dan jawabannya dibaca sebagai bentuk output export tersebut lalu dicetak sebagai JSON — jawaban yang tidak berbentuk demikian ditolak, dengan menyebutkan export-nya, sebagaimana build menolaknya.
Status saat ini: tersedia untuk kelima provider. Guest helm merender chart bersumber (dengan me-resolve root chart), workload yang disintesis, dan artefak mandiri sebagai manifest Kubernetes datar. Guest helm-chart merakit umbrella chart, dengan menyarangkan chart bersumber setiap node sebagai sub-chart, serta membawa codec patch yang setia byte dan delimiter artefak kurung siku ([[ ]]). Guest compose merender file compose bersumber dan workload yang disintesis serta menggabungkan sebuah grup dispatch menjadi satu docker-compose.yaml, dan menghubungkan sebuah service ke jaringan komponen yang disebutkan oleh x-aggrega-networks-of miliknya. Guest terraform mengeluarkan konfigurasi Terraform apa adanya (HCL atau JSON) atau mem-vendor modul bersumber dan menyediakan inputnya sebagai argumen module-block milik komponen tersebut, memvalidasi HCL modul bersumber secara struktural sebelum render, dan menyusun sebuah boundary menjadi satu konfigurasi root yang mendeklarasikan setiap komponen sebagai module block yang bersumber dari sub-direktori milik komponen itu sendiri. Guest cloudformation merender template bersumber dan fragmen stack mandiri, menggabungkan sebuah grup dispatch menjadi satu template stack, dan menghubungkan edge uses lintas boundary melalui link_publish dan link_resolve. Masing-masing merender secara offline dan deterministik.
Mendeklarasikan nama yang diturunkan guest
Guest provider biasanya menurunkan nama yang dibutuhkan output-nya tetapi tidak ditulis oleh siapa pun — pengenal yang digunakan target untuk merujuk satu sumber daya, nama tempat satu output dipublikasikan agar dapat dirujuk oleh yang lain — dari identitas node dan sumber daya yang sedang dihasilkannya. Dua node dapat menghasilkan satu nama yang sama setiap kali bagian-bagian asal penurunannya sama, dan karena nama tersebut berada di dalam byte file yang ditulis host apa adanya, host tidak dapat melihat bentrokan itu: host harus mengurai format provider untuk menemukannya, padahal pengetahuan itulah yang tetap berada di dalam guest.
Oleh karena itu, render_node mengembalikan derived_keys opsional pada output-nya, dan arahnya dibalik — alih-alih host memeriksa output, guest yang mendeklarasikan dan host yang memeriksa:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "derived_keys": { "logical-ids": ["paymentsapiQueue", "paymentsapiTopic"], "export-names": ["aggrega--prod--api--orders-db--host"] }}Setiap kunci dari derived_keys adalah sebuah ruang kunci yang dinamai oleh guest, dan setiap ruang memuat nama-nama yang diturunkan guest ke dalamnya, sesuai urutan penurunan. Baik nama ruang maupun nama di dalamnya adalah kosakata Anda: host membacanya hanya sebagai string untuk dibandingkan kesamaannya di dalam satu ruang. Host tidak mengurai nama, tidak mempelajari arti sebuah ruang atau nama, dan tidak pernah menurunkan nama sendiri — sehingga satu pemeriksaan mencakup setiap jenis nama yang diturunkan setiap provider, dan provider baru tidak memerlukan kode host baru. Dalam tipe yang dipublikasikan, derived_keys adalah map yang menjaga urutan, sehingga ruang-ruang tersebut melintas sesuai urutan yang ditetapkan guest Anda.
Yang dilakukan host terhadapnya hanyalah satu pertanyaan: di dalam satu ruang, apakah setiap nama yang dideklarasikan berbeda di antara kontributor yang output-nya digabungkan ke dalam satu perakitan? Dua kontributor yang mendeklarasikan satu nama dalam satu ruang akan menghentikan build, dan penghentian itu menyebutkan ruang, nama, dan kedua kontributor, sehingga penulis dapat bertindak tanpa membaca provider. Nama yang berbeda, dan nama yang kebetulan sama di dua ruang yang berbeda, lolos.
Tiga sifat berikut perlu diketahui saat Anda memutuskan apa yang akan dideklarasikan:
- Cakupannya adalah satu output yang dirakit — himpunan kontributor yang file-nya digabungkan bersama. Guest yang menginginkan keunikan dalam cakupan yang lebih sempit atau lebih luas dari itu menyatakan cakupan tersebut dalam nama ruang yang dideklarasikannya, sehingga pilihan tetap berada di tangan Anda, bukan host.
- Satu kontributor boleh mengulang nama dengan bebas. Sebuah node dapat di-render melalui beberapa persilangan — render sumber, sintesis workload, penempatan artefak — dan deklarasinya digabungkan. Nama yang sama yang dideklarasikan dua kali oleh satu kontributor berarti kontributor itu menggambarkan satu sumber daya dua kali, bukan bentrokan.
- Mendeklarasikan tidak mengubah byte apa pun. Field ini adalah pernyataan tentang apa yang diturunkan guest, tidak pernah merupakan perubahan terhadap apa yang dihasilkannya, sehingga output yang di-render guest identik baik ia mendeklarasikan maupun tidak. Menghilangkan
derived_keysadalah sah dan membuat pemeriksaan tidak aktif untuk guest tersebut.
Melaporkan fakta tentang apa yang dihasilkan guest
Beberapa hal tentang render sebuah node hanya terlihat oleh provider yang menghasilkannya — isi dokumen yang ditulisnya, nama yang didefinisikannya, berapa banyak sesuatu yang dihasilkannya — karena membacanya dari byte file berarti memahami format provider. render_node dapat melaporkan hal-hal tersebut sendiri, pada daftar render_facts opsional di samping file-nya:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "render_facts": [ { "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] }, { "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] } ]}Setiap fakta terdiri dari name dan value, dan keduanya milik provider Anda: fakta apa yang dilaporkannya, arti setiap nama, dan isi setiap entri adalah bagian dari kontrak terdokumentasi milik provider Anda sendiri, jadi dokumentasikan semuanya untuk para penulis yang akan membacanya.
Laporkan nilai setiap fakta sebagai daftar — sebuah array JSON — meskipun hanya berisi satu entri. Satu nama dapat dilaporkan oleh lebih dari satu render sebuah komponen: render komponen itu sendiri dapat terdiri dari beberapa panggilan — misalnya render chart dan penempatan artefak — dan setiap Feature yang dilampirkan pada komponen di-render melalui panggilan provider tersendiri. Tidak ada provider yang dapat mengetahui saat me-render apakah laporannya akan menjadi satu-satunya di bawah suatu nama, sehingga setiap laporan adalah daftar, dan compiler menggabungkan daftar-daftar yang diterima satu nama menjadi satu daftar. Fakta yang nilainya selain itu — objek, string, angka, boolean, null — ditolak saat guest Anda mengembalikannya: build berhenti dengan kode singkat E0325, menyebutkan fakta, node, dan guest Anda, serta menyatakan nilainya. Entri di dalam daftar dapat berupa nilai JSON apa pun dalam bentuk yang Anda dokumentasikan.
Bahwa sebuah nilai adalah daftar merupakan satu-satunya hal yang dipelajari compiler tentangnya. Compiler mengindeks fakta berdasarkan nama dan menyerahkan setiap daftar kepada template yang membacanya — fakta komponen host kepada setiap Feature yang dilampirkan padanya, fakta setiap pemanggil kepada Feature yang mendeklarasikan bahwa ia membaca fakta render pemanggilnya, dan fakta setiap target kepada Feature yang mendeklarasikan bahwa ia membaca fakta render komponen yang terhubung dengan host-nya, sebagaimana dijelaskan konteks template — dengan mendekode setiap daftar menjadi nilai yang dapat diiterasi oleh template. Compiler tidak pernah mempelajari arti sebuah nama atau entri dan tidak pernah menurunkan fakta sendiri, sehingga provider baru dapat melaporkan fakta baru tanpa perubahan apa pun di sisi compiler. Fakta yang dilaporkan Feature yang dilampirkan pada node dari render-nya sendiri disimpan terpisah dari fakta yang dilaporkan render node itu sendiri.
Empat sifat berikut perlu diketahui saat Anda memutuskan apa yang akan dilaporkan:
- Urutannya milik Anda. Fakta mempertahankan urutan yang dicantumkan guest Anda, dan setiap nilai mempertahankan byte-nya sendiri — urutan entri sebuah daftar dan kunci setiap objek adalah urutan yang ditulis guest Anda. Cantumkan fakta dalam urutan tetap, dan tulis setiap entri dengan urutan kunci tetap, agar input yang identik menghasilkan byte yang identik; daftar fakta, bukan map, ada justru agar urutan tersebut bertahan dalam tipe urutan milik setiap kit tanpa perlu ditandai, sedangkan map hanya mempertahankan urutan yang ditulis guest bila skemanya menandainya sebagai penjaga urutan dan guest mengisi kontainer penjaga urutan milik kit-nya.
- Melaporkan tidak mengubah byte apa pun. File yang ditulis compiler adalah file yang dikembalikan guest Anda, baik disertai fakta maupun tidak.
- Sebuah node dapat melaporkan melalui beberapa persilangan. Sebuah node dapat di-render sebagai render sumber, sintesis workload, dan penempatan artefak; fakta yang dilaporkan masing-masing disimpan sesuai urutan persilangan dijalankan, dan nama yang dilaporkan oleh lebih dari satu persilangan dibaca sebagai satu daftar yang menggabungkannya dalam urutan tersebut.
- Tidak melaporkan apa pun sudah lengkap. Menghilangkan
render_factsadalah sah, dan provider yang tidak melaporkan apa pun me-render persis seperti tanpa field tersebut.
Tipe RenderFact dipublikasikan dalam tiga paket ABI dan diekspor ulang oleh kit pengembangan plugin setiap bahasa, dan contoh render kit-kit tersebut melaporkan dua fakta di samping file-nya. Di Go, nilai adalah JSON yang ditulis guest Anda; melakukan marshal pada slice struct alih-alih map adalah yang menjaga kunci setiap entri tetap dalam urutan yang Anda deklarasikan:
type stackFact struct { Name string `json:"name"` Resources int `json:"resources"`}
stacks, err := json.Marshal([]stackFact{{Name: "payments-api", Resources: 2}})if err != nil { pdk.SetError(err) return 1}out := aggrega.RenderNodeOutput{ Files: files, RenderFacts: []aggrega.RenderFact{{Name: "stacks", Value: stacks}},}Mengecualikan unit yang di-render
Sebuah render sumber dapat menyebutkan unit yang harus dikecualikan oleh provider dari apa yang di-render-nya — misalnya sebuah Secret yang dibuat ulang oleh chart yang diambil pada setiap render. Unit hasil render mana yang disebut oleh sebuah entri adalah pengetahuan yang hanya dimiliki provider Anda, sehingga entri-entri itu dikirim ke guest Anda dan guest Anda yang melakukan pengecualiannya. Entri-entri itu tiba pada input render_node sebagai daftar omits opsional di samping source_listing:
{ "node": { "id": "payments-api" }, "context": { }, "source_listing": { "root": "/acquired/payments-chart", "root_is_dir": true, "entries": [] }, "omits": [ { "kind": "Secret", "name": "payments-api-token", "namespace": "payments" }, { "kind": "ConfigMap", "name": "payments-api-dashboards" } ]}Setiap entri terdiri atas kind, name, dan namespace opsional, yang sudah diresolusikan menjadi string biasa dan dicantumkan dalam urutan yang dideklarasikan penulis; entri yang tidak berlaku untuk build tidak dibawa. Apa yang dipilih oleh ketiga field tersebut adalah kontrak provider Anda sendiri — kind, name, dan namespace sebuah resource dalam format target Anda — jadi dokumentasikanlah untuk para penulis yang menulis entri tersebut.
Seorang penulis dapat membangun field sebuah entri dari nilai yang ia deklarasikan sensitif — misalnya resource yang dinamai menurut sebuah pengaturan sensitif. Entri seperti itu tiba dengan "sensitive": true, dan guest Anda memperlakukannya seperti setiap nilai bertanda lain yang dibawa input render (lihat Nilai yang ditandai sensitif oleh input): guest tetap mencocokkan dan menghitung entri itu berdasarkan field-nya, yang memang menjadi tujuan entri tersebut, dan menjaga setiap field-nya tidak muncul dalam penolakan, peringatan, atau baris log. Tanda itu mencakup seluruh entri, karena compiler tidak menyebutkan field mana yang dihasilkan oleh nilai tersebut. Tanda itu tidak ada bila tidak ada field yang dibangun dari nilai seperti itu.
Guest yang mematuhi entri-entri tersebut melakukan tiga hal:
- Mencocokkan setiap entri dengan apa yang di-render-nya, dalam istilah format Anda.
- Mengecualikan setiap unit yang cocok dari semua yang dikembalikannya —
files-nya, nama yang dideklarasikannya dalamderived_keys, dan fakta yang dilaporkannya dalamrender_facts— sehingga tidak ada lagi yang diterima compiler yang masih mendeskripsikan unit tersebut. - Melaporkan satu hitungan per entri pada daftar
omittedopsional di output-nya, dalam urutan kedatangan entri, masing-masing berupa jumlah unit yang cocok dengan entri itu, dihitung terlepas dari apakah entri lain juga cocok dengan unit tersebut:
{ "files": [ { "path": "templates/deployment.yaml", "content": "..." } ], "omitted": [1, 0]}Nol adalah jawaban yang lengkap: entri itu tidak cocok dengan apa pun yang di-render guest Anda. Hitungan-hitungan itu adalah satu-satunya yang dikirim kembali tentang apa yang dikecualikan; unit-unitnya sendiri cukup tidak ada dalam apa yang dikembalikan guest Anda.
Provider yang melakukan ketiga hal tersebut mendeklarasikannya dengan omits: true pada kontraknya. Entitas Plugin mencatat klaim yang sama sebagai spec.provider.contract.omits; bila entitas membawa kontrak perilaku render, proses pemuatan menolak guest yang describe()-nya melaporkan nilai berbeda. Entri-entri itu hanya menyertai daftar sumber dan tidak yang lain: render workload yang disintesis atau render set artefak tidak pernah membawanya.
Render yang tidak membawa entri tidak berubah oleh field tersebut. Kedua field bersifat opsional dan tidak ada bila kosong, sehingga render yang tidak membawa entri melintasi socket byte demi byte seperti seandainya field tersebut tidak ada, dan guest yang tidak pernah membacanya tidak terpengaruh olehnya. Tipe OmitEntry dipublikasikan dalam ketiga paket ABI dan diekspor ulang oleh kit pengembangan plugin setiap bahasa.
Apa yang dilakukan compiler dengan jawaban Anda. Entri-entri itu berasal dari key omits: yang ditulis penulis pada sebuah Recipe atau FeatureRecipe (Recipe → Field omits:); compiler mengevaluasi template setiap entri dan memberikan kepada guest Anda entri-entri yang berlaku. Kemudian compiler membaca hitungan Anda, dan hanya hitungan Anda — compiler tidak pernah melihat ke dalam file yang dikembalikan untuk memeriksanya:
- Daftar hitungan yang bukan satu hitungan non-negatif per entri yang diberikan menghentikan build — tidak ada, terlalu pendek, terlalu panjang, atau memuat hitungan di bawah nol — dengan menyebutkan node, provider Anda, berapa banyak entri yang dikirim, dan berapa banyak hitungan yang kembali. Laporan yang tidak sejajar tidak menyisakan cara untuk mengetahui entri mana yang mengecualikan apa. Lihat A provider’s omitted counts do not match the omits entries it was handed (Hitungan omitted sebuah provider tidak cocok dengan entri omits yang diberikan kepadanya).
- Nilai nol menghentikan build, dengan menyebutkan entri pertama dalam urutan penulis yang hitungannya nol: node, provider Anda, posisi entri dalam daftar yang dideklarasikan dokumennya, serta kind, name, dan namespace hasil resolusinya. Guest Anda melaporkan nol tersebut; penghentiannya dilakukan oleh compiler. Lihat An omits entry left out nothing the source rendered (Sebuah entri omits tidak mengecualikan apa pun yang di-render sumber).
- Dokumen yang mendeklarasikan
omits:yang provider-nya tidak mengklaimomits: trueditolak sebelum apa pun di-render, sehingga penulis segera mengetahui bahwa key tersebut tidak akan berpengaruh, alih-alih menemukan dokumen itu di output. Compiler membaca klaim Anda daridescribe()Anda setelah setiap Recipe dan FeatureRecipe dalam build terikat, dan menolak sebelum komponen pertama di-render — sehingga guest yang tidak mengklaim key tersebut tidak pernah diberi entri. Penolakan itu menyebutkan provider dan komponen yang menjadi tujuan render dokumen, atau, untuk FeatureRecipe yang dibangkitkan sekali untuk sebuah boundary, boundary dan attachment-nya. Lihat The provider does not support omits (Provider tidak mendukung omits).
Status saat ini: tersedia. Guest helm, compose, dan cloudformation yang didistribusikan bersama compiler mendeklarasikan klaim tersebut dan mematuhi entri-entrinya. Guest helm tidak menulis field entri mana pun ke dalam teks yang dikembalikannya. Guest compose dan cloudformation menyebutkan kind, name, dan namespace sebuah entri ketika menolak entri tersebut, serta unit yang dikecualikan sebuah entri ketika menolak file atau template yang masih menyebutkannya, dan menampilkan setiap field entri bertanda sebagai <redacted> di sana. Guest helm-chart dan terraform tidak mendeklarasikan klaim tersebut, sehingga dokumen yang mendeklarasikan omits: yang di-render oleh salah satunya akan ditolak.
Menerima file yang dikontribusikan sebuah Recipe ke boundary
Beberapa file menjadi milik boundary secara keseluruhan, bukan milik salah satu komponennya — misalnya konfigurasi provider yang dibaca target sekali untuk semua yang di-deploy boundary. Sebuah Recipe menulis file-file itu di bawah spec.boundary.artifacts, dan compiler, bukan guest Anda, yang mengerjakannya: compiler mengevaluasi setiap file terhadap konteks yang digunakan untuk mengevaluasi entri artifacts:, menggabungkan file yang dideklarasikan berdasarkan nama oleh setiap kontributor grup dispatch, dan menulis masing-masing sekali di direktori yang memuat output rakitan grup, di samping apa yang dikembalikan assemble_boundary Anda. Guest Anda tidak diberi satu pun file ini pada export mana pun dan tidak pernah ditanya tentangnya, sehingga tidak ada yang perlu diimplementasikan — hanya sebuah pernyataan tentang target Anda yang perlu dibuat:
"contract": { "input_kinds": { "sourced": true, "artifacts_standalone": true }, "boundary_assembly": "nest", "boundary_artifacts": true}Deklarasikan boundary_artifacts: true hanya bila target Anda membaca file yang ditempatkan di direktori tersebut sebagai bagian dari output boundary. Entitas Plugin mencatat klaim yang sama sebagai spec.provider.contract.boundaryArtifacts; bila entitas membawa kontrak perilaku render, proses pemuatan menolak guest yang describe()-nya melaporkan nilai berbeda. Recipe yang mendeklarasikan blok tersebut yang provider-nya tidak mengklaimnya ditolak sebelum apa pun di-render, dengan menyebutkan provider dan komponennya; lihat The provider does not support boundary artifacts (Provider tidak mendukung artefak boundary). File yang ditempatkan oleh salah satu penggabungan ini di bawah nama yang juga ditulis rakitan Anda menghentikan build sebagai two contributors writing one output path (dua kontributor menulis satu path output), sehingga nama-nama yang ditulis rakitan Anda termasuk dalam apa yang Anda dokumentasikan untuk para penulis.
Status saat ini: tersedia. Guest terraform yang didistribusikan bersama compiler mendeklarasikan klaim tersebut, dan Terraform membaca setiap file di samping konfigurasi root boundary; guest helm, compose, helm-chart, dan cloudformation tidak mendeklarasikannya.
Mendeklarasikan apa yang tidak pernah dikirimkan oleh ekosistem suatu sumber
Direktori sumber lokal sebuah Recipe — chart yang ditempatkan bersama, sebuah modul — diterbitkan bersama Recipe tersebut, dan tidak setiap file di dalamnya merupakan bagiannya. Guest provider menyatakan apa yang tidak pernah dikirimkan oleh ekosistemnya sendiri melalui source_ignore pada kontraknya, sebagai aturan pengabaian dalam sintaksis yang digunakan .gitignore:
"contract": { "input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false }, "boundary_assembly": "none", "source_ignore": { "patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"], "files": [".helmignore"] }}patternsadalah aturan yang dibaca dari akar direktori sumber, diterapkan secara berurutan, dengan kecocokan yang lebih akhir menimpa kecocokan yang lebih awal.filesmenyebutkan file pengabaian yang dipatuhi ekosistem Anda di dalam suatu sumber. Di mana pun penelusuran sumber menemukan salah satunya, barisnya dibaca sebagai aturan tambahan untuk direktori yang memuatnya, setelah pola Anda.
Deklarasi dibaca saat sebuah entitas di-pin, bukan saat dirender. Langkah pin milik penulis me-resolve plugin yang melayani kapabilitas entitas tersebut di workspace mereka, menggabungkan aturan Anda dengan .aggregaignore milik mereka sendiri — yang barisnya datang terakhir sehingga menang pada setiap path yang disebutkannya — dan mencatat nama plugin Anda, tanpa versi, bersama aturan gabungan yang persis, di entity.lock milik entitas tersebut. Setiap publikasi, perbandingan, dan render entitas itu selanjutnya menerapkan aturan yang tercatat; host mencocokkannya dan tidak memiliki opini sendiri tentang ekosistem mana pun. Jadi file yang diserahkan kepada guest Anda saat render — listing, dan setiap file yang dimintanya untuk dikemas atau dibaca oleh host — persis sama dengan file yang dibawa oleh publikasi entitas tersebut, dan file yang dikecualikan oleh aturan dijawab sebagai tidak ada, dengan menyebutkan namanya. Tautan simbolik di bawah suatu sumber ditolak sebelum guest Anda dipanggil.
Kompatibilitas mengikuti dari apa yang tercatat. Sebuah guest dapat merender Recipe yang diterbitkan untuk kapabilitasnya apabila guest tersebut menggunakan versi ABI yang sama, kontraknya cocok dengan klaim entitasnya, dan tidak membutuhkan file di luar set yang diterbitkan. Guest yang membutuhkan file yang dikecualikan dari set harus menggagalkan build-nya secara jelas dan menyebutkan file tersebut — penolakan host terhadap pengemasan atau pembacaan menyebutkannya, dan guest membawanya ke dalam kegagalannya sendiri. Apabila plugin yang diikat oleh workspace konsumen untuk suatu kapabilitas mendeklarasikan aturan yang berbeda dari yang dicatat oleh lock suatu entitas, pull konsumen mencetak peringatan yang menyebutkan kedua plugin dan perbedaannya; pull tidak pernah berhenti karenanya.
Menghilangkan source_ignore berarti tidak mendeklarasikan aturan apa pun, dan sumber yang Anda render kemudian mempertahankan setiap file yang dipertahankan oleh aturan penulis sendiri. Field ini opsional dan tidak memerlukan versi ABI tersendiri: guest yang menghilangkannya dimuat sebagai guest yang tidak mendeklarasikan apa pun. Entitas Plugin mencatat deklarasi yang sama sebagai spec.provider.contract.sourceIgnore; apabila demikian, pemuatan menolak guest yang describe()-nya melaporkan sesuatu yang berbeda.
Determinisme dan penggunaan ulang instance
Host mengonsumsi byte keluaran guest apa adanya, sehingga guest harus menghasilkan keluaran yang identik dari masukan yang identik. Secara default, guest dimuat baru untuk setiap node — tanpa state yang terbawa antar-node berdasarkan konstruksinya. Guest yang mendeklarasikan sendiri reusable_instance justru dimuat sekali per build dan instance tunggalnya melayani setiap penyeberangan, yang menghemat biaya instansiasi per node yang dominan. Karena penggunaan ulang hanya aman untuk guest tanpa state, aggrega build --verify-determinism merender setiap node dua kali melalui instance yang sama dan menghentikan build apabila dua render suatu node berbeda; build default merender sekali dan memercayai deklarasi tersebut. Cache kompilasi Wasm berbasis disk dan berlaku untuk seluruh proses, sehingga guest dikompilasi sekali dan build berikutnya melewati kompilasi ulang.
Socket linter — linter publikasi
Socket linter dikirimkan sebagai publishing-linter standar, sebuah gerbang di luar alur yang berjalan melalui aggrega lint dan bukan pada waktu kompilasi. Socket ini mengonsumsi entitas katalog (dan, dalam mode --pre-publish, versi entitas yang saat ini diterbitkan) serta mengembalikan daftar temuan, masing-masing dengan tingkat keparahan dan pesan; dalam mode --pre-publish socket ini juga mengembalikan klasifikasi kenaikan versi. Host menjalankannya melalui runtime Wasm tertanam, di balik firewall kemurnian AOT yang sama seperti setiap socket lainnya. Set aturan lengkap, tingkat keparahan, dan opt-out per aturan didokumentasikan di cli/aggrega-lint.md.
Linter adalah disiplin katalog yang bersifat opt-in: compiler tidak menjalankannya selama aggrega build (dengan satu-satunya pengecualian berupa peringatan anjuran untuk tidak memakai x-aggrega-*, yang muncul pada tingkat keparahan warn selama build dan pada tingkat keparahan halt di bawah aggrega lint --pre-publish). Karena aturannya berada dalam sebuah plugin, suatu perusahaan dapat mengarahkan aggrega lint ke plugin linter lain untuk menerapkan disiplinnya sendiri.
Tidak ada nilai parameter yang mencapai plugin linter, pada cakupan mana pun aggrega lint dijalankan. Sebelum dokumen apa pun diserahkan, host menahan nilai default parameter sebuah Aggregate, nilai yang diteruskannya ke setiap modul yang diimpornya, dan parameter sebuah Release, dengan tetap mempertahankan kontrak setiap deklarasi parameter — hanya kunci yang digunakan untuk menulis deklarasi, pada setiap tingkat persarangannya — serta setiap teks template yang membaca parameter: nilai parameter dapat berupa kredensial itu sendiri, dan plugin yang dipasang di sini mungkin merupakan kode yang tidak ditulis oleh workspace. Apa yang dibawa setiap dokumen dijelaskan di Apa yang diserahkan kepada plugin linter.
Encoding wire. Masukan dan keluaran sama-sama dikirim sebagai CBOR kanonis (RFC 8949 §4.2.1). Guest mendekode masukannya dan mengenkode keluarannya melalui titik masuk yang sudah dimiliki LinterInput dan LinterOutput dari kit-nya — DecodeCBOR dan EncodeCBOR di Go, decode_cbor dan encode_cbor di Rust, decodeCBORLinterInput dan encodeCBORLinterOutput di TypeScript — dengan membaca dan menulis byte (Vec<u8> di Rust, Host.inputBytes() dan Host.outputBytes(...) di TypeScript). Tidak diperlukan pustaka CBOR dan tidak ada yang mengurai byte secara manual. Dokumen entitas — proposed, previous, implemented_component, dan release — serta setiap nilai components dikirim sebagai byte dokumen JSON-nya, sehingga guest mengurainya sebagai JSON untuk melihat isinya. components adalah map yang ditandai skema sebagai mempertahankan urutan, sehingga pada masukan aturan yang membaca seluruh Release, map ini dikirim sebagai daftar entri berurutan dalam urutan Aggregate mendeklarasikan instance komponennya, dan guest membacanya melalui kontainer pemelihara urutan milik kit-nya. policies dikirim sebagai map yang hanya memuat flag yang disetel, sehingga flag yang tidak dibawanya dibaca sebagai false, dan setiap temuan dikirim dalam bentuk Diagnostic bersama. Jawaban yang bukan LinterOutput dalam encoding ini — yang ditulis sebagai JSON, atau yang membawa field tingkat atas yang tidak dideklarasikan oleh bentuknya — menggagalkan lint, dengan menyebutkan export yang dipanggilnya, alih-alih dibaca sebagai proses yang tidak menemukan apa pun. Saat dipanggil langsung dengan aggrega plugin run-local --export lint_rules, linter diberi payload JSON yang ditulis penulis yang dikonversi ke encoding ini, dan jawabannya dibaca sebagai bentuk output export tersebut lalu dicetak sebagai JSON — jawaban yang tidak berbentuk demikian ditolak, dengan menyebutkan export-nya, sebagaimana build menolaknya.
Status saat ini: tersedia. Publishing-linter dikirimkan dan berjalan melalui host lewat aggrega lint.
Socket parser — keluaran pohon kanonis
Parser mengubah sumber yang ditulis dalam format yang tidak dibaca secara native oleh compiler menjadi pohon terstruktur kanonis, sehingga konsumen membaca pohon tersebut alih-alih membawa parser sendiri. Host menentukan parser yang mengiklankan format yang diminta sebagai parse:<format> dan memanggil ekspor parse-nya di tiga tempat: ketika kebijakan render-verdict diberi artefak hasil render dalam format yang tidak dibacanya secara native, ketika importer meminta pohon kepada host melalui aggrega_parse_source, dan ketika impor yang tidak menyebutkan format dikenali (lihat socket importer di bawah). Guest tidak pernah memanggil parser sendiri.
Bentuk masukan (host → guest). Dokumen ParseInput yang membawa:
format— format yang diminta, salah satu kapabilitasparse:<format>milik parser tanpa prefiksnya.bytes— byte sumber.options— dokumen opsi yang disediakan konsumen untuk perilaku khusus parser, diteruskan apa adanya. Tidak ada jika konsumen tidak menyediakannya.
Bentuk keluaran (guest → host). Dokumen ParseOutput yang membawa tree — sumber yang telah di-parse sebagai dokumen JSON, yang tingkat teratasnya dapat berupa objek, larik, atau skalar — diagnostik apa pun dalam bentuk Diagnostic bersama, rentang sumber opsional yang menunjukkan letak simpul pohon dalam byte asli, dan error kegagalan ketika parse tidak dapat diselesaikan. Setiap field beserta batasannya terdapat dalam referensi skema socket parser yang dihasilkan.
Pengodean wire. Masukan dan keluaran sama-sama dikirim sebagai CBOR kanonis (RFC 8949 §4.2.1), pengodean yang juga digunakan ParseInput yang sama ketika guest menyerahkannya ke aggrega_parse_source. Guest mendekode masukannya dan mengodekan keluarannya melalui titik masuk yang sudah dibawa ParseInput dan ParseOutput dalam kit-nya — DecodeCBOR dan EncodeCBOR di Go, decode_cbor dan encode_cbor di Rust, decodeCBORParseInput dan encodeCBORParseOutput di TypeScript — dengan membaca dan menulis byte (Vec<u8> di Rust, Host.inputBytes() dan Host.outputBytes(...) di TypeScript). Tidak diperlukan pustaka CBOR dan tidak ada yang mem-parse byte secara manual. Byte sumber dikirim sebagai rangkaian byte mentah, dan dekoder yang dihasilkan mengisikannya ke tipe field milik kit: slice byte di Go, string base64 di Rust dan TypeScript. options dan tree dikirim sebagai byte dokumen JSON-nya, sehingga pohon yang ditulis parser sampai ke konsumennya apa adanya. Parser yang tidak dapat menyelesaikan prosesnya menyebutkan alasannya dalam error keluaran, dan parse gagal dengan menyebutkan parser dan pesan tersebut; jawaban yang bukan ParseOutput dalam pengodean ini — yang ditulis sebagai JSON, atau yang membawa field tingkat teratas yang tidak dideklarasikan bentuknya — juga menggagalkan parse, dengan menyebutkan parser dan ekspor parse-nya. Parse yang gagal menghentikan build pada peran render-verdict, dan sampai ke importer sebagai kegagalan yang dijawab oleh aggrega_parse_source. Demikian pula sumber yang ditolak parser — sumber yang dijawabnya dengan diagnostik halt di samping pohonnya: panggilan importer gagal dengan pesan setiap diagnostik tersebut, dalam urutan parser, dan tidak pernah diberi pohonnya. Jika dipanggil langsung dengan aggrega plugin run-local --export parse, parser diberi payload JSON yang ditulis pengguna yang dikonversi ke pengodean ini — sumber ditulis dalam payload tersebut sebagai base64, sebagaimana JSON menulis field byte apa pun — dan jawabannya dibaca sebagai bentuk output ekspor tersebut lalu dicetak sebagai JSON — jawaban yang tidak berbentuk demikian ditolak, dengan menyebutkan ekspornya, sebagaimana build menolaknya.
Definisi tipe. Tipe wire parser — ParseInput, ParseOutput, NodeSpan, dan SourceSpan — diterbitkan dalam ketiga paket ABI dan diekspor ulang oleh kit pengembangan plugin setiap bahasa, yang dihasilkan dari satu codec sehingga ketiganya tetap selaras. Contoh parse di setiap kit membaca masukannya dan menulis keluarannya dengan cara ini, demikian pula parser untuk HCL, TOML, YAML, JSON, dan JSON dengan komentar yang disertakan di dalam biner.
Status saat ini: tersedia — dijalankan pada peran render-verdict untuk artefak dalam format yang tidak dibaca secara native oleh kebijakan, melalui aggrega_parse_source untuk importer, dan untuk mengenali format impor yang tidak menyebutkan format apa pun.
Soket importer — keluaran draf penulisan
Importer mengubah sumber yang ditulis untuk alat lain — misalnya alur yang diekspor dari pembangun agen — menjadi draf berkas penulisan Aggrega. Importer berjalan di luar alur build: aggrega import, metode aggrega/import pada sesi editor, dan alat import yang ditujukan bagi asisten menentukan importer yang mengiklankan format yang diminta sebagai import:<format> lalu memanggil ekspor import-nya satu kali per impor. Build tidak pernah memanggilnya. Importer mana yang berjalan, dan apa yang diberikan operator kepadanya, dijelaskan di Importer mana yang mengubah sumber menjadi draf. Importer bawaan compiler, satu untuk setiap format yang dibacanya, dijelaskan di Importer inti: format apa saja itu, apa yang dibaca masing-masing, apa yang didraftkannya, pengaturan yang diterimanya, publikasinya bersama setiap rilis compiler, serta cara impor mengambil dan memverifikasi importer yang belum dimiliki mesin.
Bentuk masukan (host → guest). Dokumen ImportInput yang memuat:
format— format yang diminta impor, salah satu kapabilitasimport:<format>milik importer tanpa awalannya.bytes— byte sumber: seluruh berkas untuk impor sebuah berkas, dan kosong untuk impor sebuah direktori, yang berkas-berkasnya tiba di bawahsources.name— nama sumber, tanpa direktori di depannya, sehingga importer dapat menyebut sumber tersebut dalam apa yang dilaporkannya dan dalam apa yang didrafkannya: untuk impor sebuah file, nama dasar file tempatbytesdibaca; untuk impor sebuah direktori, nama dasar direktori itu sendiri, yang dibaca dari path lengkapnya, sehinggaaggrega import .menyerahkan nama direktori tempat perintah itu dijalankan, sementara setiap file dalam direktori tetap tiba dengan namanya sendiri. Tidak ada jika sumber tidak memiliki nama untuk diberikan.sources— sumber bernama, masing-masing memuat nama dan byte-nya, dalam satu daftar yang diurutkan menurut nama: untuk impor sebuah direktori, setiap berkasnya yang dipilih oleh pola berkas yang dideklarasikan importer, kecuali folder keluaran build workspace, dinamai dengan path berpemisah garis miring di dalam direktori; serta berkas-berkas yang dideklarasikan di bawahwith.sourcesoleh entriplugins.importeryang memasang importer ini, masing-masing dengan nama dasarnya. Berkas direktori dan berkaswith.sourcesdengan nama yang sama menyebabkan impor ditolak, alih-alih yang satu menyembunyikan yang lain. Tidak ada jika tidak ada sumber.settings— objek pengaturan yang dideklarasikan entri tersebut di bawahwith.settings, sebagai dokumen JSON dengan kunci yang diurutkan, diteruskan apa adanya. Tidak ada jika tidak ada entri yang memasang importer atau entri tidak mendeklarasikannya.catalog— tampilan Components yang dimiliki katalog workspace itu sendiri: katalog tempat importer itu sendiri dipilih — folder katalog workspace, atau, jika workspace tidak menyebutkan satu pun, snapshot katalog yang diterbitkan registry bawaannya dan disimpan di mesin ini — tanpa ada yang diambil untuk tampilan itu sendiri. Daftarcomponents-nya memuat satu entri per nama Component, diurutkan menurut nama; jika katalog memuat beberapa versi suatu Component, entri tersebut menjelaskan versi yang dituju oleh referensi yang menyebutnya tanpa versi. Setiap entri memuatnamedanversionComponent,labels-nya, nama kunci tingkat atas yang dideklarasikan oleh values dan provides-nya (valuesdanprovides, masing-masing diurutkan), sertasockets-nya — masing-masing berupanamesoket danselectorlabel yang harus dipenuhi dependensi yang dihubungkan melaluinya — dalam urutan yang dideklarasikan Component. Component yang memperluas Component lain memuat apa yang diwarisinya maupun apa yang dideklarasikannya, dan soket yang diwarisinya didahulukan. Tampilan ini hanya memuat nama, versi, label, dan selector — tidak pernah nilai, default, atau rahasia — dan urutannya tetap, sehingga satu katalog menghasilkan satu urutan byte. Tidak ada jika katalog tidak memuat Component.
Bentuk keluaran (guest → host). Dokumen ImportOutput yang memuat entitas yang dihasilkan impor — masing-masing berupa referensi ke entitas katalog yang ada atau badan yang didraftkan — keputusan pemetaan di baliknya, diagnostik apa pun dalam bentuk Diagnostic bersama, berkas scaffold yang akan ditulis, serta error kegagalan jika impor tidak dapat diselesaikan. Setiap field beserta batasannya ada di referensi skema soket importer yang dihasilkan.
Pengodean wire. Masukan dan keluaran sama-sama dikirim sebagai CBOR kanonis (RFC 8949 §4.2.1). Guest mendekode masukannya dan mengodekan keluarannya melalui titik masuk yang sudah dimiliki ImportInput dan ImportOutput pada kit-nya — DecodeCBOR dan EncodeCBOR di Go, decode_cbor dan encode_cbor di Rust, decodeCBORImportInput dan encodeCBORImportOutput di TypeScript — dengan membaca dan menulis byte (Vec<u8> di Rust, Host.inputBytes() dan Host.outputBytes(...) di TypeScript). Tidak diperlukan pustaka CBOR dan tidak ada yang mengurai byte secara manual. settings dikirim di dalam dokumen biner sebagai byte dokumen JSON-nya, sehingga guest mengurainya sebagai JSON untuk melihat isinya, seperti pada setiap soket lainnya. Importer yang tidak dapat menyelesaikan tugasnya menyatakan alasannya dalam error keluaran, dan impor berhenti dengan menyebut importer dan pesan tersebut; jawaban yang bukan ImportOutput dalam pengodean ini — jawaban yang ditulis sebagai JSON, atau yang memuat field tingkat atas yang tidak dideklarasikan bentuknya — juga menghentikan impor, dengan menyebut importer dan ekspor import-nya. Jika dipanggil langsung dengan aggrega plugin run-local --export import, importer menerima payload JSON yang ditulis, dikonversi ke pengodean ini, dan jawabannya dibaca sebagai bentuk output ekspor tersebut lalu dicetak sebagai JSON — jawaban yang tidak berbentuk demikian ditolak, dengan menyebut ekspornya, sebagaimana build menolaknya.
Cara sumber dengan format Anda dikenali. Impor boleh tidak menyebut format, dan host kemudian mengenali format dari apa yang dideklarasikan importer, tanpa mengetahui format apa pun sendiri. Importer mendeklarasikan dalam laporan diri describe()-nya, di bawah importer (sebuah ImporterContract), daftar detect berisi tanda pengenal yang digunakan untuk mengenali sumber dengan format-formatnya. Setiap DetectSignature menyebutkan:
syntax— format sintaksis yang digunakan untuk mengurai sumber, yaitu format yang diiklankan plugin parser sebagaiparse:<syntax>, sepertijsonatauyaml;files— pola nama berkas opsional yang dicocokkan dengan bagian akhir nama sumber: satu segmen dengan nama berkas itu sendiri, beberapa segmen berpemisah garis miring dengan jumlah segmen akhir path yang sama, dengan*,?, dan[...]mencocokkan di dalam satu segmen. Tanda pengenal yang tidak mendeklarasikan pola berlaku untuk sumber berupa satu berkas apa pun namanya, dan tidak berlaku untuk berkas apa pun dalam direktori;match— predikat yang semuanya harus dipenuhi pohon hasil penguraian, masing-masing berupaPathMatchdenganpathberupa kunci yang digabungkan dengan titik dari puncak pohon (segmen bilangan bulat memilih posisi array),isberupapresent,absent,object,array,string,number, atauboolean, dan secara opsional stringequalsatau stringprefix— paling banyak salah satu dari keduanya.
Jika impor tidak menyebut format, host mencocokkan tanda pengenal setiap importer yang menjadi pilihan impor — importer di katalog workspace dan importer inti compiler — menurut urutan identitas dan versinya: host mengurai sumber melalui parser yang disediakan katalog untuk suatu sintaksis — atau, untuk sintaksis yang tidak disediakan parser-nya oleh katalog, parser yang dibawa compiler itu sendiri — paling banyak satu kali per sintaksis, mengevaluasi predikat pada pohon, dan membaca sumber sebagai format dari satu-satunya importer yang tanda pengenalnya cocok. Parser itu pula yang digunakan untuk menjawab panggilan aggrega_parse_source dari importer, sehingga importer membaca sumbernya melalui parser yang digunakan untuk mengenalinya. Sumber yang tidak dapat diurai dalam suatu sintaksis tidak cocok dengan tanda pengenal apa pun yang menyebut sintaksis itu; sintaksis yang parser-nya tidak disediakan oleh katalog maupun compiler menghentikan pengenalan, dengan menyebut ketiadaan parser tersebut. Sumber yang tidak cocok dengan tanda pengenal mana pun ditolak dengan meminta format, dan sumber yang dikenali sebagai lebih dari satu format ditolak dengan menyebut format-format tersebut. Tanda pengenal mengenali sumber sebagai setiap format yang diiklankan importer-nya, sehingga importer yang sumbernya hendak dikenali menyediakan satu format, dan importer yang tidak mendeklarasikan tanda pengenal hanya dapat dijangkau dengan menyebut formatnya.
Entitas Plugin milik importer mencatat daftar yang sama sebagai spec.importer.detect, yang diturunkan dari describe() ketika entitas tersebut dihasilkan dari guest; pengenalan membaca catatan itu, sehingga guest tidak dimuat sampai formatnya ditetapkan. Pemuatan dan publikasi guest menolak guest yang laporannya berbeda dari catatan entitasnya, dengan menyebut importer.detect, dan entitas yang tidak mencatat apa pun tidak membuat klaim apa pun. Deskriptor ditolak saat pemuatan apabila kontrak dideklarasikan pada plugin yang bukan importer, apabila sebuah signature tidak menyebut sintaks atau menyebut pola file yang salah bentuk, dan apabila sebuah predikat tidak menyebut path, menyebut is di luar ketujuh nilai tersebut, atau menyebut equals sekaligus prefix.
Importer inti compiler dan contoh import pada kit Go mendeklarasikan signature-nya dengan cara ini. Importer Langflow membaca sumber sebagai JSON dan meminta array di data.nodes; importer Flowise meminta array di nodes dan edges serta tidak ada apa pun di data.nodes; importer n8n meminta array di nodes, objek di connections, dan tidak ada apa pun di edges maupun data.nodes; importer MCP mendeklarasikan satu signature per konfigurasi klien, dengan menyebut file-nya — .mcp.json, claude_desktop_config.json, dan .cursor/mcp.json, yang dibaca sebagai JSON dengan objek di mcpServers, serta .vscode/mcp.json, yang dibaca sebagai JSON dengan komentar, sebagaimana Visual Studio Code membacanya, dengan objek di servers — dan satu signature yang tidak menyebut file, yang meminta string $schema yang diawali dengan https://static.modelcontextprotocol.io/schemas/; importer Compose membaca sumber sebagai YAML, menyebut file yang dibaca Compose secara default — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml, dan keempat file override-nya — dan meminta objek di services; importer Dify membaca sumber sebagai YAML, tidak menyebut file, dan meminta string app di kind serta sesuatu di app.mode dan di version; importer CrewAI menyebut config/agents.yaml dan config/tasks.yaml, yang dibaca sebagai YAML tanpa meminta apa pun dari tree, crew.jsonc dan crew.json, yang dibaca sebagai JSON dengan komentar dengan list di agents, serta agents/*.jsonc dan agents/*.json, yang dibaca sebagai JSON dengan komentar dengan sesuatu di role, sehingga tidak ada dua di antaranya yang cocok dengan satu sumber, dan file yang diimpor sendirian tanpa menyebut format dibaca sebagai YAML maupun JSON; importer LangGraph menyebut langgraph.json, yang dibaca sebagai JSON dengan objek di graphs, mendeklarasikan satu signature yang tidak menyebut file, yang meminta objek di graphs dan string https://langgra.ph/schema.json di $schema, dan tidak menyebut file environment, karena pengenalan membaca setiap file yang dipilih oleh pola importer mana pun, sehingga pola yang menyebut file tersebut akan membuka file environment dari setiap direktori yang diimpor tanpa menyebut format; importer Google ADK menyebut root_agent.yaml, yang dibaca sebagai YAML dengan sesuatu di name dan di instruction, atau string di agent_class dan sesuatu di name, dan tidak menyebut file lain, karena konfigurasi sub-agent dapat diberi nama apa saja dan pola yang menyebut setiap file YAML akan membuka masing-masing file dari setiap direktori yang diimpor tanpa menyebut format; importer Agent Framework membaca sumber sebagai YAML, tidak menyebut file, dan meminta string Prompt di kind serta objek di model; contoh import pada kit Go membaca sumber sebagai YAML dan meminta string DemoSource di kind. Dalam Go:
Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{ Syntax: "json", Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},}}},Apa yang dibaca oleh impor sebuah direktori. Sumber dapat berupa direktori, dan pola file yang dideklarasikan importer menentukan apa yang dibacanya: host membaca tepat file-file dalam direktori tersebut, pada kedalaman berapa pun, yang dipilih oleh salah satu pola files dari signature importer — masing-masing dicocokkan dengan bagian akhir path file yang dipisahkan garis miring di dalam direktori — dan menyerahkannya sebagai sources dalam urutan nama, dengan bytes kosong dan nama direktori itu sendiri sebagai name. Tidak ada file lain dalam direktori yang dibuka. Folder tempat build workspace menulis file hasil render-nya — dist/ di bawah root workspace — tidak dibaca sebagai bagian dari direktori yang memuatnya: tidak satu pun filenya diserahkan atau dikenali, dan link yang mengarah kepadanya dilewati, sehingga direktori yang telah di-build dibaca sebagai proyek yang dimuatnya, sedangkan direktori yang merupakan folder tersebut, atau berada di dalamnya, dibaca sebagaimana disebutkan. Signature yang tidak mendeklarasikan pola files tidak memilih file apa pun dari sebuah direktori, sehingga importer yang tidak mendeklarasikannya membaca satu file dan menolak direktori, dan direktori yang tidak berisi file yang dipilih oleh polanya juga ditolak. Direktori dibatasi pada dirinya sendiri: link di antara file yang akan dibacanya, atau ke sebuah direktori, yang mengarah ke luar direktori ditolak sebelum apa pun dibaca, link ke direktori tidak pernah dimasuki, dan link ke file yang tidak dipilih oleh pola mana pun dilewati tanpa dibaca. Pengenalan format sebuah direktori mengikuti aturan yang sama — setiap signature dicoba terhadap file yang dipilih oleh polanya, dalam urutan nama, setiap file dibaca dan di-parse paling banyak sekali per sintaks, dan signature yang tidak mendeklarasikan pola tidak berlaku untuk satu pun di antaranya. Host tidak membatasi apa pun: direktori yang terlalu besar bagi importer ditolak oleh batas runtime milik importer itu sendiri. Tidak satu pun importer Langflow, Flowise, n8n, Dify, dan Agent Framework milik compiler yang mendeklarasikan pola files, sehingga masing-masing membaca satu file; importer MCP-nya mendeklarasikan nama keempat konfigurasi klien, sehingga ia membaca setiap konfigurasi tersebut yang ada dalam direktori, importer Compose-nya mendeklarasikan delapan nama file Compose, sehingga ia menerima setiap file Compose yang ada dalam direktori dan menggabungkan file yang akan dibaca Compose; dan importer CrewAI-nya mendeklarasikan enam nama tempat deklarasi proyek CrewAI ditulis, sehingga ia menerima deklarasi proyek dan tidak menerima satu pun bagian programnya; dan importer LangGraph-nya mendeklarasikan langgraph.json, sehingga ia menerima konfigurasi aplikasi dan tidak menerima kode maupun file environment-nya, dengan file environment hanya sampai kepadanya melalui with.sources pada lampirannya; dan importer Google ADK-nya mendeklarasikan root_agent.yaml, sehingga ia menerima konfigurasi root agent aplikasi dan tidak menerima kode maupun file environment-nya, dengan konfigurasi yang disebut oleh sub-agent-nya hanya sampai kepadanya melalui with.sources pada lampirannya.
Definisi tipe. Tipe wire importer — ImportInput, ImportSource, CatalogProjection, CatalogComponent, CatalogSocket, ImportOutput, serta bentuk entitas, keputusan, dan scaffold yang dibawanya — dipublikasikan di ketiga paket ABI dan diekspor ulang oleh plugin development kit setiap bahasa, dihasilkan dari satu codec sehingga ketiganya tetap selaras, dan demikian pula tipe pengenalan ImporterContract, DetectSignature, dan PathMatch yang dibawa oleh self-report describe. Paket importer milik kit Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer, membawa semua yang dilakukan sebuah importer apa pun formatnya, dan importer inti compiler, yang semuanya dibangun di atasnya, membaca input dan menulis output-nya dengan cara ini.
Terhadap apa importer yang dibangun di atas kit Go memberi skor. Scorer milik kit menimbang setiap node sumber terhadap Components dari view catalog dan tidak terhadap hal lain: kandidatnya adalah katalog milik workspace itu sendiri — Components katalog enterprise sama persis dengan Components pustaka standar — dan kit tidak membawa kandidat sendiri. Dari setiap Component, kit membaca nama, kategori yang dibawa label component.aggrega.ai/category-nya, label-labelnya, dan nama key yang dideklarasikan oleh values-nya; key provides dan socket-nya tidak ditimbang. Component yang ditambahkan ke katalog menjadi kandidat pada impor berikutnya, tanpa perlu membangun ulang importer. Apabila view tidak ada, karena katalog tidak berisi Component, tidak ada node yang memiliki kandidat: tidak ada yang dirujuk atau diberi petunjuk, dan setiap node yang diberi Component tersendiri oleh draf akan didrafkan. Setiap importer yang memberi skor melalui kit memberi skor dengan cara ini — termasuk importer Langflow, Flowise, n8n, dan Compose milik compiler, sedangkan importer MCP-nya tidak menimbang kandidat apa pun; importer yang tidak menggunakan kit membaca view sesuai pilihannya sendiri.
Untuk apa importer yang dibangun di atas kit Go membaca socket sebuah platform. Socket tidak berbobot apa pun dalam skor, tetapi kit membacanya untuk menata sebuah draf. Format yang alurnya dijalankan platform sebagaimana ditulis — seperti format Langflow, Flowise, dan n8n — secara default didrafkan sebagai satu instans Component platform tersebut yang membawa alur itu, dan setiap bagian alur dihubungkan ke socket pertama, dalam urutan yang dicantumkan entri catalog platform pada sockets-nya, yang selector-nya dipenuhi oleh label Component bagian tersebut, sebagaimana label itu dibawa oleh view. Hanya selector dan label yang dibaca, dan selector dicocokkan oleh fungsi yang disediakan importer, karena kit tidak membawa tata bahasa selector sendiri; jika view tidak memuat Component dengan nama platform tersebut, tidak ada bagian yang dihubungkan. Importer inti menjelaskan draf yang dibuat dengan cara ini oleh importer Langflow, Flowise, dan n8n milik compiler, serta pengaturan layout yang sebagai gantinya mendrafkan setiap node sebagai Component tersendiri.
Status saat ini: tersedia — dijalankan oleh aggrega import dan oleh operasi yang sama pada sesi editor dan tool yang digunakan asisten.
Kriteria penempatan: socket linter vs peran verdict tata kelola
Dua socket yang didokumentasikan memiliki permukaan yang serupa — keduanya menghasilkan hasil per aturan — tetapi berbeda dalam penempatan pipeline dan semantik penahanan. Kriteria untuk menentukan socket mana yang membawa suatu pemeriksaan:
- Peran verdict tata kelola (in-band, menghentikan build). Dikhususkan untuk kebijakan yang menghentikan build: verdict
haltmenghentikan pipeline kompilasi dan build tidak menghasilkan artefak. Kasus penggunaannya adalah kebijakan yang pelanggarannya membuat keluaran tidak aman untuk diterapkan: gerbang kepatuhan (penempatan batas PCI / SOC2), invarian topologi (ingress zero-trust, autentikasi lintas batas), bentuk alur kredensial (tidak ada rahasia plaintext di IR), dan sebagainya. Sebuah kebijakan bernalar atas graf IR (ir-verdict, sebelum render) atau artefak yang telah di-render (render-verdict, setelah render). - Socket linter (out-of-band, CI / IDE, bersifat saran). Dikhususkan untuk pemeriksaan praktik terbaik dan keterlacakan: aturan yang pelanggarannya mencurigakan tetapi tidak berbahaya — rahasia yatim, parameter yang tidak digunakan, kosakata label yang usang, kelengkapan tag untuk atribusi biaya, penyimpangan konvensi penamaan. Kegagalan menghasilkan keluaran berupa saran; build tetap menghasilkan artefak.
Kriteria penempatan yang dirumuskan sebagai satu aturan: jika pemeriksaan harus menghentikan build, pemeriksaan itu ditempatkan pada peran verdict tata kelola; jika pemeriksaan harus memperingatkan penulis atau peninjau tanpa memblokir pipeline, pemeriksaan itu ditempatkan di socket linter.
Keduanya dapat digunakan saat ini. Socket linter menjalankan publishing-linter melalui aggrega lint; peran verdict tata kelola dijalankan secara in-band selama aggrega build ketika sebuah workspace melampirkan plugin peran verdict. Perlu dicatat bahwa peran verdict membawa tingkat keparahannya sendiri — sebuah kebijakan dapat sendiri menghasilkan verdict warn dan info yang memberi saran tanpa menghentikan — sehingga batas antara menghentikan dan memberi saran di atas adalah panduan penempatan untuk pemeriksaan secara utuh, bukan klaim bahwa kebijakan hanya dapat menghentikan. Lihat halaman socket tata kelola untuk model tingkat keparahan.
Rujukan silang
policy-socket.md— pembahasan menyeluruh tentang governance socket: empat peran, tingkat keparahan verdict, kanal input operator, penulisan policy untuk salah satu dari dua engine yang disertakan di dalam compiler, pembungkusan policy engine asing, dan guest referensi.core-importers.md— importer milik compiler sendiri, satu untuk setiap format yang dibacanya: apa yang dibaca masing-masing, pengaturannya, dan publikasinya bersama setiap rilis compiler.10-status.md#compilation-pipeline-phases— klasifikasi plugin pipeline pada halaman Status (kesiapan runtime pipeline Wasm plugin).architecture/04-entity-taxonomy.md§“Domain 3: Infrastructure Base” — Prinsip Plugin Dua Bagian untuk FeatureRecipes kredensial (pola Fetcher + Injector).architecture/13-catalog-and-registry.md— taksonomi OCI yang diawali dengan segmen provider.entities/featurerecipe.md— permukaan authoringpipeline:pada FeatureRecipe.when-to-use-a-pipeline-step.md— panduan keputusan: langkah pipeline vs FeatureRecipe bertemplat.templates/expansion-matrix.md— aturan evaluasi templat blokpipeline:with:pada plugin pipeline dan semantik akses.steps.examples/04-secrets.md— bentuk pipeline Fetcher + Injector yang dapat diambil oleh FeatureRecipe kredensial.errors/error-translation.md— disiplin penerjemahan error yang diikuti oleh guest plugin.