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

Invarian arsitektur

Delapan invarian ini adalah aturan pendiri Aggrega. Invarian ini berlaku di seluruh rilis, di seluruh inti compiler, lapisan skema, katalog, dan permukaan plugin Wasm. Setiap keputusan desain, setiap fitur, dan setiap entitas yang ditulis mematuhinya.

Bab arsitektur lainnya merujuk invarian berdasarkan nomornya. Ketika bab berikutnya menyebut “sesuai Invarian 2” atau “berdasarkan aturan String Pipe (Invarian 3)”, rujukannya adalah halaman ini.

1. Compiler netral terhadap konten, tanpa opini sendiri, dan agnostik terhadap niat pengguna

Compiler Aggrega adalah perute teks Ahead-Of-Time (AOT). Compiler ini mengurai YAML, menelusuri graf, mengevaluasi irisan label, dan menyalurkan string dari sumber ke tujuan. Compiler ini tidak mengawasi apa yang dimasukkan penulis ke dalam values, parameters, infra, provides, atau locals. Compiler ini tidak memberlakukan konvensi penamaan, konvensi port, atau label semantik yang diciptakan seorang Architect.

Banyak aturan yang terdengar seperti aturan compiler — kontrak Zero-Port, gaya katalog Naked-Base / Flavored-Edges, pilihan primitif operasional yang cocok untuk komponen tertentu — adalah kontrak sosial: praktik terbaik dengan jalan keluar, yang dijunjung oleh para arsitek platform yang menulis katalog pustaka standar. Compiler tidak menafsirkannya.

Invarian ini membahas apa yang disimpulkan compiler dari konten yang Anda tulis, dan cakupan itulah seluruh isinya. Segelintir kunci adalah milik Aggrega sendiri — dicadangkan, dengan nilai yang diterimanya tertulis di skema yang dipublikasikan — dan skema memeriksanya sebagaimana memeriksa bidang terdeklarasi lainnya. component.aggrega.ai/type adalah salah satunya: himpunan nilainya tertutup, dan dokumen yang membawa nilai di luarnya ditolak saat dimuat. Itu adalah platform yang menyatakan arti kuncinya sendiri, bukan compiler yang membaca makna ke dalam string yang Anda tulis, dan setiap kunci milik Anda tetap tidak diawasi persis seperti yang dikatakan invarian ini. Katalog yang mengklasifikasikan komponen pada sumbu yang tidak didefinisikan Aggrega menulis kunci labelnya sendiri, yang diterima skema dengan nilai string apa pun dan dibaca secara identik oleh setiap permukaan selektor.

Yang benar-benar ditegakkan oleh compiler itu sempit: validasi skema, parsing YAML, konstruksi graf, evaluasi templat, dan perutean teks biasa dari kontrak injeksi. Selebihnya adalah konvensi, yang ditegakkan saat penulisan katalog atau di dalam soket tata kelola Wasm yang bersifat opt-in.

Perusahaan yang menulis katalog internalnya sendiri secara eksplisit bebas melanggar konvensi pustaka standar. Compiler menerima apa pun yang mereka tulis asalkan lolos validasi skema. Arsitektur mendorong praktik terbaik; arsitektur tidak membangun penjara.

2. Kemurnian AOT: compiler tidak memiliki akses ke informasi runtime

Aggrega adalah compiler Ahead-Of-Time. Pada waktu kompilasi:

  • Compiler tidak melakukan autentikasi ke API cloud.
  • Compiler tidak mengambil alamat IP aktif, nama DNS, atau URL yang dihasilkan cloud.
  • Compiler tidak mengurai secret menjadi teks biasa — secret tetap menjadi penunjuk metadata di sepanjang Representasi Perantara (Intermediate Representation).
  • Compiler tidak mengetahui status runtime dari kluster atau layanan target.
  • Compiler tidak dapat mengambil data yang belum ada (endpoint pasca-provisioning, port yang ditetapkan secara dinamis, nama sumber daya yang dihasilkan otomatis).

Apa pun yang bergantung pada status runtime dinyatakan sebagai string penunjuk deterministik — nama DNS yang stabil, string interpolasi Terraform, referensi sumber daya CloudFormation — yang disediakan oleh Ops Recipe. Compiler meneruskan penunjuk tanpa menguraikannya. Lingkungan runtime (kluster, pengelola status IaC) yang menguraikan data fisik akhir.

