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

Pipeline kompilasi (tingkat tinggi)

Bab ini merinci fisika internal compiler Go, yang mendefinisikan bagaimana YAML abstrak diterjemahkan menjadi konfigurasi fisik di sepanjang pipeline kompilasi, Graf Representasi Perantara (IR), dan socket eksekusi WebAssembly (Wasm).

Pipeline kompilasi & alur eksekusi

Aggrega menjalankan pipeline compiler Ahead-of-Time (AOT) yang ketat dengan urutan tetap, bukan logika orkestrasi yang di-hardcode. Dipicu oleh aggrega build, compiler meneruskan graf datar di antara socket WebAssembly (Wasm) yang terisolasi untuk mengevaluasi arsitektur sebelum me-render artefak fisik.

Socket Wasm berjalan pada host tertanam — toolkit Extism di atas mesin Wazero — di balik firewall kemurnian AOT yang menolak memberikan kapabilitas akses runtime apa pun kepada plugin (jaringan, sistem file, jam dinding, lingkungan, I/O standar), sehingga plugin tidak dapat merusak jaminan deterministik dan ahead-of-time. Host menjalankan publishing-linter di luar alur (out of band), melalui aggrega lint. Gerbang dalam alur (in-band) yang dijelaskan di bawah — peran label-transform dari socket governance pada konstruksi topologi dan peran IR-verdict-nya pada analisis statis, ditambah pipeline plugin yang menutup rendering — berjalan di setiap build: peran governance di mana pun workspace melampirkan plugin padanya, dan pipeline plugin untuk setiap Recipe yang mendeklarasikan langkah. Status Bahasa mencatat status setiap fase pipeline.

Pipeline dieksekusi sepenuhnya di memori dalam urutan tetap yang ketat:

Resolusi — Resolver & validator sintaksis

  • Mekanisme: Penggabungan pewarisan, interpolasi template Go, dan validasi JSON Schema 2020-12.
  • Tindakan: CLI mengambil semua entitas yang diminta (Components, Features, Releases). CLI terlebih dahulu memeriksa definisi tersebut untuk kata kunci extends. Untuk entitas Katalog, CLI melakukan deep-merge pada metadata YAML, dan kedua jenis itu berpisah jalan pada pilar data: schema: milik sebuah Feature dikomposisikan dengan milik basisnya melalui komposisi JSON Schema 2020-12, sedangkan Component yang melakukan extends hanya mengomposisikan struktur — slot lampirannya, socket topologinya, allowlist self-inject, dan asersi bernama — serta menerima blok schema: basisnya persis seperti yang ditulis basis tersebut. Release yang melakukan extends digabungkan dengan aturan yang sama: nilai anak menang kunci demi kunci, hingga nilai pertama yang tidak dapat dibagi — skalar, daftar, template — yang menggantikan secara utuh, dan kunci yang ditulis anak sebagai null dihapus. Jadi seluruh permukaan authoring-nya ikut terbawa — pohon boundary dengan infra dan lampiran Feature per komponen, blok parameters, anotasi, dan penunjuk Manifest — sedangkan tidak ada field metadata yang ikut, karena identitas dan provenans bersifat per Release. Selanjutnya, CLI melakukan interpolasi di memori dalam tiga sub-langkah: validasi kontrak parameter terhadap deklarasi parameters: bertipe milik Aggregate; interpolasi nilai yang telah di-resolve ke dalam string values: di sekitarnya; penarikan map .parameters dari setiap konteks template nilai, sehingga map tersebut hanya dapat dibaca oleh template path yang ditulis operator. Terakhir, CLI menyuntikkan blok infra yang telah di-resolve ke dalam payload komponen target. Setelah blueprint sepenuhnya konkret, compiler menggunakan deklarasi schema: terpadu dari Katalog (bentuk ringkas atau JSON Schema 2020-12 lengkap) untuk memvalidasi secara ketat konfigurasi values dan infra milik developer secara lokal.
    • Validasi skema Feature pada Release: Features yang dilampirkan melalui Release (baik yang berlaku untuk seluruh boundary maupun yang khusus komponen) di-resolve terhadap entitas Katalog-nya selama langkah ini. Compiler memvalidasi blok infra yang disediakan Release terhadap deklarasi schema: setiap Feature segera setelah resolusi katalog, sehingga keamanan tipe terjamin sebelum topologi dibangun.
    • Sub-fase ekspansi Feature berbasis anotasi: Setelah resolusi Manifest, binding Recipe/Provider, dan validasi target binding Manifest (path yang dideklarasikan di bawah mappings.features.annotations.<key>.maps ada di spec.schema milik Feature yang dirujuk), compiler menjalankan sub-fase ekspansi anotasi sebelum pembangun topologi. Sub-fase ini menelusuri boundary Release dari luar ke dalam dan subsistem Aggregate dari luar ke dalam, menghitung set anotasi efektif per komponen melalui penggabungan cascade + override + null-opt-out; mem-parse setiap nilai anotasi sebagai YAML menjadi skalar, nilai terstruktur, atau null; merutekan setiap nilai (skalar atau terstruktur per subkunci) melalui deklarasi maps milik binding Manifest ke pilar skema Feature target dengan penegakan sisi-versus-pilar (sisi Aggregate memicu maps.values; sisi Release memicu maps.infra); memvalidasi tipe per leaf terhadap spec.schema milik Feature; dan menyuntikkan lampiran Feature sintetis yang ditandai graf IR dengan origin: annotation. Skema dikompilasi sekali per build dan digunakan kembali di seluruh penelusuran cascade. Ekspansi berjalan setelah validasi target binding dan sebelum konstruksi topologi, sehingga tahap-tahap hilir memperlakukan lampiran sintetis secara struktural identik dengan lampiran eksplisit (kecuali melalui inspeksi provenans). Lihat 13-catalog-and-registry.md §“Ekspansi Feature berbasis anotasi” dan language-reference/providers/well-known-annotations.md untuk bentuk binding, semantik cascade, dan aturan komposisi lintas sisi.

