Taksonomi data dan komposisi
Taksonomi data terpadu dan aturan komposisi
Untuk menetapkan skema yang dapat diprediksi dan menghilangkan friksi kognitif, platform menggunakan tepat lima kata kunci yang dipahami secara universal dan struktur YAML yang sepenuhnya berbasis map (kamus), dengan map alih-alih array bersarang di akar struktur.
1. Standar map 5 kata kunci dan simetri skema total
Kosakata struktural langsung: Aturan mendasar desain skema adalah bahwa struktur data akar harus berupa kata kunci tunggal yang struktural. Meskipun penggunaan frasa bahasa Inggris percakapan (seperti depends_on atau runs_within) dapat membuat DSL YAML terbaca lebih alami bagi pengembang, hal itu menambah kompleksitas struktural saat memetakan kunci tersebut ke templat Go yang programatis. Untuk mempertahankan pemetaan variabel 1:1 secara langsung dan mencegah fragmentasi bahasa spesifik domain (DSL), skema JSON dari entitas inti katalog (Component, Feature) menunjukkan simetri struktural yang hampir total, yang digerakkan oleh himpunan inti kata kunci struktural yang sama yang digunakan di seluruh slot instans yang ditulis. Features kredensial (berlabel feature.aggrega.ai/kind: secret) berbagi paradigma yang identik ini — tidak ada skema terpisah untuk secret.
parameters(Kontrak lingkungan global)- Cakupan: Didefinisikan di akar
Aggregate; dipenuhi olehRelease(CI/CD) secara inline di bawahparameters:atau melaluiparameters: { $import: <path> }yang menunjuk ke file parameter eksternal. - Makna: Argumen eksternal yang secara dinamis mengubah keadaan kognitif atau logis aplikasi di berbagai lingkungan (misalnya, mengubah
workers: 2menjadiworkers: 10). Mendukung kontrak bertipe (lihat data-pillars untuk sintaksis kontrak bertipe yang lengkap) yang divalidasi sebelum interpolasi. Untuk alur kerja GitOps yang menyimpan nilai parameter dalam file terpisah, Release menggunakan bentuk$import:; compiler memuat konten file dan menggantikan map inlineparameters:. Pelapisan multi-file dinyatakan melalui rantaiextends:pada Release.
- Cakupan: Didefinisikan di akar
values(Niat kognitif - Dimiliki pengembang)- Cakupan: Digunakan secara seragam di dalam
componentsdan lampiranfeatures-nya di dalamAggregate, termasuk Features kredensial. - Makna: Keadaan kognitif inti, logika bisnis, dan konfigurasi operasional. Buram bagi compiler Go tetapi divalidasi secara ketat oleh deklarasi
schema:terpadu milik katalog (bentuk ringkas atau JSON Schema 2020-12).
- Cakupan: Digunakan secara seragam di dalam
uses(Topologi struktural - Keadaan deklaratif)- Cakupan: Digunakan secara seragam di dalam
componentsdan lampiranfeatures-nya di dalamAggregate, termasuk Features kredensial. - Makna: Pernyataan fakta deklaratif yang mendefinisikan edge jaringan dan dependensi (misalnya, “Agen ini menggunakan database ini”). Di-parse secara native oleh compiler Go untuk menggambar graf representasi perantara (IR). Divalidasi oleh deklarasi
usesSchematerpadu milik katalog untuk menegakkan keamanan tipe lintas node.
- Cakupan: Digunakan secara seragam di dalam
infra(Realitas fisik - Dimiliki Ops)- Cakupan: Digunakan secara seragam di dalam
componentssebuah batas dan lampiranfeatures-nya di dalamRelease. - Makna: Jejak fisik dan ukuran mekanis yang diinjeksikan selama Late Binding (misalnya,
cpu_limit: "4",port: 5432). Instans komponen Aggregate dan lampiranfeatures-nya tidak menyertakan fieldinfradan, bersama denganadditionalProperties: false, menolakinfrasaat validasi skema. Divalidasi oleh deklarasischema:terpadu milik katalog.
- Cakupan: Digunakan secara seragam di dalam
inject(Kontrak pengiriman - Perintah imperatif)- Cakupan: Digunakan pada instans komponen, di dalam definisi target eksplisit di dalam
uses, dan padafeaturesyang dilampirkan, termasuk Features kredensial. - Makna: Perintah eksplisit dan imperatif yang menentukan niat pengiriman (misalnya, “Compiler, injeksikan nilai yang dipetakan ini sebagai variabel lingkungan”). Ia menetapkan kontrak abstrak (
env,file,arg, atau mekanisme kustom) untuk output fisik, endpoint yang telah di-resolve, atau kredensial yang diambil, sementara mekanika fisik tentang bagaimana tepatnya mount itu dieksekusi didelegasikan sepenuhnya ke Recipe Ops yang mendasarinya. Setiap mekanisme adalah daftar entri ([{ in: API_HOST, from: "host" }]), yang masing-masing menamai pengenal lokalnya denganin:dan membawa tepat satu darifrom:atauvalue:.
- Cakupan: Digunakan pada instans komponen, di dalam definisi target eksplisit di dalam
.context(Pipa metadata generik)- Cakupan: Diinjeksikan secara diam-diam oleh compiler ke dalam templat
RecipeOps. - Makna: Membawa apa yang dirakit compiler untuk node tersebut dari bagian graf lainnya (seperti
.context.uses), yang diteruskan langsung ke mesin templat Ops.
- Cakupan: Diinjeksikan secara diam-diam oleh compiler ke dalam templat
Realitas pemetaan 1:1
Dengan mengganti kata depan percakapan dengan kata kunci infrastruktur yang ketat, pemetaan 1:1 langsung tercapai. Engineer Ops tidak perlu menerjemahkan tata bahasa; mereka cukup mereferensikan kunci yang persis ditulis pengembang.
Bentuk struktural: map di akar, array di payload. Blok topologi akar — components, features, aggregates, subsystems, boundaries — adalah map YAML dengan kunci yang ditulis pengguna yang berfungsi sebagai ID instans yang stabil. Array tidak valid di posisi-posisi ini; kunci map adalah identitas yang digunakan compiler untuk referensi silang (target: my-db), konstruksi node graf, dan resolusi Manifest. Di dalam blok payload yang buram (values, infra, parameters), array sepenuhnya diizinkan — pengembang dapat menulis tools_allowed: ["sql", "web"] atau hostnames: ["stripe.com", "twilio.com"] di dalam values sebuah Component. Skema Aggregate mendeklarasikan blok payload ini sebagai additionalProperties: true, sehingga blok tersebut buram bagi compiler Go dan divalidasi sepenuhnya oleh deklarasi schema: yang tertanam di katalog. Hal ini menempatkan volatilitas framework (bentuk API AI baru, format payload cloud-native baru) di dalam domain katalog tempat ia dapat berkembang secara independen, sementara compiler Go tetap hanya menggunakan kunci yang dapat dialamatkan di akar struktural.
2. Aliran informasi: siapa, kapan, dan untuk apa?
Untuk mencegah tabrakan namespace templat dan kebocoran konfigurasi infrastruktur fisik yang tidak disengaja ke dalam logika kognitif aplikasi, arsitektur secara eksplisit memisahkan data menjadi enam aliran yang berbeda:
- Aliran 1: Injeksi lingkungan (
parameters): Pipeline CI/CD menginjeksikan realitas deployment. Compiler memvalidasi setiap nilai yang disediakan Release terhadap kontrak bertipeparameters:, lalu menginterpolasi variabel templat Go yang telah di-resolve sebelum menjalankan validasi skemavalues:di hilir.- Penggunaan yang direkomendasikan:
parametersdicadangkan untuk logika kognitif aplikasi yang berbeda antar-lingkungan (misalnya,LOG_LEVEL=debug,ENABLE_BETA=true). Ukuran operasional dan urusan infrastruktur fisik — replika, batas CPU, ARN AWS, hostname ingress — mengalir melalui blokinframilikReleasedan overlay batas, sehinggaAggregatemilik pengembang tetap berfokus pada niat aplikasi. - Jalan keluar pragmatis: Untuk tim yang lebih kecil, pembuatan prototipe cepat, atau integrasi CI/CD lama yang pemisahan ketatnya tidak praktis,
parametersdapat membawa konfigurasi lingkungan global ke seluruh stack. Compiler menerima apa pun yang lolos validasi skema; rekomendasi di atas adalah kontrak sosial, bukan aturan compiler.
- Penggunaan yang direkomendasikan:
- Aliran 2: Niat kognitif aplikasi (
valuesdalam Components): Mendefinisikan logika intrinsik aplikasi. Deklarasischema:milik Component (bentuk ringkas atau JSON Schema 2020-12) menyediakan pemeriksaan tipe dan validasi yang ketat untuk payload ini, memberikan umpan balik “Shift-Left” langsung kepada pengembang dan memastikan konfigurasi yang diminta cocok dengan API infrastruktur yang mendasarinya. - Aliran 3: Niat operasional Feature (
valuesdalam Features): Di dalam Aggregate, pengembang meminta kapabilitas infrastruktur yang perilakunya merupakan niat aplikasi, dan meminta kredensial bertipe ketat, tanpa mengubah kode internal. Feature yang semua inputnya bersifat operasional tidak membawavaluespengembang: tim operasi melampirkannya di Release, denganinfra-nya (Aliran 4). - Aliran 4: Ukuran infrastruktur fisik (
infra): Dengan sepenuhnya melewati pengembang, ukuran fisikinfradiproyeksikan secara eksplisit dariReleaseyang spesifik lingkungan langsung ke Components berlingkup lokal dan Features yang dilampirkan padanya, termasuk Features kredensial. Untuk menghindari tabrakan validasi skema tertutup akibat penyiaran kamus apa adanya, ukuraninfradilokalkan secara ketat ke komponen eksplisit yang menargetkannya. Ini menjaga batas komputasi, replika, dan kebutuhan sumber daya mekanis tetap di domain Ops. - Aliran 5: Anotasi berjenjang (Metadata kontekstual): Data kontekstual yang luas (seperti domain operasional, namespace, atau kode penagihan) ditangani melalui anotasi berjenjang, sehingga mencegah polusi penyiaran
infra. Anotasi ini dipisahkan ke dalam bucket berdasarkan asalnya, dan penggunaan yang dimaksudkan untuk setiap bucket di bawah ini adalah kontrak sosial: templat Recipe dapat membaca ketiganya, dan compiler tidak menegakkan pemisahan tersebut (lihat labels-and-annotations):.context.annotations.release(Batas Domain 4): Digunakan secara eksklusif untuk mengatur realitas fisik. Ops secara eksplisit merutekan anotasi ini ke fieldinfralokal yang ketat melalui templat Go (misalnya, memetakan namespace regional ke komponen komputasi)..context.annotations.aggregate(Subsistem Domain 1): Digunakan secara eksklusif untuk mengatur logika kognitif dan operasional. Anotasi ini dirutekan secara eksplisit ke payloadvalueskomponen (misalnya, menurunkan kode penagihan tim secara berjenjang hingga ke konfigurasi aplikasi)..context.annotations.catalog(Katalog Domain 2): Sifat intrinsik yang tidak dapat diubah yang ditulis oleh arsitek, terutama digunakan untuk evaluasi kebijakan Wasm secara programatis.
- Aliran 6: Pipa metadata (
.context): Menerapkan persyaratan perusahaan global (tag SOC2) langsung ke templat infrastruktur fisik.
3. Abstraksi jaringan: konvensi “Zero-Port”
- Praktik terbaik: Pengembang sebaiknya menghilangkan port dari
Aggregate. Recipe Ops menangani perutean internal secara dinamis. - Jalan keluar: Jika kode internal aplikasi tidak dapat diubah, arsitek platform secara eksplisit mengekspos field
portdi deklarasischema:. Catatan arsitektur: Konvensi “Zero-Port” adalah contoh paling menonjol dari Pemisahan Kepentingan platform yang lebih luas. Filosofi yang persis sama — mengabstraksikan mekanika fisik dari pengembang — berlaku untuk permintaan CPU, batas memori, domain operasional, dan ukuran disk. Setiap kali batasan infrastruktur fisik harus bocor ke payload aplikasi pengembang (karena kode lama atau persyaratan perangkat keras yang ketat), batasan itu harus selalu diatur oleh “jalan keluar” eksplisit di deklarasischema:milik arsitek, yaitu deklarasi yang menjadi acuan validasi payload pengembang.
Nama “Zero-Port” mewakili konvensi ini; prinsipnya berlaku umum untuk setiap batasan infrastruktur fisik yang di-hardcode oleh aplikasi lama. Skema di bawah ini menggunakan tcp_keepalive_seconds sebagai contoh kerja — pengaturan waktu kernel/jaringan yang diharapkan aplikasi di lapisan soket — karena field ini jelas berada di sumbu kebocoran infra.
Skema (Domain 2):
values: image: { type: string, required: true } # The architect explicitly allows the developer to declare a hardcoded constraint tcp_keepalive_seconds: { type: integer, min: 10, max: 300 }YAML pengembang (Domain 1):
components: legacy-payment-engine: type: core/java-tomcat:1.0.0 values: image: "corp/payments:v4" tcp_keepalive_seconds: 120 # The infrastructure must adapt to the app, not vice versaPerilaku compiler: Compiler Go meneruskan tcp_keepalive_seconds: 120 ke dalam graf IR. Recipe Ops kemudian membaca {{ .values.tcp_keepalive_seconds }} untuk mengonfigurasi spesifikasi pod Kubernetes atau idle-timeout load balancer milik penyedia cloud, sehingga berhasil menjembatani kesenjangan sistem lama tanpa melanggar skema.
4. Kontrak injeksi dan map yang telah di-resolve sebelumnya
Di antara lima kata kunci struktural, inject memiliki bentuk yang berbeda dari saudara-saudaranya. parameters, values, uses, dan infra adalah keadaan deklaratif — pengembang menulis fakta tentang apa aplikasi itu dan apa dependensinya. inject adalah perintah imperatif — pengembang menentukan bagaimana sebuah nilai harus dikirim ke container yang sedang berjalan, dengan memetakan sumber data abstrak (kunci provides milik target, nilai komponen itu sendiri, respons vault dari Feature kredensial) ke mekanisme pengiriman konkret (env, file, arg, atau mekanisme kustom yang dideklarasikan Component).
Pemisahan ini bersifat struktural. Aggregate milik pengembang menyatakan “injeksikan host database sebagai variabel lingkungan DB_HOST” tanpa menyebut alamat fisik database, path vault penyimpanan secret, atau format hostname penyedia cloud. Recipe Ops menerima string yang telah di-resolve melalui .context.inject dan menggunakannya tanpa menulis rantai pencarian.
Map yang telah di-resolve sebelumnya. Selama perenderan, compiler me-resolve setiap sumber injeksi — literal self-inject dan referensi from: terhadap provides milik komponen itu sendiri, referensi lintas komponen melalui uses[].inject, intersepsi injectMapping dari FeatureRecipe — ke dalam satu kamus datar di .context.inject. Saat templat valuesMapping milik Recipe dasar dijalankan, setiap kunci injeksi sudah membawa nilai string akhirnya. Recipes mengiterasi map secara langsung ({{ range $k, $v := .context.inject.env }}) tanpa menelusuri rantai resolusi.
Nama yang diberikan pengembang untuk nilai milik komponen itu sendiri. Ketika Component mendeklarasikan spec.inject, blok inject: milik pengembang sendiri memilih nama yang digunakan nilai dan provides milik komponen itu sendiri saat mencapai pipa pengiriman. Kompiler memberi tahu Recipe, di .context.self_inject, satu nilai milik sendiri yang dibaca templat setiap entri — per mekanisme, setiap nama dipetakan ke provides.<key>, ke values.<key> untuk templat yang membaca tepat satu nilai milik sendiri dan tidak ada yang lain, atau ke string kosong — dalam bentuk yang diambil nama-nama sebuah koneksi di .context.uses.<alias>.inject. Konvensi katalog pustaka standar untuk Recipe yang menjalankan image pengembang adalah memperlakukan nama yang sebaliknya akan dipilihnya untuk nilai milik komponen itu sendiri sebagai nilai bawaan, dan menyediakan nilai milik sendiri dengan nama bawaannya hanya jika belum ada entri yang memetakan ke nilai itu. Itu adalah konvensi katalog, bukan aturan kompiler: katalog perusahaan dapat menyediakan nilai milik komponennya sendiri dengan cara apa pun yang dipilihnya. Kompiler membaca peta dari teks yang ditulis pengembang dan tidak memberikan makna apa pun pada nama-nama tersebut.
Spesifikasi lengkap kontrak injeksi — semantik konteks keadaan ganda, aturan tabrakan kunci, model intersepsi FeatureRecipe, dan contoh kerja — ada di topology-triad.
5. Mesin templat (DX Ops)
Engineer Platform Ops menulis templat terjemahan dan membutuhkan kekuatan penuh templating infrastruktur standar tanpa bahasa templat proprietary. Templat Aggrega adalah Go text/template:
- Tanpa string “ajaib”: Compiler mempertahankan kunci map pengembang apa adanya. Ops mengakses fitur dengan aman melalui pengindeksan map Go standar:
{{ (index .features "public-route").infra.hostname }}. - Pustaka Sprig: Compiler secara native mendaftarkan pustaka Sprig yang menjadi standar Helm, sehingga memberikan akses langsung ke pipeline seperti
| default,| quote, dan| toYaml. - Fragmen MappingLibrary: Fragmen pemetaan yang digunakan ulang oleh beberapa Recipes berada di sebuah MappingLibrary dan ditarik ke setiap Recipe dengan
$import:. Helper templat chart Helm (include,tpl,required,warn) tidak didaftarkan; sprig-functions mencantumkan apa saja yang didaftarkan.
6. Aturan komposisi: Aggregates, subsistem, dan Components
- Pengelompokan logis (array
subsystems): Pengembang dapat menerapkan metadata logis (kepemilikan tim, label kepatuhan) dan fitur lintas sektoral ke puluhan komponen sekaligus menggunakansubsystems. Subsistem bertindak sebagai folder rekursif pada bidang logis/niat, menurunkanannotationssecara berjenjang ke bucket.context.annotations.aggregatedan melampirkan fitur ke semua komponen yang ada di dalamnya tanpa mendikte batas fisik. Fitur tingkat subsistem mengikuti skema yang sama dengan fitur tingkat komponen (mendukungtype,values,uses,inject) karena berada di Domain 1 (Niat pengembang). Compiler meratakan fitur subsistem ke dalam daftar fitur setiap komponen yang terkandung saat finalisasi graf, menempatkannya setelah fitur milik komponen itu sendiri dan sebelum fitur apa pun yang dilampirkan Release dalam urutan eksekusi.
subsystems: finance-module: annotations: "billing.corp.com/team": "payments" features: audit-logging: type: core/audit-logger:1.0.0 values: { log_level: "verbose" } components: ledger-api: type: core/python-worker:1.0.0 ledger-db: type: core/postgres:1.0.0- Aggregates komposit DIDUKUNG (Pola modul): Aggregates berfungsi sebagai Aggregate akar yang dibangun oleh sebuah Release sekaligus modul yang dapat digunakan ulang. Aggregate induk dapat mendeklarasikan Aggregate anak persis seperti sebuah komponen, dengan meneruskan
parameterske dalamnya. Untuk mencegah keterikatan yang erat, Aggregates anak mengekspos kontrakexportedComponents:, yang menetapkan nama antarmuka publik yang stabil. Induk menjangkau komponen modul hanya melalui antarmuka ini: targetuses:menyebut modul dan salah satu alias yang diekspornya, dan compiler menyambungkan edge ke komponen internal yang disebut alias tersebut, sedangkan target yang menjangkau ke dalam modul dengan nama lain apa pun menghentikan build, dengan menyebut modul dan alias yang diekspornya. Sebuah modul dapat juga mengekspor ulang komponen yang diekspor dari modul bersarang di bawah nama antarmukanya sendiri — opsional dengan mengganti namanya — dan compiler me-resolve rantai ekspor ulang tersebut secara transitif hingga ke node internal yang mendasarinya, sehingga modul dapat tersusun hingga kedalaman berapa pun tanpa induk perlu tahu seberapa dalam target bersarang. Target yang tidak ter-resolve ke node internal mana pun tetap menghentikan build secara tegas, dan rantai ekspor ulang yang kembali ke dirinya sendiri ditolak alih-alih diikuti tanpa henti.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: child-database-module version: 1.0.0spec: components: internal-pg-primary: type: core/postgres:1.0.0
exportedComponents: # The Public Contract (Written once by the module author) primary_db: "internal-pg-primary"apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: my-catalog/child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_db-
Components tidak dapat berisi subkomponen: Components adalah blok bangunan atomik. Komposisi terjadi di tingkat Aggregate melalui subsistem dan sub-aggregate. Jika sebuah aplikasi membutuhkan beberapa container fisik (seperti API + sidecar), penyarangan fisik itu berada di dalam templat Recipe Ops, bukan di definisi Component.
-
Satu layanan koheren per Component — batas beban kerja tunggal: Sebuah Component memodelkan satu layanan koheren — satu layanan yang diekspos, atau beban kerja dari satu layanan beserta beban kerja pembantunya yang hanya internal. Label
component.aggrega.ai/typemiliknya menamai bentuk operasional layanan tunggal itu. Beberapa beban kerja fisik di dalam satu Component tidak masalah jika membentuk satu produk koheren tanpa bagian yang dapat digunakan secara independen: layanan yang chart-nya menjalankan controller ditambah webhook ditambah injector tetaplah satu Component. Ujiannya bukan multi-beban-kerja; ujiannya adalah kegunaan independen.Batas ditarik di tempat sebuah bundle berisi sesuatu yang dapat digunakan (
use) secara bermakna oleh komponen lain secara mandiri — terutama infrastruktur asing seperti database, cache, atau message broker yang sudah dimodelkan Aggrega sebagai Component tersendiri. Bundle semacam itu bukan satu Component; ia adalah Modul sub-aggregate — polaspec.aggregates+exportedComponentsyang ditunjukkan di atas — yang menyusun satu Component per layanan, sehingga setiap layanan menjadi node yang dapat dialamatkan dengan tipe, edge, serta permukaan kebijakan dan penskalaannya sendiri.Heuristiknya, dinyatakan sebagai aturan yang tegas: Apakah chart berisi sesuatu yang dapat digunakan secara bermakna oleh komponen lain secara mandiri, atau yang sudah memiliki Component di Aggrega? Jika ya, modelkan sebagai stack — Modul sub-aggregate yang menyusun Components per layanan. Jika hanya melayani satu layanan ini, modelkan sebagai satu Component.
Membungkus seluruh produk multilayanan sebagai satu Component yang buram adalah antipola yang terdokumentasi. Compiler bersifat tanpa opini sendiri dan akan menerimanya — ia merender apa pun yang lolos validasi skema — tetapi pustaka standar justru menyusun Components per layanan ke dalam sebuah Modul, karena pembungkusan monolitik menyembunyikan layanan yang dapat dimodelkan secara independen dari topologi, dari selector, dan dari kebijakan serta penskalaan per layanan. Disiplin granularitas ini adalah kontrak sosial — lihat
../language-reference/vocabulary/social-contracts.md(granularitas Component).
7. Cakupan default — pengungkapan pengelompokan secara bertahap
subsystems (di Aggregate) dan boundaries (di Release) adalah konstruksi pengelompokan, tetapi pengembang tidak perlu mendeklarasikannya sejak awal. Setiap entitas menawarkan dua bentuk penulisan, dan keduanya saling eksklusif: komponen ditulis dengan dikelompokkan di bawah cakupan bernama, atau komponen ditulis langsung di tingkat teratas — tidak pernah keduanya sekaligus. Dokumen yang mendeklarasikan components tingkat teratas sekaligus cakupan bernama akan berhenti saat dimuat dengan kesalahan amplop.
Untuk bentuk datar (components tingkat teratas), kompiler menyintesis cakupan default yang nyata saat memuat dan memasukkan komponen tingkat teratas ke dalamnya, sehingga setiap tahap berikutnya melihat struktur seragam yang memiliki cakupan. Cakupan hasil sintesis bukanlah kontainer tersembunyi: ia adalah node asli di IR yang ditandai asal-usulnya, dan dapat dibedakan dari cakupan yang secara eksplisit dinamai default oleh pengembang. Cakupan ini hanya disembunyikan di tempat penulis membaca jalur — diagnostik dan pengalamatan menampilkan jalur berbentuk akar .spec.components[…] yang benar-benar ditulis pengembang.
- Aggregate datar (komponen tingkat teratas): Komponen ditulis di bawah
spec.componentstanpasubsystems. Kompiler memasukkannya ke subsistemdefaulthasil sintesis saat memuat. Anotasi cakupan subsistem dan fitur tingkat subsistem hanya berlaku untuk subsistem yang dideklarasikan; bentuk datar tidak membawa satu pun. - Release datar (komponen tingkat teratas): Komponen ditulis di bawah
spec.componentstanpaboundaries. Kompiler memasukkannya ke batasdefaulthasil sintesis yang keluarannya datar — artefak langsung ditempatkan di bawahdist/(per penyedia:dist/compose/,dist/helm/, …), tanpa segmen nama batas. Ini adalah kasus paling sederhana:aggrega buildatas target Compose datar atau satu kluster tanpa menamai batas. (Batas yang dideklarasikan pengembang dan dinamaidefaultadalah batas bernama biasa dan, tanpadirectory:miliknya sendiri, menghasilkan keluaran kedist/boundaries/default/seperti batas lainnya.) - Jalur peningkatan: Ketika arsitektur datar berkembang menjadi arsitektur yang memerlukan pengelompokan (namespace berbeda, pengelompokan logis terpisah, deployment multi-batas), pengembang memindahkan komponen tingkat teratas ke
subsystemseksplisit, atau Ops memperkenalkanboundarieseksplisit. Karena kedua bentuk saling eksklusif, ini adalah perpindahan dari bentuk datar ke bentuk bercakupan — bukan campuran keduanya — dan identitas node dipertahankan selama transisi.
Alasannya adalah pengungkapan bertahap: mewajibkan pengelompokan untuk kasus penggunaan sepele (demo satu layanan, prototipe lokal cepat) menimbulkan hambatan yang tidak perlu. Uji orientasi “dari nol hingga berjalan dalam 10 menit” menuntut agar pengembang dapat menulis Aggregate minimal dengan satu komponen, satu Manifest, dan satu Release lalu memperoleh keluaran yang berfungsi tanpa harus terlebih dahulu memahami subsistem atau batas. Cakupan default adalah jalan masuk; cakupan yang dideklarasikan adalah ke mana arsitektur bergerak seiring pertumbuhannya.
8. Batasan arsitektural dan pola yang direkomendasikan
Entri di bawah ini adalah satu pola yang direkomendasikan dan lima batasan. Skema menegakkan Batasan 4 dan 5 — Release tidak memiliki blok values, dan instans komponen dalam Aggregate tidak memiliki kunci labels; sisanya adalah konvensi yang tidak diperiksa kompiler.
-
Pola yang direkomendasikan: pengangkatan parameter melalui string templat
- Contoh: Pengembang menulis
workers: {{ .parameters.env_workers }}di blokvaluesmiliknya, tanpa tanda kutip, sehingga nilainya tiba sebagai bilangan bulat sesuai deklarasinya. - Mengapa: Jika Aggregate mendeklarasikan
env_workerssebagai parameter bertipe (type: integer), kompiler terlebih dahulu memvalidasi nilai yang diberikan Release terhadap kontrak. Validasi kontrak parameter terjadi sebelum interpolasi; interpolasi terjadi sebelum validasi skemavalues:di sekitarnya. Hal ini menjaga agar Aggregate tetap dapat digunakan ulang: Ops memasok bilangan bulat melaluiparameters:milikRelease, kompiler memvalidasinya terhadap deklarasiparameters:yang bertipe, menyubstitusikan nilai yang telah diselesaikan ke dalam dokumen, dan deklarasischema:milik Component berhasil memvalidasi bilangan bulat yang dihasilkan.
- Contoh: Pengembang menulis
-
Batasan 1: Kredensial adalah lampiran, bukan nilai
- Pola yang tidak dianjurkan: Pengembang menulis
values: { password: "123" }pada sebuah komponen. - Mengapa: konvensi pustaka standar adalah bahwa kredensial diminta sebagai lampiran di bawah
features:, dengan menyebuttypeFeature kredensial (yang berlabelfeature.aggrega.ai/kind: secret) dan menggunakanvaluesmilik lampiran itu sendiri untuk mendeskripsikan kueri ke penyimpanan rahasia. Ini adalah konvensi, bukan pemeriksaan kompiler — kompiler tidak menafsirkan arti sebuah daunvaluesdan akan membawa literal inline apa adanya. Permukaan lampiranlah yang membuat bentuk yang ditulis dengan baik tersedia dan bertipe.
- Pola yang tidak dianjurkan: Pengembang menulis
-
Batasan 2: Components yang agnostik terhadap kapabilitas
- Pola yang tidak didukung: Arsitek menulis
aws_instance_type: stringdi deklarasischema:milik Component. - Mengapa: Berdasarkan konvensi, Components agnostik terhadap kapabilitas. Target perangkat keras fisik berada di Recipes milik Ops atau di anotasi
.contextgenerik, bukan di dalam logika kognitif inti aplikasi.
- Pola yang tidak didukung: Arsitek menulis
-
Batasan 3: Logika kondisional pada metadata
- Pola yang tidak didukung: Ops menulis
{{ if eq .context.labels.gpu "true" }}di sebuahRecipeuntuk mengubah strategi deployment secara mendasar. - Mengapa: Saluran
.contextmelewati validasischema:per pilar. Mengandalkan label yang tidak tervalidasi untuk logika infrastruktur inti membuat platform rapuh. Objek.contextmembawa penandaan metadata (mis. penagihan, SOC2); perutean struktural termasuk dalam pilar yang divalidasi skema.
- Pola yang tidak didukung: Ops menulis
-
Batasan 4: Release tidak dapat menimpa nilai pengembang
- Pola yang tidak didukung: Ops mencoba menimpa logika kognitif pengembang (mis. mengubah
workers: 4menjadiworkers: 10) dariRelease. - Mengapa:
Aggregateadalah satu-satunya sumber kebenaran bagi niat pengembang. Jika sebuah nilai di-hardcode diAggregate, nilai itu tidak dapat diubah di seluruh lingkungan. Jika sebuah nilai harus berubah per lingkungan, pengembang menggunakan pengangkatan parameter. SkemaReleasemenegakkan hal ini dengan melarang blokvalues, sehingga Ops terbatas pada pemenuhan kontrakparametersdan pendefinisianinfrafisik.
- Pola yang tidak didukung: Ops mencoba menimpa logika kognitif pengembang (mis. mengubah
-
Batasan 5: Label tingkat instans pada Aggregate
- Pola yang tidak didukung: Pengembang menulis
labels: {}pada instans komponen di dalamAggregate. - Mengapa: Label adalah ciri tingkat katalog yang tidak dapat diubah dan ditulis oleh arsitek platform — identitas semantik yang dibaca oleh mesin kebijakan dan selektor. Release merutekan komponen ke batas melalui penargetan ID eksplisit berbasis map (
components: { "my-agent": {} }), yang mempertahankan kemampuan menyarangkaninfradan penimpaan fitur per komponen tanpa mencampurkan kepengarangan label ke dalam Aggregate pengembang.
- Pola yang tidak didukung: Pengembang menulis
9. Perimeter keamanan & pagar pengaman egress eksplisit (tujuan di luar perimeter)
Tidak ada aplikasi yang berdiri sendiri di ruang hampa. Arsitektur Aggrega yang telah dikompilasi merepresentasikan graf yang dipetakan secara ketat. Namun, sistem AI modern terus-menerus berinteraksi dengan entitas di luar perimeter terkompilasi ini — seperti LLM SaaS publik (Anthropic, OpenAI), API publik generik (Stripe, Twilio), atau database brownfield lama (Oracle on-premise).
Untuk mengintegrasikan sistem eksternal ini secara aman, Aggrega memisahkan secara ketat batas keamanan dari mekanika eksekusi. Batas keamanan diatur oleh aturan Component universal dan pagar pengaman egress eksplisit.
1. Aturan Component universal
Jika sebuah aplikasi berinteraksi dengan suatu entitas — baik itu database lokal, sumber daya cloud terkelola, LLM SaaS, maupun endpoint API publik generik — entitas itu WAJIB dideklarasikan sebagai Component tersendiri di Aggregate. Aturan ini adalah sebuah konvensi: kompiler tidak dapat melihat panggilan yang dilakukan aplikasi, sehingga tidak ada yang memeriksanya.
Dengan memperlakukan API SaaS eksternal dan database lama sebagai node kelas satu dalam graf representasi perantara (IR), pengembang memperoleh kemampuan untuk melampirkan konfigurasi proxy Zero-Trust langsung ke panggilan keluar. Misalnya, dengan memodelkan API Stripe sebagai node tersendiri, pengembang dapat melampirkan fitur header-injector padanya, sehingga konfigurasi yang dihasilkan mencegah agen pemanggil menyimpan token API mentah di memorinya sendiri.
2. Pagar pengaman egress eksplisit (kesesuaian infrastruktur)
Alih-alih mengandalkan logika kompiler yang di-hardcode untuk mengatur egress jaringan, Aggrega sepenuhnya mendelegasikan keamanan perimeter kepada mesin kebijakan perusahaan yang agnostik dan plugin rendering Wasm. Hal ini memastikan konfigurasi yang dihasilkan sesuai secara ketat dengan persetujuan egress eksplisit.
- Kait katalog (Domain 2): Ketika arsitek mendefinisikan komponen SaaS publik (mis.
core/external-service), ia melampirkan label korporat yang tidak dapat diubah padanya (mis.security.enterprise.com/zone: "untrusted-external"). - Pagar pengaman kebijakan (waktu kompilasi): Sebelum konfigurasi apa pun dihasilkan, mesin kebijakan OPA atau Kyverno mengevaluasi graf. Perusahaan menulis aturan sederhana: “Jika node internal terhubung ke node yang berlabel
untrusted-external, ID node target tersebut harus tercantum secara eksplisit dalam arrayparameters.approved_egressmilik lingkungan.” Jika pengembang mencoba merutekan data ke tujuan eksternal yang tidak disetujui, mesin kebijakan menghentikan build. - Pembuatan konfigurasi (waktu render): Jika kebijakan lolos, aturan egress di-render dari apa yang dilampirkan operator. Feature
core/egress-allowlist, yang dilampirkan ke komponen pemanggil di Release, me-render dihelmsatu KubernetesNetworkPolicyper workload yang di-render komponen tersebut, yang hanya mengizinkan egress ke pod miliknya sendiri, ke pod dari target edgeuses-nya pada port yang dideklarasikan pod tersebut, ke DNS kluster, dan ke rentang alamat yang dicantumkan lampiran untuk target yang tidak dijalankan kluster, seperti API SaaS publik. Build berhenti kecuali Release menegaskan, denganinfra.control_plane_present: true, bahwa plugin jaringan kluster menegakkan kebijakan jaringan, dan berhenti dengan menyebut setiap koneksi eksternal semacam itu yang tidak mencantumkan rentang alamat; dicompose, yang tidak memiliki kebijakan jaringan, lampiran tersebut menghentikan build. Pengembang tidak pernah menulis aturan firewall.
Hal ini menjamin — melalui peran putusan tata kelola yang mengevaluasi topologi yang dideklarasikan — bahwa infrastruktur yang dideklarasikan secara eksplisit sesuai dengan kebijakan egress tanpa kompiler Go inti perlu memahami arti “eksternal”. (Catatan: Egress zero-trust yang sesungguhnya bergantung pada kluster target yang menjalankan CNI Default Deny saat runtime; konfigurasi yang dihasilkan hanya memetakan pengecualian yang diotorisasi).
Satu Component per layanan eksternal
Setiap layanan eksternal dideklarasikan sebagai komponen tersendiri, tidak digabungkan ke dalam array multi-target. Jika sebuah aplikasi memanggil lima API pihak ketiga yang berbeda, pengembang mendeklarasikan lima komponen core/external-service yang berbeda. Deklarasi per layanan inilah yang memungkinkan mesin kebijakan dan plugin Wasm menargetkan setiap tujuan keluar secara individual — melampirkan kebijakan egress yang berbeda, fitur proxy yang berbeda, atau kait observabilitas yang berbeda ke setiap dependensi eksternal.
Memisahkan keamanan dari eksekusi (skenario “brownfield”)
Penting untuk dicatat bahwa label semantik (mis. untrusted-external) menentukan kebijakan keamanan jaringan, bukan eksekusi. Label ini tidak bergantung pada apakah Aggrega me-render artefak yang menyediakan sumber daya tersebut.
- Skenario A (API SaaS publik): Berlabel
untrusted-externaldi katalog (memicu pagar pengaman egress kebijakan). Direalisasikan oleh workload referensi (tanpa sumber daya komputasi yang disediakan; lihat §10). - Skenario B (database lama internal): Berlabel
internal-trusted(melewati pagar pengaman egress, tetap berada di dalam VPC). Direalisasikan oleh workload referensi (tanpa sumber daya komputasi yang disediakan; lihat §10). - Skenario C (database yang di-host sendiri): Berlabel
internal-trusted. Dieksekusi melalui plugin perender Helm (disediakan secara fisik sebagai StatefulSet Kubernetes).
10. Layanan yang tidak disediakan build: Workloads referensi
Ketika aplikasi berinteraksi dengan database lama on-premise atau API SaaS publik (seperti Stripe), aturan Component universal menetapkan bahwa entitas eksternal ini harus dideklarasikan sebagai komponen tersendiri di Aggregate. Namun, Aggrega tidak boleh mencoba menghasilkan artefak fisik Pod Kubernetes atau instans AWS RDS untuk entitas tersebut.
Recipe yang merealisasikan komponen semacam itu mendeklarasikan Workload dengan form: reference: sebuah endpoint — host atau URL — opsional sebuah port, dan tanpa kontainer. Kompiler meneruskan keduanya sebagai string penunjuk yang deterministik dan tidak pernah me-resolve-nya. Apa yang di-render penyedia untuk Workload referensi adalah urusan penyedia itu sendiri: helm menghasilkan ExternalName Service yang membawa host endpoint tersebut, sehingga workload di kluster dapat menjangkau layanan yang endpoint-nya berupa nama DNS dengan nama yang stabil di dalam kluster; compose tidak me-render apa pun untuknya. Kubernetes memperlakukan externalName sebagai nama DNS, sehingga endpoint yang ditulis sebagai alamat IP dijangkau di alamat yang diterima konsumen, bukan melalui Service.
Pada kedua penyedia, provides: milik Recipe menjangkau setiap konsumen melalui .context.uses dan kontrak inject persis seperti milik komponen yang disediakan. Karena itu, penyambungan konsumen tidak berubah ketika targetnya beralih dari disediakan ke direferensikan: hanya Recipe yang menjadi tujuan pemetaan target oleh Manifest yang berubah.
Pipeline eksekusi langkah demi langkah
1. Domain 1 (Aggregate): Niat pengembang Pengembang meminta database Oracle lama. Ia tidak peduli di mana database itu berada; ia hanya menetapkan bahwa agen pemanggilnya mengharapkan string koneksi dikirimkan sebagai variabel lingkungan. Karena IP-nya statis dan diketahui sebelumnya, ia meneruskannya melalui parameter.
components: legacy-oracle: type: core/legacy-database:1.0.0 values: host: "{{ .parameters.legacy_oracle_ip }}" sid: "PROD_DB"
my-agent: type: core/python-worker:1.0.0 values: {} uses: databases: legacy_db: target: legacy-oracle inject: env: - in: ORACLE_DSN # Local env var from: "primary_endpoint" # Target provides key2. Domain 4 (Manifest): Perutean Ops memetakan tipe database lama ke Recipe yang memformat string koneksinya. Manifest menyebut sebuah Recipe dan tidak lebih; Recipe yang disebutnya mendeklarasikan Workload dengan form: reference, dan bentuk itulah yang mencegah node menyediakan sumber daya komputasi. Perutean tetap sepenuhnya datar dan dapat diprediksi karena map hanya memiliki tepat satu bentuk, apa pun targetnya.
spec: mappings: components: type: "core/legacy-database": "oracle-dsn-formatter:1.0.0"3. Domain 3 (Recipe referensi): Menyusun serah terima Engineer Ops menulis Recipe tersebut. Recipe ini membangun string koneksi primary_endpoint dari values milik pengembang di blok locals-nya, menerbitkannya di bawah provides, dan mendeklarasikan Workload referensi yang menunjuk ke host database.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: oracle-dsn-formatter version: 1.0.0spec: capability: helm implements: core/legacy-database:1.0.0
# The connection string, built from the Developer's values locals: primary_endpoint: "oracle://{{ .values.host }}:1521/{{ .values.sid }}"
# The public contract a consumer's inject reads provides: primary_endpoint: "{{ .locals.primary_endpoint }}"
# No compute: an endpoint the build does not provision workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: reference endpoint: "{{ .values.host }}" port: 15214. Eksekusi kompiler saat rendering (serah terima)
- Kompiler mengevaluasi Recipe untuk
legacy-oracle. Untuk Release yang menyediakanlegacy_oracle_ip: "10.0.4.55",primary_endpoint-nya adalahoracle://10.0.4.55:1521/PROD_DB. - Di
helm, Workload referensi me-render satu ExternalName Service,legacy-oracle, denganexternalName: 10.0.4.55dan port1521; dicompose, Workload tersebut tidak me-render apa pun. - Kompiler kemudian me-render Recipe untuk
my-agent. Saluran.context.uses-nya membawaprovidesmilik node Oracle, dan kontrak inject telah me-resolveORACLE_DSNterhadapnya.
5. Domain 3 (Recipe pemanggil): Memenuhi kontrak Resep Helm standar untuk worker Python membaca map inject yang diterimanya, persis seperti yang dilakukannya untuk database yang disediakan build.
# Inside python-worker-helm (The calling agent's recipe)env: # The compiler pre-resolved the target's provides into the inject map {{- range $key, $value := .context.inject.env }} - name: {{ $key }} # Renders: ORACLE_DSN value: "{{ $value }}" # Renders: oracle://10.0.4.55:1521/PROD_DB {{- end }}11. Penyaluran lintas pilar melalui schema-bridge: Menjembatani niat ke infrastruktur
Lihat inheritance-and-interface untuk pola schema-bridge yang dengan aman mengekspos pengaturan infrastruktur khusus melalui komponen anak — sebuah bidang values: yang menghadap pengembang, dideklarasikan pada schema: milik Component, yang disalurkan oleh templat valuesMapping: milik Recipe ke keluaran hasil render berbentuk infra:.
12. Penyediaan greenfield (“Aggregates platform”)
Jebakan yang berulang dalam rekayasa platform adalah memaksa router (file Release) menangani penyediaan kluster Hari-0 yang berat (mis. menyalakan kluster AWS EKS baru sebelum men-deploy aplikasi ke dalamnya). Hal ini menghasilkan file perutean yang panjang dan sulit dibaca.
Aggrega menangani hal ini dengan prinsip “kura-kura sampai ke dasar”. Skema Release tidak memiliki blok untuk menginstal infrastruktur; penyediaan kluster dimodelkan dengan Aggregates platform.
Karena kluster AWS EKS, control plane Istio, dan AWS VPC pada akhirnya hanyalah sumber daya cloud fisik, semuanya dimodelkan persis seperti komponen aplikasi.
- Aggregate platform: Tim infrastruktur menulis
Aggregate.yamlstandar yang komponennya adalahcore/aws-vpc,core/eks-cluster, dancore/istio-base. - Release platform: Tim men-deploy agregat ini. Perender yang terikat pada komponen platform ini mengeluarkan artefak yang diperlukan untuk mendirikan infrastruktur dasar.
- Release aplikasi: Ketika pengembang aplikasi siap men-deploy agen AI-nya, tim Ops cukup menargetkan kluster yang baru dibuat dengan sebuah batas di file
Releasemilik aplikasi itu sendiri.