Inilah Inversi Kontrol Sejati (True Control Inversion): developer menetapkan Injection Contract di Aggregate, compiler menghubungkan penunjuk deterministik lebih awal, dan lingkungan runtime menguraikan data fisik akhir. Persyaratan yang benar-benar membutuhkan penguraian saat runtime berada di pipeline Wasm milik Ops Recipe, bukan di inti compiler.

3. String Pipe: compiler tidak dapat menyimpulkan makna

Compiler tidak menafsirkan arti nilai yang dialirkan. Ketika Component A menggunakan Component B, compiler mengambil skalar yang dihasilkan Recipe milik Component B melalui provides — sebuah string, angka, atau boolean — dan mengalirkannya ke konteks Recipe milik Component A, yang diubah menjadi string secara deterministik di batas injeksi. Apakah nilai itu FQDN, hostname lokal, literal IP, nomor port, atau DSN berformat Wasm tidak ada bedanya: compiler tidak memvalidasi kemampuan rute, ketepatan protokol, atau kesesuaian semantik.

Ada dua konsekuensi:

  • Compiler tidak menebak tujuan komponen dari namanya. Komponen bernama database-production tidak dikenali sebagai database. Label tipe semantik seperti component.aggrega.ai/type (jika ada) adalah metadata buram yang digunakan untuk pencocokan label, bukan logika percabangan compiler.
  • Compiler tidak membedakan hostname dari nama database, dari nomor port, atau dari nilai buram sembarang. Semuanya adalah entri skalar dalam konteks injeksi, yang dikirimkan sebagai string.

Triad topologi — provides pada Recipe yang menghasilkan, uses pada Aggregate yang mengonsumsi, inject pada edge — adalah Injection Contract. Compiler mengevaluasi label dan meneruskan string; interpretasi adalah kontrak penulisan antara Recipe dan Component.

4. Tanpa infrastruktur hantu: compiler tidak pernah menciptakan komputasi atau fitur

Compiler tidak pernah secara diam-diam menyuntikkan komputasi, Features, anotasi, proxy perutean, atau sumber daya lain apa pun yang tidak dideklarasikan secara eksplisit oleh penulis. Pelanggaran kebijakan menghasilkan pagar pengaman yang lantang (Loud Guardrails) — build berhenti dengan galat spesifik yang memberi tahu penulis apa yang harus diperbaiki, di dokumen yang ia tulis — bukan mutasi diam-diam yang menimbulkan misteri infrastruktur saat debug.

Sumber daya masuk ke graf melalui deklarasi eksplisit pada waktu penulisan:

  • Aggregate milik developer (komponen, edge uses, lampiran Feature).
  • Lampiran Feature pada Release (tambahan di tingkat operator).
  • Ekspansi berbasis anotasi (Manifest mendeklarasikan binding anotasi → Feature; anotasi pada Component atau batas adalah deklarasi eksplisit).
  • Produksi sumber daya di tingkat Recipe: rendering source milik Recipe menghasilkan artefak utama; sintesis workload memancarkan bentuk deployment khusus provider (spesifikasi Pod, layanan Compose, dll.); entri artifacts: (inline atau dimuat dengan $import:) memancarkan manifest pendukung yang intrinsik bagi Recipe; Pembuatan Sumber Daya FeatureRecipe memancarkan sumber daya pendukung per Feature yang dipicu oleh lampiran Feature yang eksplisit.

Jalur di tingkat Recipe adalah deklarasi waktu penulisan yang berjarak satu langkah: penulis Recipe menulis source / workload / artifacts / valuesMapping terhadap kontrak Component, dan Aggregate milik developer memilih Components mana yang berpartisipasi. Sumber daya yang muncul di output hasil render dapat ditelusuri kembali ke deklarasi di Aggregate, di Release, atau di binding anotasi, atau ke penulisan Recipe yang dipilih oleh tipe komponen milik Aggregate.

Sintesis mengubah bentuk yang dideklarasikan penulis menjadi format output khusus provider. Spesifikasi Workload yang ditulis sebagai map kontainer dapat dirender sebagai spesifikasi Pod Kubernetes, blok layanan Compose, atau modul Terraform — transformasinya digerakkan oleh provider, tetapi sumber dayanya dapat ditelusuri kembali ke deklarasi Workload milik penulis.