Konstruksi topologi — Pembangun topologi & gerbang mutasi

  • Mekanisme: Ekspansi AST + peran label-transform dari socket governance.
  • Tindakan: Compiler secara native membaca blok uses yang dideklarasikan secara eksplisit dari komponen yang telah divalidasi untuk menggambar edge topologis antar-node dalam graf secara deterministik, dengan membiarkan blok values sepenuhnya opak. Selanjutnya compiler mengevaluasi Gerbang mutasi, meneruskan proyeksi graf — label setiap node dan values yang dideklarasikan instance-nya, yang diserahkan compiler tanpa membacanya — bersama nama dan lingkungan Release ke plugin governance yang dilampirkan pada peran label-transform. Lalu plugin tersebut mengevaluasi konteks dan mengembalikan JSONPatch untuk menandai graf secara otomatis dan dinamis (misalnya, menyuntikkan label compliance.aggrega.ai/data-class: restricted berdasarkan lingkungan Release, atau datastore.aggrega.ai/engine: vector berdasarkan ekstensi yang dideklarasikan sebuah database); patch hanya menjangkau label.

Finalisasi graf

  • Mekanisme: Normalisasi.
  • Tindakan: Compiler memfinalisasi Graf Representasi Perantara (IR) yang datar, dengan mempertahankan edge topologis eksplisit yang digambar oleh pembangun topologi. Kemudian compiler menormalisasi Features yang dilampirkan beserta payload values-nya ke dalam dictionary datar yang dipetakan berdasarkan ID node, sehingga graf yang agnostik terhadap kapabilitas siap untuk divalidasi.
    • Normalisasi payload IR: Bentuk struktural IR menegakkan satu sumber kebenaran (Single Source of Truth) untuk konfigurasi: lapisan topologi hanya membawa struktur graf (identitas node, edge, label metadata), dan status konfigurasi yang dinormalisasi berada di dictionary terpisah di memori yang diteruskan compiler ke plugin hilir. Mutator yang mengubah konfigurasi mengubahnya di satu tempat; penyedia membaca status yang dinormalisasi tanpa risiko drift akibat penyimpanan yang redundan.

