Kontrak sosial
Aggrega, secara desain, adalah kompiler tanpa opini sendiri. Sesuai invarian pendiri yang didokumentasikan di architecture/05-invariants.md, kompiler mengurai YAML, menelusuri graf, mengevaluasi irisan label, dan menyalurkan string antar-komponen — tetapi kompiler tidak mengawasi apa yang dimasukkan pengembang ke dalam values, parameters, infra, provides, atau locals; kompiler tidak memberlakukan konvensi penamaan, konvensi port, maupun label semantik yang diciptakan seorang Architect; kompiler tidak menebak tujuan komponen dari namanya. Banyak disiplin yang terdengar seperti aturan kompiler sebenarnya adalah kontrak sosial: praktik terbaik yang dijunjung oleh konvensi penulisan, bukan oleh skema atau penegakan saat runtime.
Batas netralitas itu perlu dinyatakan secara gamblang, karena batasnya hanya satu garis dan mudah ditafsirkan berlebihan. Beberapa kunci adalah milik Aggrega sendiri — dicadangkan, dengan nilai yang diterimanya tertulis dalam skema yang dipublikasikan — dan kunci-kunci tersebut memang diperiksa oleh skema, sama seperti skema memeriksa bidang lain yang dideklarasikan. Mendeklarasikan himpunan nilai dari kunci yang didefinisikan oleh platform itu sendiri bukanlah kompiler yang membaca makna dari apa yang Anda tulis; itu adalah platform yang menyatakan arti kuncinya sendiri. Segala sesuatu yang Anda tulis di bawah kunci milik Anda sendiri tetap sepenuhnya tidak diawasi, sebagaimana dijelaskan halaman ini.
Halaman ini adalah inventaris kanonis kontrak sosial bahasa ini. Penulis yang mempelajari kontrak-kontrak tersebut dari halaman ini dapat memahami mengapa kompiler menerima build yang cacat menurut konvensi (kompiler memang menerimanya — kompiler tidak menafsirkan konvensi) dan di mana tanggung jawab untuk menangkap pelanggaran tersebut berada (disiplin penulisan, perhatian peninjau, atau plugin linter yang dijalankan oleh aggrega lint).
Tiga kelas disiplin
Disiplin Aggrega terbagi menjadi tiga kelas berdasarkan cara disiplin tersebut ditegakkan. Klasifikasi ini penting karena setiap kelas memiliki mode kegagalan yang berbeda ketika disiplinnya dilanggar.
Ditegakkan oleh skema
Disiplin ditegakkan oleh validasi JSON Schema 2020-12 pada waktu pemuatan (JSON Schema amplop entitas, ditambah deklarasi schema: tingkat pilar pada entitas Component dan Feature). Pelanggaran menghasilkan penghentian fatal sebelum build berlanjut; compiler menolak untuk melanjutkan. Penulis yang mencoba melanggar disiplin yang ditegakkan oleh skema akan melihat galat validasi eksplisit yang menunjuk ke field dan batasannya.
Contoh: field wajib amplop entitas (apiVersion / kind / metadata.name / metadata.version); regex SemVer pada metadata.version; himpunan nilai tertutup pada label tercadang component.aggrega.ai/type; larangan mekanis skema Release terhadap blok values: (sesuai Invariant 5); penolakan extends-plus-aggregate pada Release (invariant Single Source of Truth); aturan bentuk Recipe yang menegakkan kontrak komposisi jenis input.
Disiplin yang ditegakkan oleh skema adalah jaminan terkuat yang dimiliki bahasa ini. Compiler menolak me-render apa pun yang melanggarnya.
Ditegakkan oleh plugin kebijakan
Disiplin ditegakkan oleh plugin Wasm yang berjalan pada salah satu titik soket yang terdokumentasi (peran tata kelola label-transform saat konstruksi topologi; peran tata kelola ir-verdict saat analisis statis; soket linter di luar alur). Pelanggaran menghasilkan kegagalan kebijakan yang menghentikan build (soket dalam alur) atau peringatan anjuran (soket di luar alur), bergantung pada semantik gating soket tersebut.
Suatu disiplin ditegakkan dengan cara ini hanya di tempat plugin yang memeriksanya berjalan: runtime Wasm memanggil plugin pada titik soket yang terdokumentasi, dan disiplin yang tidak diperiksa plugin mana pun tetap menjadi konvensi. Linter publikasi, yang dijalankan oleh aggrega lint, memeriksa sebagian dari satu konvensi di halaman ini — lihat Konvensi yang diperiksa aturan linter. Tidak ada aturan linter publikasi yang memeriksa hermetisitas (Sprig FuncMap menyediakan helper yang merusak determinisme output sesuai catatan determinisme di templates/sprig-functions.md) atau penamaan sumber daya cloud (Recipes yang output valuesMapping:-nya mereferensikan field nama sumber daya cloud tanpa interpolasi release_name / instance_id, sesuai entities/recipe.md “Cloud-resource naming discipline”); plugin linter milik Anda sendiri dapat memeriksa keduanya.
Untuk permukaan kontrak plugin Wasm dan kriteria penempatannya (soket linter vs peran verdict tata kelola), lihat plugins/plugin-contract.md.
Dijunjung oleh konvensi
Disiplin hanya dijaga oleh disiplin penulisan ditambah perhatian peninjau. Compiler tidak menegakkannya; tidak ada skema yang menolak pelanggaran; tidak ada plugin Wasm yang menandainya. Penulis mempelajari disiplin ini dari dokumentasi, mengikutinya karena bentuk arsitektur bergantung padanya, dan mengandalkan tinjauan PR untuk menangkap kelalaian. Pelanggaran tidak menghasilkan sinyal pada waktu kompilasi — build berhasil, output yang di-render berfungsi sejauh yang diketahui compiler, dan pelanggaran disiplin baru muncul ketika perkakas hilir atau perilaku runtime bergantung pada konvensi tersebut.
Disiplin yang dijunjung oleh konvensi adalah daftar penopang yang harus dipelajari penulis dari dokumentasi. Compiler tidak menafsirkannya; kesalahan di dalamnya tidak merusak build, tetapi merusak bentuk arsitektur yang menjadi sandaran Aggrega. Sebagian besar halaman ini mendokumentasikannya.
Konvensi
Kontrak sosial berikut dijunjung oleh konvensi. Setiap entri menyebutkan disiplinnya, tempat konvensi tersebut didokumentasikan, dan mode kegagalannya jika dilanggar. Setiap entri mempertahankan nomornya di mana pun ia berada: kontrak 3, disiplin prefiks tercadang, diperiksa oleh aturan linter untuk kunci anotasi dan dijelaskan di bawah Konvensi yang diperiksa aturan linter.
1. Memilih tipe operasional yang sesuai dengan komponen
Label tercadang component.aggrega.ai/type menyebutkan jenis sebuah komponen, yang diambil dari himpunan tertutup primitif cloud universal: server, worker, task, function, stateful-server, resource. Keanggotaan dalam himpunan tersebut ditegakkan oleh skema, bukan dijunjung oleh konvensi. Aggrega mendefinisikan kunci ini beserta nilai yang diterimanya, skema Component menyebutkan nilai-nilai tersebut, dan dokumen yang memuat nilai lain ditolak saat dimuat — E0215, kondisi entity-envelope-invalid, menyebutkan label tersebut dan mencantumkan nilai yang dapat diterimanya. Penolakan itulah yang tidak dicakup oleh entri ini.
Yang tetap merupakan konvensi adalah nilai mana yang sesuai dengan komponen yang Anda hadapi. Tidak ada yang memeriksa bahwa basis data relasional diberi label stateful-server dan bukan server, atau bahwa konsumen antrean adalah worker dan bukan task; selektor mengevaluasi nilai apa pun yang ditemukannya tanpa menafsirkan maknanya. Arsitek yang menulis sebuah Component memilih nilai yang menggambarkan bagaimana infrastruktur harus memperlakukannya, dan selektor, plugin kebijakan, serta plugin rendering Wasm di hilir semuanya bergantung pada kejujuran pilihan tersebut.
Mengklasifikasikan pada sumbu Anda sendiri. Himpunan tertutup tersebut hanya mengatur satu kunci tercadang ini dan tidak ada yang lain. Katalog yang memerlukan klasifikasi yang tidak didefinisikan Aggrega — tingkatan, zona data, kelas layanan, atau pembagian lebih rinci dari primitif operasional — menambahkan kunci labelnya sendiri di samping kunci tercadang. Skema Component menerima kunci label tambahan apa pun dengan nilai string, dan mekanisme selektor yang sama membacanya, sehingga acme.aggrega.ai/storage-tier: oltp berdampingan dengan component.aggrega.ai/type: stateful-server dan appliesTo milik sebuah Feature atau selector milik sebuah soket dapat menargetkan keduanya. Perluasan dilakukan pada kunci Anda sendiri, tidak pernah pada nilai di dalam kunci milik Aggrega.
Didokumentasikan di: architecture/02-ecosystem-philosophy.md (ontologi operasional) + labels-and-annotations.md (disiplin prefiks) + errors/sentinels.md (E0215).
Mode kegagalan: Nilai dari himpunan yang tidak sesuai dengan komponen menyesatkan semua hal yang membaca label tersebut. Penyimpanan data yang diberi label server ditolak oleh Feature atau soket yang memilih stateful-server — penghentian yang menyebutkan selektornya, bukan label yang keliru — dan plugin kebijakan atau plugin rendering yang membaca label tersebut memperlakukannya sebagai komputasi tanpa status. Jika hanya pembaca semacam itu yang melihatnya, build berhasil; kesalahan baru muncul setelah artefak yang dirender mencapai klaster.
2. Pemisahan tiga wadah .context.annotations.*
Anotasi yang diturunkan secara bertingkat masuk ke dalam tiga wadah bernama — .context.annotations.release, .context.annotations.catalog, .context.annotations.aggregate — masing-masing membawa maksud yang berbeda. Target disiplinnya: release adalah “tempat komponen ini berjalan, diatur oleh Ops”; catalog adalah “apa komponen ini, ditulis oleh Arsitek”; aggregate adalah “apa yang dilakukan komponen ini, ditulis oleh Developer”.
Compiler tidak menegakkan batas antarwadah. Ketiga wadah berbagi bentuk datar string → string; template sebuah Recipe dapat membaca ketiganya, dan tidak ada yang mencegah anotasi batas Release ditafsirkan sebagai metadata kognitif atau anotasi katalog dirutekan ke infra:. Pemisahan ini dijaga oleh penulis yang menuliskan anotasi ke wadah yang tepat dan oleh peninjau yang menangkap kebocoran antarwadah.
Didokumentasikan di: labels-and-annotations.md (Pemisahan tiga wadah adalah Social Contract).
Mode kegagalan: Logika perutean yang bergantung pada perbedaan maksud wadah (misalnya, Recipe yang merutekan .context.annotations.release.aggrega.ai/region ke field region Terraform) secara diam-diam memakai anotasi apa pun yang muncul di wadah tersebut, terlepas dari maksud penulisannya. Build berhasil; keluaran yang dirender dapat memuat nilai yang salah secara semantik.
4. Kemandirian provides: pada Recipe
Template provides: pada Recipe hanya mencakup data milik node itu sendiri — .values, .infra, .context.instance_id, .context.rendered_name jika provider node melaporkannya, .locals node yang telah di-resolve, ditambah string statis. Referensi ke .context.inject dan .context.uses dilarang karena evaluasi provides menjalankan template tersebut dalam urutan apa pun; membaca data lintas node akan mengikatnya pada urutan iterasi topologis, yang sengaja dihindari oleh desain. .locals termasuk dalam cakupan, bukan di luarnya: locals node di-resolve di bagian awal tahap yang sama, sebelum provides-nya, dan bersifat lokal terhadap node, sehingga membacanya tidak berdampak pada urutan. Menyebut kunci yang tidak dideklarasikan blok locals akan menghentikan build.
Ini adalah aturan dengan dua bagian, masing-masing menyebutkan di mana ia diperiksa. Compiler memeriksa bagian pertama: evaluasi provides memeriksa setiap template terhadap daftar izin positif berisi root yang didefinisikan konteksnya sebelum template dijalankan, sehingga pembacaan .context.inject / .context.uses menghentikan build dengan galat eksplisit alih-alih merender nilai kosong; aturan ini juga didokumentasikan di templates/expansion-matrix.md baris 6. Konvensi menjunjung bagian kedua: pola yang lebih luas (provides bersifat publik; locals bersifat privat) berlandaskan konvensi.
Didokumentasikan di: templates/expansion-matrix.md baris 6 + vocabulary/data-pillars.md “provides: dan locals: — wajah publik vs wajah privat”.
Mode kegagalan: compiler mendeteksi dan menghentikan build saat evaluasi template ketika referensi terlarang muncul langsung di provides:. Disiplin publik-vs-privat yang lebih luas (jangan mengekspos state internal melalui kunci provides:) hanya berupa konvensi — penulis yang memperlakukan provides: sebagai namespace internal Recipe menghasilkan kontrak yang diandalkan pemanggil; refactoring menjadi perubahan yang merusak kompatibilitas.
5. Determinisme — helper non-hermetik dalam template jalur render
Deterministic Output Invariant milik Aggrega (Invariant 8 di architecture/05-invariants.md) mensyaratkan keluaran yang identik per byte untuk masukan yang identik per byte. FuncMap lengkap Sprig menyediakan helper yang membaca status lingkungan (pembaca jam dinding now / date; pembangkit acak randAlpha / uuidv4; pembaca environment env / expandenv; resolver jaringan getHostByName). Penulis yang memanggil helper ini dari template yang berkontribusi pada keluaran yang di-render melanggar kontrak determinisme.
Compiler tidak mendeteksi atau memblokir penggunaan helper non-hermetik. FuncMap Sprig menyediakannya sesuai templates/sprig-functions.md “Determinism caveat”; disiplin ini dijaga oleh penulis yang menghindari helper tersebut dalam template jalur render dan oleh peninjau yang menangkap penggunaannya saat tinjauan PR.
Didokumentasikan di: templates/sprig-functions.md “Determinism caveat”.
Mode kegagalan: Keluaran build berbeda antar-eksekusi dengan masukan yang sama. Ketidakcocokan ini muncul saat diff GitOps, ketika tooling hilir (ArgoCD, Flux) melihat drift tak terduga antara manifest yang di-commit dan status cluster, atau saat audit ketika dua kompilasi dari masukan yang sama menghasilkan artefak yang berbeda.
Tidak ada aturan linter publikasi yang memeriksa templat untuk pemanggilan helper non-hermetik. Nama helper tertulis di dalam templat, sehingga plugin linter milik Anda sendiri dapat menemukannya (lihat Konvensi yang diperiksa aturan linter).
6. Batas pilar (penunjuk arah, bukan tembok)
Batas pilar adalah disiplin penulisan, bukan penegakan oleh bahasa. Mesin template mengizinkan pembacaan lintas pilar di setiap lokasi kecuali dilarang secara eksplisit oleh aturan kemandirian (misalnya, provides: dan source: Recipe yang membaca .context.inject / .context.uses). Penulis sebaiknya:
- Membaca
.valuesuntuk muatan kognitif (intent yang ditulis developer). - Membaca
.infrauntuk ukuran fisik (sizing yang ditulis Ops). - Membaca
.context.uses.<alias>.provides.<key>untuk string penunjuk lintas komponen. - Membaca
.context.injectuntuk pipa pengiriman pasca-hidrasi.
Mesin template tidak membatasi pembacaan. Template Recipe yang membaca .infra.replicas untuk mengisi field values: tetap berfungsi; tidak ada yang mencegah rute lintas pilar tersebut. Sasaran disiplin ini adalah penunjuk arah — batas-batas tersebut menjelaskan intent penulisan (siapa pemilik data) alih-alih pembatasan saat runtime.
Didokumentasikan di: vocabulary/data-pillars.md “Pillar boundaries and authoring discipline”.
Mode kegagalan: Kebocoran lintas pilar — muatan kognitif developer berisi detail ukuran fisik, atau sizing yang ditulis Ops berisi metadata kognitif. Build berhasil; pembagian penulisan empat domain menjadi kabur seiring waktu karena penulis mengambil jalan pintas melewati pilar; pemeliharaan hilir menjadi lebih sulit karena korespondensi antara pilar dan alur data melemah.
7. Semantik sumber ganda containers.<name>.variables pada Workload
Map variables: memadukan dua sumber data yang berbeda melalui ekspresi template Go: literal pilar developer (entri yang membaca .values / .infra / .locals) dan data pipa lintas komponen (entri yang membaca .context.inject.env.<KEY>). Penulis memilih satu sumber per entri berdasarkan apakah nilainya lokal terhadap komponen atau diturunkan lintas komponen.
Compiler tidak membedakan kedua sumber tersebut; keduanya mengalir ke daftar Kubernetes env: yang sama pada Deployment yang di-render. Semantik sumber ganda hanya berlaku saat penulisan — disiplinnya adalah menamai intent (entri ini lokal terhadap komponen; entri itu diturunkan lintas komponen) agar pemelihara di masa depan dapat membaca entri mana yang bergantung pada keluaran inject-hydration yang mana.
Didokumentasikan di: entities/workload.md “Field-semantics essentials” (variables).
Mode kegagalan: Penulis yang tidak membedakan kedua sumber kehilangan jejak “entri mana yang terikat ke provides: target mana”. Merefaktor kunci provides: milik target secara diam-diam merusak setiap entri variables: pemanggil yang membaca melalui pipa inject.
8. Disiplin penamaan sumber daya cloud
Recipes yang menghasilkan nama sumber daya cloud (nama bucket S3, pengenal database RDS, nama role IAM, nama stack CloudFormation — setiap field yang nilainya menempati namespace global di penyedia cloud) harus menggabungkan {{ .metadata.release_name }} dan/atau {{ .context.instance_id }} ke dalam nama yang di-render untuk menghindari tabrakan ketika Recipe yang sama dijalankan di beberapa Releases atau instans komponen.
Compiler tidak memeriksa keluaran valuesMapping: untuk field nama sumber daya cloud yang tidak memiliki interpolasi ini. Disiplin ini dijaga oleh penulis Recipe (yang mengetahui field mana yang menamai sumber daya yang unik secara global untuk penyedia target) dan peninjau (yang menangkap pola sumber daya tanpa nama unik saat tinjauan PR).
Didokumentasikan di: entities/recipe.md “Cloud-resource naming discipline”.
Mode kegagalan: Dua Releases dari Aggregate yang sama (prod-billing dan staging-billing) sama-sama mencoba men-deploy sumber daya dengan nama global yang sama; deployment kedua gagal saat runtime dengan penolakan dari sisi cloud. Build Aggrega berhasil; kegagalan deployment baru muncul ketika Release kedua diterapkan.
Tidak ada aturan linter publikasi yang memeriksa field nama sumber daya cloud untuk interpolasi yang diperlukan; plugin linter milik Anda sendiri dapat melakukannya (lihat Konvensi yang diperiksa aturan linter).
9. Granularitas Component — satu layanan koheren per Component
Sebuah Component memodelkan satu layanan yang koheren — satu layanan yang diekspos, atau workload dari satu layanan beserta workload pembantunya yang hanya bersifat internal. Ketika sebuah chart membundel layanan yang secara bermakna dapat di-use sendiri oleh komponen lain — terutama infrastruktur asing seperti database, cache, atau message broker yang sudah dimodelkan Aggrega sebagai Component tersendiri — pustaka standar menyusun Components per layanan menjadi Module sub-aggregate (spec.aggregates + exportedComponents) alih-alih membungkus seluruh produk sebagai satu Component yang buram. Disiplinnya: multi-workload boleh dalam satu Component; kemampuan untuk digunakan secara independen adalah garis yang memecah satu Component menjadi sebuah stack.
Compiler agnostik terhadap granularitas ini. Compiler me-render apa pun yang lolos validasi skema — compiler tidak memeriksa berapa banyak layanan yang dibundel oleh Recipe sebuah Component, maupun apakah salah satunya dapat digunakan secara independen. Penulis yang membungkus produk lima layanan sebagai satu Component menghasilkan Component yang diterima dan di-render compiler tanpa keluhan; konvensi ini dijaga oleh disiplin penulisan dan perhatian peninjau.
Didokumentasikan di: ../../architecture/06-data-taxonomy-and-composition.md (Satu layanan koheren per Component — batas workload tunggal).
Mode kegagalan: Pembungkusan multi-layanan yang monolitik berhasil di-build, tetapi layanan yang dibundel tidak terlihat oleh topologi, selector, dan kebijakan — layanan tersebut tidak dapat diskalakan, diganti, atau dijadikan dependensi secara independen. Merefaktor monolit tersebut menjadi Components per layanan di kemudian hari merupakan perubahan yang merusak bagi setiap konsumen yang mereferensikan node terbungkus tunggal tersebut.
Mengapa konvensi ada
Masing-masing konvensi ini secara desain merupakan disiplin penulisan, meskipun skema atau kebijakan Wasm dapat menegakkan salah satu di antaranya. Alasan per jenis kontrak:
Ekstensibilitas. Disiplin prefiks yang dicadangkan (kontrak 3) menggambarkan kosakata pustaka standar, bukan seluruh kosakata yang valid. Katalog perusahaan menulis prefiks dan kunci label mereka sendiri untuk memperluas pustaka standar; menegakkan konvensi prefiks melalui skema akan mengubah “disiplin pustaka standar” menjadi “satu-satunya bentuk yang diizinkan bahasa” — itulah tembok yang sengaja dihindari arsitektur. Sumbu tipe operasional (kontrak 1) mempertahankan ekstensibilitas yang sama pada permukaan yang berbeda: kunci cadangan yang didefinisikan Aggrega membawa himpunan tertutup yang ditegakkan skema, dan katalog memperluasnya dengan menambahkan kunci label miliknya sendiri di sampingnya, bukan nilai di dalam kunci milik Aggrega. Yang diperiksa skema adalah himpunan nilai dari satu kunci yang dimilikinya; yang tetap terbuka adalah setiap kunci lainnya, tempat kosakata katalog itu sendiri berada.
Kemurnian AOT. Disiplin penamaan sumber daya cloud (kontrak 8) dan disiplin determinisme (kontrak 5) memerlukan introspeksi konten templat untuk menentukan apakah suatu bidang merupakan nama sumber daya cloud atau pemanggilan helper non-hermetik. Kemurnian AOT (Invarian 2) mencegah compiler bergantung pada status runtime; introspeksi templat statis dapat dilakukan (plugin linter membaca templat entitas sebagaimana ditulis), tetapi melakukannya di dalam compiler inti akan mengikat logika internal compiler pada urusan penulisan per domain. Arsitektur memindahkan pemeriksaan ini keluar dari compiler dan ke dalam plugin Wasm sesuai Invarian 6 (Batas ABI Wasm).
Fleksibilitas penulisan. Disiplin batas pilar (kontrak 6) dan semantik sumber ganda variables (kontrak 7) menggambarkan pola penulisan, bukan batasan runtime. Sintaks templat yang sama dapat mengekspresikan pola yang mematuhi disiplin maupun yang melanggarnya; menjadikan disiplin tersebut pemeriksaan runtime akan mengharuskan compiler menafsirkan maksud penulisan yang tidak dapat diaksesnya. Arsitektur memperlakukan konvensi sebagai dokumentasi yang dipelajari penulis, bukan sebagai invarian runtime. Granularitas Component (kontrak 9) juga termasuk di sini: perusahaan dapat membungkus suatu produk pada granularitas apa pun yang disukai katalognya, dan compiler — netral terhadap konten dan tanpa opini sendiri sesuai Invarian 1 — tidak dapat mengetahui apakah workload yang dibundel dapat digunakan secara mandiri, sehingga batas satu layanan yang koheren tetap menjadi disiplin penulisan, bukan tembok skema. Pilihan tipe operasional (kontrak 1) memiliki bentuk yang sama: skema menetapkan nilai mana yang ada, tetapi nilai mana yang menggambarkan suatu komponen tertentu adalah penilaian pemodelan tentang bagaimana infrastruktur harus memperlakukannya, dan tidak ada apa pun dalam Recipe atau blok values yang memberi tahu compiler apakah penilaian itu benar.
Penegakan dalam dua bagian. Kemandirian provides: pada Recipe (kontrak 4) sebagian ditegakkan oleh compiler — jalur render mendeteksi pembacaan .context.inject / .context.uses dalam templat provides: lalu berhenti. Disiplin publik-vs-privat yang lebih luas (jangan mengekspos status internal) berlandaskan konvensi karena compiler tidak dapat menentukan string mana yang harus tetap internal bagi Recipe tanpa maksud penulisan.
Ketiga jalur ini penting karena masing-masing menandakan di mana tanggung jawab untuk menangkap pelanggaran berada. Ditegakkan oleh skema: compiler. Ditegakkan oleh plugin kebijakan: plugin yang memeriksanya, di tempat plugin itu berjalan. Dijunjung oleh konvensi: penulis dan peninjau. Penulis yang memahami jalur-jalur ini mengetahui kesalahan mana yang akan ditangkap compiler dan mana yang akan lolos tanpa peringatan ke perangkat hilir atau runtime.
Konvensi yang diperiksa aturan linter
Linter publikasi, yang dijalankan oleh aggrega lint, memeriksa sebagian satu konvensi di halaman ini: kunci anotasi pada kontrak 3, di bawah. Temuannya bersifat saran, dan bagian konvensi yang tidak dijangkaunya dijunjung oleh konvensi, sebagaimana entri-entri di atas.
Tidak ada aturan linter publikasi yang memeriksa konvensi lain di halaman ini. Dua di antaranya dapat diperiksa oleh aturan linter, karena pelanggarannya tertulis di dalam entitas: determinisme (kontrak 5) — templat yang memanggil helper non-hermetik — dan penamaan sumber daya cloud (kontrak 8) — output valuesMapping: yang menamai sumber daya cloud tanpa interpolasi release_name / instance_id. Demikian pula kunci label di bawah prefiks tercadang (kontrak 3). Sebuah workspace dapat melampirkan plugin linter miliknya sendiri di bawah plugins.linter, di samping linter publikasi, untuk memeriksa salah satu di antaranya; The discipline rules mencantumkan aturan yang dibawa linter publikasi.
Konvensi lainnya (1, 2, 4, 6, 7, 9) bergantung pada apa yang dimaksud penulis, yang tidak dapat dibaca aturan mana pun dari apa yang ditulis. Pemisahan bucket didorong oleh ekstensibilitas (katalog perusahaan melakukan override) — penegakan melalui skema akan bertentangan dengan fleksibilitas tersebut. Bagian sumbu tipe operasional yang tersisa setelah skema menetapkan himpunan nilai — memilih primitif yang sesuai dengan komponen — didorong oleh maksud penulisan: compiler tidak dapat membedakan tipe operasional yang dipilih dengan baik dari yang dipilih dengan buruk, karena keduanya adalah nilai yang diterimanya. Disiplin batas pilar dan semantik variables bersumber ganda didorong oleh maksud penulisan — compiler tidak dapat menentukan maksud dari sintaksis templat saja. Swa-kecukupan provides: pada Recipe ditegakkan sebagian; disiplin publik-versus-privat yang lebih luas bergantung pada kunci mana yang ingin dijaga penulis tetap internal, yang tidak dinyatakan di mana pun dalam Recipe. Granularitas Component juga didorong oleh maksud penulisan — apakah workload yang dibundel dapat digunakan secara mandiri merupakan penilaian pemodelan yang tidak dapat dibaca compiler dari konten Recipe.
3. Disiplin prefiks tercadang
Kunci anotasi dan label mengikuti bentuk <namespace>/<name>. Lima prefiks tercadang memiliki aturan penulisan tertentu: aggrega.ai/ (khusus platform), feature.aggrega.ai/ (pintasan Feature resmi), component.aggrega.ai/ (sifat intrinsik Component), aggregate.aggrega.ai/ (identitas modul Aggregate), dan <any-other-domain>/ (perusahaan / komunitas).
Compiler tidak menolak anotasi yang ditulis di bawah prefiks tercadang pada entitas katalog atau Release; hanya binding anotasi Manifest atau label keluaran Recipe yang mengklaim kunci di bawah aggrega.ai/ yang menghentikan build. Perusahaan yang mendeklarasikan aggrega.ai/internal-billing-tag: "..." di luar kosakata platform menghasilkan anotasi yang diterima compiler dan diturunkan melalui sistem wadah; pembaruan platform di kemudian hari yang memperkenalkan aggrega.ai/internal-billing-tag yang sebenarnya akan bertabrakan secara diam-diam.
Didokumentasikan di: labels-and-annotations.md (Disiplin prefiks) + providers/well-known-annotations.md.
Mode kegagalan: Anotasi kustom di bawah prefiks tercadang bertabrakan dengan anotasi platform di masa depan yang bernama sama; perilaku yang diharapkan platform secara diam-diam menimpa atau hidup berdampingan dengan nilai yang ditulis perusahaan, bergantung pada urutan.
Linter publikasi, yang dijalankan oleh aggrega lint, menandai sebagai temuan bersifat saran (E0277) kunci anotasi entitas katalog di bawah aggrega.ai/ yang bukan salah satu anotasi terkenal platform, serta kunci di bawah feature.aggrega.ai/ pada entitas selain Feature. Kunci label, prefiks tercadang lainnya, dan anotasi di luar metadata.annotations entitas — misalnya yang ditulis oleh Release — tidak diperiksa, sehingga bagi semua itu disiplin tersebut tetap menjadi konvensi.
Rujukan silang
architecture/05-invariants.md— delapan invarian dasar yang melandasi pembingkaian Aggrega bahwa “kompiler netral terhadap konten”; setiap konvensi berada dalam ketegangan dengan satu atau lebih invarian ini.architecture/02-ecosystem-philosophy.md— alasan desain lengkap dari ontologi operasional.vocabulary/labels-and-annotations.md— pemisahan tiga kelompok sebagai kontrak sosial; disiplin prefiks yang dicadangkan.vocabulary/data-pillars.md— batas pilar sebagai penunjuk arah; pembingkaian publik-vs-privat untukprovides:danlocals:.templates/sprig-functions.md— catatan determinisme yang menyebutkan helper non-hermetik.entities/recipe.md— disiplin penamaan sumber daya cloud + contoh yang dikerjakan.entities/workload.md— semantik sumber gandavariables:pada Workload.templates/expansion-matrix.md— kemandirianprovides:pada Recipe sebagai aturan yang ditegakkan kompiler.plugins/plugin-contract.md— kriteria penempatan di soket linter.cli/aggrega-lint.md— aturan linter publikasi, dan cara melampirkan linter milik Anda sendiri.