Soket tata kelola membawa peran per lampiran, dan perannya — bukan jenis plugin — yang menentukan apa yang boleh dilakukan sebuah lampiran terhadap build. Plugin tata kelola yang dilampirkan dalam peran putusan — yang meninjau graf IR (ir-verdict) atau artefak hasil render (render-verdict) — dapat menolak build tetapi tidak dapat mengubahnya. Jika putusan semacam itu menginginkan sebuah sumber daya ditambahkan, putusan itu menggagalkan build dengan petunjuk perbaikan agar penulis sendiri yang menambahkan sumber daya tersebut; host membaca output putusan hanya sebagai terima-atau-tolak dan tidak pernah menerapkannya sebagai perubahan, sehingga penulisan ulang graf tanpa diminta agar patuh — persis infrastruktur hantu yang dilarang invarian ini — tidak dapat berasal dari peran putusan. Plugin tata kelola yang dilampirkan dalam peran transformasi (label-transform atau annotation-transform) adalah pengecualian yang sempit dan eksplisit: operator yang melampirkannya — secara opt-in, melalui konfigurasi plugins.governance di workspace — telah mendeklarasikan transformasi itu, sehingga perubahan yang dibuatnya adalah deklarasi eksplisit, dengan kedudukan yang sama dengan ekspansi berbasis anotasi, bukan injeksi diam-diam. Pembedanya adalah undangan: putusan yang tidak diminta tidak boleh menulis ulang build, sedangkan transformasi yang dilampirkan secara eksplisit boleh, karena operator memintanya. Karena transformasi membentuk output hasil render, transformasi disematkan di lockfile seperti setiap plugin yang membentuk output — transformasi yang berlaku ditetapkan saat pull, sehingga mengubahnya berarti melakukan pull ulang, bukan pergeseran diam-diam antar-build; putusan tidak membentuk output apa pun dan tidak disematkan.

5. Aggregate adalah permukaan penulisan; Release tidak dapat mendeklarasikan values:

Skema Release secara mekanis melarang blok values:. Operator tidak dapat menulis values pada Component atau Feature dari sebuah Release. Ini adalah penegakan skema di tingkat JSON Schema — bukan kontrak sosial, bukan konvensi — dan bersifat lantang: setiap dokumen entitas divalidasi terhadap skema jenisnya saat dimuat, sehingga Release yang membawa values: menghentikan build dengan diagnostik yang menyebutkan file dan kunci yang bermasalah, alih-alih diabaikan diam-diam.

Ini tidak berarti nilai identik di semua lingkungan. Jalur yang didukung untuk variasi per lingkungan adalah Pengangkatan Parameter (Parameter Hoisting):

  1. Developer mengekspos bidang bertipe parameters.* di Aggregate.
  2. Template values milik Component merujuknya: storage_size: "{{ .parameters.db_size }}".
  3. Release memenuhi parameter tersebut: parameters: { db_size: "100Gi" }.
  4. Output hasil render mencerminkan nilai khusus lingkungan.

Aggregate tetap menjadi Satu-satunya Sumber Kebenaran tentang nilai mana yang diekspos untuk variasi per lingkungan (deklarasi parameters) dan bagaimana nilai itu mengalir ke nilai komponen (referensi template). Release memenuhi; Release tidak menimpa.

Dua batasan lain melindungi invarian yang sama:

  • Ketika sebuah Release menggunakan extends, mendeklarasikan penunjuk aggregate: dilarang oleh skema. Release turunan harus men-deploy Maksud Developer (Developer Intent) yang sama dengan induknya.
  • Release tidak dapat memperkenalkan komputasi yang tidak dideklarasikan Aggregate, dan tidak dapat mengalihkan target edge yang dideklarasikan developer. Di dalam soket yang dideklarasikan Architect, Release boleh menghubungkan dan mengonfigurasi edge antar-komponen yang sudah ada: Release mengatur infra per edge pada edge yang dihubungkan developer, atau menghubungkan edge menuju soket yang dideklarasikan tetapi belum terikat ke komponen yang sudah ada. Release tidak dapat mendeklarasikan values per edge (itu tetap di Aggregate), mengikat soket yang tidak dideklarasikan usesSchema milik Component, atau mengarahkan edge ke komponen yang tidak ada — masing-masing menghentikan build. Perhatikan deklarasi mana yang dimaksud klausa tengah itu: soket harus muncul di usesSchema milik Component katalog. Penulis Aggregate boleh menamai soket yang tidak dideklarasikan tipe komponennya, dan permukaan Release sengaja tidak dibuka dengan cara yang sama — operator menghubungkan dan mengonfigurasi di dalam sebuah arsitektur, bukan menciptakannya.