Analisis statis — Penganalisis statis & gerbang validasi

  • Mekanisme: Pemeriksaan kemurnian topologis + peran ir-verdict dari socket governance.
  • Tindakan: Compiler menjalankan analisis statis abstrak atas Graf IR. Pertama, compiler mengekstrak string selector dari definisi usesSchema dan mengevaluasinya menggunakan mesin pencocokan label Go native (yang mendukung semantik bergaya Kubernetes AND, OR melalui in(), dan NOT melalui !=) di sepanjang edge graf yang didefinisikan secara eksplisit untuk menjamin keamanan tipe lintas node atas socket yang dideklarasikan. Edge pada socket ad-hoc — socket yang dinamai oleh penulis Aggregate dan tidak dideklarasikan oleh katalog — tidak memiliki entri katalog dan karena itu tidak memiliki selector, sehingga tidak ada yang perlu dievaluasi oleh pemeriksaan ini dan tidak ada yang hilang; setiap edge mencatat termasuk jenis yang mana, dan apa yang boleh dibawa oleh edge ad-hoc dibatasi oleh provides yang dideklarasikan target sebagai gantinya. Compiler juga mengevaluasi selector appliesTo dan appliesToAnyOf milik Feature untuk memverifikasi bahwa fitur yang dilampirkan kompatibel dengan label komponen targetnya, serta selector milik setiap slot lampiran yang terisi terhadap label Feature yang mengisinya. Kedua, compiler mengevaluasi setiap mandat keberadaan yang dideklarasikan oleh Component sebuah node — setiap anotasi features.aggrega.ai/requiredType.<label> — terhadap set lampiran akhir node tersebut. Penganalisis adalah tempat yang tepat untuk pemeriksaan ini karena merupakan tahap pertama yang memegang kedua bagian aturan: anotasi entitas Component yang telah di-resolve dan set lampiran yang dihasilkan cascade 5 Tingkat, dengan menghitung secara setara lampiran yang dilampirkan pada Aggregate, pada subsistem, pada Release, maupun hasil ekspansi anotasi. Mandat yang tidak dipenuhi oleh lampiran mana pun menghentikan build; mandat yang deklarasinya salah bentuk berhenti dengan diagnostik tersendiri, sehingga deklarasi yang rusak tidak pernah terbaca sebagai persyaratan yang terpenuhi. Ketiga, compiler mengeksekusi Gerbang validasi, meneruskan struktur graf lengkap (termasuk semua node, edge, fitur yang dilampirkan, dan path DFS yang telah dihitung sebelumnya) ke plugin governance yang dilampirkan pada peran ir-verdict. Kebijakan Wasm kustom milik perusahaan mengevaluasi topologi. Jika plugin Wasm mengembalikan array kegagalan (misalnya, mendeteksi path berkelanjutan dari node public ke node restricted tanpa fitur proxy tertentu), build dihentikan.

