Skema lockfile per-Release Aggrega
Referensi yang dihasilkan. Jangan diedit secara manual — hasilkan ulang dari JSON Schema yang dipublikasikan.
Id skema: https://aggrega.ai/schemas/lockfile-v1beta1.schema.json
Lockfile yang dihasilkan mesin, yang menyematkan setiap URI yang diresolusi dari sebuah Release untuk build berikutnya yang deterministik. Berada di <release-stem>.lock di samping <release-stem>.yaml; dihasilkan oleh aggrega pull --release <release>; dikonsumsi oleh aggrega build --release <release>. Dua bentuk provenans mencatat dua hubungan berbeda dalam graf dependensi: referenced_from (daftar string) muncul pada entities, sebagai jalur situs penulisan bertitik yang mencatat dari bagian mana dalam Release / Aggregate / Manifest / .aggrega-config.yaml setiap URI ditarik masuk, dan pada plugins, sebagai referensi setiap entitas Plugin yang dilalui untuk mencapai sebuah artefak; consumers (daftar rekaman {consumer_uri, fragments}) muncul pada schema_libraries, mapping_libraries, workload_libraries, dan artifact_libraries untuk mencatat entitas katalog mana yang mereferensikan fragmen <entry-name> mana dari sebuah pustaka — bentuk terstruktur ini membuat diff konsumen yang terdampak oleh kenaikan versi pustaka dapat ditelusuri tanpa me-resolve Release lagi. Disiplin evolusi skema: menambahkan bagian tingkat teratas baru adalah SemVer-MINOR (aditif); menambahkan field baru di dalam bagian yang sudah ada adalah SemVer-MINOR; menghapus kunci atau memperketat batasan adalah SemVer-MAJOR.
Jenis tingkat teratas: object
Properti
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
entities | object[] | tidak | Entitas katalog yang dapat dijangkau dari Release ini: Component, Feature, Recipe, FeatureRecipe, Plugin, Aggregate, Aggregate dan Manifest milik Release itu sendiri, serta Manifest yang diperluas oleh Manifest tersebut. Setiap entri diidentifikasi oleh kind miliknya bersama dengan URI kanonisnya, sehingga dua entitas berbeda jenis yang berbagi nama — misalnya sebuah Aggregate dan sebuah Manifest yang sama-sama bernama imported/flow — adalah dua entri, masing-masing dicocokkan dengan digest miliknya sendiri. Setiap entri mencatat versi yang telah di-resolve, digest dari apa yang dibawa entitas, serta asal situs penulisan (referenced_from) yang menarik URI tersebut ke dalam closure dependensi Release. Lockfile yang entrinya tidak membawa kind sudah usang: aggrega pull --release <release> menulisnya kembali. Default: [] |
external_inputs | ExternalInput[] | tidak | Input jarak jauh yang di-pin ke dalam penyimpanan input beralamat konten pada saat akuisisi — konten yang dikonsumsi oleh render plugin provider dari luar workspace, seperti dokumen skema jarak jauh atau dependensi chart yang tidak di-vendor. Setiap entri mem-pin satu URL ke digest yang menamai byte-nya di penyimpanan. Build menyajikan input yang di-pin dari penyimpanan dan membaca bagian ini tanpa akses jaringan. Default: [] |
generated_at | string | ya | Stempel waktu RFC 3339 dari pull yang menghasilkan lockfile ini; pola membatasi nilai pada bentuk tersebut saat lockfile dimuat. Provenans diagnostik — mencatat momen waktu nyata dari resolusi. Sengaja berubah di antara pull; bukan bagian dari jaminan identitas byte lockfile. Pola: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$. |
mapping_libraries | LibraryEntry[] | tidak | Entri MappingLibrary yang dicapai closure dependensi Release melalui situs Recipe / FeatureRecipe valuesMapping: { $import: ... }. Daftar consumers pada setiap entri mencatat entitas katalog mana yang merujuk fragmen <entry-name> mana dari library — catatan terstruktur yang membuat diff dampak kenaikan versi library dapat dilacak tanpa me-resolve Release lagi. Default: [] |
mutators | object[] | tidak | Lampiran tata kelola peran transform yang telah di-resolve, dalam urutan penulisan. Plugin peran transform (label-transform, yang menulis ulang label node; atau annotation-transform, yang menyisipkan anotasi sebelum ekspansi) membentuk byte output yang di-render, sehingga himpunan lampiran — daftar berurutan, ditambah untuk setiap lampiran peran, koordinat plugin, dan fungsi ekspor — merupakan input penentu byte yang di-pin di sini. Build membaca bagian ini — tidak pernah .aggrega-config.yaml — untuk merekonstruksi himpunan, urutan, peran, dan fungsi ekspor, sehingga output build tidak berubah oleh perubahan plugins.governance yang dibuat setelah pull (baru diadopsi pada pull berikutnya). Urutan bersifat SEMANTIK: setiap runner transform menerapkan lampiran perannya dalam urutan daftar, sehingga tidak seperti bagian plugins / providers yang diurutkan berdasarkan URI, daftar ini tidak pernah diurutkan ulang. Digest konten plugin TIDAK diduplikasi di sini: digest tersebut bersumber tunggal di bagian plugins dan entities, yang dirujuk oleh catatan ini melalui identitas. Default: [] |
plugins | object[] | tidak | Plugin Wasm yang byte-nya membentuk output yang dirender, masing-masing di-pin oleh digest konten .wasm-nya: plugin governance yang dilampirkan dalam peran transform (label-transform, annotation-transform) di bawah .aggrega-config.yaml plugins.governance, ditambah URI plugin tersemat apa pun dari Recipes / FeatureRecipes / Providers yang dirujuk. Plugin governance yang dilampirkan dalam peran verdict (ir-verdict, render-verdict) dan lampiran plugins.linter mengembalikan verdict dan tidak membentuk byte output apa pun, sehingga keduanya tidak di-pin: keduanya tidak muncul di sini maupun di bawah entities, dan file aturan yang dibaca lampiran verdict dicatat di bawah verdict_inputs. Default: [] |
providers | object[] | tidak | Pilihan provider per kapabilitas yang telah di-resolve. Setiap entri mem-pin satu kapabilitas (mis. helm) ke identitas OCI tanpa digest dari plugin perenderan provider yang me-render-nya, di-resolve saat pull dari daftar plugins.providers di .aggrega-config.yaml (jika kapabilitas dilayani secara ambigu) atau dari satu-satunya plugin yang melayaninya (jika tidak ambigu). Build membaca bagian ini — tidak pernah .aggrega-config.yaml — untuk memilih provider, sehingga output build tidak berubah oleh perubahan konfigurasi workspace yang dibuat setelah pull. Digest konten plugin TIDAK diduplikasi di sini: digest tersebut bersumber tunggal di bagian plugins dan entities, yang dirujuk oleh catatan ini melalui identitas. Koeksistensi versi tetap terjaga: catatan ini memilih repositori plugin per kapabilitas; versi konkret berada di entities (satu entri per versi plugin yang di-resolve), dan pin versi spec.capability pada setiap Recipe memilih di antaranya saat render. Default: [] |
release | string | ya | Path ke Release yang sesuai dengan lockfile ini, di-resolve relatif terhadap direktori lockfile itu sendiri (mis. ./release-prod.yaml). Konvensi penamaan per Release menempatkan <release-stem>.lock di samping <release-stem>.yaml; path relatif membuat lockfile mendeskripsikan dirinya sendiri tanpa path absolut yang spesifik mesin. Ini menamai Release; apa yang dimuat Release saat di-resolve dicatat di bawah release_documents. |
release_documents | object[] | tidak | File Release yang dibaca oleh resolusi, masing-masing dicatat dengan digest konten byte-nya: Release pemilik lockfile ini terlebih dahulu, lalu setiap Release yang di-extend-nya, dalam urutan penelusuran rantai extends. Semua yang diminta Release di-resolve dari apa yang dimuatnya, sehingga Release yang diedit setelah pull tidak lagi cocok dengan digest yang dicatat, dan build — atau aggrega pull --verify — berhenti dengan menyebutkan file tersebut, dengan aggrega pull --release <release> sebagai perbaikannya, sebelum apa pun di-render. Digest mencakup byte apa adanya, tanpa ada yang dinormalisasi, aturan yang sama dengan yang diikuti pin Aggregate dan Manifest: suntingan komentar atau spasi dihitung sebagai perubahan. Lockfile tanpa bagian ini tidak mencatat file Release, dan build yang memuatnya melaporkan Release sebagai tidak tercatat. File yang diimpor Release melalui parameters tidak dicatat di sini. |
schema_libraries | LibraryEntry[] | tidak | Entri SchemaLibrary yang dicapai closure dependensi Release melalui situs $ref dan $import: dalam konten entitas schema: / usesSchema: / featuresSchema:. Daftar consumers pada setiap entri mencatat entitas katalog mana yang merujuk fragmen <entry-name> mana dari library — catatan terstruktur yang membuat diff dampak kenaikan versi library dapat dilacak tanpa me-resolve Release lagi. Default: [] |
source_artifacts | SourceArtifactEntry[] | tidak | Artefak sumber yang ditarik dari field spec.source Recipe / FeatureRecipe saat pull. Setiap entri mengidentifikasi identitas {kind, url, chart, pinned_version} yang unik dengan digest konten, mediatype, dan back-pointer referenced_by: terstruktur yang menyebutkan setiap entitas katalog yang di-resolve ke artefak ini. url adalah URL identitas yang ditulis; lokasi artefak yang di-resolve untuk sumber helm root repo dicatat terpisah di bawah resolved_url: sebagai provenans. Beberapa Recipes yang mem-pin chart yang sama pada versi yang sama dideduplikasi menjadi satu entri dengan beberapa catatan referenced_by:. Enum kind mencakup empat jenis sumber yang dapat di-resolve, serta terraform-module-oci, yang tidak dilayani adapter sumber mana pun: Recipe atau FeatureRecipe yang menyebutnya ditolak saat dibaca, sehingga tidak ada pull yang mencatat entri jenis tersebut. Default: [] |
toolchain | object | tidak | Versi toolchain yang menghasilkan lockfile ini: versi compiler itu sendiri, dan versi setiap plugin inti yang dibawa compiler. Dicatat agar lockfile dapat menjawab setelahnya compiler mana dan plugin inti mana yang me-resolve dan me-render sebuah build — pertanyaan yang tidak selalu dapat dijawab oleh bagian yang di-pin, karena plugin provider inti yang disajikan dari dalam biner compiler dibiarkan tanpa pin sehingga tidak membawa versi tercatatnya sendiri. Hanya versi: stempel ini tidak pernah mencatat asal byte plugin, sehingga dua mesin yang mem-pin closure dependensi yang sama dengan compiler yang sama menulis stempel yang sama. Tidak ada yang membandingkan bagian ini, memperingatkan tentangnya, atau menolak build karenanya, dan ketiadaannya dari lockfile tidak menimbulkan pesan: toolchain bukan bagian dari closure dependensi yang di-pin lockfile. Dengan alasan yang sama, bagian ini dikecualikan dari perbandingan identitas byte antara dua pull dari input yang sama, sama halnya dengan generated_at. |
verdict_inputs | object[] | tidak | Input aturan eksternal yang dibaca oleh lampiran governance berperan verdict (ir-verdict / render-verdict) pada waktu kompilasi — file aturan Kyverno / Rego yang diberikan melalui with.sources milik lampiran tersebut. Dicatat sebagai digest konten per sumber, untuk audit dan visibilitas pergeseran antar-pull: digest yang membentuk sebuah verdict dapat dibandingkan antar-pull, sehingga file aturan yang berubah muncul sebagai diff lockfile. Bagian ini adalah PROVENANCE, bukan input build: tidak seperti mutators.sources, bagian ini tidak membawa content, dan build TIDAK membacanya — plugin verdict di-cache alih-alih di-pin dan membaca input aturannya secara langsung (verdict tidak membentuk byte output apa pun, sehingga tidak ada yang di-pin lockfile untuk output deterministik yang mencakupnya). Karena plugin verdict tidak di-pin, plugin tersebut tidak ada di bagian entities / plugins; oleh karena itu catatan ini mengidentifikasi lampiran melalui URI yang ditulis, berdiri sendiri alih-alih menunjuk ke bagian-bagian tersebut. Pencatatan digest membuat input yang menentukan keputusan terima/tolak dapat diaudit dan direproduksi tanpa mem-pin-nya ke dalam build. Default: [] |
version | const 1 | ya | Versi skema lockfile: 1. Perubahan SemVer-MAJOR pada skema akan menaikkannya. Konstanta: 1 |
workload_libraries | LibraryEntry[] | tidak | Entri WorkloadLibrary yang dicapai closure dependensi Release melalui situs Recipe workload: { $import: ... }. Daftar consumers pada setiap entri mencatat entitas katalog mana yang merujuk fragmen <entry-name> mana dari library tersebut — catatan terstruktur yang membuat diff dampak kenaikan versi library dapat dilacak tanpa me-resolve Release lagi. Default: [] |
artifact_libraries | LibraryEntry[] | tidak | Entri ArtifactLibrary yang dicapai closure dependensi Release melalui situs Recipe / FeatureRecipe artifacts.<name>: { $import: ... }. Daftar consumers pada setiap entri mencatat entitas katalog mana yang merujuk bundel <entry-name> mana dari library tersebut — catatan terstruktur yang membuat diff dampak kenaikan versi library dapat dilacak tanpa me-resolve Release lagi. Default: [] |
Properti tambahan tidak diizinkan.
lockfile.entities[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
kind | string (enum) | ya | Jenis entitas katalog, dibaca dari tempat Release, Aggregate miliknya, atau Manifest miliknya menyebutkannya: component dan feature untuk tipe Component atau Feature yang disebutkan oleh Aggregate, Release, atau pemetaan Manifest, recipe dan feature_recipe untuk realisasi yang diikat oleh pemetaan Manifest, plugin untuk entitas Plugin, aggregate untuk Aggregate milik Release itu sendiri dan setiap Aggregate yang disertakannya, serta manifest untuk Manifest milik Release itu sendiri dan Manifest yang diperluasnya. Bersama dengan uri, nilai ini mengidentifikasi entri: build membandingkan setiap entri dengan entitas yang jenis dan URI-nya sama, sehingga suntingan pada salah satu dari dua entitas bernama sama yang berbeda jenis akan terdeteksi. Nilai yang diizinkan: "aggregate", "component", "feature", "feature_recipe", "manifest", "plugin", "recipe" |
uri | string | ya | URI kanonis entitas katalog (misalnya hub.aggrega.ai/component/core/compute/api-server). |
resolved_version | string | ya | Versi konkret yang dipilih resolver pada waktu pull — versi milik entitas katalog itu sendiri (misalnya 1.2.3), atau kosong untuk entitas tingkat atas yang di-resolve melalui path, bukan melalui versi. Dicatat sebagai satu segmen path, karena nilai ini menamai satu segmen, sehingga tidak mengandung /, \ maupun ..: nilai ini membentuk slot cache tempat build membaca kembali entitas ini, dan nilai yang keluar dari direktori cache akan menamai lokasi di luarnya. Pola: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | ya | Digest dari apa yang dibawa oleh publikasi entitas, dalam bentuk sha256: diikuti 64 karakter heksadesimal huruf kecil: SHA-256 atas dokumen entitas dan setiap file yang dideklarasikannya di sampingnya, diurutkan menurut path, masing-masing menyumbangkan path-nya dan SHA-256 dari byte-nya. Entitas yang tidak mendeklarasikan file apa pun dihitung sebagai satu dokumennya. Tidak ada hal lain yang masuk ke dalamnya — bukan cara arsip dikompresi, bukan timestamp, bukan bit izin apa pun, termasuk bit eksekusi — sehingga entitas mencatat digest yang sama baik dibaca dari direktori katalog maupun diambil dari registry, dan pada checkout mana pun dari file yang sama, di sistem mana pun. Pola: ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | tidak | Digest manifest OCI dari artefak yang di-resolve, dalam bentuk sha256: diikuti 64 karakter heksadesimal huruf kecil. Tanda tangan terikat pada digest ini, dan manifest menamai digest dari byte yang dipublikasikan, yang menjadi acuan pemeriksaan pengambilan maupun pembacaan dari cache sebelum entitas dicocokkan dengan digest-nya di atas. Hanya ada untuk entitas yang di-resolve dari registry. Pola: ^sha256:[a-f0-9]{64}$. |
referenced_from | string[] | tidak | Asal situs penulisan — path bertitik ke dalam YAML Release / Aggregate / Manifest (misalnya aggregate.spec.components.api.type) yang mencatat mengapa URI ini ada di dalam closure dependensi Release. Default: [] |
signature | VerifiedSignature | tidak | Fakta tanda tangan terverifikasi yang dicatat ketika tanda tangan entitas ini diverifikasi pada waktu pull, terhadap kebijakan kepercayaan registry yang melakukan resolve. |
deprecation | DeprecationRecord | tidak | Penanda deprecation retroaktif terverifikasi yang dicatat ketika penanda deprecation yang ditandatangani dan tepercaya ditemukan pada artefak ini pada waktu pull. Penanda adalah referrer OCI bertanda tangan dari artefak yang di-deprecate-nya, dilampirkan setelah publikasi tanpa memublikasikan ulang artefak tersebut. Mencatat tingkat keparahan dan pesan penanda beserta penanda tangan terverifikasi yang membuatnya. Build membaca fakta ini dan menegakkan kebijakan deprecation hanya dari lockfile; build tidak pernah menemukan ulang atau memverifikasi ulang penanda tersebut. |
Properti tambahan tidak diizinkan.
lockfile.mutators[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
plugin | string | ya | Koordinat plugin yang di-resolve dari plugin berperan transform — identitas <pluginType>/<name> milik entitas Plugin (misalnya governance/tag-injector). Melakukan join berdasarkan identitas ke bagian plugins dan entities untuk digest dan set versi yang di-pin. |
role | string (enum) | ya | Peran transform yang terikat pada lampiran ini, dicatat apa adanya dari entri plugins.governance yang ditulis, sehingga build menjalankan lampiran tepat pada peran tersebut alih-alih menyimpulkan suatu peran: label-transform menulis ulang label node saat konstruksi topologi; annotation-transform menyisipkan anotasi sebelum ekspansi, selama resolusi. Nilai yang diizinkan: "label-transform", "annotation-transform" |
function | string | tidak | Override export yang dinamai oleh lampiran. Jika tidak ada, export default peran tersebut yang dipilih (mutate untuk label-transform, transform_annotations untuk annotation-transform). |
settings | object | tidak | Objek pengaturan bebas yang dideklarasikan lampiran, di-pin sebagaimana ditulis dan diserahkan ke plugin apa adanya. Build membaca pengaturan dari sini — tidak pernah dari konfigurasi langsung — sehingga perubahan pengaturan setelah pull tidak menggeser output build. Tidak ada jika lampiran tidak mendeklarasikannya. |
sources | object[] | tidak | Pin beralamat konten dari file sumber yang dideklarasikan lampiran, diurutkan menurut nama dasar. Build merekonstruksi sumber yang dibaca plugin dari konten yang tercatat pada setiap pin, bukan dari pembacaan langsung di host, sehingga output build tetap tidak berubah terhadap perubahan file sumber setelah pull. Tidak ada jika lampiran tidak mendeklarasikannya. |
Properti tambahan tidak diizinkan.
lockfile.mutators[].sources[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
content | string | ya | Konten file sumber, dibawa apa adanya sehingga build merekonstruksi input sumber plugin dari lockfile. |
digest | string | ya | Alamat konten dari konten yang tercatat, dalam bentuk sha256: diikuti 64 karakter heksadesimal huruf kecil. Pull ulang membandingkan file yang mendasarinya dengan digest ini untuk mendeteksi pergeseran. Pola: ^sha256:[a-f0-9]{64}$. |
path | string | ya | Nama dasar file sumber — tidak pernah berupa path host absolut, sehingga pin bersifat portabel dan deterministik. |
Properti tambahan tidak diizinkan.
lockfile.plugins[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
uri | string | ya | Identitas polos artefak .wasm milik plugin Wasm — jalur <pluginType>/<name> (mis. governance/aggrega-security-baseline). Segmen pertama adalah tipe plugin (provider, linter, pipeline-step, governance, cli, parser, importer); segmen sesudahnya adalah nama plugin. Tipe dan nama bersama-sama membentuk identitas plugin — nama yang sama di bawah dua tipe adalah dua plugin. Lokasi pengambilan fisik diturunkan dari identitas ini ditambah registry yang dikonfigurasi, dan tidak pernah dibawa di dalam lockfile. |
resolved_version | string | ya | Digest konten yang menjadi hasil resolusi artefak Wasm, dalam bentuk sha256: diikuti 64 karakter heksadesimal huruf kecil. Artefak plugin dialamatkan berdasarkan konten, bukan dinamai berdasarkan versi — sebuah .wasm dibawa inline di dalam manifest plugin-nya dan di-pin oleh digest byte-nya — sehingga field ini mencatat digest tersebut, yang juga merupakan digest di bawah. Nilai ini membentuk slot cache tempat build membaca kembali artefak tersebut, sehingga tidak memuat /, \, maupun .., yang memang sudah dikecualikan oleh bentuk sha256:. Pola: ^sha256:[a-f0-9]{64}$. |
digest | string | ya | Digest konten artefak Wasm yang diresolusi, dalam bentuk sha256: diikuti 64 karakter heksadesimal huruf kecil — bentuk penulisan alamat konten di setiap tempat ia dibandingkan. Pola: ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | tidak | Digest manifest OCI dari artefak Wasm yang diresolusi, dalam bentuk sha256: diikuti 64 karakter heksadesimal huruf kecil. Tanda tangan berkomitmen pada digest ini; digest konten di atas adalah identitas portabel yang digunakan untuk pin cache dan pemeriksaan integritas. Hanya ada untuk artefak yang diresolusi dari registry. Pola: ^sha256:[a-f0-9]{64}$. |
referenced_from | string[] | tidak | Alasan artefak ini ada di dalam closure dependensi Release: referensi setiap entitas Plugin yang dilalui untuk mencapainya, sebagaimana bagian entities mencatat entitas tersebut (mis. governance/label-injector:1.0.0). Default: [] |
signature | VerifiedSignature | tidak | Fakta tanda tangan terverifikasi yang dicatat saat tanda tangan plugin ini diverifikasi pada waktu pull, terhadap kebijakan kepercayaan per-registry yang sama dengan entitas katalog. |
deprecation | DeprecationRecord | tidak | Penanda deprecation retroaktif terverifikasi yang dicatat ketika penanda deprecation yang ditandatangani dan tepercaya ditemukan pada artefak ini pada waktu pull. Penanda adalah referrer OCI bertanda tangan dari artefak yang di-deprecate-nya, dilampirkan setelah publikasi tanpa memublikasikan ulang artefak tersebut. Mencatat tingkat keparahan dan pesan penanda beserta penanda tangan terverifikasi yang membuatnya. Build membaca fakta ini dan menegakkan kebijakan deprecation hanya dari lockfile; build tidak pernah menemukan ulang atau memverifikasi ulang penanda tersebut. |
Properti tambahan tidak diizinkan.
lockfile.providers[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
capability | string | ya | Kapabilitas yang provider-nya dipilih oleh binding ini — nama kapabilitas polos yang diikat oleh sebuah Recipe melalui spec.capability (mis. helm, compose). |
plugin | string | ya | Identitas polos plugin perenderan provider yang diresolusi (identitas entitas Plugin, yaitu metadata.pluginType dan metadata.name miliknya yang digabungkan dengan garis miring, mis. provider/helm). Digabungkan berdasarkan identitas ke dalam bagian plugins dan entities untuk digest yang di-pin dan himpunan versinya. |
Properti tambahan tidak diizinkan.
lockfile.release_documents[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
digest | string | ya | Digest konten byte file Release pada saat resolusi membacanya, dalam bentuk sha256: diikuti 64 karakter heksadesimal huruf kecil. Pola: ^sha256:[a-f0-9]{64}$. |
path | string | ya | Jalur file Release relatif terhadap direktori yang memuat Release pemilik lockfile ini, dengan garis miring maju (mis. release-prod.yaml, ../shared/base-release.yaml) — tidak pernah berupa jalur host absolut, sehingga catatan ini portabel dan deterministik. |
Properti tambahan tidak diizinkan.
lockfile.toolchain
Versi toolchain yang menghasilkan lockfile ini: versi compiler itu sendiri, dan versi setiap plugin inti yang dibawa compiler. Dicatat agar lockfile dapat menjawab setelahnya compiler mana dan plugin inti mana yang me-resolve dan me-render sebuah build — pertanyaan yang tidak selalu dapat dijawab oleh bagian yang di-pin, karena plugin provider inti yang disajikan dari dalam biner compiler dibiarkan tanpa pin sehingga tidak membawa versi tercatatnya sendiri. Hanya versi: stempel ini tidak pernah mencatat asal byte plugin, sehingga dua mesin yang mem-pin closure dependensi yang sama dengan compiler yang sama menulis stempel yang sama. Tidak ada yang membandingkan bagian ini, memperingatkan tentangnya, atau menolak build karenanya, dan ketiadaannya dari lockfile tidak menimbulkan pesan: toolchain bukan bagian dari closure dependensi yang di-pin lockfile. Dengan alasan yang sama, bagian ini dikecualikan dari perbandingan identitas byte antara dua pull dari input yang sama, sama halnya dengan generated_at.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
compiler_version | string | ya | Versi compiler yang menulis lockfile ini, dalam bentuk tanpa awalan v yang dilaporkan oleh setiap antarmuka Aggrega (1.2.0, bukan v1.2.0). Build yang diberi stempel versi mencatat versi tersebut — build rilis bertag mencatat tag-nya — dan build tanpa stempel versi mencatat penanda (devel), sehingga lockfile yang dihasilkan oleh compiler tanpa stempel tidak dikira sebagai keluaran rilis. Dicatat sebagai satu segmen jalur, sehingga tidak memuat /, \, maupun ... Pola: ^([^/\\.]|\.[^/\\.])*\.?$. |
core_plugins | object[] | ya | Versi setiap plugin inti yang dibawa compiler, satu entri per plugin, diurutkan menurut koordinat plugin. Plugin inti diterbitkan pada tag compiler itu sendiri dengan versi yang sama, sehingga versi-versi ini terbaca sama, baik compiler menyajikan plugin dari dalam dirinya maupun mengambilnya dari registry — itulah yang menjaga stempel ini bebas dari detail khusus mesin. Kosong untuk build yang tidak membawa plugin inti. Default: [] |
Properti tambahan tidak diizinkan.
lockfile.toolchain.core_plugins[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
plugin | string | ya | Koordinat plugin inti — identitas <pluginType>/<name> milik entitas Plugin (mis. provider/helm), identitas yang sama yang digunakan bagian providers dan mutators untuk menyebut sebuah plugin. |
version | string | ya | Versi plugin inti ini, dalam bentuk tanpa awalan v yang dilaporkan oleh setiap antarmuka Aggrega. Dicatat sebagai satu segmen jalur, sehingga tidak memuat /, \, maupun ... Pola: ^([^/\\.]|\.[^/\\.])*\.?$. |
Properti tambahan tidak diizinkan.
lockfile.verdict_inputs[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
plugin | string | ya | URI plugin yang ditulis untuk lampiran verdict, sebagaimana tertulis di .aggrega-config.yaml plugins.governance (mis. governance/aggrega-security-baseline:1.0.0). Mengidentifikasi lampiran pemilik masukan aturan yang dicatat; plugin verdict di-cache alih-alih di-pin, sehingga tidak memiliki entri di bagian plugins / entities untuk digabungkan. |
role | string (enum) | ya | Peran verdict yang terikat pada lampiran ini — ir-verdict (pada analisis statis, atas graf IR) atau render-verdict (pada perenderan, atas artefak yang dirender). Membedakan plugin yang sama yang dilampirkan pada kedua tahap verdict, masing-masing berpotensi dengan masukan aturannya sendiri. Nilai yang diizinkan: "ir-verdict", "render-verdict" |
sources | object[] | tidak | Digest konten file masukan aturan yang dideklarasikan lampiran, dalam urutan nama dasar. Tidak ada jika lampiran tidak mendeklarasikan sumber. |
Properti tambahan tidak diizinkan.
lockfile.verdict_inputs[].sources[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
digest | string | ya | Alamat konten byte file masukan aturan pada waktu pull, dalam bentuk sha256: diikuti 64 karakter heksadesimal huruf kecil. Pull ulang menghitungnya kembali, sehingga file aturan yang berubah muncul sebagai diff lockfile. Pola: ^sha256:[a-f0-9]{64}$. |
path | string | ya | Nama dasar file masukan aturan — tidak pernah berupa jalur host absolut, sehingga catatan ini portabel dan deterministik. |
Properti tambahan tidak diizinkan.
Definisi
DeprecationRecord
Penanda deprecation retroaktif terverifikasi yang dicatat ketika penanda deprecation yang ditandatangani dan tepercaya ditemukan pada artefak ini pada waktu pull. Penanda adalah referrer OCI bertanda tangan dari artefak yang di-deprecate-nya, dilampirkan setelah publikasi tanpa memublikasikan ulang artefak tersebut. Mencatat tingkat keparahan dan pesan penanda beserta penanda tangan terverifikasi yang membuatnya. Build membaca fakta ini dan menegakkan kebijakan deprecation hanya dari lockfile; build tidak pernah menemukan ulang atau memverifikasi ulang penanda tersebut.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
message | string | ya | Pesan deprecation yang dapat dibaca manusia yang dibawa oleh penanda — biasanya petunjuk migrasi. |
severity | string (enum) | ya | Tingkat keparahan penanda, berurutan warning < error < retracted. Build berhenti ketika tingkat keparahan ini memenuhi atau melampaui ambang henti yang dikonfigurasi, dan mengeluarkan peringatan jika tidak. Nilai yang diizinkan: "warning", "error", "retracted" |
signer | VerifiedSignature | tidak | Penanda tangan terverifikasi dari penanda, dicatat dengan cara yang sama seperti penanda tangan tanda tangan artefak: subjek/penerbit sertifikat untuk mode keyless, atau sidik jari kunci yang di-pin untuk mode keyed. Penanda adalah artefak bertanda tangan tersendiri, sehingga penanda tangannya memiliki bentuk yang sama dengan tanda tangan artefak — dan bundle_digest di sini menamai bundel tanda tangan milik penanda itu sendiri, bukan milik artefak yang di-deprecate. |
Properti tambahan tidak diizinkan.
ExternalInput
Satu input eksternal yang di-pin: URL yang diminta oleh render, pin SHA-256 yang menamai byte-nya di penyimpanan input beralamat konten (sha256/<digest>), ukuran payload, dan provenans konsumen yang membutuhkannya. Pin bersifat otoritatif — URL yang di-pin selalu dilayani dari penyimpanan, dan pengisian ulang penyimpanan diverifikasi terhadap digest ini sebelum byte-nya mencapai render.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
required_by | string[] | ya | Provenans — situs render yang meminta input ini. Diurutkan dan dihilangkan duplikatnya oleh penulis lockfile. |
sha256 | string | ya | Pin SHA-256 dalam hex huruf kecil. Untuk input https, digest dari byte payload; untuk input oci, digest manifest yang dihasilkan dari resolusi referensi. Menamai blob penyimpanan di sha256/<digest>. Pola: ^[0-9a-f]{64}$. |
size | integer | ya | Ukuran payload yang di-pin dalam byte. Jumlah byte tidak pernah negatif. Minimum: 0. |
url | string | ya | URL input sebagaimana ditulis di situs render — kunci pencarian yang mencocokkan permintaan saat render dengan pin-nya. |
Properti tambahan tidak diizinkan.
LibraryEntry
Bentuk umum yang digunakan bersama oleh entri schema_libraries, mapping_libraries, workload_libraries, dan artifact_libraries. Daftar consumers menangkap hubungan graf katalog — entitas katalog mana yang mereferensikan fragmen <entry-name> mana dari library ini — untuk mendukung diff dampak terstruktur ketika digest library berubah. Library adalah artefak OCI seperti artefak lainnya, sehingga mencatat fakta terverifikasi yang sama dengan entitas katalog: digest manifest yang menjadi komitmen tanda tangannya, tanda tangan terverifikasi itu sendiri, dan penanda deprecation retroaktif terverifikasi yang ditemukan saat pull.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
uri | string | ya | URI kanonis dari entitas library. |
resolved_version | string | ya | Versi konkret yang dihasilkan saat pull (pemilihan versi minimum atas graf dependensi library) — versi milik library itu sendiri. Dicatat sebagai satu segmen path, karena nilai ini membentuk slot cache tempat build membaca kembali library, sehingga tidak memuat /, \ maupun ..: nilai yang keluar dari direktori cache akan menamai lokasi di luarnya. Pola: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | ya | Digest konten dari artefak library yang dihasilkan, dalam bentuk sha256: diikuti 64 karakter hex huruf kecil — bentuk penulisan alamat konten di setiap tempat ia dibandingkan. Pola: ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | tidak | Digest manifest OCI dari artefak library yang dihasilkan, dalam bentuk sha256: diikuti 64 karakter hex huruf kecil. Tanda tangan berkomitmen pada digest ini; digest konten di atas adalah identitas portabel yang digunakan untuk pin cache dan pemeriksaan integritas. Hanya ada untuk library yang di-resolve dari registry. Pola: ^sha256:[a-f0-9]{64}$. |
signature | VerifiedSignature | tidak | Fakta tanda tangan terverifikasi yang dicatat ketika tanda tangan library ini diverifikasi saat pull, terhadap kebijakan kepercayaan per registry yang sama seperti entitas katalog. |
deprecation | DeprecationRecord | tidak | Penanda deprecation retroaktif terverifikasi yang ditemukan pada library ini saat pull. Build melaporkannya dan, jika workspace mengonfigurasi ambang henti yang dipenuhi oleh tingkat keparahan yang tercatat, berhenti — sehingga library yang ditarik setelah versinya di-pin diumumkan pada setiap build, bukan hanya saat pemilihan versi, yang dilewati oleh versi yang di-pin secara eksplisit. |
consumers | object[] | tidak | Catatan tentang entitas katalog mana yang mereferensikan library ini dan pada fragmen <entry-name> mana. Menangkap fan-in: banyak konsumen per library, masing-masing berpotensi mereferensikan banyak fragmen. Setiap catatan memuat URI konsumen beserta himpunan fragmen yang ditarik oleh konsumen tersebut. Default: [] |
Properti tambahan tidak diizinkan.
LibraryEntry.consumers[]
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
consumer_uri | string | ya | URI kanonis entitas katalog yang merujuk library ini: sebuah Component atau Feature untuk library skema, sebuah Recipe atau FeatureRecipe untuk library mapping, workload, atau artefak, atau library lain dengan jenis yang sama yang entrinya merujuk library ini. |
fragments | string[] | ya | Himpunan fragmen <entry-name> yang direferensikan konsumen ini di dalam library (mis. ["#/schemas/PortSpec", "#/schemas/EndpointSpec"]). Urutannya dikanonisasi secara leksikografis oleh penulis. |
Properti tambahan tidak diizinkan.
SourceArtifactEntry
Satu pin artefak sumber: identitas {kind, url, chart, module_subdir, pinned_version}, digest konten yang memverifikasi pull, mediatype kanonis, dan penunjuk balik terstruktur ke setiap entitas katalog yang di-resolve ke artefak ini. chart dan module_subdir adalah dua istilah pemilih — masing-masing menyebut apa pun yang tidak disebut oleh URL saja, untuk kind yang memerlukannya.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
kind | enum | ya | Kind sumber. Menentukan adapter mana yang me-resolve artefak dan mediatype mana yang diharapkan. terraform-module-oci termasuk dalam himpunan ini, dan tidak ada adapter sumber yang melayaninya: Recipe atau FeatureRecipe yang menyebutnya ditolak saat dibaca. Nilai yang diizinkan: "helm-oci-chart", "helm-https-chart", "compose-https-fragment", "git-repository", "terraform-module-oci" |
url | string | ya | URL yang ditulis — URL identitas sebagaimana ditulis dalam spec.source.url milik Recipe. Untuk helm-https-chart, ini adalah root repo (bentuk repo-root) atau .tgz langsung (bentuk langsung) persis seperti yang ditulis; build merekonstruksi URL yang sama ini secara offline, sehingga URL ini menjadi identitas stabil yang menjadi kunci pin. Untuk git-repository, URL repositori yang dapat di-clone. Untuk helm-oci-chart, referensi registry. Untuk compose-https-fragment, URL HTTPS dari fragmen tersebut. Lokasi artefak hasil resolve untuk sumber helm repo-root dicatat terpisah di bawah resolved_url: sebagai provenans. |
chart | string | tidak | Nama chart untuk sumber helm repo-root (spec.source.chart milik Recipe), bagian dari identitas {kind, url, chart, module_subdir, pinned_version} sehingga dua chart yang disajikan dari satu root repo pada versi yang sama di-pin ke entri yang berbeda. Tidak ada untuk sumber .tgz langsung, OCI, compose, atau git, yang tidak satu pun memilih chart di dalam URL. |
module_subdir | string | tidak | Direktori di dalam repositori bersumber git yang merupakan artefak (spec.source.module_subdir milik Recipe), bagian dari identitas {kind, url, chart, module_subdir, pinned_version} sehingga dua direktori dari satu repositori pada commit yang sama di-pin ke entri yang berbeda. Tidak ada jika seluruh repositori adalah artefak, dan untuk setiap kind yang mencapai artefaknya melalui URL alih-alih dengan menelusuri ke dalam clone. |
pinned_version | string | ya | Versi konkret yang di-pin saat pull. Untuk kind helm-*, versi chart. Untuk git-repository, commit tempat referensi yang ditulis di-resolve (BUKAN ref tag/branch asli — itu dicatat di bawah requested_ref: pada setiap entri referenced_by:, setiap kali Recipe menulis spec.source.ref:). Build menemukan entri ini berdasarkan apa yang ditulis Recipe: ref: yang ditulis jika ada, dicocokkan dengan requested_ref: yang dicatat, dan nilai yang di-pin ini jika tidak — sehingga Recipe yang menyebut tag di-resolve ke commit tempat tag itu di-pin, tanpa commit tersebut pernah muncul dalam Recipe. Dicatat sebagai satu segmen path, karena nilai ini membentuk slot cache tempat build membaca kembali artefak, sehingga tidak memuat /, \, maupun ... Pola: ^([^/\\.]|\.[^/\\.])*\.?$. |
resolved_url | string | tidak | Hanya provenans: lokasi artefak konkret tempat URL yang ditulis di-resolve saat pull. Untuk sumber helm repo-root, ini adalah URL .tgz langsung yang di-resolve oleh indeks repositori untuk chart+versi; nilai ini dicatat untuk diagnostik dan BUKAN bagian dari identitas artefak. Tidak ada jika lokasi hasil resolve sama dengan URL yang ditulis (sumber .tgz langsung, OCI, compose, atau git). |
digest | string | ya | Digest konten dari arsip .tar.gz hasil resolve, dalam bentuk sha256: diikuti 64 karakter hex huruf kecil. Verifikasi saat build membaca byte slot cache, menghitung ulang digest, dan membandingkannya dengan field ini; ketidakcocokan menghentikan build dengan melaporkan ketidakcocokan digest konten. Pola: ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | tidak | Digest manifest OCI dari artefak hasil resolve, dalam bentuk sha256: diikuti 64 karakter hex huruf kecil. Manifest adalah akar kepercayaan independen yang menjadi acuan verifikasi arsip di cache; digest konten di atas adalah identitas portabel yang digunakan untuk pin cache dan pemeriksaan integritas. Hanya ada untuk sumber yang didistribusikan melalui OCI (helm-oci-chart). Pola: ^sha256:[a-f0-9]{64}$. |
mediatype | string | ya | Media type kanonis yang diumumkan registry (atau default kind tersebut untuk kind tanpa metadata registry). Dicatat untuk provenans diagnostik. |
referenced_by | SourceArtifactReference[] | ya | Entitas katalog yang di-resolve ke artefak ini, diurutkan berdasarkan (uri, field) untuk output yang deterministik. Sebuah entri hanya ada karena sebuah Recipe atau FeatureRecipe menariknya, sehingga daftar ini tidak pernah kosong. Minimal 1 entri. |
Properti tambahan tidak diizinkan.
SourceArtifactReference
Satu penunjuk balik entitas katalog → artefak sumber. entity + uri bersama-sama mengidentifikasi entitas katalog; field menyebut path sisi sumber di dalam spec entitas tempat artefak dideklarasikan. requested_ref: yang opsional mempertahankan spec.source.ref: yang ditulis Recipe, dan ditulis setiap kali Recipe menulisnya (tag/branch git-repository → SHA commit).
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
entity | enum | ya | Kind entitas katalog yang memegang penunjuk balik ini. Nilai yang diizinkan: "recipe", "feature_recipe" |
uri | string | ya | URI kanonis dari Recipe atau FeatureRecipe (mis. hub.aggrega.ai/recipe/helm/mariadb-bitnami:1.0.0). |
field | string | ya | Path sisi sumber di dalam spec entitas tempat artefak dideklarasikan. Nilainya adalah spec.source. |
requested_ref | string | tidak | Opsional — spec.source.ref: yang ditulis Recipe, ditulis setiap kali Recipe menulisnya. Untuk Recipe git-repository yang menulis ref: v1.0.0, field ini mempertahankan "v1.0.0" sementara pinned_version: memuat commit tempat referensi itu di-resolve. Tidak ada jika Recipe tidak menulis ref:, yaitu setiap kind yang resolver-nya mem-pin versi yang ditulis apa adanya (helm-, compose-). Field ini menjalankan dua tugas sekaligus, dan mencatatnya tanpa syarat itulah yang mencegah keduanya saling meniadakan. Build melakukan join padanya untuk menemukan entri ini dari Recipe yang menyebut referensi alih-alih commit. Dan pull yang bukan upgrade menahan setiap referensi yang dicatat pada versi yang di-pin: referensi yang telah berpindah di remote-nya menghentikan eksekusi alih-alih diadopsi. |
Properti tambahan tidak diizinkan.
VerifiedSignature
Fakta tanda tangan terverifikasi yang dicatat ketika tanda tangan sebuah artefak diverifikasi pada saat pull, terhadap kebijakan kepercayaan registry yang melakukan resolusi. Setiap artefak yang dapat ditandatangani mencatatnya dengan cara yang sama — entitas katalog, pustaka, plugin Wasm — karena semuanya diverifikasi melalui satu jalur, bukan satu jalur per kind. Mencatat mode verifikasi, identitas/penerbit keyless yang cocok (jika keyless), dan digest beralamat konten dari bundle tanda tangan di dalam cache konten. Build tidak menjalankan ulang verifikasi. Sebelum apa pun dirender, build membaca fakta ini pada setiap entri yang menjadi dasar build, di setiap bagian: build menghitung ulang hash bundle yang di-cache dan membandingkan hasilnya dengan bundle_digest, lalu berhenti jika blob tidak ada atau berbeda; dan untuk entri yang dilayani oleh cache konten, build membaca dari bundle tersebut untuk artefak mana tanda tangan itu dibuat, lalu berhenti jika tanda tangan itu dibuat untuk artefak yang berbeda dari artefak yang dibaca build untuk entri tersebut — sehingga signature yang disalin dari satu entri ke entri lain ditolak, apa pun yang dinyatakan persyaratan penandatanganan. Build tidak memverifikasi tanda tangan apa pun, sehingga bundle yang ditulis ke cache secara manual, yang dibuat untuk artefak milik entri itu sendiri, tidak dapat dibedakan dari bundle yang diverifikasi oleh pull. Dan jika konfigurasi kepercayaan workspace mewajibkan tanda tangan untuk entri yang dilayani oleh cache konten — persyaratan yang diterapkan pull saat mengambil artefak, sehingga pengecualian dan registry advisory yang memungkinkan pull menerima artefak tanpa tanda tangan juga memungkinkan build menerima entrinya — entri yang tidak membawa fakta akan menghentikan build. Entri yang dibaca dari direktori katalog, dari salinan di dalam biner compiler, atau dari samping Release tidak pernah dikenai persyaratan tersebut.
| Properti | Jenis | Wajib | Deskripsi |
|---|---|---|---|
bundle_digest | string | ya | Digest SHA-256 dari blob bundle tanda tangan yang di-cache, dalam bentuk sha256: diikuti 64 karakter heksadesimal huruf kecil. Nilai ini menamai blob cache, sehingga membentuk sebuah path dan tidak memuat /, \, maupun .. — yang sudah dikecualikan oleh bentuk sha256: — dan pada entri di bagian mana pun, nilai inilah yang menjadi pembanding saat build menghitung ulang hash blob tersebut. Pola: ^sha256:[a-f0-9]{64}$. |
identity | string | tidak | Penanda tangan terverifikasi dari tanda tangan: subjek sertifikat penandatanganan untuk tanda tangan keyless, atau keyed:sha256: diikuti SHA-256 dari teks PEM kunci publik yang di-pin untuk tanda tangan keyed. |
issuer | string | tidak | Penerbit OIDC terverifikasi untuk tanda tangan keyless. Kosong untuk tanda tangan keyed. |
mode | string (enum) | ya | Mode verifikasi yang menerima tanda tangan. Nilai yang diizinkan: "keyless", "keyed" |
Properti tambahan tidak diizinkan.