Konfigurasi koneksi per edge dicakup ke konsumen: values dan infra yang dibawa pada edge hanya muncul di konteks render node yang menulis edge tersebut, tidak pernah di konteks target. Karena itu, output hasil render sebuah komponen bersifat invarian terhadap koneksi yang dibuat komponen lain kepadanya — menghubungkan atau mengonfigurasi edge ke sebuah target tidak pernah mengusik apa yang dirender Recipe milik target. Satu-satunya tempat koneksi itu terlihat adalah Feature yang dilampirkan ke target: FeatureRecipe miliknya dapat membaca komponen mana yang menggunakan target, sehingga sumber daya yang dipancarkannya — misalnya kebijakan yang mengizinkan tepat pemanggil yang dideklarasikan — mengikuti penghubungan, sementara output target sendiri tidak. Bahkan di sana, values dan infra per edge tetap berada pada konsumen.

6. Batas ABI WebAssembly: kecerdasan khusus domain berada di Wasm

Biner host Go tidak berisi logika khusus cloud atau infrastruktur sama sekali. Semua kecerdasan khusus domain, rendering template, dan pemformatan berada secara ketat di dalam plugin WebAssembly yang dijalankan oleh runtime Wazero yang tertanam. Host Go mengorkestrasi pipeline dan meneruskan payload melintasi ABI ke guest Wasm sebagai penunjuk memori, dalam encoding yang dibawa setiap soket.

Ada dua akibat wajar:

  • Logika khusus Provider (rendering khusus Helm, pemformatan khusus Terraform, penggabungan khusus Compose) tidak pernah berada di inti compiler Go. Compiler menguraikan nama provider yang dideklarasikan Recipe di spec.capability menjadi Plugin rendering provider yang melayaninya dan mengirimkan node ke plugin tersebut; penerjemahannya sendiri berjalan sepenuhnya di guest Wasm. Host tidak menyimpan kode Go per provider untuk provider standar, sehingga tidak ada apa pun di dalam proses untuk dijadikan cadangan — nama provider yang tidak terurai ke Plugin mana pun yang melayaninya menghentikan build alih-alih merender suatu default bawaan.
  • Logika kebijakan (aturan keamanan, pemeriksaan kepatuhan, perhitungan FinOps) tidak pernah berada di inti compiler Go. Kebijakan berada di soket tata kelola Wasm yang dipilih secara opt-in oleh perusahaan — plugin yang dilampirkan dalam peran putusan (ir-verdict / render-verdict) untuk menerima atau menolak build, atau dalam peran transformasi (label-transform / annotation-transform) untuk membentuk label atau anotasi.

Batas ABI menjaga inti Go tetap ringkas, dapat diaudit, dan tidak bergantung pada cloud. Mengganti logika rendering sebuah provider adalah penggantian artefak Wasm, bukan kompilasi ulang Aggrega itu sendiri.

7. Pemisahan kepentingan (pembagian empat domain) — panduan, bukan penjara

Panduan desain Aggrega memisahkan penulisan ke dalam empat domain:

  • Developer Intent — Aggregate.
  • Platform Architect — entitas katalog Component dan Feature.
  • Platform Ops — Recipe, FeatureRecipe, Plugin (termasuk Plugin rendering provider).
  • Platform Operator — Manifest, Release.

Deployment tipikal yang berfungsi dengan baik mengikuti pembagian ini: developer menulis maksud aplikasi, bukan infrastruktur fisik; tim Ops menulis infrastruktur fisik, bukan logika aplikasi. Aggrega dirancang untuk digunakan dengan cara ini, dan dokumentasi resmi, contoh, serta katalog pustaka standar ditulis mengikuti pembagian ini.