Perenderan

  • Mekanisme: Intersepsi pra-render (injectMapping), late binding (valuesMapping), dan socket rendering Wasm (pipeline).
  • Tindakan: Fase akhir pembuatan artefak dibagi menjadi sub-fase temporal yang ketat yang berjalan dalam urutan tetap, sehingga eksekusi tetap deterministik:
    • Inject mapping (intersepsi pra-render): Compiler Go me-resolve kontrak abstrak .context.inject milik Developer. Kemudian compiler mengeksekusi template Go injectMapping dari semua FeatureRecipes yang dilampirkan mengikuti urutan eksekusi Model Bawang 5 Tingkat yang ketat (Sub-Aggregate — lampiran milik komponen modul itu sendiri, lalu lampiran yang dideklarasikan subsistem modulnya, dari luar ke dalam → komponen Aggregate root → subsistem Aggregate root → boundary Release dari luar ke dalam → khusus komponen Release). Compiler secara native melakukan deep-merge atas dictionary yang dihasilkan di atas pipa memori .context.inject milik Caller. Ini menulis ulang variabel lingkungan dan string koneksi untuk Caller dengan aman sebelum Recipe basis melihatnya. Sebuah mapping boleh menulis ulang apa yang dikirimkan oleh blok inject: milik Caller sendiri atau oleh salah satu koneksinya; kunci yang sudah dikirimkan oleh Feature lain yang dilampirkan — melalui mapping-nya sendiri atau blok inject:-nya sendiri — menghentikan build dengan menyebutkan kedua lampiran, sehingga urutan eksekusi tidak pernah memutuskan di antara nilai dua lampiran.
    • Preamble locals: Sebelum template provides apa pun dijalankan, compiler mengevaluasi entri .locals milik Recipe sesuai urutan penulisannya, masing-masing terhadap konteks lokal-node yang mandiri — .context.instance_id, .values, .infra, dan entri dari blok yang sama yang sudah di-resolve sejauh ini, tetapi tidak .context.inject atau .context.uses. Karena itu, sebuah entri dapat membaca entri saudara yang didefinisikan di atasnya dan menerima nilai saudara tersebut yang telah di-resolve; urutan penulisan adalah bagian dari kontrak di mana pun satu entri membaca entri lain, dan blok tersebut tidak pernah diurutkan ulang agar sebuah referensi dapat di-resolve. Me-resolve locals terlebih dahulu itulah yang memungkinkan template provides membaca .locals. Template .source milik Recipe dievaluasi terhadap konteks yang sama setelah locals tersebut di-resolve, sehingga .locals tetap dapat digunakan kembali sebagai singkatan di seluruh template Recipe dan penulis dapat memparameterisasi .source (versi chart, path, registry) per boundary.
    • Rendering basis (valuesMapping Recipe basis): Compiler mengevaluasi template valuesMapping milik Recipe basis. Template tersebut membaca string yang diintersepsi dari pipa .context.inject (yang ditulis ulang selama inject mapping), dan dictionary values yang dihasilkan diumpankan ke penyedia yang disebutkan oleh capability milik Recipe — penyedia helm dan helm-chart sama-sama me-render melalui Helm — untuk me-render artefak infrastruktur basis.
    • Parsing dan validasi Workload: Untuk Recipe yang mendeklarasikan workload: — konten blok inline, atau workload: { $import: <path> } yang menamai sebuah file — dokumen tersebut dievaluasi sebagai template terhadap konteks render node, lalu di-parse sebagai YAML ke dalam bentuk Workload dan diperiksa: byte hasil render divalidasi terhadap skema Workload, nilai hasil decode juga divalidasi terhadapnya (byte membawa kunci yang dibuang oleh decode, dan decode menghilangkan field yang diberikan kosong, sehingga masing-masing menolak apa yang tidak dapat dilihat oleh yang lain), setiap entri attachments diperiksa terhadap slot yang dideklarasikan oleh featuresSchema milik Component yang terikat, dan setiap referensi sumber daya diperiksa terhadap provides yang telah di-resolve dari slot yang dinamainya. Kegagalan di sini menghentikan build. Workload yang telah di-parse ditempatkan pada konteks template sebagai .workload, sehingga template yang dievaluasi kemudian pada node yang sama dapat membacanya.
    • Evaluasi artefak: Setiap entri yang dideklarasikan Recipe di bawah artifacts: — konten inline, atau file yang dinamai oleh $import: milik entri itu sendiri — dibaca, di-parse sebagai template, dievaluasi terhadap konteks template lengkap, dan membawa provenans build. Proyeksi yang dihasilkan diserahkan ke penyedia, yang menentukan format output, tempat provenans diletakkan, path output, dan byte akhir. Setiap file yang dihasilkan mencatat dari bentuk penulisan mana file itu berasal, sehingga tabrakan nama file dapat menyebutkan setiap kontributor.
    • Sintesis Workload: Workload yang telah di-parse diserahkan ke penyedia yang disebutkan oleh capability milik Recipe, yang menerjemahkannya menjadi sumber daya native penyedia tersebut. Recipe yang tidak mendeklarasikan workload: tidak memiliki apa pun untuk disintesis di sini; file-nya berasal dari render source sebagai gantinya.
    • Rendering Feature (Resource Generation FeatureRecipe): Setiap lampiran pada node yang FeatureRecipe terikatnya membawa source, workload, artifacts, dan/atau valuesMapping miliknya sendiri — pola Resource Generation, yang digunakan untuk manifest tambahan seperti ServiceMonitor, NetworkPolicy, ConfigMap sidecar, atau sumber daya pengiriman kredensial — dievaluasi dalam satu kali lintasan, dalam urutan Model Bawang 5 Tingkat yang sama dengan yang diikuti inject mapping. Ada satu urutan atas satu set lampiran: Feature operasional dan Feature kredensial menempuh jalur yang sama, dan yang membedakan keduanya adalah apa yang dihasilkan FeatureRecipe masing-masing. .values dan .infra setiap lampiran ditukar ke cakupannya sendiri; lampiran mewarisi .locals yang telah dievaluasi dari Recipe basis; .attachment_name menamai instans yang sedang di-render dan .provides membawa provides milik lampiran itu sendiri yang telah di-resolve, kantong yang sama yang dibaca konsumen. Dictionary values yang dihasilkan diumpankan ke penyedia yang disebutkan oleh capability milik FeatureRecipe itu sendiri, dan file hasil render ditambahkan ke output boundary dengan membawa dua koordinat — komponen tempat Feature dilampirkan, lalu nama yang digunakan untuk melampirkannya — sehingga satu nama Feature yang dilampirkan ke beberapa komponen menjaga masing-masing tetap terpisah. Bentuk yang diambil koordinat tersebut mengikuti tata letak penyedia host itu sendiri: direktori <component>--<instance>/ di samping direktori milik komponen, di mana target memberi setiap kontributor posisinya sendiri, dan prefiks nama file <component>--<instance>-- di mana target hanya membaca file yang berada langsung di dalam sebuah direktori. FeatureRecipes yang hanya untuk inject — yang hanya membawa injectMapping, yang sudah ditangani selama inject mapping — dilewati di sini. Seperti sub-fase sebelumnya, rendering fitur berjalan untuk satu komponen pada satu waktu, sehingga sebuah lampiran biasanya dievaluasi tepat setelah komponen tempat ia dilampirkan. Lampiran yang FeatureRecipe-nya mendeklarasikan readsCallerRenderFacts: true atau readsTargetRenderFacts: true justru dievaluasi setelah setiap komponen, dan setiap lampiran yang tidak mendeklarasikan keduanya, selesai di-render — sehingga setiap komponen yang terhubung ke host-nya, dan setiap komponen yang dihubungkan dengan host-nya, sudah di-render saat itu — dan output-nya berada di tempat yang sama seperti seharusnya.
    • Pipeline plugin (eksekusi langkah Wasm): Compiler membaca array pipeline milik Recipe dan mengeksekusi langkah-langkahnya sesuai urutan deklarasi. Compiler mengirimkan plugin Wasm yang dinamai pada setiap langkah terhadap dokumen hasil render node, menerapkan operasi JSON Patch RFC 6902 yang dikembalikan langkah tersebut ke dokumen yang dituju operasi tersebut, dan menghasilkan efek samping langkah tersebut di sampingnya — permukaan di balik mutasi presisi seperti menyuntikkan sidecar Envoy atau memasang VolumeMount secret. Langkah yang gerbang when:-nya di-render sebagai falsy dilewati sebagai pass-through, sehingga set dokumen tidak berubah untuk langkah berikutnya. URI plugin setiap langkah di-resolve sebelum eksekusi ke byte artefak terverifikasi yang dipatok lockfile berdasarkan digest. Langkah-langkah pipeline milik FeatureRecipe dieksekusi dengan cara yang sama, atas dokumen hasil render milik lampiran itu sendiri dan, untuk lampiran bercakupan komponen, juga dokumen milik komponen host.

