Katalog dan registri
Bab ini mendefinisikan bagaimana platform diskalakan di seluruh perusahaan melalui Katalog Open Container Initiative (OCI): bagaimana katalog ditata, bagaimana sebuah referensi diresolusi, bagaimana sebuah entitas dipublikasikan dan disematkan, serta bentuk nama yang diikuti entitas katalog.
Katalog Aggrega: taksonomi dan resolusi registri
Compiler Aggrega mengandalkan registri bertipe ketat yang terinspirasi OAM untuk menguraikan niat developer yang abstrak (Domain 1) menjadi realitas Ops yang konkret (Domain 3). Untuk mendukung ekosistem yang terbuka dan terdistribusi sambil mempertahankan pengalaman developer yang mulus, semua skema, binding infrastruktur, kebijakan yang dapat diprogram, dan plugin adaptor mengikuti taksonomi URI Open Container Initiative (OCI) yang terstandardisasi. Karena setiap entitas katalog dapat dialamatkan melalui URI, aggrega pull mengambil entitas yang dibutuhkan sebuah Release ke dalam cache dan menyematkannya dalam lockfile-nya, lalu build membacanya dari sana. Workspace lokal developer hanya berisi file Aggregate dan Release miliknya, bukan salinan katalog.
1. Struktur direktori inti (katalog)
Folder aggrega-catalog milik pustaka standar (dan setiap katalog pihak ketiga yang patuh) diorganisasikan untuk menegakkan Pemisahan Tanggung Jawab secara fisik. Strukturnya secara eksplisit memisahkan antarmuka abstrak dari implementasi infrastruktur konkretnya.
Untuk Components dan Features, segmen URI dipetakan 1:1 ke segmen jalur sistem file. Components menggunakan URI tiga segmen ({publisher}/{category}/{name}) dengan segmen kategori yang membawa salah satu dari himpunan tertutup kategori kognitif — kata yang sama dengan label component.aggrega.ai/category milik komponen (cermin direktori 1:1, yang diperiksa oleh aturan category-matches-directory milik linter publikasi). Features tetap datar ({publisher}/{name}) — himpunan kecil yang tumbuh lambat. Klasifikasi ontologi operasional (stateful-server, server, dll.) berada di label component.aggrega.ai/type, tidak pernah di struktur direktori; label kapabilitas kognitif (datastore.aggrega.ai/engine, agent.aggrega.ai/autonomy, …) melapiskan subset perilaku di atasnya. UI web hub menggunakan label untuk pemfilteran dan pencarian; kategori melayani navigasi sistem file sekaligus sumbu penjelajahan katalog.
Pohon di bawah ini bersifat ilustratif dalam isinya dan tepat dalam bentuknya. Jika sebuah entitas digambar secara lengkap, entitas itu berlanjut hingga ke file daunnya, sehingga seluruh jalur nyata dapat dibaca dari diagram: tingkat direktori mana yang membawa segmen URI mana, di mana segmen versi wajib berada, dan nama file apa yang digunakan setiap jenis entitas pada daun. Pohon ini menampilkan segelintir entri per tingkat alih-alih seluruh isi katalog — ... menandai penghilangan, dan nama-nama yang ditulis di sampingnya adalah entri lain pada tingkat yang sama.
aggrega-catalog/│├── schemalibrary/ # TIER 3: Reusable JSON Schema 2020-12 definitions│ │ # Shared shapes (BaseComponentParameter,│ │ # BaseDatastoreParameter) consumed from a Component or│ │ # Feature schema via $ref: <Library>#/schemas/<name>│ │ # Path: {name}/{version}/library.yaml│ ││ ├── ai-datastores/│ │ └── 1.0.0/│ │ └── library.yaml│ └── base-components/│ └── 1.0.0/│ └── library.yaml│├── workloadlibrary/ # TIER 3: Reusable Workload template fragments│ │ # Shared bodies (StatelessService) consumed from a│ │ # Recipe via workload: { $import: <Library>#/workloads/<name> }│ │ # Path: {name}/{version}/library.yaml│ ││ └── base-workloads/│ └── 1.0.0/│ └── library.yaml│├── component/ # DOMAIN 2: Abstract Interfaces│ │ # URI: {publisher}/{category}/{name}│ │ # Path: {publisher}/{category}/{name}/{version}/component.yaml│ │ # type: core/datastore/mariadb:1.0.0│ │ # → component/core/datastore/mariadb/1.0.0/component.yaml│ ││ ├── core/ # "core" = official Aggrega standard library│ │ ├── ai-agent/ # AI agent frameworks, platforms, patterns│ │ │ └── ... # anthropic, crewai, langflow, pydantic-ai, …│ │ ├── ai-model/ # model providers and inference runtimes│ │ │ └── ... # ai21, anthropic, azure-openai, openai, …│ │ ├── ai-tool/ # tools agents invoke│ │ │ └── ... # browser, mcp, search, …│ │ ├── ai-pipeline/ # AI data/processing pipelines│ │ │ └── ... # argo-workflows, temporal│ │ ├── datastore/ # persistent datastores│ │ │ ├── mariadb/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ ├── postgres/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ └── ... # etcd, ferretdb, qdrant, redis, valkey, …│ │ ├── gateway/ # API and AI gateways│ │ │ └── ... # apisix, contour, kong, nginx, …│ │ ├── compute/ # generic compute primitives│ │ │ └── ... # function, keda, server, task, worker, …│ │ ├── messaging/ # event buses, queues│ │ │ └── ... # kafka, nats, rabbitmq, …│ │ ├── observability/ # metrics, logs, traces│ │ │ └── ... # grafana, loki, otel-collector, prometheus, tempo, …│ │ ├── security/ # identity, secrets, certificates│ │ │ └── ... # cert-manager, external-secrets, keycloak, …│ │ ├── devtool/ # developer-facing tooling│ │ │ └── ... # adminer, promptlayer, …│ │ └── storage/ # object/file storage, and the backup controllers│ │ │ # that copy a cluster's resources, or its│ │ │ # volumes' files, into a bucket│ │ ├── s3-object-store/│ │ │ └── 1.0.0/│ │ │ └── component.yaml│ │ └── ... # barman-cloud-plugin, gcs, k8up, velero, …│ └── example/ # a second publisher, same three-segment shape│ └── compute/│ └── greeter/│ └── 1.0.0/│ └── component.yaml│├── feature/ # DOMAIN 2: Abstract Interfaces│ │ # Flat: {publisher}/{name} (no category segment)│ │ # Path: {publisher}/{name}/{version}/feature.yaml│ │ # type: core/data-masking:1.0.0│ │ # → feature/core/data-masking/1.0.0/feature.yaml│ ││ ├── core/│ │ ├── data-masking/│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ ├── secret-value/ # feature.aggrega.ai/kind: secret│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ └── ... # k8s-dns-resolver, public-ingress, retry-policy, …│ └── ... # other publishers, same flat shape│├── aggregate/ # DOMAIN 1: Reusable Aggregate Modules│ │ # Path: {publisher}/{name}/{version}/aggregate.yaml│ └── core/│ ├── keycloak/│ │ └── 1.0.0/│ │ └── aggregate.yaml│ └── ... # agenta, apisix, dify, harbor, kong, thanos, …│├── recipe/ # DOMAIN 3: Concrete Implementations│ │ # Organized by CAPABILITY (the one a Recipe declares│ │ # in spec.capability).│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ │ # The version directory may bundle the Recipe's own│ │ # source charts or modules beside recipe.yaml.│ │ # OCI: hub.aggrega.ai/recipe/helm/mariadb:1.0.0│ ││ ├── helm/│ │ ├── mariadb/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── postgres/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── compose/│ │ └── mariadb/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── terraform/│ │ └── mariadb-rds-module/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── module/ # bundled Terraform source│ │ ├── main.tf│ │ └── variables.tf│ └── cloudformation/│ └── postgres-rds/│ └── 1.0.0/│ └── recipe.yaml│├── feature-recipe/ # DOMAIN 3: Concrete Implementations│ │ # Capability leads the path, same as recipes.│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ ││ ├── helm/│ │ ├── k8s-secret-from-parameter/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── public-ingress/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── chart/ # bundled Helm source│ │ ├── Chart.yaml│ │ └── templates/│ │ └── ingress.yaml│ ├── compose/│ │ └── dotenv-secret/│ │ └── 1.0.0/│ │ └── recipe.yaml│ └── ... # terraform, cloudformation│└── plugin/ # ARTIFACTS: Plugin entities, each a content-addressed │ # reference to a Wasm artifact. The compiled artifact │ # is published separately and is not stored here. │ # Path: {pluginType}/{name}/{version}/plugin.yaml │ ├── linter/ │ └── publishing/ │ └── 0.5.0/ │ └── plugin.yaml └── provider/ # the directory mirrors metadata.pluginType ├── helm/ │ └── 0.5.0/ │ └── plugin.yaml └── ... # cloudformation, compose, helm-chart, terraformKategori komponen adalah himpunan tertutup, dan himpunan itulah — bukan sistem file — yang menjadi otoritas kategori. Nilai kategori yang belum memiliki entitas adalah kosakata yang dicadangkan: sumbu penjelajahan tetap stabil dan penulis tahu di mana komponen mendatang akan ditempatkan, sehingga rak kosong itu benar, bukan kekosongan yang menunggu penghuni. Karena katalog tidak membawa file placeholder, direktori untuk nilai semacam itu dibuat ketika entitas pertamanya masuk.
Daftar otoritatif — setiap kategori, apa yang dimuatnya, nilai type operasional yang biasanya dibawa entitasnya, dan direktori mana yang ada — adalah bagian Kategori Component dari panduan konvensi katalog, yang diterbitkan bersama katalog pustaka standar yang diaturnya.
Sumbu type hanya membawa primitif operasional — kosakata kognitif tidak pernah muncul di sana, dan skema Component yang diterbitkan mengenumerasi nilai yang diterima kunci yang dicadangkan itu, sehingga kata kognitif yang ditulis di sana ditolak saat dokumen dimuat. Pembagian tiga sumbu: type operasional (bagaimana infrastruktur memperlakukan komponen), category kognitif (apa komponen itu, dicerminkan oleh direktori), dan label kapabilitas per peran (subset perilaku — sebuah entitas adalah category: datastore ditambah nilai datastore.aggrega.ai/engine apa pun yang dibawa identitas produknya sendiri, sehingga core/datastore/qdrant membawa vector dan core/datastore/redis membawa kv, dan kedua sumbu dapat dikueri). Kapabilitas yang kebenarannya bergantung pada apa yang dikonfigurasi penulis sama sekali tidak dibawa di katalog: kapabilitas itu disuntikkan pada waktu kompilasi oleh peran label-transform dari socket tata kelola, yang membaca values yang dideklarasikan developer. Kategori yang murni AI membawa prefiks ai-; kategori penggunaan ganda tampil tanpa prefiks dengan nuansa AI yang dinyatakan melalui label kapabilitas. Kategori dipilih berdasarkan cara pengguna bernavigasi dan menjelajah, bukan cara compiler mengklasifikasikan — kosakata kategori dan label kapabilitas adalah istilah yang dicocokkan compiler dengan selektor tanpa memberinya makna apa pun. Nama komponen tidak mengulang kategorinya: model OpenAI pustaka standar adalah core/ai-model/openai, bukan core/ai-model/openai-model.
2. Skema terpisah dan pipeline sintesis jembatan
Untuk menghilangkan boilerplate per Component di sekitar deklarasi soket topologi, Aggrega membagi validasi menjadi dua bagian dan memeriksa masing-masing di tempat subjeknya berada:
usesSchema(YAML deklaratif). Mendeklarasikan soket topologi yang ditawarkan sebuah entitas katalog, dan memberi masing-masing sebuah kontrak. CLI Go membacanya secara native untuk mengekstrak stringselector:bagi pencocokan label selama analisis statis dan untuk memvalidasi mekanismeinjectyang diizinkan. Setiap entri soket mendukung field opsionalrequired: true(defaultfalse) — jika disetel, kompiler memancarkan galat validasi apabila tidak ada dependensi yang dideklarasikan di soket tersebut. Ini adalah padanan soket dari semantikrequired: truepada entrifeaturesSchema: keduanya menghentikan build. Mendeklarasikan soket di sini adalah yang dilakukan katalog pustaka standar dan tetap menjadi jalur yang lebih baik — tetapi itu bukan satu-satunya cara pengembang dapat menggambar sebuah edge. Penulis Aggregate dapat menamai pada komponennya sendiri sebuah soket yang tidak dideklarasikan olehusesSchemaini, termasuk pada entitas yang sama sekali tidak mendeklarasikanusesSchema; soket ad hoc seperti itu tidak membawa selektor, daftar izininject, maupun skema per edge, justru karena tidak ada entri di sini yang membawanya.usesdari lampiran Feature danusesper edge dari Release tidak terbuka dengan cara itu — keduanya hanya boleh menamai soket yang dideklarasikan. Lihat dependency-resolution §“Domain 2: Skema terpisah” untuk kontrak lengkapnya dan apa yang dilepaskan oleh soket ad hoc.- Desugaring. Jika pengembang menggunakan bentuk singkat array YAML (
uses: databases: ["db1"]), CLI menormalkannya menjadi sebuah map ({"db1": {"target": "db1"}}). - Sintesis jembatan. Kompiler memproyeksikan tabel slot
featuresSchema:ke dalam fragmen JSON Schema 2020-12 — satu properti per slot lampiran, yang menggambarkan bentuk isian yang boleh mengikatnya, dengan kata kunci ekstensix-aggrega-inject:pada slot yang mendeklarasikan daftar izininject. Validasi JSON Schema mengabaikan kata kunci ekstensi selama validasi struktural, dan tidak ada yang membaca kembali kata kunci tersebut dari fragmen: pemeriksaan yang memerlukan daftar izin sebuah slot membaca slot itu sendiri. Tabel soketusesSchema:tidak diproyeksikan ke fragmen apa pun.selector:daninject:sebuah soket tetap berada di YAML bertipe yang ditulis arsitek dan dibaca dari sana, danvalueSchema:/infraSchema:per edge sebuah soket dibungkus dan dikompilasi tersendiri, tanpa batasan yang dikarang di sekitarnya. - Komposisi. Arsitek platform menulis deklarasi
schema:yang ketat (bentuk ringkas atau JSON Schema 2020-12 penuh) yang mendefinisikanvalues,infra, danprovides. Deklarasi itu adalah kontrak milik entitas itu sendiri dan dikompilasi tersendiri: baik fragmen slot maupun tabel soket tidak dilebur ke dalamnya. Setiap permukaan diperiksa di tempat subjeknya berada, sehingga kesalahan soket dilaporkan pada entri soket yang ditulis arsitek, bukan pada path di dalam blokschema:— dan arsitek tetap tidak menulis boilerplateusesapa pun.
Contoh — deklarasi soket dan apa yang dilakukan kompiler dengannya: YAML arsitek platform
spec: usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: ["env", "file", "ssm_param"] # env and file are core mechanisms; ssm_param is a user-provided mechanism
schema: values: ha_mode: { type: boolean, default: false } infra: replicas: { type: integer, min: 1 } provides: host: { type: string, required: true }
assertions: # The Architect can write cross-pillar invariants against the unified instance content. ha-mode-needs-two-databases: | {{- if eq .values.ha_mode true -}} {{- if lt (len .uses.databases) 2 -}} {{- fail "ha_mode=true requires at least two database attachments" -}} {{- end -}} {{- end -}}Apa yang dilakukan kompiler dengannya Tabel soket dibaca sebagai YAML bertipe sebagaimana adanya: string selector: diteruskan ke mesin pencocokan label native, dan daftar inject: membatasi mekanisme pengiriman mana yang boleh dinamai oleh edge yang melewati soket tersebut. Blok schema: dikompilasi secara terpisah, sebagai kontrak values / infra / provides milik entitas itu sendiri. Penganalisis statis membaca string selector: dari entri soket yang ditulis arsitek — bersama dengan appliesTo / appliesToAnyOf dari entitas Feature — dan mengevaluasi pencocokan label terhadap metadata.labels setiap target untuk memvalidasi keamanan tipe lintas node.
Selektor bergaya Kubernetes di usesSchema
Mesin pencocokan label native kompiler Go mengevaluasi string selektor menggunakan semantik seleksi standar bergaya Kubernetes (AND melalui koma, OR melalui in(), NOT melalui !=/notin()). Mesin yang sama ini — dan tata bahasa string selektor yang sama — juga mengevaluasi selektor lampiran Feature (appliesTo, dan setiap item dari appliesToAnyOf). Lapisan selektor semata-mata adalah gerbang topologi — deklarasi schema: per pilar memvalidasi konten values, infra, dan provides secara independen. Setelah kompiler Go menggambar edge topologis pada saat konstruksi topologi, penganalisis statis membaca string selector dari entri soket yang ditulis arsitek dan mengevaluasinya terhadap labels katalog node target untuk memvalidasi keamanan tipe lintas node.
usesSchema: # 1. The AND Operator (Comma) databases: selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
# 2. The OR Operator (Set-based 'in') datastores: selector: "datastore.aggrega.ai/engine in (relational, vector)"
# 3. The NOT Operator internal_systems: selector: "compliance.aggrega.ai/data-class!=public"Selektor yang tidak dapat dibaca mesin sebagai salah satu dari enam bentuk persyaratannya — persyaratan kosong, kunci yang mengandung spasi atau salah satu dari =, !, (, ) dan koma, himpunan yang tidak ditutup — menghentikan build pada setiap edge yang dijaganya alih-alih dibaca sebagai selektor lain. Tata bahasa selektor mencantumkan bentuk-bentuknya dan setiap penolakan.
3. Format skema dan komposisi
Untuk menyediakan validasi yang ketat sekaligus metadata katalog standar (penulis, versi, deskripsi), definisi Domain 2 (Antarmuka) dan Domain 3 (Implementasi) ditulis sebagai amplop YAML. Domain 2 menggunakan deklarasi schema: tertanam yang dinyatakan dalam bentuk ringkas (default; ~15 kata kunci, ditransformasikan secara mekanis ke JSON Schema 2020-12) atau dalam YAML JSON Schema penuh.
Mengapa setiap YAML katalog mengulang amplop. Amplop (blok apiVersion, kind, metadata) muncul di bagian atas setiap file katalog — Component, Feature, Recipe, FeatureRecipe, Aggregate, Manifest, Release, Plugin — betapa pun pendeknya isi. Pengulangan ini disengaja: setiap file dirancang untuk di-parse, divalidasi, di-lint, dan diperiksa sebagai artefak mandiri. Satu file yang ditarik dari registry OCI, diletakkan di sandbox CI, atau dibuka di editor pihak ketiga harus membawa cukup deskripsi diri agar perkakas hilir dapat mengidentifikasi jenis entitas yang diwakilinya dan versi skema mana yang berlaku. Lokasi direktori tidak pernah menggantikan amplop: setiap parser, validator, dan linter membaca jenis entitas dan versi skema dari amplop. Biayanya adalah boilerplate mekanis per file; manfaatnya adalah jaminan perkakas mandiri berlaku di seluruh permukaan distribusi OCI, sistem file lokal, dan permukaan IDE / CI / inspect. Penulis menyalin amplop dari file yang ada saat menulis konten katalog baru, atau memulai dari aggrega scaffold <kind>, yang mencetak dokumen awal untuk jenis tersebut dengan apiVersion dan kind yang sudah terisi.
Untuk menjaga prinsip DRY (Don’t Repeat Yourself, “jangan mengulang diri sendiri”), katalog menggunakan dua mekanisme komposisi yang berbeda:
- Entri SchemaLibrary bersama (
$ref:lintas dokumen): Definisi JSON Schema yang dapat digunakan ulang disimpan dalam entitas katalog SchemaLibrary (Tier 3). Definisi tersebut dirujuk berdasarkan identitas melalui$ref:lintas dokumen (<library>#/schemas/<entry>, tanpa host — versinya berasal dari lockfile) dari skema Component atau Feature konsumen mana pun. Rantai ditelusuri pada waktu kompilasi. Lihat entities/schemalibrary untuk bentuk penulisan entitas pustaka dan vocabulary/cross-document-ref untuk semantik resolusinya. - Pewarisan tunggal (
extends): Untuk baseline komponen yang lengkap, entitas dapat menggunakan propertiextends: "URI". Kompiler Go membaca rantai induk secara rekursif dan melakukan deep merge pada metadata YAML (menimpa label saat terjadi konflik dan menambahkan array). Kedua jenis katalog kemudian berpisah jalan pada pilar data.schema:milik Feature dikomposisikan dengan milik basisnya di bawah komposisi JSON Schema 2020-12. Component yang memperluas tidak menulis konten pilar sama sekali: ia menulis penanda literalschema: inheriteddan menerima blokschema:basisnya persis seperti yang ditulis basis, pada setiap kedalaman rantai. Yang dikomposisikan oleh Component seperti itu sebagai gantinya adalah struktur — slot lampirannya (featuresSchema), soket topologi (usesSchema), daftar izin self-inject (inject), danassertionsbernama semuanya digabungkan di sepanjang rantai. Lihat entities/component untuk contoh perluasan komponen basis dan turunan + governance-and-compliance §“Pewarisan dan disiplin publikasi” untuk apa yang diselesaikan pewarisan secara konstruksi dan apa yang tetap menjadi aturan disiplin publikasi.
Lihat entities/component untuk contoh perluasan komponen basis dan turunan, dan entities/recipe untuk penulisan Recipe dengan pointer dan mapper beserta contoh lengkap.
4. Konfigurasi workspace (.aggrega-config.yaml)
File .aggrega-config.yaml di root workspace adalah konfigurasi workspace proyek — deklarasi milik workspace itu sendiri, cocok untuk kontrol sumber sebagaimana go.mod atau package.json. Berdasarkan konvensi, direktori .aggrega/ tidak dimasukkan ke kontrol sumber — cantumkan direktori itu di .gitignore, sebagaimana Anda melakukannya untuk node_modules/ atau .terraform/.
Bagian workspace adalah penanda root: keberadaannya menandai root workspace, dan bagian ini hanya membawa direktori katalog yang mendefinisikan root — catalog_dirs, dan map releases yang memberi sebuah Release direktori katalognya sendiri. Setiap pengaturan lain berada di tingkat teratas. Banyak di antaranya berupa nilai tunggal; yang lain berupa bagian yang mengumpulkan pengaturan satu urusan di bawah satu kunci. Setiap field bersifat opsional dengan default yang terdokumentasi. Himpunan lengkap dan terkini kunci tingkat teratas, masing-masing dengan tipe, default, dan maknanya, dibuat dari skema di schema/other/aggrega-config; contoh di bawah menunjukkan penanda root bersama beberapa pengaturan bernilai tunggal:
workspace: # Root marker; presence marks the workspace root catalog_dirs: # Ordered list of local catalog directories (checked before cache) - ./aggrega-catalogdefault_registry: hub.aggrega.ai # Default registry for unqualified URIsoffline: false # Set true for air-gapped environmentsauto_pull: true # Opt in to the implicit pull; the default is false, keeping build read-onlyartifact_cache_dir: .aggrega/cache # On-disk artifact cache rootBlok signing: membawa default penandatanganan artefak yang digunakan oleh aggrega push --sign dan aggrega sign, baik di tingkat teratas (global) maupun per registry:
signing: # Global signing defaults fulcio_url: https://fulcio.sigstore.dev # Keyless certificate authority (defaults to public-good) rekor_url: https://rekor.sigstore.dev # Keyless transparency log (defaults to public-good) timestamp_url: https://tsa.example.com/api/v1/timestamp # Optional RFC3161 timestamp authority (no default; opt-in) key_path: ./keys/signing.pem # Optional: path to a held keyed-key PEM (a pointer, never inline material)registries: - host: hub.example.com signing: # Per-registry override of the global signing block key_path: ./keys/hub.pemPrioritas per field adalah flag CLI > signing per registry > signing global > default public-good. Fulcio dan Rekor secara default menggunakan instans public-good Sigstore, sehingga keduanya opsional; timestamp_url tidak memiliki default — stempel waktu tepercaya tanpa kunci berasal dari penyertaan dalam log transparansi Rekor, dan otoritas stempel waktu RFC3161 bersifat opt-in (setel timestamp_url, atau --timestamp-url, dengan endpoint lengkap untuk mengaktifkannya). Keamanan: blok signing: tidak membawa materi rahasia — token identitas OIDC tidak pernah menjadi field konfigurasi (rahasia berumur pendek, yang diberikan pada saat penandatanganan: diperoleh melalui alur browser di terminal interaktif atau dari workflow di GitHub Actions, dan selain itu diteruskan dengan --identity-token atau diekspor sebagai AGGREGA_IDENTITY_TOKEN atau SIGSTORE_ID_TOKEN), dan kunci privat tidak pernah ditulis inline; key_path adalah path ke file kunci. Inilah asimetri yang disengaja dengan sisi verifikasi, yang menyematkan kunci publik inline, sementara di sisi penandatanganan selalu hanya ada path kunci.
Tandai root tanpa katalog yang di-vendor dengan menulis workspace: {}. Daftar catalog_dirs mendukung penyiapan monorepo di mana katalog bersama berada di direktori saudara. Kompiler memeriksa setiap direktori secara berurutan. Flag offline: true mencegah akses jaringan apa pun — kompiler hanya menggunakan path lokal dan cache, serta berhenti jika suatu entitas tidak ditemukan secara lokal. Pengaturan berbagian masing-masing mengumpulkan satu urusan. Di antaranya: pengatur ketatnya waktu build dan petunjuk penulisan; soket lampiran Wasm tingkat workspace (governance, linter, importer, providers, cli), yang masing-masing menerima daftar referensi plugin; ketatnya lint per aturan, termasuk sakelar kebijakan disiplin publikasi; penyetelan cache parse daemon dan ukuran pool worker pengiriman permintaannya; serta batas ukuran pada penyimpanan modul terkompilasi yang berlaku untuk seluruh mesin. Yang lain lagi membawa default penandatanganan dan kepercayaan tanda tangan serta perilaku daemon itu sendiri. Setiap kunci tingkat teratas didokumentasikan sepenuhnya di schema/other/aggrega-config.
Tiga cache yang berbeda dapat dikonfigurasi, dan membedakannya layak diluangkan waktu sejenak karena namanya mirip sedangkan cakupannya tidak. artifact_cache_dir menamai cache konten on-disk per workspace yang dijelaskan di bawah. parse_cache membatasi cache parse in-memory milik daemon, yang hanya hidup selama daemon hidup. compiled_module_cache membatasi penyimpanan on-disk untuk kode mesin plugin terkompilasi — salah satu cache yang dibagikan oleh setiap workspace di mesin, karena bentuk terkompilasi sebuah plugin bergantung pada plugin tersebut, bukan pada proyek yang menggunakannya:
# .aggrega-config.yaml — most at home in the global config file, since the store is machine-widecompiled_module_cache: max_bytes: 53687091200 # Default 50 GiB; 0 disables the capDi antara cache yang dibagikan oleh setiap proyek di mesin, inilah yang dapat mendominasi penggunaan cache on-disk, karena setiap plugin yang dijalankan mesin dikompilasi ke dalamnya sekali dan disimpan, sehingga ini satu-satunya cache dengan batas ukuran tetap. Setiap pemanggilan yang membuka penyimpanan menerapkan batas sebelum mengompilasi apa pun, menghapus seluruh entri mulai dari yang paling lama dikompilasi hingga sisanya muat. (Build yang dijalankan dengan --disable-plugin-cache justru mengompilasi ke memori, sehingga tidak memperbesar maupun memangkas penyimpanan.) Menghapus sebuah entri hanya mengakibatkan kompilasi ulang di kemudian hari dan tidak lebih, dan itulah yang membuat batas aman diturunkan dan aman diterapkan saat build lain sedang berjalan di mesin yang sama. Setel batas di atas apa yang dikompilasi oleh satu build: karena batas diterapkan sebelum kompilasi, batas di bawah working set satu build membuat setiap build membuang dan mengompilasi ulang modul yang sama, dan karena alasan yang sama penyimpanan dapat berada di atas batas di antara build dan dipangkas lagi di awal build berikutnya. aggrega cache status melaporkan ukuran penyimpanan, dan aggrega cache evict --max-size memangkasnya sesuai permintaan ke batas yang diberikan di baris perintah.
Root artifact_cache_dir membawa tiga subpohon paralel yang diisi secara seragam oleh satu pemanggilan aggrega pull, satu per kelas dependensi yang disematkan: <artifact_cache_dir>/entities/<encoded-kind>/<encoded-reference>/<encoded-version>/ untuk entitas katalog (Components, Features, Recipes, FeatureRecipes, Aggregates, pustaka, dan Plugins beserta file eksekusi yang dipublikasikannya), dengan jenis berupa jenis yang dipakai entitas saat dipublikasikan, sehingga dua entitas dengan jenis berbeda yang berbagi referensi dan versi yang sama — sebuah Component dan sebuah Recipe dengan nama yang sama — menempati dua slot; <artifact_cache_dir>/source-artifacts/<kind>/<host>/<path>/<version>/<digest-prefix>/ untuk artefak sumber yang ditarik dari field spec.source Recipe / FeatureRecipe (chart Helm, fragmen compose); dan <artifact_cache_dir>/inputs/sha256/<hex-digest> untuk input eksternal — dokumen jarak jauh yang diminta provider dari host saat merender, seperti $ref di values.schema.json sebuah chart yang menunjuk ke URL. Setiap slot cache artefak sumber membawa arsip .tgz yang otoritatif, direktori turunan extracted/ yang dibuat ulang pada setiap pembacaan build, dan file metadata.yaml yang mencatat identitas {kind, url, version, digest, mediatype, pulled_at} artefak. Setiap slot cache entitas membawa artefak yang dipublikasikan sebagaimana diambil dan manifes OCI yang menjadi acuan verifikasinya. Slot dari setiap jenis yang dokumennya dapat menamai file di sampingnya — Recipe, FeatureRecipe, Component, Feature — juga membawa direktori turunan extracted/ yang memuat file-file yang dibawa artefak tersebut, dalam direktori yang dinamai berdasarkan digest konten artefak: dokumen dan file yang dideklarasikan entitas jika dipublikasikan sebagai arsip, dan dokumen saja jika dipublikasikan sebagai dokumennya (§6). Direktori entitas disusun di sana dari artefak yang terverifikasi pada setiap pembacaan, dengan cara yang sama seperti file artefak sumber: setiap file diperiksa terhadap artefak, file yang diubah atau ditambahkan secara manual di direktori tersebut dibuang alih-alih dibaca, tidak ada hal lain di bawah extracted/ yang dibaca, dan artefak yang gagal verifikasi ditolak sebelum apa pun disusun. Pembacaan hanya menulis ulang apa yang berbeda dari artefak, sehingga build yang membaca satu cache pada saat yang sama — permintaan yang ditangani aggrega serve secara berdampingan, atau dua perintah atas satu workspace — masing-masing menemukan file yang diserahkan kepadanya dalam keadaan utuh. Segmen <digest-prefix> 12 karakter memisahkan {kind, url, version} yang sama yang diberi tag ulang pada digest upstream berbeda ke dalam slot yang berbeda. Input eksternal tidak memerlukan slot seperti itu: input disimpan sebagai satu file yang dinamai berdasarkan digest konten tempat lockfile menyematkannya, sehingga apa yang dibaca build berikutnya dialamatkan oleh sematan, bukan oleh URL asal byte tersebut — itulah yang memungkinkan build tersebut menyajikan input dengan jaringan ditolak.
Tiga direktori lain dapat muncul di samping ketiganya, dan tidak satu pun menyimpan konten dependensi yang disematkan: index/ membawa snapshot yang dapat dicari per registry yang ditulis oleh aggrega registry update (§8), signatures/ men-cache setiap bundel tanda tangan yang terverifikasi di bawah digest-nya sendiri, sehingga pembacaan berikutnya memeriksa ulang blob yang di-cache terhadap digest tempat blob itu dicatat alih-alih mengambil bundel lagi, dan catalog-snapshots/ menyimpan setiap snapshot katalog terbitan yang dibaca oleh suatu impor (§8) — arsip dan manifesnya dalam slot yang dinamai menurut digest manifes, dengan pohon katalog dihamparkan dari arsip pada setiap pembacaan, serta berkas current yang menyebutkan snapshot yang dibaca workspace jika tidak ada yang menyebutkan snapshot lain.
Bundel dokumentasi tidak termasuk di antaranya. Byte-nya hanya bergantung pada registry tempat bundel itu dipublikasikan dan versi publikasinya, sehingga disimpan sekali per mesin, di samping penyimpanan modul terkompilasi di bawah root cache per pengguna yang sama, di docs-bundles/<encoded-reference>/<encoded-version>/ di bawah root tersebut: bundel, manifes yang menjadi acuan verifikasinya, dan tanda tangan yang diverifikasi oleh pengambilannya. artifact_cache_dir tidak menjangkaunya. Sebelum sebuah halaman dibaca darinya, tanda tangan tersebut diverifikasi lagi di bawah pemeriksaan tanda tangan milik workspace pembaca untuk registry bundel, sehingga salinan yang diloloskan oleh pengaturan longgar sebuah workspace tidak disajikan ke workspace yang pemeriksaannya menolaknya — lihat aggrega-explain dan aggrega-cache.
artifact_cache_dir ditulis relatif terhadap root workspace, dan artinya direktori yang sama tidak peduli dari direktori mana sebuah perintah dipanggil atau direktori katalog mana yang sedang dipindai. Nilai absolut ditolak saat konfigurasi dimuat, dengan diagnostik yang menamai field tersebut: setiap pembaca pengaturan meresolusinya terhadap root workspace, sehingga path absolut akan menamai lokasi yang tidak dijangkau satu pun dari mereka, dan kegagalannya jika tidak demikian akan senyap — cache yang ditulis oleh pull diam-diam berhenti menjadi cache yang dibaca build. Cache boleh berada di dalam direktori katalog, dan dalam tata letak default memang demikian, karena direktori katalog umumnya adalah root workspace itu sendiri. Yang tidak boleh adalah cache menjadi direktori katalog: pemindaian katalog melompati cache, sehingga direktori cache yang juga merupakan direktori katalog mengeluarkan seluruh isi direktori itu dari setiap pemindaian. artifact_cache_dir: . menamai root workspace, yang dalam tata letak default persis kasus itu, dan nilai ini ditolak saat konfigurasi dimuat dengan diagnostik yang menamai field tersebut — begitu pula penulisan lain apa pun yang tereduksi menjadi root workspace. Kedua bentuk itu, bersama path absolut di atas, adalah yang dapat dikenali sendiri oleh pemeriksaan konfigurasi. Nilai yang menamai direktori katalog lain — sub, dalam workspace yang catalog_dirs-nya mencantumkan sub — dimuat tanpa keluhan, dan satu-satunya gejala adalah entitas di bawahnya tidak lagi ditemukan. Karena itu, menjaga cache di luar setiap direktori yang tercantum di workspace.catalog_dirs adalah bagian dari menulis konfigurasi, bukan sesuatu yang diperiksanya untuk Anda.
Melompati cache itulah yang mencegah artefak resolusi dibaca seolah-olah seorang penulis telah menulisnya. Slot cache menyimpan byte yang ditempatkan di sana oleh pengambilan dari registry, disimpan di bawah koordinat tempat byte itu diambil dan dijamin oleh digest lockfile; pemindaian yang memungutnya sebagai konten katalog yang ditulis penulis akan mengambil byte yang belum diverifikasi oleh apa pun, pada path yang tidak dapat diedit penulis. Satu konsekuensi perlu dinyatakan dengan jelas: jika cache menyimpan entitas yang tidak disematkan oleh lockfile mana pun — tertinggal oleh pull yang terputus, disalin secara manual, atau terdampar ketika sebuah Release berhenti merujuknya — entitas itu tidak terlihat oleh pemindaian katalog, dan build atau validasi yang bergantung padanya berhenti dengan menyatakan bahwa entitas tidak ditemukan. Solusinya adalah melakukan pull Release lagi, sehingga entitas diresolusi melalui lockfile dan digest-nya dicatat; penghentian tersebut menamai entitasnya agar sematan yang hilang dapat diidentifikasi. Alternatifnya — tetap meresolusinya — adalah pembacaan tanpa verifikasi yang justru hendak dicegah oleh lompatan atas cache.
Lockfile berlaku per Release: menyelesaikan release.yaml akan menulis release.lock di sebelahnya (nama dasar file Release ditambah .lock). aggrega pull menyelesaikan dependensi dan menulis lockfile; aggrega build membacanya dan menggunakan versi yang dipin terlepas dari status registry pada saat build. Workspace melakukan commit atas lockfile ketika reprodusibilitas build di berbagai mesin penting; setelah sebuah entitas, pustaka, plugin, atau Release itu sendiri berubah di workspace, aggrega pull --release <release> memperbaruinya, menyelesaikan ulang apa yang berubah sambil mempertahankan setiap pin lainnya, dan aggrega pull --upgrade --release <release> adalah cara mengadopsi versi lebih baru yang kini ditawarkan oleh registry. Lockfile mencatat setiap entitas yang telah diselesaikan beserta jenisnya, URI-nya sebagaimana ditulis, versi yang diselesaikan, digest konten, dan lokasi yang mereferensikannya. Jenis dan URI bersama-sama mengidentifikasi sebuah entri, sehingga Release yang Aggregate dan Manifest-nya memiliki nama yang sama mencatat satu entri untuk masing-masing, dan suntingan pada salah satunya menghentikan build berikutnya hingga sebuah pull mencatatnya:
# release.lockentities: - kind: component uri: core/datastore/mariadb:1.0.0 resolved_version: 1.0.0 digest: sha256:5deeedb9acc1be00d4e0f98e55e01d301a0bcc01d702c015a9d9628ff573650a referenced_from: - aggregate.spec.components.db.type - kind: recipe uri: mariadb-bitnami:1.0.0 resolved_version: 1.0.0 digest: sha256:215b54e2da1ce512fcdccff87f6f71daac707bc77e4214b60b946b27a24e483a referenced_from: - manifest.spec.mappings.components.type.core/datastore/mariadb:1.0.0generated_at: "2026-06-11T16:48:15Z"mapping_libraries: []plugins: []release: release.yamlschema_libraries: []source_artifacts: []version: 1Setiap entri yang dipin membawa jenis + URI + versi yang diselesaikan + digest yang dapat dialamatkan berdasarkan konten. Digest diverifikasi pada setiap pengambilan; byte yang tidak cocok dengan digest yang dipin menghentikan build dengan galat integritas. Digest sebuah entitas diambil atas apa yang dibawa oleh publikasinya — dokumennya dan setiap file yang dideklarasikannya di sebelahnya, masing-masing berdasarkan path dan byte-nya — bukan atas byte yang digunakan untuk mengirimkannya, sehingga entitas yang sama mencatat digest yang sama baik dibaca dari direktori katalog maupun diambil dari registry, bagaimanapun arsipnya dikompresi dan bit izin apa pun, termasuk bit eksekusi, yang diberikan checkout kepada file-filenya. Digest milik registry sendiri atas byte yang dipublikasikan adalah acuan pertama untuk memeriksa sebuah pengambilan, melalui manifest, yang digest-nya dicatat oleh entri hasil resolusi registry di samping digest-nya sendiri.
5. Model resolusi entitas tiga tingkat
Compiler menyelesaikan setiap referensi entitas yang ditemui selama kompilasi melalui pencarian berjenjang yang ketat. Ketiga tingkat — path lokal, workspace dan cache, serta registry — sesuai dengan tiga alur kerja penulisan yang hidup berdampingan dalam proyek Aggrega yang sehat: sebuah Release yang menyebut file di sebelahnya, sebuah tim yang menggunakan katalog yang di-commit ditambah cache yang telah ditarik sebelumnya, dan sebuah pull yang menjangkau registry untuk artefak yang belum diambil. Tingkat workspace dan cache serta tingkat registry dari jenjang yang sama mengevaluasi kolom type dalam Aggregates, nilai URI dalam pemetaan Manifest, deklarasi implements pada Recipes dan FeatureRecipes, serta referensi plugin di dalam pipeline Recipe dan FeatureRecipe; tingkat path lokal hanya dicapai oleh file yang disebut sebuah Release dan Manifest-nya.
Path lokal. Referensi aggregate, manifest, atau extends milik Release, atau extends milik Manifest, yang diawali dengan ./ atau ../ (prefiks path relatif POSIX) dibaca langsung dari disk relatif terhadap Release. Tanpa pencarian katalog, tanpa panggilan registry. Prefiks eksplisit membedakan maksud path lokal dari pencarian nama pada tingkat sintaksis: Release yang menulis aggregate: ./aggregate.yaml menyebut sebuah file; aggregate: checkout menyebut sebuah Aggregate berdasarkan metadata.name-nya. Resolver tidak pernah menebak isi string untuk memutuskan tingkat mana yang berlaku — prefiks itulah pembedanya. Setiap referensi lain, termasuk type Component dalam sebuah Aggregate, diselesaikan melalui tingkat workspace dan cache serta tingkat registry: entitas yang ditulis secara lokal ditempatkan di bawah catalog/ pada root workspace atau di direktori yang tercantum dalam workspace.catalog_dirs, dan type yang ditulis sebagai path file relatif menghentikan build sebagai entitas yang tidak dimuat katalog mana pun.
Workspace dan cache. Referensi tanpa prefiks path lokal eksplisit dicari terlebih dahulu di direktori yang tercantum dalam workspace.catalog_dirs (pohon katalog lokal proyek yang ditulis di dalam repositori atau disalin ke dalamnya — lihat §4 untuk bentuk konfigurasinya) — atau, untuk Release yang diberi direktori sendiri oleh konfigurasi di bawah workspace.releases, di direktori milik Release tersebut — kemudian di direktori catalog/ pada root workspace, lalu di artifact_cache_dir (lokasi .aggrega/cache/ yang diabaikan git, berisi artefak yang ditarik dari resolusi registry sebelumnya, yang subpohonnya dijelaskan di §4). Kecocokan cache pada build kedua dan seterusnya itulah yang menjaga loop internal tetap bebas jaringan bahkan ketika proyek bergantung pada konten katalog jarak jauh.
Registry. Jika tingkat workspace dan cache tidak menghasilkan kecocokan, aggrega pull — atau build yang dijalankan dengan --auto-pull atau dengan pengaturan auto_pull milik workspace — menjalankan pull OCI berbasis ORAS terhadap default_registry (default hub.aggrega.ai), membongkar artefak ke dalam cache untuk build berikutnya, dan melanjutkan dengan entitas yang telah diselesaikan. Build tanpa keduanya hanya membaca apa yang disematkan lockfile-nya, dan berhenti sambil menyebut aggrega pull ketika lockfile tidak ada. Bentuk URI OCI yang disusun oleh panggilan registry mengikuti taksonomi tipe entitas yang dijelaskan di §6 (Pengemasan artefak & taksonomi OCI). URI singkat dalam Aggregates dan Manifests diperluas ke bentuk OCI lengkapnya sebelum panggilan registry; aturan inferensi yang menggerakkan perluasan tersebut terdapat pada referensi URI singkat yang peka konteks milik Manifest dan di §8 di bawah.
Prioritas dan pembayangan. Prioritas resolusi secara ketat adalah path lokal > workspace dan cache > registry. Entitas di direktori katalog lokal dengan identitas yang sama dengan entitas registry membayangi entitas registry tersebut — ini disengaja dan memungkinkan penulis katalog bereksperimen dengan modifikasi sebelum memublikasikannya. Pembayangan yang sama berlaku antara catalog_dirs dan cache: entitas yang ada di direktori katalog workspace lebih diutamakan daripada salinan dalam cache, sehingga suntingan lokal pada katalog yang disalin ke repositori langsung berlaku.
Di dalam tingkat workspace dan cache, catalog_dirs adalah tumpukan prioritas berurutan dengan prinsip yang pertama menang. Ketika identitas entitas yang sama muncul di lebih dari satu direktori katalog yang tercantum, direktori yang tercantum lebih awal menang dan kemunculan berikutnya dibayangi — ditimpa, tidak dimuat, dan bukan galat. Hal ini memungkinkan proyek menempatkan direktori katalognya sendiri di depan direktori bersama atau yang disalin ke repositori dan menimpa entitas tertentu berdasarkan identitas, sementara sisanya jatuh ke direktori bersama. Penimpaan ini dapat diamati: detail resolusi melaporkan direktori mana yang menang dan mana yang dibayangi, sehingga pelapisan tidak pernah terjadi diam-diam. Pembayangan hanya berlaku antar direktori; dua file dalam satu direktori yang mengklaim identitas yang sama merupakan kesalahan penulisan dan menghentikan pemuatan. Direktori yang disebut lebih dari sekali — oleh flag --catalog dan di catalog_dirs, atau dua kali dalam daftar — adalah satu entri tumpukan, dicari sekali di tempat pertama kali ia disebut, sehingga pembayangan selalu melibatkan dua file berbeda dan tidak pernah direktori yang dibaca terhadap dirinya sendiri. Karena prioritas mengikuti urutan direktori yang dikendalikan penulis, himpunan hasil resolusi bersifat deterministik.
Direktori catalog/ pada root workspace bergabung dengan tumpukan itu di akhir, bukan di awal, dan hanya ketika direktori tersebut ada — sehingga apa pun yang dicantumkan proyek menang atasnya saat terjadi tabrakan, dan mencantumkan satu direktori yang tidak terkait tidak pernah diam-diam menghentikan pembacaannya. Direktori ini dilewati ketika entri yang tercantum sudah menjangkaunya, karena penelusuran direktori yang tercantum bersifat rekursif dan tumpukan yang menyebut root workspace sudah membacanya. Menghilangkan catalog_dirs dan menuliskannya sebagai daftar kosong adalah pernyataan yang berbeda: jika dihilangkan, workspace tetap membaca catalog/; jika ditulis sebagai [], workspace tidak membaca katalog lokal sama sekali, dan itulah cara workspace menyatakan bahwa ia tidak memilikinya.
Build terisolasi dari jaringan. Menetapkan offline: true (§4) melewati tingkat registry sepenuhnya. Referensi yang gagal diselesaikan di tingkat path lokal atau tingkat workspace dan cache memunculkan galat entitas tidak ditemukan alih-alih diam-diam mencoba panggilan jaringan, yang memberi pipeline CI yang secara hukum tidak dapat menjangkau jaringan sebuah kontrak gagal-cepat yang deterministik.
Tempat jenjang beroperasi. Jenjang mengambil entitas ke dalam memori; mekanisme resolusi lebih lanjut yang dilapiskan di atasnya — pencarian dua tingkat type vs name milik Manifest, pencocokan versi tiga bentuk implements (persis / rentang yang kompatibel dengan versi mayor / tanpa versi) di vocabulary/inheritance-and-interface, dan pemilihan Recipe per sumbu berdasarkan provider dan instans komponen — beroperasi pada entitas yang sudah ditarik resolver melalui jenjang ini.
6. Pengemasan artefak & taksonomi OCI (kapabilitas sebagai segmen terdepan)
Aggrega memperlakukan logika infrastruktur dengan cara yang sama seperti Docker memperlakukan image kontainer, menggunakan standar Open Container Initiative (OCI) melalui ORAS (OCI Registry As Storage). Pengguna dapat meng-host katalog Aggrega mereka di registry standar mana pun (GHCR, AWS ECR, Aggrega Hub).
Karena Recipes secara ketat 1:1 dengan sebuah kapabilitas rendering — sebuah Recipe menyebut satu kapabilitas di spec.capability dan tidak dapat menargetkan dua — cara paling rapi untuk mengaturnya di registry OCI adalah menempatkan kapabilitas di segmen repositori terdepan.
Taksonomi OCI mencakup semua tipe entitas. Nama repositori adalah segmen kind — kind milik entitas, dalam huruf kecil — diikuti identitas entitas, seluruhnya dalam huruf kecil:
hub.aggrega.ai/component/core/datastore/mariadb:1.0.0— Component, penerbitcore, kategoridatastorehub.aggrega.ai/component/core/compute/api-server:1.0.0— Component, penerbitcore, kategoricomputehub.aggrega.ai/feature/core/data-masking:1.0.0— Feature, penerbitcore(datar, tanpa kategori)hub.aggrega.ai/aggregate/core/db-module:1.0.0— Modul Aggregate yang dapat digunakan ulanghub.aggrega.ai/recipe/helm/mariadb:1.0.0— Recipe, kapabilitashelmhub.aggrega.ai/recipe/helm-chart/mariadb:1.0.0— Recipe, kapabilitashelm-charthub.aggrega.ai/recipe/compose/mariadb:1.0.0— Recipe, kapabilitascomposehub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0— FeatureRecipe, kapabilitashelmhub.aggrega.ai/schemalibrary/aidatastores:1.0.0— SchemaLibrary, definisi skema bersama;metadata.nameberformat PascalCaseAIDatastoresdiubah menjadi huruf kecil dalam nama repositorihub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0— MappingLibrary, fragmen pemetaan Go-template bersamahub.aggrega.ai/plugin/provider/helm:0.5.0— Plugin, tipe soketprovider(segmenmetadata.pluginType)
Kind yang dapat dipublikasikan mencakup kind penulisan katalog beserta Aggregate, sebuah modul yang dapat digunakan ulang (dapat dipublikasikan baik nantinya direferensikan sebagai spec.aggregate tingkat atas milik sebuah Release maupun disarangkan di blok aggregates: milik Aggregate lain), dan Plugin, referensi beralamat konten ke artefak WebAssembly yang dirutekan compiler dan dieksekusi runtime. Plugin adalah artefak struktural yang dapat dipublikasikan, bukan kind penulisan katalog. Release dan Manifest adalah masukan sisi deployment yang berada di kontrol sumber dan tidak pernah di-push — aggrega push menolaknya — sehingga keduanya tidak memiliki mediatype publikasi. aggrega push --list-kinds melaporkan himpunan yang dipublikasikan oleh biner yang terpasang, satu kind per baris. Setiap kind yang dapat dipublikasikan memiliki mediatype OCI sendiri dalam masing-masing dari dua bentuk yang diambil sebuah publikasi:
| Kind entitas | Dipublikasikan sebagai dokumennya | Dipublikasikan bersama file yang dideklarasikannya |
|---|---|---|
| Component | application/vnd.aggrega.component.v1beta1+yaml | application/vnd.aggrega.component.v1beta1+tar+gz |
| Feature | application/vnd.aggrega.feature.v1beta1+yaml | application/vnd.aggrega.feature.v1beta1+tar+gz |
| Recipe | application/vnd.aggrega.recipe.v1beta1+yaml | application/vnd.aggrega.recipe.v1beta1+tar+gz |
| FeatureRecipe | application/vnd.aggrega.featurerecipe.v1beta1+yaml | application/vnd.aggrega.featurerecipe.v1beta1+tar+gz |
| Aggregate | application/vnd.aggrega.aggregate.v1beta1+yaml | — tidak mendeklarasikan file |
| SchemaLibrary | application/vnd.aggrega.schemalibrary.v1beta1+yaml | — tidak mendeklarasikan file |
| MappingLibrary | application/vnd.aggrega.mappinglibrary.v1beta1+yaml | — tidak mendeklarasikan file |
| WorkloadLibrary | application/vnd.aggrega.workloadlibrary.v1beta1+yaml | — tidak mendeklarasikan file |
| ArtifactLibrary | application/vnd.aggrega.artifactlibrary.v1beta1+yaml | — tidak mendeklarasikan file |
| Plugin | application/vnd.aggrega.wasmplugin.v1beta1+yaml | — dipublikasikan melalui manifest-nya sendiri |
Apa yang dibawa sebuah publikasi, dan karenanya bentuknya, mengikuti dari apa yang dideklarasikan entitas — bukan dari kind-nya, dan bukan dari apa yang ada di direktorinya. Sebuah publikasi membawa dokumen entitas dan file yang disebut oleh entitas itu sendiri di sebelahnya: source: lokal milik Recipe atau FeatureRecipe — sebuah direktori ikut terbawa bersama setiap file di bawahnya yang dipertahankan oleh aturan pengabaian yang tercatat dalam entity.lock miliknya — setiap file yang diimpor oleh entri valuesMapping:, workload:, dan artifacts: miliknya dengan $import:, serta entity.lock yang ditulis oleh langkah pin-nya; dan setiap file skema yang diimpor oleh Component atau Feature, termasuk setiap file dalam rantai impor. Tidak ada hal lain di direktori yang ikut terbawa: catatan, README, atau keluaran build di sebelah entitas bukan bagian dari apa yang dipublikasikannya, apa pun namanya, dan tidak mengubah bentuk publikasinya. Entitas yang tidak menyebut apa pun dipublikasikan sebagai dokumen yang ditulisnya, byte demi byte, di bawah mediatype +yaml milik kind-nya; entitas yang menyebut sebuah file dipublikasikan sebagai tar yang dikompresi gzip berisi dokumen dan file-file tersebut, di bawah mediatype +tar+gz milik kind-nya. Aggregate, Plugin, dan kind pustaka tidak mendeklarasikan file di sebelah dokumennya, sehingga selalu dipublikasikan sebagai dokumen — termasuk Aggregate di root workspace, karena setiap path yang dideklarasikannya menyebut entitas lain, bukan file yang dibawanya; begitu pula Recipe yang seluruh kontennya inline. Sumber jarak jauh adalah referensi, bukan file, sehingga tidak membawa apa pun, meskipun entity.lock yang mencatat pin-nya menjadikan Recipe semacam itu sebuah arsip. Segmen versi setiap mediatype sama untuk semua kind yang dapat dipublikasikan, dan segmen pengodean menyatakan bentuk mana dari keduanya yang dimiliki byte tersebut. Perkakas hilir melakukan dispatch berdasarkan string mediatype lengkap — kind, versi, dan pengodean bersama-sama.
Satu bentuk tulisan tidak menyebut direktori yang dapat diketahui sebuah publikasi: sumber lokal yang ditulis sebagai template. Direktorinya baru dipilih ketika sebuah Release mengisi template tersebut, sehingga entitas membawa setiap file di direktorinya sendiri yang dipertahankan oleh aturan pengabaian yang tercatat, agar direktori mana pun yang dipilih Release sudah ikut terbawa; aggrega push memberi tahu hal ini saat terjadi. Membawa hanya yang disebut memiliki konsekuensi, dan konsekuensi itu jatuh pada konsumen: file yang dibaca sebuah entitas dan tidak disebut di mana pun tidak ikut terbawa, dan build konsumenlah — bukan push penerbit — yang menghadapi ketiadaannya, dengan menyebut path yang hilang di dalam slot cache-nya.
File mana dari sebuah direktori sumber yang menjadi milik entitas diputuskan sekali, saat entitas dipin, dan dicatat. Plugin yang melayani kapabilitas entitas di workspace penulis mendeklarasikan apa yang tidak pernah dikirimkan oleh ekosistemnya — direktori kontrol versi milik plugin chart dan kepatuhannya terhadap .helmignore milik chart, .terraform/ milik plugin modul — dan .aggregaignore milik penulis di sebelah entitas memiliki keputusan akhir. Langkah pin mencatat plugin tersebut dan aturan yang telah disusun dalam entity.lock, dan publikasi, setiap perbandingan pin sumber, baris lockfile entitas, serta proses rendering semuanya menerapkan aturan yang tercatat alih-alih menanyai plugin lagi, sehingga apa yang dipublikasikan adalah apa yang dirender oleh build milik penulis sendiri, dan binding yang berubah atau biner yang lebih baru tidak menggeser digest apa pun sampai entitas dipin lagi. Compiler tidak memiliki pendapat tentang ekosistem mana pun: aturan berasal dari plugin dan penulis, dan compiler hanya mencocokkannya. Tautan simbolik di antara file-file entitas ditolak alih-alih diikuti, karena apa yang ditunjuknya akan terbawa dengan namanya. aggrega pin menjelaskan aturan tersebut secara lengkap.
Nama Recipe tidak membawa prefiks domain maupun kapabilitas: direktori tipe entitas dan segmen kapabilitas sudah menyatakan keduanya.
Konvensi penamaan: Components (Domain 2) menggunakan {publisher}/{category}/{name}, sedangkan Features (Domain 2) dan Aggregates yang dapat digunakan ulang (Domain 1) menggunakan {publisher}/{name}, dengan segmen publisher menyebut vendor/penulis (core = pustaka standar resmi, acme = perusahaan). Entitas Domain 3 (Recipe, FeatureRecipe) menggunakan {capability}/{name}, dengan kapabilitas adalah provider yang dideklarasikan entitas di spec.capability; sebuah referensi juga dapat menyebut entitas tanpa prefiks, hanya dengan daunnya. Nama Recipe juga TIDAK menyertakan kapabilitas, karena kapabilitas sudah menjadi segmen terdepan dari URI kanonis.
Recipes menggunakan kata kunci implements untuk mengikat diri pada antarmuka yang dipenuhinya. Kolom implements mendukung pencocokan persis, rentang yang kompatibel dengan versi mayor, atau tanpa versi (lihat vocabulary/inheritance-and-interface untuk Pencocokan Versi implements). Recipe dari entri pemetaan Manifest harus mengimplementasikan tipe yang dipetakannya, atau basis yang dirujuk tipe itu melalui extends: kunci entri, dan tipe setiap instans komponen yang dijangkau kunci pada versi yang tidak disebutnya, pada versi yang digunakan build untuk mengompilasi instans tersebut — sehingga sebuah kunci tidak dapat mengirim instans ke Recipe yang ditulis untuk versi lain dari tipenya.
Ketika seorang engineer Ops menjalankan aggrega push, CLI memublikasikan entitas dalam bentuk tersebut, secara imutabel pada versinya. Konsumen mengambilnya melalui Model Resolusi Tiga Tingkat, menyimpannya dalam cache secara lokal di .aggrega/cache/, dan menata apa yang dibawanya di slot cache entitas (§4) — file-file sebuah arsip, atau dokumennya saja.
Entitas yang di-pull membaca file yang dibawanya persis seperti ia membacanya di sampingnya dalam direktori katalog. Entitas dibaca dari tempatnya di pohon yang telah ditata itu, sehingga source: atau $import: relatif yang dideklarasikannya — ditulis langsung, atau dihasilkan oleh template — di-resolve di dalam apa yang dipublikasikan, dan path yang keluar dari direktori milik entitas itu sendiri ditolak di sana sama seperti di direktori katalog. Tidak ada apa pun di luar pohon yang dibaca sebagai gantinya: bukan direktori tempat build dijalankan, dan bukan file yang ditaruh di slot cache. Component atau Feature yang skemanya diimpor dari sebuah file membawa file tersebut, sehingga salinan yang di-pull memuat kontrak yang dipublikasikan dan memvalidasi nilai yang ditulis terhadapnya persis seperti yang dilakukan salinan yang dibaca dari direktori katalog.
Membaca kembali entitas dari sebuah paket adalah langkah kebalikannya, dan langkah ini mengidentifikasi entitas berdasarkan apa dokumen itu sebenarnya, bukan berdasarkan namanya: dokumen di tingkat teratas paket yang kind:-nya adalah jenis entitas yang dapat dipublikasikan. Nama file entitas adalah konvensi katalog dan bukan kontrak, sehingga recipe.yaml adalah apa yang ditulis katalog pustaka standar, bukan apa yang diwajibkan format, dan file yang dibawa di samping entitas — template chart, fragmen compose — tidak dikira sebagai entitas tersebut. Aturannya tidak bisa dibalik, yaitu didasarkan pada jenis yang dicari konsumen: jenis dibaca dari entitas, yang berada di dalam paket, sehingga pada saat paket harus dibuka belum ada jenis yang dapat dijadikan dasar. Sisi pembaca berhenti alih-alih memilih ketika tingkat teratas paket berisi dua dokumen entitas — paket yang dihasilkan klien lain dengan mengemas seluruh direktori yang berisi dua entitas, yang kemudian akan berada di bawah masing-masing koordinat terpublikasinya sebagai satu artefak. Publikasi produk ini tidak dapat menghasilkannya, karena setiap entitas hanya membawa apa yang dideklarasikannya, dan sisi penerbit juga menolak direktori seperti itu: setiap jenis memiliki direktorinya sendiri kecuali Aggregate, Release, dan Manifest, dan aggrega pin serta aggrega push menolak entitas dari jenis lain apa pun yang memiliki entitas lain di sampingnya, sementara pemuatan katalog, lint, dan build membiarkan direktori itu apa adanya. Nama sebuah direktori tidak dinilai di sisi mana pun: tata letak <name>/<version>/ adalah konvensi katalog pustaka standar.
Entitas yang dipublikasikan dibaca melalui langkah yang sama. Sebuah koordinat membawa tepat satu salinan entitasnya, dalam bentuk yang diberikan oleh deklarasinya, dan seseorang melihatnya dengan aggrega inspect oci://<registry>/<repository>:<tag>, bukan melalui salinan yang dapat dibaca yang dipublikasikan di sampingnya — sehingga tidak ada salinan kedua yang bisa menjadi berbeda dari salinan yang di-resolve oleh build. Perintah ini membongkar arsip menurut aturan di atas, membaca entitas sebuah Plugin dari manifesnya, bukan dari executable yang dipublikasikan bersamanya, dan menampilkan hasilnya sebagaimana file dari jenis itu ditampilkan; lihat Membaca entitas yang dipublikasikan.
Anotasi manifes yang dapat dicari. Setiap publikasi membubuhkan sekumpulan kecil anotasi yang dapat dicari ke manifes OCI artefak, sehingga indeks registry atau peramban katalog dapat memfilter artefak berdasarkan metadata katalognya tanpa mengambil dan mengurai badan setiap entitas. Setiap entitas membawa deskripsinya yang dapat dibaca manusia (anotasi deskripsi OCI standar) serta kategori katalog dan jenisnya. Sebuah Plugin juga membawa tipe socket-nya dan capability yang dilayaninya. Anotasi inilah yang dibaca kembali oleh aggrega registry update ke dalam indeks lokal yang dapat dicari (§8).
Setiap file yang dipublikasikan diberi nama. Setiap file yang dibawa publikasi diberi nama pada manifes dengan anotasi standar org.opencontainers.image.title, yang merupakan nama yang digunakan klien OCI generik untuk menulis file tersebut ketika menarik artefak ke sebuah direktori. Nama itu menyatakan apa file tersebut, dan ekstensinya mengikuti media type file:
| Apa yang dipublikasikan | File yang ditulis klien OCI generik |
|---|---|
| entitas yang dipublikasikan sebagai dokumennya | entity.yaml |
| entitas yang dipublikasikan bersama file yang dideklarasikannya | entity.tar.gz |
| sebuah Plugin | entity.yaml, entitasnya, di samping entity.wasm, executable-nya |
| tanda tangan yang dilampirkan pada artefak | signature.json |
| penanda deprecation yang dilampirkan pada artefak | deprecation.json |
artefak data yang dipublikasikan dengan aggrega push-artifact | nama yang diberikan dengan --name |
Jadi oras pull hub.aggrega.ai/component/core/compute/server:1.0.0 -o ./server menempatkan entitas yang dipublikasikan di ./server/entity.yaml, byte demi byte seperti saat dipublikasikan. oras melewati deskriptor yang tidak membawa nama dan tetap melaporkan keberhasilan, itulah sebabnya setiap deskriptor yang dikemas publikasi membawa nama. Nama diturunkan dari media type saja, tidak pernah dari nama file yang dipublikasikan, sehingga byte yang sama yang dipublikasikan dari file dengan nama berbeda menghasilkan manifes yang sama. Entitas yang dipublikasikan bersama file-filenya tiba sebagai paketnya: entity.tar.gz menamai paket itu, dan entitas di dalamnya ditemukan menurut aturan di atas, bukan berdasarkan nama file apa pun. Resolusi milik Aggrega sendiri tidak pernah membaca nama-nama ini — ia memilih setiap file berdasarkan media type-nya dan memercayainya berdasarkan digest-nya — jadi nama-nama itu ada untuk setiap klien lain.
7. Arsitektur Recipe: pointer dan mapper
Lihat entities/recipe untuk permukaan authoring Recipe yang lengkap — source: (pointer), valuesMapping: (mapper, dengan tiga mode authoring: block scalar inline, $import: file, $import: pustaka ke sebuah entri MappingLibrary), skema sumber yang digerakkan Wasm, dukungan IaC native, dan contoh lengkap.
8. Registry default dan URI singkat yang sadar konteks
Untuk menghilangkan YAML yang membengkak, compiler me-resolve URI singkat secara sadar konteks berdasarkan posisi skema tempat URI itu muncul. Registry default dikonfigurasi di .aggrega-config.yaml (default-nya hub.aggrega.ai).
Sebuah host registry hanya memiliki satu pembacaan. Setiap registries[].host ditulis sebagai host itu sendiri — nama host huruf kecil yang mengandung titik, localhost, satu nama diikuti port, alamat IPv4, atau alamat IPv6 dalam tanda kurung siku, masing-masing dengan :port opsional, dan tanpa skema, path, kredensial, atau huruf kapital — karena ejaan itulah kunci tempat setiap kebijakan kepercayaan per registry ditemukan, dan persyaratan tanda tangan bawaan hub resmi dikaitkan dengan hub.aggrega.ai. default_registry menamai host dengan cara yang sama, dan boleh diikuti path repositori, seperti ghcr.io/acme: semua yang dipublikasikan melalui default kemudian berada di bawah path itu, dan setiap referensi singkat di-resolve di bawahnya, sementara kepercayaan tetap ditentukan oleh host saja. default_registry dapat juga ditulis sebagai name: dari sebuah entri registries, dan kemudian mewakili host entri tersebut. Nama dibaca sekali, saat konfigurasi di-resolve, terhadap entri yang berlaku setelah setiap file konfigurasi dan lingkungan, sehingga setiap pembaca default — publikasi, pengikatan lokasi, verifikasi tanda tangan, dan setiap pencarian kepercayaan — membaca host dari satu entri itu, dan tidak satu pun dari mereka mencapai host yang dieja seperti nama tersebut; nama yang diikuti path ditolak, karena nama mewakili entri, bukan lokasi. Nama dicocokkan sebelum ejaan host, dan nama yang dimiliki dua entri ditolak karena ambigu. Pembacaan yang sama menentukan tiga hal yang dilakukan pull terhadap host: lokasi registry tempat identitas katalog tanpa host diikat, apakah artefak yang diambil menamai registry yang tanda tangannya diperiksa sama sekali, dan kebijakan kepercayaan mana yang digunakan pemeriksaan itu. Ejaan yang bisa mencapai sebuah registry tetapi melewatkan kebijakannya — huruf kapital, port HTTPS default yang eksplisit, skema, kredensial, path pada host sebuah entri registries — ditolak di tempat ia dikonfigurasi, dengan menyebutkan ejaan yang harus ditulis, begitu pula satu nama tanpa port yang tidak menamai entri apa pun, yang merupakan bentuk segmen pertama identitas katalog, bukan bentuk host. Penolakan berlaku di setiap lapisan yang dapat menetapkan nilai tersebut: file konfigurasi, tempat skema menyatakan bentuk yang sama sebagai pola pada setiap registries[].host; variabel lingkungan AGGREGA_DEFAULT_REGISTRY; dan baris perintah. Jadi setiap host yang dapat dinamai konfigurasi adalah host yang artefaknya diverifikasi di bawah kebijakan yang ditulis untuknya. Host dinilai berdasarkan ejaannya saja; apakah nama itu dapat di-resolve, atau apakah sebuah registry menjawab di sana, adalah state runtime yang tidak pernah diambil oleh compiler. konfigurasi menguraikan bentuk-bentuk yang diterima beserta contohnya.
URI singkat di-resolve secara sadar konteks terhadap Manifest; lihat ../language-reference/entities/manifest.md §URI singkat yang sadar konteks untuk aturan inferensi yang spesifik.
Mengelola registry
aggrega registry mengelola registry yang diketahui workspace dan kebijakan kepercayaan tanda tangannya. Identitas sebuah registry adalah host-nya; subperintah-subperintahnya berbagi satu model pengalamatan:
aggrega registry add <host>mendaftarkan sebuah registry dan mem-pin kebijakan kepercayaannya, dengan mengambil kebijakan yang diiklankan registry pada kontak pertama kecuali flag kepercayaan menyediakannya secara manual.--name <alias>opsional melampirkan alias yang mudah diingat pada entri berkunci host yang sama — host tetap menjadi identitas, dan alias di-resolve ke host itu di mana pun sebuah registry dinamai. Sebuah alias bersifat unik di seluruh registry.aggrega registry listmencetak setiap registry yang dikonfigurasi — host, alias, ringkasan singkat postur kepercayaan, dan penanda pada default — dalam urutan host menaik. Perintah ini membaca konfigurasi yang telah di-resolve dan tidak menghubungi jaringan apa pun.aggrega registry remove <name|host>menghapus entri kebijakan kepercayaan sebuah registry, yang dialamatkan melalui host atau aliasnya. Perintah ini hanya menghapus kebijakan kepercayaan: pointerdefault_registrydibiarkan tidak tersentuh dan kemampuan untuk melakukan push ke host itu tidak terpengaruh, sehingga host kembali ke kepercayaan default alih-alih menjadi tidak dapat dijangkau.default_registryyang ditulis sebagai nama entri yang dihapus tidak lagi menamai apa pun setelahnya, dan ditolak sampai ditulis ulang.aggrega registry updatememperbarui indeks lokal yang dapat dicari, yang dijelaskan di bawah ini.
Di mana pun sebuah registry dinamai — argumen subperintah registry atau flag --registry pada aggrega push dan aggrega push-artifact — resolver yang sama menafsirkan token tersebut: alias yang dikonfigurasi di-resolve ke host-nya, dan token lain apa pun dibaca sebagai host yang dinamainya, dengan skema, path, dan kredensial sebuah referensi dibuang. Di tempat host itu menjadi sesuatu yang menjadi dasar pengambilan keputusan tanda tangan — tujuan aggrega push atau aggrega push-artifact, atau kunci tempat aggrega registry add menulis sebuah entri — host itu diwajibkan mengikuti satu pembacaan di atas dan ditolak, dengan menyebutkan ejaan yang harus ditulis, jika tidak ditulis seperti itu. Host yang belum terdaftar yang ditulis seperti itu adalah tujuan yang sah dan diterima.
Indeks lokal yang dapat dicari
aggrega registry update [<name|host>] membangun indeks lokal yang dapat dicari dari registry yang diketahui workspace. Perintah ini menelusuri repositori setiap registry yang dikonfigurasi, memilih versi rilis tertinggi dari masing-masing, membaca anotasi manifes yang dapat dicari dari versi tersebut (§6), dan menulis indeks per registry ke cache artefak. Tanpa argumen, perintah ini mengindeks setiap registry yang dikonfigurasi; dengan satu argumen registry (host atau alias), perintah ini hanya mengindeks registry tersebut.
Indeks ini mengikuti model penyegaran eksplisit yang sudah dikenal dari manajer paket: registry update adalah perintah yang menghubungi registry, dan aggrega search berikutnya membaca indeks yang telah ditulis secara offline. File catatan sebuah registry bersifat deterministik — dua pembaruan terhadap state registry yang sama menghasilkan byte yang identik, dan stempel waktu kesegaran disimpan di file pendamping sehingga tidak pernah mengganggu catatan. Repositori tanpa versi rilis, atau yang tidak dapat dibaca, dilewati sehingga satu repositori yang tidak terbaca tidak pernah membuat seluruh indeks ditinggalkan.
Snapshot katalog yang diterbitkan
Setiap penerbitan katalog pustaka standar juga menerbitkan katalog secara utuh: satu artefak OCI, sebuah tar terkompresi gzip berisi setiap berkas yang dimuat pohon katalog pada commit yang diterbitkan oleh penerbitan tersebut, di catalog/snapshot di bawah registry tempat katalog diterbitkan — hub.aggrega.ai/catalog/snapshot untuk hub resmi. Artefak ini baru didorong setelah setiap entitas dari penerbitan tersebut berada di registry, sehingga tidak menyebutkan entitas apa pun yang tidak dimuat registry. Artefak ini diberi tag commit tempat ia dibangun dan tag latest, serta ditandatangani tanpa kunci oleh penerbit, sebagaimana setiap entitas dari penerbitan tersebut, sehingga identitas penerbit memverifikasinya di bawah kebijakan kepercayaan registry; latest baru berpindah ke sebuah snapshot setelah snapshot itu ditandatangani. Arsip ditulis dengan satu tata letak tetap — entri dalam urutan menaik berdasarkan namanya, masing-masing dengan mode, pemilik, dan waktu modifikasi yang sama — sehingga satu commit selalu menghasilkan tar yang sama.
Satu-satunya pembacanya adalah impor yang workspace-nya tidak menyebutkan folder katalog apa pun: tidak ada workspace.catalog_dirs, tidak ada AGGREGA_CATALOG_DIRS, dan tidak ada direktori catalog/ di root workspace. aggrega import, impor dalam sesi editor, dan alat impor asisten menjalankan operasi yang sama, sehingga masing-masing memperoleh snapshot dengan cara yang sama. Impor mengambilnya dari registry default workspace melalui gerbang lalu lintas keluar dan proses masuk yang sama dengan pull, memverifikasi tanda tangannya di bawah kebijakan kepercayaan registry tersebut sebelum apa pun disimpan, menyimpannya di cache artefak workspace, dan membacanya di sana sebagai folder katalog, terikat pada digest-nya — sehingga importer ditawari Components katalog, dan --target membuat draf Manifest dari Recipes-nya, melalui jalur yang persis sama dengan yang ditempuh folder katalog. Catatan yang ditulis impor di samping draf-drafnya menyebutkan snapshot melalui digest manifesnya, sehingga impor berikutnya atas draf yang sama membaca katalog yang sama tanpa permintaan, dan aggrega import --upgrade mengambil snapshot terbaru dan sejak saat itu mengimpor terhadapnya. Dalam postur offline, impor yang harus mengambil snapshot akan berhenti, dengan menyebutkan apa yang harus dijalankan. Workspace yang menyebutkan folder katalog mengimpor terhadap folder tersebut dan tidak mengambil snapshot apa pun. Tidak ada perintah lain yang membaca snapshot: pull, build, dan validasi menyelesaikan setiap entitas melalui tingkatan di §5 dan mematoknya di lockfile, dan draf impor mereferensikan entitas katalog berdasarkan nama, sehingga membangunnya menyelesaikan entitas-entitas tersebut dengan cara yang sama.
9. Pinning lockfile dan imutabilitas artefak
Disiplin pinning lockfile menambatkan setiap dependensi ke artefak tertentu yang dapat dialamatkan berdasarkan konten. Pada resolusi lockfile pertama (aggrega pull), resolver memeriksa registry, memilih versi sesuai batasan tiga bentuk URI (persis / rentang / tanpa versi), dan menulis versi yang di-pin + digest ke <release-stem>.lock milik Release. Pemanggilan aggrega build berikutnya menggunakan nilai yang di-pin terlepas dari mutabilitas registry; versi baru dapat dipublikasikan tanpa memengaruhi lockfile yang sudah ada.
Model pinning membawa satu aturan penopang: begitu sebuah name:version dipublikasikan ke registry dan di-resolve ke digest D, pemetaan itu bersifat permanen. Memublikasikan ulang name:version yang sama dengan konten berbeda ditolak saat push. aggrega push sendiri menegakkan hal ini pada setiap publikasi: ia me-resolve artefak yang sudah ada di name:version pada registry tujuan; jika ada dan digest-nya cocok dengan konten yang akan di-push, push tidak mengunggah apa pun dan hanya melampirkan apa yang masih kurang pada publikasi itu — tanggal publikasinya, dan tanda tangannya jika push menandatangani; jika ada dan digest-nya berbeda, push berhenti dengan error pelanggaran imutabilitas yang menyebutkan kedua digest.
Imutabilitas penting karena dua konsekuensi:
- Pin lockfile dapat dipercaya. Ketika lockfile mencatat
mariadb:1.0.0pada digestD, build yang mengambil berdasarkan digest menerima byteD. Tanpa imutabilitas, perubahan di sisi registry dapat mengganti byteDdi bawah pin lockfile, merusak stabilitas dari waktu lock hingga waktu build. Build yang dapat direproduksi bergantung pada jaminan ini. - Perubahan metadata setelah publikasi memiliki jalur yang jelas. Menandai versi yang dipublikasikan sebagai deprecated, merotasi kunci penandatanganan, atau mengubah atestasi tidak dapat dilakukan dengan mengubah artefak yang dipublikasikan (aturannya melarang hal itu). Hal tersebut harus dilakukan dengan memublikasikan versi patch baru atau artefak sidecar yang mencatat perubahan metadata secara terpisah. Kedua jalur dapat diaudit — versi baru atau sidecar muncul sebagai entri registry tersendiri — dan tidak satu pun mengubah byte artefak asli.
Aturan imutabilitas berlaku seragam untuk setiap artefak Aggrega yang dipublikasikan melalui OCI (entitas, SchemaLibrary, MappingLibrary, plugin Wasm yang direferensikan oleh pipeline[].plugin: Recipe / pipeline[].plugin: FeatureRecipe / plugins.{governance,linter,importer}[]: konfigurasi workspace). Apa pun yang di-pin oleh name:version ditambah digest konten di lockfile tunduk pada imutabilitas.
Imutabilitas bersifat tanpa syarat, dan tidak ada konfigurasi yang melonggarkannya. Tidak ada flag maupun pengaturan konfigurasi workspace yang mengizinkan penimpaan, karena registry tidak menyediakan jalur penimpaan yang dapat diaktifkan oleh operator. Konten yang berubah dipublikasikan dengan versi baru, dan aggrega lint --pre-publish memverifikasi bahwa kenaikan versi sesuai dengan klasifikasi perubahan.
Resolusi ulang ke versi yang lebih baru memerlukan tindakan eksplisit pengguna: aggrega pull --upgrade --release <release> <uri> me-resolve ulang satu dependensi sambil mempertahankan setiap pin lainnya, dan aggrega pull --upgrade --release <release> me-resolve ulang semua dependensi terhadap state registry saat ini. Dependensi berbentuk rentang dan tanpa versi di-resolve ulang ke versi terbaru yang cocok; pin berbentuk persis tidak berpindah kecuali pengguna secara eksplisit melakukan upgrade ke versi persis yang berbeda. Lockfile adalah sumber kebenaran untuk build; bentuk yang diketik pengguna menyatakan batasan versi pada waktu authoring.
10. Penegakan bentuk nama entitas katalog
Nama entitas katalog mengikuti pola per jenis entitas — dicantumkan di bawah ini, dan diuraikan per jenis di Ikhtisar referensi entitas. Nama-nama ini adalah permukaan yang berbeda dari nama instance yang ditulis developer dalam sebuah Aggregate atau Release, yang berbagi satu pola terlepas dari jenisnya; pola itu ada di ../language-reference/02-naming-conventions.md “Nama instance”. Field metadata.name yang dideklarasikan YAML katalog tidak selalu identik dengan URI referensi kanonis entitas: Component dan Feature menyematkan segmen penerbit dan pengelompokan langsung di metadata.name; Recipe dan FeatureRecipe mendeklarasikan metadata.name yang hanya berisi leaf, dan URI kanonis dua segmennya memasangkan leaf itu dengan spec.capability yang dideklarasikan entitas; setiap jenis pustaka mendeklarasikan token PascalCase di metadata.name.
Bentuk per jenis entitas:
- Component — tiga segmen kebab-case
{publisher}/{category}/{name}yang dideklarasikan dimetadata.name. Contoh:core/datastore/postgres. - Feature — dua segmen kebab-case
{publisher}/{name}yang dideklarasikan dimetadata.name. Contoh:core/data-masking. - Recipe — satu leaf kebab-case di
metadata.name(misalnya,postgres). URI referensi kanonis{capability}/{name}(sesuai §6 di atas) memasangkanspec.capabilityyang dideklarasikan entitas dengan leaf itu; segmen awal dicocokkan denganspec.capability, bukan dengan lokasi entitas di disk, sehingga memindahkanrecipe.yamltidak mengubah cara ia direferensikan. Katalog pustaka standar menempatkan entitas di<catalog-root>/recipe/<capability>/<name>/<version>/recipe.yamlagar pohonnya mencerminkan koordinat, tetapi pencerminan itu adalah konvensi katalog, bukan sumber URI. Sebuah referensi juga dapat menamai recipe secara polos — leaf saja, tanpa segmen capability — yang merupakan bentuk dominan dalam praktik dan di-resolve kapan pun hanya satu recipe dalam katalog yang memiliki nama tersebut. Tidak ada segmen penerbit yang muncul dalam URI Recipe, dan referensi yang membawa segmen ketiga tidak cocok dengan recipe mana pun. - FeatureRecipe — satu leaf kebab-case di
metadata.name(misalnya,k8s-secret-from-parameter), simetris dengan Recipe: URI kanonis{capability}/{name}darispec.capabilityyang dideklarasikan ditambah leaf, leaf polos diterima dengan cara yang sama, dan pohon<catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yamlmencerminkan koordinat berdasarkan konvensi. - Jenis-jenis pustaka — SchemaLibrary, MappingLibrary, WorkloadLibrary, dan ArtifactLibrary — satu token PascalCase di
metadata.nameyang cocok dengan^[A-Z][A-Za-z0-9]*$(misalnya,BaseComponents,AIDatastores,BaseWorkloads). Bentuknya sama pada setiap jenis pustaka, sehingga memindahkan entri antar pustaka tidak pernah berarti mengganti nama ke konvensi yang berbeda. Envelope JSON Schema setiap jenis pustaka juga mendeklarasikan pola tersebut, sebagai tambahan pada pemeriksaan yang dijelaskan di bawah.
Untuk Component, Feature, Recipe, dan FeatureRecipe, JSON Schema untuk metadata.name menerima string tidak kosong apa pun, sehingga tidak ada bagian dari bentuknya yang struktural untuk jenis-jenis itu. Setiap bentuk yang didokumentasikan — termasuk jenis-jenis pustaka, yang envelope-nya juga mendeklarasikan polanya — diperiksa oleh plugin disiplin publikasi, yang membawa pola-pola tersebut sebagai sumber kebenaran regex yang dibagikan dengan distribusi compiler. Tidak ada jenis yang diberi bentuk di sini yang kemudian diabaikan oleh plugin.
Pemeriksaan ini bersifat opt-in: satu perintah menjalankannya, dan perintah itu hanya berjalan ketika seorang penulis memintanya. Dua perintah yang paling sering diasumsikan menjalankannya tidak melakukannya:
aggrega lintmelaporkan pelanggaran bentuk nama. Plugin membandingkanmetadata.namesetiap entitas dengan pola untuk jenisnya. Pemeriksaan berjalan ketika seorang penulis memanggilaggrega lint— pada satu entitas, pada closure dependensi sebuah Release dengan--release, atau pada setiap entitas katalog jika dipanggil tanpa argumen — dan set aturan yang sama dapat dijangkau dari permukaan alat untuk editor yang disediakan CLI. Temuan bersifat saran: temuan dilaporkan dengan tingkat keparahanwarn, dan tidak menghentikan proses.
warn: E0278 name-shape: metadata.name "mariadbSynth" does not match the documented pattern for Recipe entities (^[a-z][a-z0-9-]*$)Temuan diawali dengan tingkat keparahannya dan kode singkat tempat aturannya terdaftar, yang dijabarkan oleh aggrega explain E0278. Path file yang bermasalah dicetak di atas temuan, dan eksekusi atas seluruh katalog diakhiri dengan jumlah entitas yang diperiksa dan temuan saran yang dimunculkan.
aggrega buildtidak memeriksa bentuk nama. Output yang di-render tidak bergantung pada nama entitas Aggrega, sehingga build atas katalog yang memuat nama yang tidak sesuai tidak mengeluarkan peringatan maupun diagnostik, dan berhasil persis seperti biasanya.aggrega pushjuga tidak memeriksa bentuk nama. Publikasi menolak atas dasar lain — terutama aturan imutabilitas di atas, di mana memublikasikan ulangname:versionyang sudah ada dengan konten berbeda akan berhenti. Ketika sebuah penolakan menyebutaggrega lint --pre-publish, penolakan itu memberi tahu penulis perintah mana yang harus dijalankan; push tidak menjalankannya.
Karena baik build maupun publikasi tidak memeriksa bentuk, katalog yang ingin konvensi itu dipatuhi menjalankan aggrega lint dengan sengaja — dalam hook pre-commit, atau sebagai langkah pipeline. Perhatikan bahwa temuan bentuk nama bersifat saran: aggrega lint melaporkannya dan tetap keluar dengan sukses, sehingga pipeline yang ingin menjadikan konvensi itu sebagai gerbang membaca temuan yang dilaporkan alih-alih mengandalkan status keluar.
Kebijakan per workspace menonaktifkan aturan tersebut:
# .aggrega-config.yaml — lint sectionlint: publishing_discipline: allow_nonstandard_names: true # default falseDengan kebijakan ditetapkan, aturan bentuk nama tidak melaporkan apa pun sama sekali. Kebijakan ini juga dapat ditetapkan untuk satu pemanggilan dengan aggrega lint --allow-nonstandard-names, atau dipaksa nonaktif kembali dengan --no-allow-nonstandard-names. Penggunaan yang sah adalah katalog yang tidak akan pernah dipublikasikan, eksperimen multi-penerbit, dan entitas untuk tujuan khusus.
11. Ekspansi Feature berbasis anotasi
Blok mappings.features.annotations milik Manifest mendeklarasikan binding antara kunci anotasi dan tipe Feature, ditambah tabel routing yang dikelompokkan per pilar (maps.infra, maps.values) yang menamai properti skema Feature yang boleh diisi oleh setiap anotasi. Subfase ekspansi anotasi dalam resolusi menelusuri batas Release dari luar ke dalam dan subsistem Aggregate dari luar ke dalam, menghitung set anotasi efektif per komponen melalui kaskade dan override dengan opt-out null untuk seluruh nilai dan per subkunci, serta menyuntikkan lampiran Feature sintetis yang membawa origin: annotation dalam provenance IR-nya. Pembahasan lengkap tentang bentuk binding dan authoring ada di language-reference/entities/manifest.md dan language-reference/providers/well-known-annotations.md; bagian ini mendokumentasikan mekanisme pada waktu pemuatan katalog dan waktu inspect yang diandalkan jalur ekspansi.
Cache kompilasi skema. spec.schema.{infra,values} setiap Feature dikompilasi sekali per build dan digunakan ulang di seluruh penelusuran kaskade. Validasi tipe per subkunci yang berulang terhadap skema Feature yang sama (satu cakupan kaskade per komponen, untuk ratusan komponen) membaca skema yang sudah dikompilasi alih-alih mengompilasinya lagi. Tidak ada yang disimpan antar build, sehingga skema Feature yang berubah dikompilasi ulang dari awal oleh build berikutnya.
Validasi target binding (pemuatan katalog). Saat pemuatan katalog, compiler menelusuri setiap binding features.annotations milik Manifest dan memverifikasi bahwa setiap path bertitik yang dideklarasikan di bawah maps.infra dan maps.values sesuai dengan properti yang benar-benar dideklarasikan oleh spec.schema.<pillar> milik Feature yang direferensikan. Binding yang merutekan ke path yang tidak tercantum dalam skema Feature menghentikan pemuatan katalog dengan OPS_ERROR yang jelas yang menyebutkan kunci binding, path yang hilang, URI Feature, dan lokasi sumber.
Lint tumpang-tindih pilar skema (pemuatan katalog). Peringatan saran muncul ketika spec.schema sebuah Feature mendeklarasikan nama properti yang sama di kedua pilar infra dan values. Tumpang-tindih ini jarang disengaja — properti bernama sama di berbagai pilar mengaburkan maksud authoring (pilar mana yang aktif ketika sebuah anotasi menargetkan nama yang sama?) dan memperumit pesan diagnostik. Peringatan ini tidak memblokir dan tidak memiliki opt-out: penulis yang memang bermaksud tumpang-tindih mempertahankannya beserta peringatannya, dan penulis yang tidak bermaksud demikian mengganti nama properti di salah satu pilar.
Lint tumpang-tindih map binding (resolusi). Peringatan saran muncul ketika sebuah path subkunci muncul di bawah maps.infra sekaligus maps.values di seluruh binding Manifest. Path yang muncul di kedua daftar pilar tidak koheren — satu subkunci anotasi tidak dapat merutekan ke kedua pilar secara bersamaan, dan pemecahan seri deterministik yang diterapkan compiler (path yang muncul di kedua daftar dirutekan ke infra; anotasi yang ditulis di Aggregate hanya boleh dirutekan melalui values, sehingga anotasi yang ditulis di sana untuk path tersebut ditolak) adalah jaring pengaman, bukan bentuk authoring yang dimaksudkan. Peringatan ini tidak memblokir; penulis yang menjalankan dengan mengabaikan peringatan tetap mendapatkan build yang bersih, dengan pemecahan seri terlihat dalam provenance IR.
Penampilan provenance pada aggrega inspect. Perintah inspect menampilkan satu tanda kurung per lampiran Feature yang mencatat sumber setiap leaf yang terisi:
[explicit]— Feature dilampirkan secara eksplisit melalui blokfeatures:sebuah Aggregate atau Release.[annotation: <key> from <source>]— setiap leaf yang terisi berasal dari kunci anotasi yang sama. Tanda kurung menyebutkan kunci dan tempat anotasi dideklarasikan: file, dan path kunci bertitik di dalamnya.- Tanda kurung per leaf — komposisi lintas sisi di mana setiap leaf yang terisi ditampilkan dengan tanda kurung sumbernya sendiri (sebagian
[explicit], sebagian[annotation: <key> from <source>]). Bentuk ini memperlihatkan penggabungan di mana yang eksplisit menang per field: ketika lampiran eksplisit dan kontribusi anotasi menargetkan instance Feature yang sama pada Component yang sama tetapi menulis leaf yang berbeda, kedua kontribusi tetap berada pada leaf masing-masing dan output inspect menyebutkan sumber setiap leaf secara individual.
Penampilan inspect membaca map per pilar values_provenance dan infra_provenance milik IR — yang diisi selama ekspansi anotasi bersamaan dengan penyuntikan lampiran sintetis — dan mengeluarkan bentuk tanda kurung yang paling baik merangkum sumber kolektif leaf-leaf tersebut. Mekanisme inspect adalah permukaan introspeksi kanonis untuk memahami mengapa lampiran Feature tertentu berakhir pada Component tertentu dan dari mana nilai-nilainya berasal.