Pembagian empat domain adalah panduan dan kerangka desain, bukan penegakan oleh compiler. Compiler (sesuai Invarian 1) tanpa opini sendiri. Pengguna bebas untuk:

  • Menggabungkan peran (satu orang menulis Aggregates sekaligus Recipes).
  • Mencampur kepentingan (Architect meng-hardcode label kepatuhan langsung pada Components core/* ketika katalog perusahaan menuntutnya).
  • Melintasi batas domain (developer menggunakan Pengangkatan Parameter untuk menyuntikkan kepentingan infrastruktur ke dalam Aggregate ketika kode lama menuntutnya).

Compiler menerima pola penulisan apa pun yang lolos validasi skema. Arsitektur mendorong praktik terbaik; batasan di tingkat skema (seperti larangan values: pada Release di Invarian 5) adalah satu-satunya penyeberangan domain yang benar-benar ditolak compiler. Semua pemisahan lainnya adalah kontrak sosial yang dijaga oleh penulis katalog dan, jika perusahaan memilih opt-in, oleh soket tata kelola Wasm.

8. Output deterministik

Dengan input yang identik, compiler menghasilkan output yang identik byte demi byte. Dua kompilasi atas Aggregate + Release + Manifest yang sama terhadap katalog yang sama menghasilkan artefak hasil render yang sama persis byte demi byte.

Inilah kontrak yang diandalkan alat GitOps dan alur kerja tinjauan berbasis diff. Pull request yang tidak mengubah input seharusnya tidak menghasilkan diff apa pun pada output hasil render. Pull request yang mengubah input seharusnya hanya menampilkan diff yang ditimbulkan oleh perubahan itu — tanpa pengurutan ulang palsu, tanpa perubahan stempel waktu, tanpa artefak iterasi map.

Output deterministik dijaga melalui tiga disiplin:

  • Map berurutan menurut penulis: setiap map yang urutan iterasinya dapat memengaruhi output hasil render menggunakan kontainer map berurutan, sehingga iterasi mengikuti urutan deklarasi penulis, bukan urutan hash.
  • Tidak ada konten berbasis jam atau acak dalam artefak hasil render kecuali penulis secara eksplisit menyuntikkannya melalui input template.
  • Rendering bersifat murni: pemanggilan guest Wasm yang sama dengan input yang sama menghasilkan output yang sama.

Flag --trace milik compiler (lihat language-reference/cli/aggrega-build.md) memberi penulis dan operator permukaan verifikasi untuk invarian ini. Dua kompilasi atas input yang sama dengan --trace aktif menghasilkan dump trace yang identik byte demi byte; diff apa pun pada suatu pass menunjukkan letak regresi. Determinisme bukan hanya properti saat rilis — determinisme dapat diamati di setiap status perantara compiler melalui tata letak trace per node.

Output deterministik adalah kontrak yang membuat Aggrega aman digunakan sebagai sumber kebenaran dalam siklus GitOps.

Cakupan invariansi di seluruh tingkat resolusi

Jaminan output identik byte demi byte mencakup artefak yang disematkan di lockfile — entitas yang diuraikan melalui artefak registry yang digest-nya dicatat lockfile (tingkat registry dalam model resolusi entitas tiga tingkat). Ketika build membaca file yang dinamai Release berdasarkan jalur (jalur lokal yang diawali ./ atau ../) atau entitas di direktori katalog workspace (catalog_dirs:, pada tingkat workspace dan cache), invariansi bergantung pada file tersebut tetap tidak berubah antar-build. Lockfile mencatat entitas di direktori katalog workspace berdasarkan digest dokumennya dan file yang dideklarasikannya, sehingga build berhenti pada entitas yang berubah sejak pull alih-alih merendernya — dengan satu pengecualian: Recipe atau FeatureRecipe yang dinamai Manifest dengan referensi yang juga merupakan nama sebuah Component atau Feature dicatat di bawah referensi itu sebagai Component atau Feature tersebut, sehingga input-nya hanya ditahan oleh pin di sebelahnya dalam lock, dan suntingan pada dokumennya sendiri tidak terdeteksi. Menjaga file tetap seperti semula adalah tanggung jawab sistem kontrol sumber (biasanya Git).

Referensi jalur lokal yang file dasarnya berubah di antara dua kompilasi menghasilkan diff yang sah pada output hasil render meskipun bentuk input compiler tidak berubah — jaminan output deterministik tetap terjaga (input byte yang sama → output byte yang sama), tetapi input-nya berbeda karena file lokal berubah. Katalog yang membutuhkan invariansi antar-build untuk setiap sumber menarik artefak dari registry ke cache yang disematkan lockfile alih-alih membacanya dari jalur lokal atau direktori workspace; lockfile adalah jangkar identitas byte.