Ketiga jenis input Recipe mencapai compiler: source: + valuesMapping: melalui rendering basis, workload: melalui parsing workload dan sintesis workload, dan artifacts: melalui evaluasi artefak. Jenis mana yang boleh diserahkan ke penyedia tertentu tidak diputuskan per sub-tahap — hal itu ditetapkan sekali per node, sebelum dispatch render apa pun, dari kontrak yang dideklarasikan penyedia itu sendiri, sehingga Recipe yang jenis inputnya tidak diterima oleh penyedia yang terikat ditolak di sana alih-alih di tengah proses rendering. Lihat 16-recipe-input-composition.md untuk model komposisi tiga jenis input, jenis Workload, dan mekanisme Artifacts, serta Status Bahasa untuk penyedia mana yang menerima jenis mana.

Output native GitOps

Agar tetap secara ketat tanpa opini sendiri terhadap cara output-nya diterapkan, plugin rendering menghasilkan artefak yang dibuat ke dalam struktur direktori yang bersih dan terisolasi per boundary (misalnya, dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/). Ini memungkinkan controller GitOps eksternal (seperti ArgoCD atau Flux) untuk menyinkronkan dan menerapkan infrastruktur tanpa compiler Aggrega pernah membutuhkan kredensial API cluster langsung.

graph TD
    subgraph CLI_Orchestrator ["The Aggrega Compiler Pipeline"]
        direction TB
        A["Resolution — The Resolver & Syntax Validator<br/>(Inheritance Merge + Parameter Interpolation + JSON Schema 2020-12 Validation)"] --> B["Topology construction — The Topology Builder<br/>(AST Expansion + governance label-transform)"]
        
        B -->|"Emits IR Graph"| C["Graph finalization<br/>(Normalization)"]
        
        C -->|"Flat IR Graph"| D["Static analysis — The Static Analyzer<br/>(Selectors + governance ir-verdict Gate)"]
        
        D -->|"Validated Topology"| E["Rendering<br/>Inject mapping: Pre-Render Interception (injectMapping)<br/>Base rendering (valuesMapping)<br/>The plugin pipeline: Wasm Mutation (pipeline)"]
    end
graph LR
    E["Rendering"]
    E -->|"Stringified Artifacts"| F["Helm Charts"]
    E -->|"Stringified Artifacts"| G["Docker Compose"]
    E -->|"Stringified Artifacts"| H["Kubernetes Manifests"]
    E -->|"Stringified Artifacts"| I["Terraform Configuration"]
    E -->|"Stringified Artifacts"| J["CloudFormation Templates"]

Peta sumber infrastruktur

Aggrega mengompilasi Aggregate.yaml ~30 baris menjadi ribuan baris konfigurasi JSON atau YAML fisik. Tanpa cara untuk melacak sumber daya yang sedang berjalan kembali ke sumbernya, men-debug kegagalan di “main.tf.json baris 4.032” memaksa developer merekonstruksi pemetaan secara manual. Untuk mengatasi hal ini, plugin rendering Aggrega menggabungkan pengidentifikasi jejak ke dalam permukaan metadata native milik penyedia — metadata.labels dan metadata.annotations untuk Kubernetes, komentar provenans untuk Terraform, dan konvensi setara per penyedia — sehingga setiap objek hasil render membawa penunjuk kembali ke sumber asalnya. Label aggrega.ai/compiler-version (didokumentasikan di governance-and-compliance §5) adalah salah satu kunci jejak dalam kelompok ini; di sampingnya, stempel itu membawa aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri, dan aggrega.ai/environment, dan penyedia helm, helm-chart, compose, terraform, serta cloudformation masing-masing menghasilkannya — penyedia helm-chart pada file templat yang ditambahkan sebuah Recipe ke chart, karena penyedia itu menyalin templat milik chart tanpa perubahan.

Stempel ini tidak membawa kunci yang mengidentifikasi asal fitur atau jenis katalog.

Dua permukaan debug lain disertakan bersama compiler. aggrega build --trace menulis status antara setiap node, pass demi pass, ke .trace/ di samping dist/, untuk penulis Recipe yang memeriksa apa yang diterima dan dihasilkan setiap tahap; dan diagnostik yang menghentikan build membawa kategori permukaan penulisan tempat ia berada — DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR, dan lainnya — di mana pun kegagalan memilikinya, sehingga ia menunjuk penulis yang tepat. Error yang menelusuri field manifest hasil generasi yang gagal kembali ke baris templat yang menghasilkannya bukan bagian dari compiler.

Pipeline validator

Fase validasi skema dalam resolusi bertumpu pada pipeline validator yang mengubah konten spesifikasi entitas (bentuk ringkas, YAML JSON Schema, atau campuran) menjadi satu dokumen JSON Schema 2020-12 terpadu dengan provenans per daun, lalu memvalidasi konten instans yang ditulis pengembang terhadapnya. Lima tahap berjalan berurutan sebagai transformasi murni; masing-masing merupakan fungsi deterministik atas input yang dideklarasikannya.

Tahap 1 — Kompilasi bentuk ringkas. Kompiler menelusuri pohon YAML dari konten schema:, parameters:, dan SchemaLibrary; melakukan dispatch per node (daun bentuk ringkas vs YAML JSON Schema vs referensi $ref: vs komposisi); lalu menghasilkan JSON Schema 2020-12 yang telah diresolusi. Bentuk ringkas dan YAML JSON Schema dapat bercampur di batas node mana pun melalui escape $jsonschema:; kompiler menangani kasus campuran dengan menelusuri pohon dan melakukan dispatch per node. Transformasi ini adalah fungsi murni: input bentuk ringkas yang sama selalu menghasilkan output JSON Schema yang sama. Lihat language-reference/vocabulary/compact-form-authoring.md untuk kosakata kata kunci.

Tahap 2 — Resolusi spec.templates dan $instantiate:. Untuk entri SchemaLibrary yang ditulis sebagai referensi templat, kompiler menelusuri setiap entri pustaka yang memanggil $instantiate: dengan $args:, menyubstitusikan nilai parameter sebagai penggantian skalar literal, dan menghasilkan entri skema konkret. Substitusi berjalan sekali per pemuatan pustaka; entri yang telah diresolusi disimpan dalam cache. Lihat language-reference/entities/schemalibrary.md untuk bentuk penulisan entitas pustaka.

Tahap 3 — Ekspansi $ref: lintas dokumen. Untuk referensi SchemaLibrary melalui $ref: (bentuk identitas <Library>#/schemas/<entry>), kompiler menelusuri rantai referensi pada waktu kompilasi dengan meneruskan tumpukan resolusi; konten yang dirujuk disisipkan ke dalam skema konsumen. Ekspansi ini mempertahankan deteksi siklus (siklus menghentikan build dengan galat yang menyebut rantainya), pengaman identitas-bukan-lokasi (referensi yang membawa host registry menghentikan build dengan arahan ke bentuk identitas — referensi menunjuk pustaka berdasarkan identitas, bukan lokasi fisik), dan komposisi sumber tunggal (blok $ref: hanya menerima referensi polos; override di sisi konsumen dikomposisikan melalui allOf: milik JSON Schema). Lihat language-reference/vocabulary/cross-document-ref.md untuk semantik resolusinya.

Tahap 4 — Sintesis jembatan untuk featuresSchema:. Kompiler menelusuri konten featuresSchema: setiap entitas sesuai urutan penulis dan menghasilkan fragmen JSON Schema yang menggambarkan bentuk isian yang dapat mengikat setiap slot lampiran, dengan kata kunci ekstensi x-aggrega-inject: pada slot yang mendeklarasikan allowlist inject. Fragmen itu dikompilasi dan diperiksa tersendiri, terhadap blok lampiran yang ditulis, alih-alih digabungkan ke dalam konten schema: yang ditujukan bagi pengembang; kata kunci ekstensi adalah metadata yang diabaikan oleh validasi JSON Schema, dan tidak ada tahap berikutnya yang membacanya kembali dari fragmen — pemeriksaan yang membutuhkan allowlist sebuah slot membaca slot itu. Tabel soket usesSchema: tidak diproyeksikan ke fragmen apa pun: selector: dan inject: sebuah soket dibaca sebagai YAML bertipe yang ditulis Arsitek, dan valueSchema: / infraSchema: per edge dari sebuah soket dikompilasi tersendiri. Sintesis ini adalah fungsi murni atas inputnya.

Tahap 5 — Penggabung khusus dengan provenans. Untuk entitas yang mendeklarasikan extends:, kompiler menelusuri rantai induk; JSON Schema induk yang telah diresolusi menjadi basis; override anak diterapkan di atasnya. Setiap daun dalam skema yang telah diresolusi membawa tag provenans per daun (jalur file, nomor baris, asal induk atau anak). Output penggabung adalah yang dikonsumsi mesin validator; mesin validator adalah implementasi pihak ketiga yang sesuai dengan JSON Schema 2020-12 tanpa modifikasi, dengan penelusur deterministik di sekelilingnya untuk mengeluarkan temuan secara berurutan.

Kelima tahap berjalan sebelum mesin validator melihat skema. Mesin menerima satu dokumen JSON Schema 2020-12 yang telah diresolusi ditambah konten instans pengembang; mesin menghasilkan laporan validasi. Pemformat galat merujuk tag provenans untuk menghasilkan diagnostik bagi pengguna yang menyebut posisi sumber dengan jelas — termasuk file asal untuk batasan yang diwarisi sebuah Feature dari basisnya alih-alih ditulisnya sendiri.

Pipeline validator berjalan di tempat setiap payload pertama kali lengkap — values dan infra sebuah komponen selama resolusi, komponen-komponen sebuah sub-aggregate saat konstruksi topologi memasukkannya, dan payload sebuah lampiran pada finalisasi graf — sehingga temuan skema menghentikan build sebelum analisis statis mengevaluasi selector apa pun, dan sebelum evaluasi asersi, yang memungkinkan templat asersi mengandalkan payload yang telah divalidasi.

Menjaga determinisme di sepanjang pipeline

Setiap tahap pipeline kompilasi menjaga Invarian Output Deterministik: dengan file sumber yang sama, lockfile yang sama, dan versi kompiler yang sama, build menghasilkan output yang identik byte demi byte. Invarian ini mendasar — pengalamatan berbasis konten dalam lockfile membutuhkan digest artefak yang stabil; build yang dapat direproduksi membutuhkan agar rilis yang ditulis di laptop pengembang A terkompilasi menjadi output yang sama di laptop pengembang B dan di CI; kemudahan meninjau diff membutuhkan agar perubahan sumber tampil sebagai satu-satunya perubahan dalam output yang dikompilasi.

Determinisme dijaga oleh sejumlah kecil disiplin yang dipatuhi setiap transformasi:

  • Urutan iterasi tetap. Setiap penelusuran atas YAML berbentuk map beriterasi dalam urutan tetap, karena iterasi map bawaan Go diacak. Kompiler mengurutkan sebelum beriterasi di sebagian besar tahap (kompiler bentuk ringkas, penggabung, resolver spec.templates, pemformat galat, serializer YAML); proyeksi slot lampiran justru membawa urutan penulis sendiri, sehingga urutan properti tabel slot adalah urutan saat tabel itu ditulis.
  • Tanpa penyematan waktu. Kompilasi tidak menyematkan stempel waktu dalam output. Build pada pukul 14.00 menghasilkan artefak yang sama dengan build pada pukul 02.00. Metadata provenans penggabung menggunakan file:baris, bukan file:stempel waktu.
  • Jalur relatif terhadap workspace. Semua jalur dalam output yang telah diresolusi bersifat relatif terhadap workspace; lapisan resolusi jalur menormalkannya sebelum jalur masuk ke output apa pun.
  • Tanpa sumber acak, tanpa status eksternal. Transformasi adalah fungsi murni atas input yang dideklarasikannya (konten entitas, rantai induk, lockfile). Status eksternal hanya dirujuk selama resolusi (pengambilan artefak OCI), dan konten yang telah diresolusi dialamatkan berdasarkan konten melalui digest.
  • Serialisasi YAML kanonis. Output ditulis dalam satu bentuk tetap untuk satu input: urutan kunci yang sama di setiap kedalaman pada setiap eksekusi, dengan array dan array enum: dalam urutan input; indentasi 2 spasi; akhir baris Unix LF; string tanpa tanda kutip jika YAML mengizinkan; bentuk boolean true/false; null dihilangkan untuk field yang tidak ada.
  • Urutan alfabetis $defs:. Entri $defs: skema dikeluarkan dalam urutan kunci alfabetis di JSON Schema yang telah diresolusi. $defs: secara konseptual adalah kamus, bukan daftar berurutan; urutan alfabetis membuat diff dapat diprediksi di seluruh reorganisasi sumber.
  • Paralelisme tidak muncul di output. Kompiler dapat memparalelkan unit-unit independen (entitas yang berbeda dapat dikompilasi secara bersamaan). Hasil paralel dikumpulkan ke dalam struktur deterministik (misalnya diurutkan menurut nama entitas) sebelum diserialisasi.

Pengujian end-to-end compiler mengompilasi setiap fixture beberapa kali dalam satu pengujian dan memastikan bahwa setiap eksekusi menghasilkan file yang sama dengan isi yang identik byte demi byte. Pengulangan kompilasi itulah yang menangkap kebocoran urutan iterasi map atau iterasi atas himpunan yang tidak diurutkan, yang menghasilkan output stabil pada sebagian besar eksekusi dan sesekali berbeda. Pengujian ini berjalan bersama rangkaian pengujian compiler lainnya.

Invarian Output Deterministik berlaku pada waktu build: dengan file sumber yang sama + lockfile yang sama + versi kompiler yang sama, output identik byte demi byte. Properti pendampingnya pada waktu lock (dengan file sumber yang sama + status registry yang sama, lockfile yang sama) lebih lemah — registry dapat berubah (versi baru dapat diterbitkan; sidecar dapat ditambahkan; metadata per komponen dapat berkembang), sehingga dua pemanggilan lock terhadap file sumber yang sama pada waktu berbeda dapat menghasilkan lockfile yang berbeda. Itulah tujuan lockfile, mengikuti konvensi di npm, Cargo, dan Go. Dari lockfile yang baru, build menghasilkan output deterministik. Pemisahan dua momen inilah yang membuat perubahan di sisi registry dapat ditoleransi: sidecar yang diterbitkan pada waktu T2 mengubah pemanggilan lock berikutnya; sidecar itu tidak mengubah build terhadap lockfile yang dihasilkan pada T1.