Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Katalog i rejestr

Ten rozdział definiuje, jak platforma skaluje się w całym przedsiębiorstwie dzięki katalogowi OCI (Open Container Initiative): jak zorganizowany jest katalog, jak rozwiązywane jest odwołanie, jak encja jest publikowana i przypinana oraz jakie kształty nazw stosują encje katalogu.

Katalog Aggrega: taksonomia i rozwiązywanie rejestru

Kompilator Aggrega opiera się na ściśle typowanym rejestrze inspirowanym OAM, aby rozwiązywać abstrakcyjną intencję dewelopera (Domena 1) w konkretną rzeczywistość Ops (Domena 3). Aby wspierać otwarty, rozproszony ekosystem przy zachowaniu płynnego doświadczenia deweloperskiego, wszystkie schematy, powiązania infrastruktury, programowalne polityki i wtyczki adapterów stosują ustandaryzowaną taksonomię URI Open Container Initiative (OCI). Ponieważ każda encja katalogu jest adresowalna przez URI, aggrega pull pobiera do pamięci podręcznej te, których potrzebuje encja Release, i przypina je w jej pliku blokady, a kompilacja odczytuje je stamtąd. Lokalny workspace dewelopera zawiera tylko jego pliki Aggregate i Release, a nie kopię katalogu.

1. Główna struktura katalogów (katalog)

Folder aggrega-catalog biblioteki standardowej (oraz każdy zgodny katalog firm trzecich) jest zorganizowany tak, by fizycznie egzekwować rozdzielenie odpowiedzialności. Struktura jawnie oddziela abstrakcyjne interfejsy od ich konkretnych implementacji infrastruktury.

W przypadku encji Components i Features segmenty URI odpowiadają 1:1 segmentom ścieżki w systemie plików. Encje Components używają trzysegmentowego URI ({publisher}/{category}/{name}), w którym segment kategorii zawiera jedną z zamkniętego zbioru kategorii poznawczych — to samo słowo co etykieta component.aggrega.ai/category komponentu (lustro 1:1 katalogu, sprawdzane przez regułę category-matches-directory lintera publikacji). Encje Features pozostają płaskie ({publisher}/{name}) — to niewielki zbiór, który rośnie powoli. Operacyjna klasyfikacja ontologiczna (stateful-server, server itd.) znajduje się w etykiecie component.aggrega.ai/type, nigdy w strukturze katalogów; etykiety możliwości poznawczych (datastore.aggrega.ai/engine, agent.aggrega.ai/autonomy, …) nakładają na to podzbiory behawioralne. Interfejs webowy huba używa etykiet do filtrowania i wyszukiwania; kategorie służą zarówno nawigacji w systemie plików, jak i osi przeglądania katalogu.

Poniższe drzewo jest poglądowe w swojej treści i dokładne w swoim kształcie. Tam, gdzie encja jest narysowana w całości, sięga aż do swojego pliku liścia, więc z diagramu można odczytać całą rzeczywistą ścieżkę: który poziom katalogu niesie który segment URI, gdzie znajduje się obowiązkowy segment wersji i jakiej nazwy pliku używa każdy rodzaj encji w liściu. Pokazuje garść wpisów na poziom zamiast pełnej zawartości katalogu — ... oznacza pominięcie, a nazwy zapisane obok to kolejne wpisy na tym samym poziomie.

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, terraform

Kategorie komponentów tworzą zbiór zamknięty i to ten zbiór — nie system plików — jest źródłem prawdy o kategoriach. Wartość kategorii, która nie ma jeszcze żadnej encji, jest zarezerwowanym słownictwem: oś przeglądania pozostaje stabilna, a autor wie, gdzie trafi przyszły komponent, więc pusta półka jest poprawna, a nie jest wakatem czekającym na lokatora. Ponieważ katalog nie zawiera plików zastępczych, katalog dla takiej wartości jest tworzony, gdy pojawi się jej pierwsza encja.

Wiążącą listą — każdej kategorii, tego, co zawiera, operacyjnych wartości type, które zwykle mają jej encje, oraz istniejących katalogów — jest sekcja Kategorie encji Component przewodnika po konwencjach katalogu, publikowanego razem z katalogiem biblioteki standardowej, którym zarządza.

Oś type niesie wyłącznie prymitywy operacyjne — słownictwo poznawcze nigdy się na niej nie pojawia, a opublikowany schemat encji Component wylicza wartości, które przyjmuje zarezerwowany klucz, więc zapisane tam słowo poznawcze jest odrzucane przy wczytywaniu dokumentu. Podział na trzy osie: operacyjny type (jak infrastruktura traktuje komponent), poznawcza category (czym on jest, odzwierciedlona przez katalog) oraz etykiety możliwości dla poszczególnych ról (podzbiory behawioralne — encja to category: datastore plus ta wartość datastore.aggrega.ai/engine, którą niesie jej własna tożsamość produktu, więc core/datastore/qdrant niesie vector, a core/datastore/redis niesie kv, i obie osie można odpytywać). Możliwość, której prawdziwość zależy od tego, co skonfiguruje autor, w ogóle nie jest przechowywana w katalogu: wstrzykuje ją w czasie kompilacji rola label-transform gniazda zarządzania, która odczytuje zadeklarowane przez dewelopera values. Kategorie czysto AI mają prefiks ai-; kategorie podwójnego zastosowania występują bez prefiksu, a ich charakter AI wyrażają etykiety możliwości. Kategorie dobiera się według tego, jak użytkownicy nawigują i przeglądają, a nie według tego, jak klasyfikuje kompilator — słownictwo kategorii i etykiety możliwości to terminy, z którymi kompilator dopasowuje selektory i którym nie przypisuje żadnego znaczenia. Nazwa komponentu nie powtarza jego kategorii: model OpenAI w bibliotece standardowej to core/ai-model/openai, a nie core/ai-model/openai-model.

2. Podzielony schemat i potok syntezy mostu

Aby wyeliminować szablonowy kod dla każdej encji Component wokół deklaracji gniazd topologii, Aggrega dzieli walidację na dwie części i sprawdza każdą tam, gdzie znajduje się jej przedmiot:

  1. usesSchema (deklaratywny YAML). Deklaruje gniazda topologii, które oferuje encja katalogu, i nadaje każdemu z nich kontrakt. CLI w Go natywnie go odczytuje, aby wyodrębnić ciągi selector: do dopasowywania etykiet podczas analizy statycznej oraz aby walidować dozwolone mechanizmy inject. Każdy wpis gniazda obsługuje opcjonalne pole required: true (domyślnie false) — gdy jest ustawione, kompilator zgłasza błąd walidacji, jeśli w tym gnieździe nie zadeklarowano żadnej zależności. Jest to odpowiednik semantyki required: true we wpisach featuresSchema dla gniazd: oba zatrzymują kompilację. Deklarowanie gniazda w tym miejscu jest tym, co robi katalog biblioteki standardowej, i pozostaje lepszą drogą — ale nie jest to jedyny sposób, w jaki programista może narysować krawędź. Autor encji Aggregate może nazwać na własnym komponencie gniazdo, którego ten usesSchema nie deklaruje, również na encji, która w ogóle nie deklaruje usesSchema; takie gniazdo ad hoc nie niesie selektora, listy dozwolonych inject ani schematu dla poszczególnych krawędzi, właśnie dlatego, że nie ma tu wpisu, który by je niósł. uses dołączenia encji Feature i uses dla krawędzi w encji Release nie są w ten sposób otwarte — oba mogą nazywać wyłącznie zadeklarowane gniazdo. Pełny kontrakt oraz to, z czego rezygnuje gniazdo ad hoc, opisuje dependency-resolution §„Domena 2: podzielony schemat”.
  2. Desugaring. Jeśli programiści używają skróconej formy tablicy YAML (uses: databases: ["db1"]), CLI normalizuje ją do mapy ({"db1": {"target": "db1"}}).
  3. Synteza mostu. Kompilator rzutuje tabelę slotów featuresSchema: na fragment JSON Schema 2020-12 — jedna właściwość na slot dołączenia, opisująca kształt wypełnienia, które może go związać, ze słowem kluczowym rozszerzenia x-aggrega-inject: na slocie deklarującym listę dozwolonych inject. Walidacja JSON Schema ignoruje słowa kluczowe rozszerzeń podczas walidacji strukturalnej i nic nie odczytuje ich z powrotem z fragmentu: kontrola, która potrzebuje listy dozwolonych danego slotu, odczytuje sam slot. Tabela gniazd usesSchema: nie jest rzutowana na żaden fragment. selector: i inject: gniazda pozostają w typowanym YAML napisanym przez architekta i są stamtąd odczytywane, a valueSchema: / infraSchema: dla krawędzi danego gniazda jest opakowywany i kompilowany osobno, bez żadnego ograniczenia wymyślonego wokół niego.
  4. Kompozycja. Architekt platformy pisze ścisłą deklarację schema: (forma kompaktowa lub pełny JSON Schema 2020-12) definiującą values, infra i provides. Ta deklaracja jest własnym kontraktem encji i jest kompilowana osobno: ani fragment slotów, ani tabela gniazd nie są do niej włączane. Każda powierzchnia jest sprawdzana tam, gdzie znajduje się jej przedmiot, więc błąd gniazda jest zgłaszany przy wpisie gniazda napisanym przez architekta, a nie przy ścieżce wewnątrz bloku schema: — a architekt nadal nie pisze żadnego szablonowego kodu uses.

Przykład — deklaracja gniazda i to, co kompilator z nią robi: YAML architekta platformy

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 -}}

Co kompilator z nią robi Tabela gniazd jest odczytywana jako typowany YAML, którym jest: ciąg selector: trafia do natywnego silnika dopasowywania etykiet, a lista inject: ogranicza, które mechanizmy dostarczania może nazwać krawędź przechodząca przez to gniazdo. Blok schema: jest kompilowany osobno, jako własny kontrakt values / infra / provides encji. Analizator statyczny odczytuje ciąg selector: z wpisu gniazda napisanego przez architekta — razem z appliesTo / appliesToAnyOf z encji Feature — i ocenia dopasowanie etykiet względem metadata.labels każdego celu, aby zwalidować bezpieczeństwo typów między węzłami.

Selektory w stylu Kubernetes w usesSchema

Natywny silnik dopasowywania etykiet kompilatora Go ocenia ciągi selektorów przy użyciu standardowej semantyki wyboru w stylu Kubernetes (AND przez przecinek, OR przez in(), NOT przez !=/notin()). Ten sam silnik — i ta sama gramatyka ciągów selektorów — ocenia również selektory dołączeń encji Feature (appliesTo oraz każdy element appliesToAnyOf). Warstwa selektorów jest wyłącznie bramką topologii — deklaracje schema: dla poszczególnych filarów niezależnie walidują zawartość values, infra i provides. Gdy kompilator Go wyznaczy krawędzie topologiczne podczas budowy topologii, analizator statyczny odczytuje ciągi selector z wpisów gniazd napisanych przez architekta i ocenia je względem katalogowych labels węzła docelowego, aby zwalidować bezpieczeństwo typów między węzłami.

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, którego silnik nie potrafi odczytać jako jednej z sześciu form wymagania — pusty wymóg, klucz zawierający biały znak lub jeden ze znaków =, !, (, ) i przecinek, niezamknięty zbiór — zatrzymuje build na każdej krawędzi, której strzeże, zamiast zostać odczytanym jako jakiś inny selektor. Gramatyka selektorów wymienia formy i każdą odmowę.

3. Formaty i kompozycja schematów

Aby zapewnić zarówno ścisłą walidację, jak i standardowe metadane katalogu (autor, wersja, opis), definicje Domeny 2 (Interfejsy) i Domeny 3 (Implementacje) są pisane jako koperty YAML. Domena 2 wykorzystuje osadzone deklaracje schema: wyrażone w formie kompaktowej (domyślnie; ~15 słów kluczowych, mechanicznie przekształcanych w JSON Schema 2020-12) lub w pełnym YAML JSON Schema.

Dlaczego każdy YAML katalogu powtarza kopertę. Koperta (blok apiVersion, kind, metadata) pojawia się na początku każdego pliku katalogu — Component, Feature, Recipe, FeatureRecipe, Aggregate, Manifest, Release, Plugin — niezależnie od tego, jak krótka jest treść. Powtórzenie jest celowe: każdy plik jest zaprojektowany tak, aby można go było parsować, walidować, lintować i inspekcjonować jako samodzielny artefakt. Pojedynczy plik pobrany z rejestru OCI, umieszczony w piaskownicy CI lub otwarty w edytorze firmy trzeciej musi zawierać wystarczająco dużo samoopisu, aby narzędzia na dalszym etapie mogły ustalić, jaki rodzaj encji reprezentuje i która wersja schematu ma zastosowanie. Położenie katalogu nigdy nie zastępuje koperty: każdy parser, walidator i linter odczytuje rodzaj encji i wersję schematu z koperty. Kosztem jest mechaniczny szablonowy kod w każdym pliku; korzyścią jest to, że gwarancja samodzielnych narzędzi obowiązuje na powierzchni dystrybucji OCI, w lokalnym systemie plików i na powierzchniach IDE / CI / inspect. Autorzy kopiują kopertę z istniejących plików, tworząc nową zawartość katalogu, albo zaczynają od aggrega scaffold <kind>, które wypisuje dokument startowy dla danego rodzaju z wypełnionymi apiVersion i kind.

Aby zachować zasadę DRY (Don’t Repeat Yourself, „nie powtarzaj się”), katalog stosuje dwa odrębne mechanizmy kompozycji:

  • Współdzielone wpisy SchemaLibrary (międzydokumentowe $ref:): Wielokrotnego użytku definicje JSON Schema są przechowywane w encjach katalogu SchemaLibrary (Tier 3). Odwołuje się do nich przez tożsamość za pomocą międzydokumentowego $ref: (<library>#/schemas/<entry>, bez hosta — wersja pochodzi z pliku blokady) z dowolnego konsumującego schematu encji Component lub Feature. Łańcuch jest przechodzony w czasie kompilacji. Kształt tworzenia encji biblioteki opisuje entities/schemalibrary, a semantykę rozwiązywania — vocabulary/cross-document-ref.
  • Dziedziczenie pojedyncze (extends): W przypadku kompletnych bazowych komponentów encje mogą używać właściwości extends: "URI". Kompilator Go rekurencyjnie odczytuje łańcuch rodziców i głęboko scala metadane YAML (nadpisując etykiety w razie konfliktu i dołączając tablice). Następnie oba rodzaje katalogowe rozchodzą się w kwestii filarów danych. schema: encji Feature składa się ze schematem jej bazy zgodnie z kompozycją JSON Schema 2020-12. Rozszerzająca encja Component nie tworzy żadnej zawartości filarów: zapisuje dosłowny znacznik schema: inherited i otrzymuje blok schema: swojej bazy dokładnie tak, jak baza go napisała, na każdej głębokości łańcucha. To, co taka encja Component składa zamiast tego, to struktura — jej sloty dołączeń (featuresSchema), gniazda topologii (usesSchema), lista dozwolonych samowstrzykiwań (inject) i nazwane assertions są scalane wzdłuż łańcucha. Przykłady rozszerzania komponentów bazowych i potomnych zawiera entities/component + governance-and-compliance §„Dziedziczenie i dyscyplina publikacji” wyjaśnia, co dziedziczenie rozstrzyga z założenia, a co pozostaje regułą dyscypliny publikacji.

Przykłady rozszerzania komponentów bazowych i potomnych zawiera entities/component, a tworzenie encji Recipe ze wskaźnikami i mapperami wraz z kompletnymi przykładami opisuje entities/recipe.

4. Konfiguracja obszaru roboczego (.aggrega-config.yaml)

Plik .aggrega-config.yaml w katalogu głównym obszaru roboczego to konfiguracja obszaru roboczego projektu — własna deklaracja obszaru roboczego, nadająca się do kontroli wersji tak jak go.mod czy package.json. Katalog .aggrega/ zgodnie z konwencją pozostaje poza kontrolą wersji — należy dodać go do .gitignore, tak jak node_modules/ czy .terraform/.

Sekcja workspace jest znacznikiem katalogu głównego: jej obecność wyznacza katalog główny obszaru roboczego i zawiera ona wyłącznie katalogi katalogu definiujące katalog główny — catalog_dirs oraz mapę releases, która nadaje encji Release własne katalogi katalogu. Każde inne ustawienie znajduje się na najwyższym poziomie. Wiele z nich to pojedyncze wartości; inne to sekcje grupujące pod jednym kluczem ustawienia jednego zagadnienia. Każde pole jest opcjonalne i ma udokumentowane wartości domyślne. Kompletny, aktualny zestaw kluczy najwyższego poziomu, każdy z typem, wartością domyślną i znaczeniem, jest generowany ze schematu w schema/other/aggrega-config; poniższy przykład pokazuje znacznik katalogu głównego obok kilku ustawień o pojedynczej wartości:

.aggrega-config.yaml
workspace: # Root marker; presence marks the workspace root
catalog_dirs: # Ordered list of local catalog directories (checked before cache)
- ./aggrega-catalog
default_registry: hub.aggrega.ai # Default registry for unqualified URIs
offline: false # Set true for air-gapped environments
auto_pull: true # Opt in to the implicit pull; the default is false, keeping build read-only
artifact_cache_dir: .aggrega/cache # On-disk artifact cache root

Blok signing: zawiera domyślne ustawienia podpisywania artefaktów używane przez aggrega push --sign i aggrega sign, zarówno na najwyższym poziomie (globalnie), jak i dla poszczególnych rejestrów:

.aggrega-config.yaml
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.pem

Pierwszeństwo dla każdego pola to: flaga CLI > signing dla rejestru > globalne signing > domyślna wartość public-good. Fulcio i Rekor domyślnie korzystają z instancji public-good Sigstore, więc są opcjonalne; timestamp_url nie ma wartości domyślnej — zaufany znacznik czasu bez kluczy pochodzi z włączenia do dziennika przejrzystości Rekor, a urząd znaczników czasu RFC3161 jest opcjonalny (aby go włączyć, należy ustawić timestamp_url lub --timestamp-url z pełnym punktem końcowym). Bezpieczeństwo: blok signing: nie zawiera żadnych tajnych materiałów — token tożsamości OIDC nigdy nie jest polem konfiguracji (to krótkotrwały sekret, przekazywany w momencie podpisywania: pozyskiwany przez przepływ w przeglądarce w interaktywnym terminalu lub z workflow w GitHub Actions, a w pozostałych przypadkach przekazywany przez --identity-token lub eksportowany jako AGGREGA_IDENTITY_TOKEN albo SIGSTORE_ID_TOKEN), a klucz prywatny nigdy nie jest podawany inline; key_path to ścieżka do pliku klucza. To celowa asymetria względem strony weryfikacji, która przypina klucz publiczny inline, podczas gdy po stronie podpisywania jest zawsze tylko ścieżka do klucza.

Katalog główny bez dołączonych katalogów oznacza się, wpisując workspace: {}. Lista catalog_dirs obsługuje konfiguracje monorepo, w których współdzielony katalog znajduje się w sąsiednim katalogu. Kompilator sprawdza każdy katalog po kolei. Flaga offline: true uniemożliwia jakikolwiek dostęp do sieci — kompilator używa wyłącznie lokalnych ścieżek i pamięci podręcznej, zatrzymując się, jeśli encja nie zostanie znaleziona lokalnie. Ustawienia w sekcjach grupują każde jedno zagadnienie. Wśród nich: pokrętła rygoru w czasie budowania i wskazówki dla autorów; gniazda dołączeń Wasm na poziomie obszaru roboczego (governance, linter, importer, providers, cli), z których każde przyjmuje listę odwołań do wtyczek; rygor lintowania dla poszczególnych reguł, w tym przełączniki polityk dyscypliny publikacji; strojenie pamięci podręcznej parsowania demona i rozmiar jego puli workerów rozsyłających żądania; oraz limit rozmiaru magazynu skompilowanych modułów wspólnego dla całej maszyny. Jeszcze inne zawierają domyślne ustawienia podpisywania i zaufania do podpisów oraz własne zachowanie demona. Każdy klucz najwyższego poziomu jest w pełni udokumentowany w schema/other/aggrega-config.

Konfigurowalne są trzy odrębne pamięci podręczne i warto poświęcić chwilę na ich rozróżnienie, ponieważ ich nazwy są podobne, a zakresy nie. artifact_cache_dir wskazuje opisaną poniżej dyskową pamięć podręczną treści dla obszaru roboczego. parse_cache ogranicza przechowywaną w pamięci pamięć podręczną parsowania demona, która żyje tylko tak długo jak demon. compiled_module_cache ogranicza dyskowy magazyn skompilowanego kodu maszynowego wtyczek — jedną z pamięci podręcznych współdzielonych przez wszystkie obszary robocze na maszynie, ponieważ skompilowana postać wtyczki zależy od wtyczki, a nie od używającego jej projektu:

# .aggrega-config.yaml — most at home in the global config file, since the store is machine-wide
compiled_module_cache:
max_bytes: 53687091200 # Default 50 GiB; 0 disables the cap

Spośród pamięci podręcznych współdzielonych przez wszystkie projekty na maszynie to ona może zacząć dominować w wykorzystaniu pamięci podręcznej na dysku, ponieważ każda wtyczka uruchamiana przez maszynę jest do niej kompilowana raz i przechowywana, dlatego jako jedyna ma stały limit rozmiaru. Każde wywołanie, które otwiera magazyn, stosuje limit przed skompilowaniem czegokolwiek, usuwając całe wpisy, zaczynając od najdawniej skompilowanych, aż reszta się zmieści. (Build uruchomiony z --disable-plugin-cache kompiluje zamiast tego do pamięci, więc ani nie powiększa magazynu, ani go nie przycina.) Usunięcie wpisu kosztuje późniejszą ponowną kompilację i nic więcej, i właśnie dzięki temu obniżenie limitu oraz jego stosowanie podczas działania innych buildów na tej samej maszynie jest bezpieczne. Należy ustawić go powyżej tego, co kompiluje pojedynczy build: ponieważ limit jest stosowany przed kompilacją, limit niższy niż zbiór roboczy pojedynczego buildu sprawia, że każdy build odrzuca i ponownie kompiluje te same moduły, a z tego samego powodu magazyn może pozostawać powyżej limitu między buildami i jest ponownie przycinany na początku następnego. aggrega cache status raportuje rozmiar magazynu, a aggrega cache evict --max-size przycina go na żądanie do limitu podanego w wierszu poleceń.

Katalog główny artifact_cache_dir zawiera trzy równoległe poddrzewa, które jedno wywołanie aggrega pull wypełnia jednolicie, po jednym na każdą klasę przypiętych zależności: <artifact_cache_dir>/entities/<encoded-kind>/<encoded-reference>/<encoded-version>/ dla encji katalogu (Components, Features, Recipes, FeatureRecipes, Aggregates, biblioteki oraz Plugins wraz z publikowanymi przez nie plikami wykonywalnymi), gdzie rodzaj jest tym, pod którym encja jest publikowana, więc dwie encje różnych rodzajów, które mają wspólne odwołanie i wersję — encja Component i encja Recipe o tej samej nazwie — zajmują dwa sloty; <artifact_cache_dir>/source-artifacts/<kind>/<host>/<path>/<version>/<digest-prefix>/ dla artefaktów źródłowych pobranych z pól spec.source encji Recipe / FeatureRecipe (charty Helm, fragmenty compose); oraz <artifact_cache_dir>/inputs/sha256/<hex-digest> dla wejść zewnętrznych — zdalnych dokumentów, o które provider prosi hosta podczas renderowania, takich jak $ref w pliku values.schema.json chartu, wskazujący na URL. Każdy slot pamięci podręcznej artefaktu źródłowego zawiera wiarygodne archiwum .tgz, pochodny katalog extracted/ generowany od nowa przy każdym odczycie przez build oraz plik metadata.yaml zapisujący tożsamość {kind, url, version, digest, mediatype, pulled_at} artefaktu. Każdy slot pamięci podręcznej encji zawiera opublikowany artefakt w postaci, w jakiej został pobrany, oraz manifest OCI, względem którego jest weryfikowany. Slot każdego rodzaju, którego dokument może nazwać plik obok siebie — Recipe, FeatureRecipe, Component, Feature — zawiera również pochodny katalog extracted/ z plikami, które niesie dany artefakt, w katalogu nazwanym od skrótu treści artefaktu: dokument i pliki zadeklarowane przez encję, jeśli została opublikowana jako archiwum, oraz sam dokument, jeśli została opublikowana jako swój dokument (§6). Katalog encji jest tam rozkładany z zweryfikowanego artefaktu przy każdym odczycie, tak samo jak pliki artefaktu źródłowego: każdy plik jest sprawdzany względem artefaktu, plik zmieniony lub dodany ręcznie w tym katalogu jest odrzucany zamiast odczytywany, nic innego pod extracted/ nie jest odczytywane, a artefakt, który nie przejdzie weryfikacji, jest odrzucany, zanim cokolwiek zostanie rozłożone. Odczyt przepisuje tylko to, co różni się od artefaktu, więc buildy odczytujące jedną pamięć podręczną w tym samym czasie — żądania obsługiwane równolegle przez aggrega serve lub dwa polecenia na jednym obszarze roboczym — znajdują każdy w całości pliki, które otrzymały. 12-znakowy segment <digest-prefix> rozdziela do odrębnych slotów to samo {kind, url, version} ponownie otagowane przy różnych skrótach upstream. Wejście zewnętrzne nie potrzebuje takiego slotu: jest przechowywane jako pojedynczy plik nazwany od skrótu treści, do którego przypina je plik blokady, więc to, co odczytuje późniejszy build, jest adresowane przez przypięcie, a nie przez URL, z którego przyszły bajty — i właśnie to pozwala temu buildowi serwować wejście przy zablokowanej sieci.

Obok tych trzech mogą pojawić się jeszcze trzy katalogi i żaden z nich nie zawiera treści przypiętych zależności: index/ zawiera przeszukiwalne migawki dla poszczególnych rejestrów zapisywane przez aggrega registry update (§8), signatures/ przechowuje w pamięci podręcznej każdy zweryfikowany pakiet podpisu pod jego własnym skrótem, dzięki czemu późniejszy odczyt ponownie sprawdza zbuforowany blob względem skrótu, pod którym go zapisano, zamiast ponownie pobierać pakiet, a catalog-snapshots/ przechowuje każdą opublikowaną migawkę katalogu odczytaną przez import (§8) — archiwum i jego manifest w slocie nazwanym skrótem manifestu, przy czym drzewo katalogu jest rozkładane z archiwum przy każdym odczycie, oraz plik current wskazujący migawkę, którą odczytuje obszar roboczy, gdy nic nie wskazuje innej.

Pakietu dokumentacji nie ma wśród nich. Jego bajty zależą wyłącznie od rejestru, w którym jest opublikowany, i od wersji, w której jest opublikowany, dlatego jest przechowywany raz na maszynę, obok magazynu skompilowanych modułów pod tym samym katalogiem głównym pamięci podręcznej użytkownika, w docs-bundles/<encoded-reference>/<encoded-version>/ poniżej tego katalogu głównego: pakiet, manifest, względem którego jest weryfikowany, oraz podpisy zweryfikowane przy jego pobraniach. artifact_cache_dir do niego nie sięga. Zanim jakakolwiek strona zostanie z niego odczytana, te podpisy są ponownie weryfikowane w ramach własnej kontroli podpisów odczytującego obszaru roboczego dla rejestru pakietu, dzięki czemu kopia wpuszczona przez luźniejsze ustawienia jednego obszaru roboczego nie jest serwowana obszarowi roboczemu, którego kontrola ją odrzuca — zob. aggrega-explain i aggrega-cache.

artifact_cache_dir zapisuje się względem katalogu głównego obszaru roboczego i oznacza ten sam katalog niezależnie od tego, z którego katalogu wywołano polecenie ani które katalogi katalogu są skanowane. Wartość bezwzględna jest odrzucana przy ładowaniu konfiguracji z diagnostyką wskazującą pole: każdy czytelnik tego ustawienia rozwiązuje je względem katalogu głównego obszaru roboczego, więc ścieżka bezwzględna wskazywałaby miejsce, do którego żaden z nich nie sięga, a błąd byłby w przeciwnym razie cichy — pamięć podręczna zapisywana przez pull po cichu przestałaby być pamięcią podręczną odczytywaną przez build. Pamięć podręczna może znajdować się wewnątrz katalogu katalogu, i w domyślnym układzie tak jest, ponieważ katalogiem katalogu jest zwykle sam katalog główny obszaru roboczego. Nie może natomiast być katalogiem katalogu: skan katalogu pomija pamięć podręczną, więc katalog pamięci podręcznej, który jest jednocześnie katalogiem katalogu, wyłącza całą zawartość tego katalogu z każdego skanu. artifact_cache_dir: . wskazuje katalog główny obszaru roboczego, co w domyślnym układzie jest właśnie takim przypadkiem, i jest odrzucane przy ładowaniu konfiguracji z diagnostyką wskazującą pole — podobnie jak każdy inny zapis, który sprowadza się do katalogu głównego obszaru roboczego. Te dwa kształty, wraz z powyższą ścieżką bezwzględną, to te, które kontrola konfiguracji potrafi rozpoznać samodzielnie. Wartość wskazująca jakiś inny katalog katalogu — sub w obszarze roboczym, którego catalog_dirs wymienia sub — ładuje się bez zastrzeżeń, a jedynym objawem jest to, że encje pod nim przestają być znajdowane. Trzymanie pamięci podręcznej poza każdym katalogiem wymienionym w workspace.catalog_dirs jest zatem częścią pisania konfiguracji, a nie czymś, co ona sprawdza za użytkownika.

Pomijanie pamięci podręcznej sprawia, że artefakt rozwiązywania nie jest odczytywany tak, jakby napisał go autor. Slot pamięci podręcznej zawiera bajty umieszczone tam przez pobranie z rejestru, przechowywane pod współrzędną, z której je pobrano, i poręczone skrótem z pliku blokady; skan, który podjąłby taki slot jako zawartość katalogu napisaną przez autora, przyjmowałby bajty, których nic nie zweryfikowało, ze ścieżki, której autor nie może edytować. Jedną konsekwencję warto powiedzieć wprost: jeśli pamięć podręczna zawiera encję, której nie przypina żaden plik blokady — pozostawioną przez przerwany pull, skopiowaną ręcznie lub osieroconą, gdy encja Release przestała się do niej odwoływać — ta encja nie jest widoczna dla skanu katalogu, a build lub walidacja, która od niej zależy, zatrzymuje się z komunikatem, że encji nie znaleziono. Rozwiązaniem jest ponowne wykonanie pull dla encji Release, aby encja została rozwiązana przez plik blokady, a jej skrót zapisany; zatrzymanie wskazuje encję, aby można było zidentyfikować brakujące przypięcie. Alternatywa — rozwiązanie jej mimo wszystko — to właśnie niezweryfikowany odczyt, któremu ma zapobiegać pomijanie pamięci podręcznej.

Lockfile jest osobny dla każdej encji Release: rozwiązanie release.yaml zapisuje obok niego release.lock (rdzeń nazwy pliku Release plus .lock). aggrega pull rozwiązuje zależności i zapisuje lockfile; aggrega build go odczytuje i używa przypiętych wersji niezależnie od stanu rejestru w czasie budowania. Workspace’y commitują lockfile, gdy liczy się powtarzalność budowania na różnych maszynach; gdy w workspace zmieni się encja, biblioteka, plugin lub sama encja Release, aggrega pull --release <release> odświeża go, ponownie rozwiązując to, co się zmieniło, i zachowując każde inne przypięcie, a aggrega pull --upgrade --release <release> służy do przyjęcia nowszej wersji, którą rejestr teraz oferuje. Lockfile zapisuje każdą rozwiązaną encję wraz z jej rodzajem, jej URI w postaci, w jakiej został napisany, rozwiązaną wersją, digestem zawartości i miejscami, które się do niej odwołują. Rodzaj i URI razem identyfikują wpis, więc encja Release, której encje Aggregate i Manifest mają tę samą nazwę, zapisuje po jednym wpisie dla każdej z nich, a edycja którejkolwiek z nich zatrzymuje następne budowanie, dopóki pull jej nie zapisze:

# release.lock
entities:
- 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.0
generated_at: "2026-06-11T16:48:15Z"
mapping_libraries: []
plugins: []
release: release.yaml
schema_libraries: []
source_artifacts: []
version: 1

Każdy przypięty wpis zawiera rodzaj + URI + rozwiązaną wersję + digest adresowany treścią. Digest jest weryfikowany przy każdym pobraniu; bajty niezgodne z przypiętym digestem zatrzymują budowanie z błędem integralności. Digest encji jest liczony z tego, co niesie jej publikacja — jej dokumentu i każdego pliku, który deklaruje obok niego, każdego według ścieżki i bajtów — a nie z bajtów, w jakich podróżuje, więc ta sama encja zapisuje ten sam digest niezależnie od tego, czy została odczytana z katalogu katalogowego, czy pobrana z rejestru, jakkolwiek skompresowano jej archiwum i jakiekolwiek bity uprawnień, łącznie z bitem wykonywania, checkout nadał jej plikom. Pobranie jest najpierw sprawdzane względem digestu, który sam rejestr wylicza z opublikowanych bajtów, za pośrednictwem manifestu, którego digest wpis rozwiązany przez rejestr zapisuje obok własnego.

5. Trójpoziomowy model rozwiązywania encji

Kompilator rozwiązuje każde odwołanie do encji napotkane podczas kompilacji za pomocą ścisłego kaskadowego wyszukiwania. Trzy poziomy — ścieżka lokalna, workspace i pamięć podręczna oraz rejestr — odpowiadają trzem przepływom pracy autorskiej, które współistnieją w zdrowym projekcie Aggrega: encji Release wskazującej pliki leżące obok niej, zespołowi korzystającemu z katalogu zapisanego w repozytorium oraz wcześniej pobranej pamięci podręcznej, a także operacji pull sięgającej do rejestru po artefakt, który nie został jeszcze pobrany. Poziom workspace i pamięci podręcznej oraz poziom rejestru tej samej kaskady oceniają pola type w encjach Aggregates, wartości URI w mapowaniach encji Manifest, deklaracje implements w encjach Recipes i FeatureRecipes oraz odwołania plugin w potokach encji Recipe i FeatureRecipe; do poziomu ścieżki lokalnej docierają tylko pliki wskazywane przez encję Release i jej Manifest.

Ścieżka lokalna. Odwołanie aggregate, manifest lub extends encji Release albo extends encji Manifest, zaczynające się od ./ lub ../ (prefiks względnej ścieżki POSIX), jest odczytywane bezpośrednio z dysku względem encji Release. Bez wyszukiwania w katalogu, bez wywołania rejestru. Jawny prefiks na poziomie składniowym odróżnia zamiar użycia ścieżki lokalnej od wyszukiwania po nazwie: encja Release, która zapisuje aggregate: ./aggregate.yaml, wskazuje plik; aggregate: checkout wskazuje encję Aggregate po jej metadata.name. Resolver nigdy nie analizuje treści ciągu znaków, aby zdecydować, który poziom ma zastosowanie — wyróżnikiem jest prefiks. Każde inne odwołanie, w tym type encji Component w encji Aggregate, jest rozwiązywane przez poziom workspace i pamięci podręcznej oraz poziom rejestru: encję utworzoną lokalnie umieszcza się w catalog/ w katalogu głównym workspace lub w katalogu wymienionym w workspace.catalog_dirs, a type zapisany jako względna ścieżka pliku zatrzymuje kompilację jako encja, której nie zawiera żaden katalog.

Workspace i pamięć podręczna. Odwołanie bez jawnego prefiksu ścieżki lokalnej jest najpierw wyszukiwane w katalogach wymienionych w workspace.catalog_dirs (lokalnych dla projektu drzewach katalogowych, napisanych w repozytorium lub do niego skopiowanych — kształt konfiguracji opisuje §4) — albo, dla encji Release, której konfiguracja przypisuje własne katalogi w workspace.releases, w katalogach tej encji Release — następnie w katalogu catalog/ w katalogu głównym workspace, a potem w artifact_cache_dir (ignorowanej przez git lokalizacji .aggrega/cache/, przechowującej artefakty pobrane we wcześniejszych rozwiązaniach z rejestru, której poddrzewa opisuje §4). Trafienie w pamięci podręcznej przy drugim i kolejnych budowaniach sprawia, że pętla wewnętrzna pozostaje wolna od sieci, nawet gdy projekt zależy od zdalnej zawartości katalogu.

Rejestr. Jeśli poziom workspace i pamięci podręcznej nie zwróci dopasowania, aggrega pull — lub budowanie uruchomione z --auto-pull albo z ustawieniem workspace auto_pull — wykonuje oparty na ORAS pull OCI z default_registry (domyślnie hub.aggrega.ai), rozpakowuje artefakt do pamięci podręcznej na potrzeby kolejnych budowań i kontynuuje z rozwiązaną encją. Budowanie bez żadnego z nich odczytuje tylko to, co przypina jego plik blokady, a gdy pliku blokady brakuje, zatrzymuje się, wskazując aggrega pull. Postać URI OCI, którą konstruuje wywołanie rejestru, jest zgodna z taksonomią typów encji opisaną w §6 (Pakowanie artefaktów & taksonomia OCI). Skrócone URI w encjach Aggregates i Manifests są rozwijane do pełnej postaci OCI przed wywołaniem rejestru; reguły wnioskowania sterujące tym rozwinięciem znajdują się w dokumentacji encji Manifest Skrócone URI zależne od kontekstu oraz w §8 poniżej.

Pierwszeństwo i przesłanianie. Pierwszeństwo rozwiązywania to ściśle ścieżka lokalna > workspace i pamięć podręczna > rejestr. Encja w lokalnym katalogu katalogowym o tej samej tożsamości co encja w rejestrze przesłania encję z rejestru — jest to zamierzone i pozwala autorom katalogów eksperymentować ze zmianami przed publikacją. To samo przesłanianie działa między catalog_dirs a pamięcią podręczną: encja obecna w katalogu katalogowym workspace ma pierwszeństwo przed kopią w pamięci podręcznej, dzięki czemu lokalne zmiany w skopiowanym do repozytorium katalogu działają natychmiast.

W obrębie poziomu workspace i pamięci podręcznej catalog_dirs jest uporządkowanym stosem pierwszeństwa, w którym wygrywa pierwszy. Gdy ta sama tożsamość encji pojawia się w więcej niż jednym wymienionym katalogu katalogowym, wygrywa katalog wymieniony wcześniej, a późniejsze wystąpienie zostaje przesłonięte — nadpisane, niezaładowane i niebędące błędem. Pozwala to projektowi umieścić własny katalog katalogowy przed współdzielonym lub skopiowanym do repozytorium i nadpisać wybrane encje według tożsamości, podczas gdy pozostałe przechodzą do katalogu współdzielonego. Nadpisanie jest obserwowalne: szczegóły rozwiązywania podają, który katalog wygrał, a który został przesłonięty, więc nakładanie warstw nigdy nie odbywa się po cichu. Przesłanianie dotyczy wyłącznie różnych katalogów; dwa pliki w jednym katalogu, które deklarują tę samą tożsamość, są błędem autorskim i zatrzymują ładowanie. Katalog wskazany więcej niż raz — przez flagę --catalog i w catalog_dirs albo dwukrotnie na liście — jest jednym wpisem stosu, przeszukiwanym raz w miejscu, w którym został wskazany po raz pierwszy, więc przesłonięcie zawsze dotyczy dwóch różnych plików, a nigdy katalogu odczytanego względem samego siebie. Ponieważ pierwszeństwo wynika z kontrolowanej przez autora kolejności katalogów, rozwiązany zbiór jest deterministyczny.

Katalog catalog/ w katalogu głównym workspace dołącza do tego stosu na jego końcu, a nie na początku, i tylko wtedy, gdy katalog istnieje — dzięki temu wszystko, co projekt wymieni, wygrywa z nim w razie kolizji, a wymienienie jednego niezwiązanego katalogu nigdy po cichu nie powoduje, że przestaje on być odczytywany. Jest pomijany, gdy wymieniony wpis już do niego sięga, ponieważ przechodzenie wymienionego katalogu jest rekurencyjne, a stos wskazujący katalog główny workspace już go odczytał. Pominięcie catalog_dirs i zapisanie go jako pustej listy to różne deklaracje: po pominięciu workspace nadal odczytuje catalog/; zapisany jako [] nie odczytuje żadnego lokalnego katalogu, i w ten sposób workspace deklaruje, że go nie ma.

Budowania odizolowane od sieci. Ustawienie offline: true (§4) całkowicie pomija poziom rejestru. Odwołanie, którego nie udało się rozwiązać na poziomie ścieżki lokalnej ani na poziomie workspace i pamięci podręcznej, skutkuje błędem brakującej encji zamiast cichej próby wywołania sieciowego, co daje potokom CI, które z przyczyn prawnych nie mogą sięgać do sieci, deterministyczny kontrakt szybkiego niepowodzenia.

Gdzie działa kaskada. Kaskada ładuje encję do pamięci; dalsze mechanizmy rozwiązywania zbudowane na niej — dwupoziomowe wyszukiwanie type kontra name w encji Manifest, dopasowanie wersji implements w trzech formach (dokładne / zakres zgodny z wersją główną / bez wersji) opisane w vocabulary/inheritance-and-interface oraz wybór encji Recipe dla każdej osi według providera i instancji komponentu — działają na encjach, które resolver już pobrał przez tę kaskadę.

6. Pakowanie artefaktów & taksonomia OCI (capability jako wiodący segment)

Aggrega traktuje logikę infrastruktury tak samo, jak Docker traktuje obrazy kontenerów, korzystając ze standardów Open Container Initiative (OCI) za pośrednictwem ORAS (OCI Registry As Storage). Użytkownicy mogą hostować swój katalog Aggrega w dowolnym standardowym rejestrze (GHCR, AWS ECR, Aggrega Hub).

Ponieważ encje Recipes są ściśle w relacji 1:1 z capability renderowania — encja Recipe wskazuje jedną capability w spec.capability i nie może celować w dwie — najczystszym sposobem ich organizacji w rejestrze OCI jest umieszczenie capability w wiodącym segmencie repozytorium.

Taksonomia OCI obejmuje wszystkie typy encji. Nazwa repozytorium to segment rodzaju — kind encji zapisany małymi literami — po którym następuje tożsamość encji, w całości małymi literami:

  • hub.aggrega.ai/component/core/datastore/mariadb:1.0.0 — Component, wydawca core, kategoria datastore
  • hub.aggrega.ai/component/core/compute/api-server:1.0.0 — Component, wydawca core, kategoria compute
  • hub.aggrega.ai/feature/core/data-masking:1.0.0 — Feature, wydawca core (płasko, bez kategorii)
  • hub.aggrega.ai/aggregate/core/db-module:1.0.0 — Moduł Aggregate wielokrotnego użytku
  • hub.aggrega.ai/recipe/helm/mariadb:1.0.0 — Recipe, capability helm
  • hub.aggrega.ai/recipe/helm-chart/mariadb:1.0.0 — Recipe, capability helm-chart
  • hub.aggrega.ai/recipe/compose/mariadb:1.0.0 — Recipe, capability compose
  • hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0 — FeatureRecipe, capability helm
  • hub.aggrega.ai/schemalibrary/aidatastores:1.0.0 — SchemaLibrary, współdzielone definicje schematów; metadata.name w PascalCase AIDatastores jest zapisywane małymi literami w nazwie repozytorium
  • hub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0 — MappingLibrary, współdzielone fragmenty mapowań w szablonach Go
  • hub.aggrega.ai/plugin/provider/helm:0.5.0 — Plugin, typ gniazda provider (segment metadata.pluginType)

Rodzaje, które można publikować, obejmują rodzaje autorskie katalogu, a także encję Aggregate, moduł wielokrotnego użytku (publikowalny niezależnie od tego, czy później będzie wskazywany jako spec.aggregate najwyższego poziomu encji Release, czy zagnieżdżony w bloku aggregates: innej encji Aggregate), oraz encję Plugin, adresowane treścią odwołanie do artefaktu WebAssembly, który kompilator kieruje, a środowisko uruchomieniowe wykonuje. Plugin jest strukturalnym artefaktem publikowalnym, a nie rodzajem autorskim katalogu. Release i Manifest to wejścia po stronie wdrożenia, które znajdują się w systemie kontroli wersji i nigdy nie są wypychane — aggrega push je odrzuca — więc nie mają mediatype publikacji. aggrega push --list-kinds podaje zbiór, który publikuje zainstalowany plik binarny, po jednym rodzaju w wierszu. Każdy publikowalny rodzaj ma własny mediatype OCI w każdej z dwóch postaci, jakie przyjmuje publikacja:

Rodzaj encjiPublikowana jako jej dokumentPublikowana z deklarowanymi przez nią plikami
Componentapplication/vnd.aggrega.component.v1beta1+yamlapplication/vnd.aggrega.component.v1beta1+tar+gz
Featureapplication/vnd.aggrega.feature.v1beta1+yamlapplication/vnd.aggrega.feature.v1beta1+tar+gz
Recipeapplication/vnd.aggrega.recipe.v1beta1+yamlapplication/vnd.aggrega.recipe.v1beta1+tar+gz
FeatureRecipeapplication/vnd.aggrega.featurerecipe.v1beta1+yamlapplication/vnd.aggrega.featurerecipe.v1beta1+tar+gz
Aggregateapplication/vnd.aggrega.aggregate.v1beta1+yaml— nie deklaruje żadnego pliku
SchemaLibraryapplication/vnd.aggrega.schemalibrary.v1beta1+yaml— nie deklaruje żadnego pliku
MappingLibraryapplication/vnd.aggrega.mappinglibrary.v1beta1+yaml— nie deklaruje żadnego pliku
WorkloadLibraryapplication/vnd.aggrega.workloadlibrary.v1beta1+yaml— nie deklaruje żadnego pliku
ArtifactLibraryapplication/vnd.aggrega.artifactlibrary.v1beta1+yaml— nie deklaruje żadnego pliku
Pluginapplication/vnd.aggrega.wasmplugin.v1beta1+yaml— publikuje przez własny manifest

To, co niesie publikacja, a więc jej postać, wynika z tego, co deklaruje encja — nie z jej rodzaju i nie z tego, co znajduje się w jej katalogu. Publikacja niesie dokument encji i pliki, które sama encja wskazuje obok niego: lokalne source: encji Recipe lub FeatureRecipe — katalog podróżuje z każdym plikiem pod nim, który zachowują reguły ignorowania zapisane w jego entity.lock — każdy plik, który jej wpisy valuesMapping:, workload: i artifacts: importują za pomocą $import:, oraz entity.lock zapisany przez jej krok przypinania; a także każdy plik schematu, który importuje encja Component lub Feature, łącznie z każdym plikiem łańcucha importów. Nic innego z katalogu nie podróżuje: notatka, README lub wynik budowania obok encji nie są częścią tego, co ona publikuje, niezależnie od nazwy, i nie zmieniają postaci, w jakiej publikuje. Encja, która niczego nie wskazuje, jest publikowana jako jej napisany dokument, bajt w bajt, pod mediatype +yaml jej rodzaju; encja, która wskazuje plik, jest publikowana jako skompresowane gzipem archiwum tar dokumentu i tych plików, pod mediatype +tar+gz jej rodzaju. Encje Aggregate, Plugin i rodzaje bibliotek nie deklarują żadnego pliku obok swojego dokumentu, więc zawsze są publikowane jako dokument — łącznie z encją Aggregate w katalogu głównym workspace, ponieważ każda ścieżka, którą deklaruje, wskazuje inną encję, a nie niesiony przez nią plik; tak samo encja Recipe, której cała zawartość jest inline. Zdalne źródło jest odwołaniem, a nie plikiem, więc niczego nie niesie, choć entity.lock zapisujący jego przypięcie czyni taką encję Recipe archiwum. Segment wersji każdego mediatype jest wspólny dla wszystkich publikowalnych rodzajów, a segment kodowania mówi, którą z dwóch postaci mają bajty. Narzędzia na dalszym etapie rozdzielają obsługę według pełnego ciągu mediatype — rodzaju, wersji i kodowania łącznie.

Jedna postać autorska nie wskazuje katalogu, który publikacja mogłaby znać: lokalne źródło zapisane jako szablon. Jego katalog jest wybierany dopiero wtedy, gdy encja Release wypełnia szablon, więc encja niesie każdy plik ze swojego katalogu, który zachowują jej zapisane reguły ignorowania, tak aby jakikolwiek katalog wybierze encja Release, już podróżował; aggrega push informuje o tym, gdy to następuje. Niesienie wyłącznie tego, co wskazane, ma swój koszt, który ponosi konsument: plik, który encja odczytuje i nigdzie nie wskazuje, nie podróżuje, a to budowanie konsumenta — nie push wydawcy — napotyka jego brak, podając brakującą ścieżkę w swoim slocie pamięci podręcznej.

To, które pliki katalogu źródłowego należą do encji, rozstrzyga się raz, przy przypinaniu encji, i zostaje to zapisane. Plugin obsługujący capability encji w workspace autora deklaruje, czego jego ekosystem nigdy nie dostarcza — katalogi kontroli wersji pluginu dla chartów i respektowanie przez niego .helmignore chartu, .terraform/ pluginu dla modułów — a .aggregaignore autora obok encji ma ostatnie słowo. Krok przypinania zapisuje ten plugin i złożone reguły w entity.lock, a publikacja, każde porównanie przypięć źródła, wiersz encji w lockfile i renderowanie stosują zapisane reguły, zamiast ponownie pytać plugin, więc to, co jest publikowane, jest tym, co renderuje budowanie samego autora, a zmienione powiązanie lub nowszy plik binarny nie zmienia żadnego digestu, dopóki encja nie zostanie ponownie przypięta. Kompilator nie ma zdania na temat żadnego ekosystemu: reguły pochodzą od pluginu i autora, a kompilator jedynie je dopasowuje. Dowiązanie symboliczne wśród plików encji jest odrzucane, a nie śledzone, ponieważ to, na co wskazuje, podróżowałoby pod jego nazwą. aggrega pin przedstawia reguły w całości.

Nazwa encji Recipe nie zawiera ani prefiksu domeny, ani capability: katalog typu encji i segment capability już wskazują jedno i drugie.

Konwencja nazewnictwa: encje Components (domena 2) używają {publisher}/{category}/{name}, a encje Features (domena 2) i wielokrotnego użytku encje Aggregates (domena 1) używają {publisher}/{name}, gdzie segment publisher wskazuje dostawcę/autora (core = oficjalna biblioteka standardowa, acme = przedsiębiorstwo). Encje domeny 3 (Recipe, FeatureRecipe) używają {capability}/{name}, gdzie capability to provider, którego encja deklaruje w spec.capability; odwołanie może też wskazywać encję bez prefiksu, samym liściem. Nazwy encji Recipe NIE zawierają również capability, ponieważ jest ona już wiodącym segmentem kanonicznego URI.

Encje Recipes używają słowa kluczowego implements, aby powiązać się z interfejsem, który realizują. Pole implements obsługuje dopasowanie dokładne, według zakresu zgodnego z wersją główną lub bez wersji (dopasowanie wersji implements opisuje vocabulary/inheritance-and-interface). Encja Recipe we wpisie mapowania encji Manifest musi implementować typ, dla którego jest mapowana, lub bazę, którą ten typ extends: klucz wpisu oraz typ każdej instancji komponentu, do której klucz dociera w wersji, której nie wskazuje, w wersji, w jakiej kompilacja kompiluje tę instancję — więc klucz nie może skierować instancji do encji Recipe napisanej dla innej wersji jej typu.

Gdy inżynier Ops uruchamia aggrega push, CLI publikuje encję w tej postaci, niezmiennie pod jej wersją. Konsument pobiera ją przez trójpoziomowy model rozwiązywania, zapisuje lokalnie w pamięci podręcznej w .aggrega/cache/ i rozkłada to, co ona niesie, w slocie pamięci podręcznej encji (§4) — pliki archiwum albo sam dokument.

Pobrana encja odczytuje niesione przez siebie pliki dokładnie tak, jak odczytuje je obok siebie w katalogu katalogu encji. Encja jest odczytywana ze swojego miejsca w tym rozłożonym drzewie, więc względne source: lub $import:, które deklaruje — zapisane wprost albo wygenerowane przez szablon — rozwiązuje się wewnątrz tego, co zostało opublikowane, a ścieżka wychodząca poza własny katalog encji jest tam odrzucana tak samo jak w katalogu katalogu encji. Nic spoza drzewa nie jest odczytywane w jego miejsce: ani katalog, z którego uruchamiane jest budowanie, ani plik podrzucony do slotu pamięci podręcznej. Encja Component lub Feature, której schemat jest importowany z pliku, niesie ten plik, więc pobrana kopia wczytuje opublikowany kontrakt i waliduje względem niego napisane wartości dokładnie tak, jak kopia odczytana z katalogu katalogu encji.

Odczytanie encji z powrotem z pakietu jest krokiem odwrotnym i identyfikuje encję po tym, czym dokument jest, a nie po tym, jak się nazywa: jest to dokument na najwyższym poziomie pakietu, którego kind: jest publikowalnym rodzajem encji. Nazwa pliku encji jest konwencją katalogu, a nie kontraktem, więc recipe.yaml to nazwa, którą zapisuje katalog biblioteki standardowej, a nie wymóg formatu, a plik niesiony obok encji — szablon chartu, fragment compose — nie zostaje z nią pomylony. Reguła nie może działać odwrotnie, według rodzaju, którego szuka konsument: rodzaj jest odczytywany z encji, która znajduje się wewnątrz pakietu, więc w chwili, gdy pakiet trzeba otworzyć, nie ma jeszcze rodzaju, według którego można by go dobrać. Strona odczytująca zatrzymuje się, zamiast wybierać, gdy najwyższy poziom pakietu zawiera dwa dokumenty encji — pakiet, który tworzy inny klient, pakując cały katalog zawierający dwie encje, który znalazłby się wtedy pod opublikowanymi współrzędnymi każdej z nich jako jeden artefakt. Publikacja tego produktu nie może go wytworzyć, ponieważ każda encja niesie tylko to, co deklaruje, a strona publikująca dodatkowo odrzuca taki katalog: każdy rodzaj ma własny katalog z wyjątkiem Aggregate, Release i Manifest, a aggrega pin i aggrega push odrzucają encję każdego innego rodzaju, obok której znajduje się inna encja, natomiast wczytanie katalogu, lint i budowanie pozostawiają katalog bez zmian. Nazwa katalogu nie jest oceniana po żadnej stronie: układ <name>/<version>/ jest konwencją katalogu biblioteki standardowej.

Opublikowana encja jest odczytywana tym samym krokiem. Współrzędna niesie dokładnie jedną kopię swojej encji, w postaci nadanej jej przez deklaracje, a człowiek ogląda ją za pomocą aggrega inspect oci://<registry>/<repository>:<tag>, a nie przez czytelną kopię opublikowaną obok — nie ma więc drugiej kopii, która mogłaby rozejść się z tą, którą rozwiązuje budowanie. Polecenie rozpakowuje archiwum według powyższej reguły, odczytuje encję Plugin z jej manifestu, a nie z opublikowanego z nią pliku wykonywalnego, i renderuje wynik tak, jak renderuje się plik tego rodzaju; zob. Reading a published entity.

Wyszukiwalne adnotacje manifestu. Każda publikacja nanosi na manifest OCI artefaktu niewielki zestaw wyszukiwalnych adnotacji, aby indeks rejestru lub przeglądarka katalogu mogły filtrować artefakty według metadanych katalogu bez pobierania i parsowania treści każdej encji. Każda encja niesie swój czytelny dla człowieka opis (standardową adnotację opisu OCI) oraz kategorię i rodzaj w katalogu. Encja Plugin niesie dodatkowo typ gniazda i obsługiwane capabilities. Te adnotacje aggrega registry update wczytuje z powrotem do lokalnego indeksu wyszukiwania (§8).

Każdy opublikowany plik ma nazwę. Każdy plik niesiony przez publikację jest nazwany w manifeście standardową adnotacją org.opencontainers.image.title, czyli nazwą, pod którą generyczny klient OCI zapisuje ten plik, pobierając artefakt do katalogu. Nazwa mówi, czym jest plik, a jego rozszerzenie wynika z typu mediów pliku:

Co jest publikowanePlik zapisywany przez generycznego klienta OCI
encja publikowana jako jej dokumententity.yaml
encja publikowana z deklarowanymi przez nią plikamientity.tar.gz
encja Pluginentity.yaml, encja, obok entity.wasm, jej pliku wykonywalnego
podpis dołączony do artefaktusignature.json
znacznik wycofania dołączony do artefaktudeprecation.json
artefakt danych opublikowany za pomocą aggrega push-artifactnazwa podana w --name

Tak więc oras pull hub.aggrega.ai/component/core/compute/server:1.0.0 -o ./server zostawia opublikowaną encję w ./server/entity.yaml, bajt w bajt taką, jaką opublikowano. oras pomija deskryptor bez nazwy i mimo to zgłasza sukces, dlatego każdy deskryptor pakowany przez publikację ma nazwę. Nazwa jest wyprowadzana wyłącznie z typu mediów, nigdy z nazwy opublikowanego pliku, więc te same bajty opublikowane z inaczej nazwanego pliku dają ten sam manifest. Encja opublikowana ze swoimi plikami dociera jako swój pakiet: entity.tar.gz nazywa pakiet, a encję wewnątrz niego odnajduje się według powyższej reguły, a nie po nazwie pliku. Własne rozwiązywanie Aggrega nigdy nie odczytuje tych nazw — wybiera każdy plik po typie mediów i ufa mu na podstawie digestu — więc istnieją one dla wszystkich innych klientów.

7. Architektura encji Recipe: wskaźniki i mapery

Pełny opis tworzenia encji Recipe zawiera entities/recipe — source: (wskaźnik), valuesMapping: (maper, z trzema trybami tworzenia: blokowy skalar inline, plikowy $import:, biblioteczny $import: do wpisu MappingLibrary), schematy źródeł sterowane przez Wasm, natywna obsługa IaC oraz przykłady.

8. Domyślny rejestr i skrócone URI zależne od kontekstu

Aby wyeliminować rozrost YAML, kompilator rozwiązuje skrócone URI w zależności od kontekstu, względem pozycji w schemacie, w której występują. Domyślny rejestr konfiguruje się w .aggrega-config.yaml (domyślnie hub.aggrega.ai).

Host rejestru ma jedno odczytanie. Każdy registries[].host zapisuje się jako sam host — nazwę hosta małymi literami zawierającą kropkę, localhost, pojedynczą nazwę z portem, adres IPv4 lub adres IPv6 w nawiasach kwadratowych, każdy z opcjonalnym :port, bez schematu, ścieżki, poświadczeń i wielkich liter — ponieważ ta pisownia jest kluczem, pod którym odnajdywana jest każda polityka zaufania danego rejestru, a wbudowany wymóg podpisu oficjalnego huba jest powiązany z kluczem hub.aggrega.ai. default_registry wskazuje host w ten sam sposób i może po nim podawać ścieżkę repozytorium, np. ghcr.io/acme: wszystko, co jest publikowane przez rejestr domyślny, trafia wtedy pod tę ścieżkę i każde krótkie odwołanie jest pod nią rozwiązywane, natomiast o zaufaniu nadal decyduje sam host. default_registry można zamiast tego zapisać jako name: wpisu registries i wtedy oznacza host tego wpisu. Nazwa jest odczytywana raz, podczas rozwiązywania konfiguracji, względem wpisów obowiązujących po uwzględnieniu wszystkich plików konfiguracyjnych i środowiska, więc każdy odbiorca wartości domyślnej — publikowanie, powiązanie lokalizacji, weryfikacja podpisów i każde wyszukiwanie zaufania — odczytuje host tego jednego wpisu i żaden z nich nie trafia do hosta zapisanego tak jak ta nazwa; nazwa, po której następuje ścieżka, jest odrzucana, ponieważ nazwa oznacza wpis, a nie lokalizację. Nazwa jest dopasowywana przed pisownią hosta, a nazwa występująca w dwóch wpisach jest odrzucana jako niejednoznaczna. To samo odczytanie rozstrzyga trzy rzeczy, które pobieranie robi z hostem: lokalizację rejestru, z którą wiązana jest tożsamość katalogowa bez hosta, czy pobrany artefakt wskazuje rejestr, którego podpis jest w ogóle sprawdzany, oraz względem której polityki zaufania to sprawdzenie jest wykonywane. Pisownia, która mogłaby dotrzeć do rejestru z pominięciem jego polityki — wielkie litery, jawny domyślny port HTTPS, schemat, poświadczenia, ścieżka w hoście wpisu registries — jest odrzucana w miejscu konfiguracji, z podaniem pisowni, którą należy zastosować; tak samo odrzucana jest pojedyncza nazwa bez portu, która nie wskazuje żadnego wpisu, ponieważ ma kształt pierwszego segmentu tożsamości katalogowej, a nie hosta. Odrzucenie obowiązuje na każdej warstwie, która może ustawić tę wartość: w pliku konfiguracyjnym, gdzie schemat określa ten sam kształt jako wzorzec dla każdego registries[].host; w zmiennej środowiskowej AGGREGA_DEFAULT_REGISTRY; oraz w wierszu poleceń. Dzięki temu każdy host, który może wskazać konfiguracja, jest hostem, którego artefakty są weryfikowane według polityki dla niego zapisanej. Host jest oceniany wyłącznie na podstawie pisowni; to, czy nazwa się rozwiązuje lub czy pod nią odpowiada rejestr, jest stanem środowiska uruchomieniowego, którego kompilator nigdy nie pobiera. Strona konfiguracja opisuje akceptowane formy wraz z przykładami.

Skrócone URI są rozwiązywane w zależności od kontekstu względem encji Manifest; szczegółowe reguły wnioskowania opisuje ../language-reference/entities/manifest.md, §Context-Aware Shorthand URIs.

Zarządzanie rejestrami

aggrega registry zarządza rejestrami znanymi obszarowi roboczemu i ich polityką zaufania do podpisów. Tożsamością rejestru jest jego host; podpolecenia korzystają z jednego modelu adresowania:

  • aggrega registry add <host> rejestruje rejestr i przypina jego politykę zaufania, pobierając przy pierwszym kontakcie politykę ogłaszaną przez rejestr, chyba że flagi zaufania podają ją ręcznie. Opcjonalna flaga --name <alias> dołącza przyjazny alias do tego samego wpisu kluczowanego hostem — tożsamością pozostaje host, a alias jest na niego rozwiązywany wszędzie tam, gdzie wskazuje się rejestr. Alias jest unikalny wśród rejestrów.
  • aggrega registry list wypisuje każdy skonfigurowany rejestr — host, alias, krótkie podsumowanie stanu zaufania oraz znacznik przy rejestrze domyślnym — w rosnącej kolejności hostów. Odczytuje rozwiązaną konfigurację i nie łączy się z siecią.
  • aggrega registry remove <name|host> usuwa wpis polityki zaufania rejestru, wskazany przez host lub alias. Usuwa wyłącznie politykę zaufania: wskaźnik default_registry pozostaje nienaruszony, a możliwość wypychania do tego hosta pozostaje bez zmian, więc host wraca do domyślnego zaufania, zamiast stać się nieosiągalny. default_registry zapisany jako nazwa usuniętego wpisu nie wskazuje potem niczego i jest odrzucany, dopóki nie zostanie przepisany.
  • aggrega registry update odświeża lokalny indeks wyszukiwania, opisany poniżej.

Wszędzie tam, gdzie wskazuje się rejestr — w argumencie podpolecenia registry lub we fladze --registry poleceń aggrega push i aggrega push-artifact — ten sam mechanizm rozwiązywania interpretuje token: skonfigurowany alias jest rozwiązywany na swój host, a każdy inny token jest odczytywany jako host, który wskazuje, z pominięciem schematu, ścieżki i poświadczeń odwołania. Tam, gdzie host staje się czymś, względem czego podejmowana jest decyzja o podpisie — miejscem docelowym aggrega push lub aggrega push-artifact albo kluczem, pod którym aggrega registry add zapisuje wpis — obowiązuje go jedno opisane wyżej odczytanie i jest odrzucany, z podaniem pisowni, którą należy zastosować, jeśli nie jest tak zapisany. Niezarejestrowany host zapisany w ten sposób jest prawidłowym miejscem docelowym i jest akceptowany.

Lokalny indeks wyszukiwania

aggrega registry update [<name|host>] buduje lokalny indeks wyszukiwania rejestrów znanych obszarowi roboczemu. Przechodzi przez repozytoria każdego skonfigurowanego rejestru, wybiera najwyższą wydaną wersję każdego z nich, odczytuje adnotacje wyszukiwania manifestu tej wersji (§6) i zapisuje indeks dla każdego rejestru w pamięci podręcznej artefaktów. Bez argumentu indeksuje każdy skonfigurowany rejestr; z jednym argumentem rejestru (hostem lub aliasem) indeksuje tylko ten jeden.

Indeks działa według modelu jawnego odświeżania, znanego z menedżerów pakietów: registry update to polecenie, które łączy się z rejestrami, a późniejsze aggrega search odczytuje zapisany indeks offline. Plik rekordów rejestru jest deterministyczny — dwie aktualizacje względem tego samego stanu rejestru dają identyczne bajty, a znacznik czasu aktualności znajduje się w osobnym pliku obok, więc nigdy nie zaburza rekordów. Repozytorium bez wydanej wersji lub takie, którego nie da się odczytać, jest pomijane, dzięki czemu pojedyncze nieczytelne repozytorium nigdy nie przerywa budowy całego indeksu.

Opublikowana migawka katalogu

Każda publikacja katalogu biblioteki standardowej publikuje również katalog jako całość: jeden artefakt OCI, skompresowane gzipem archiwum tar ze wszystkimi plikami, które drzewo katalogu zawiera w commicie opublikowanym przez tę publikację, pod catalog/snapshot w rejestrze, w którym katalog jest publikowany — hub.aggrega.ai/catalog/snapshot w przypadku oficjalnego huba. Jest wypychany dopiero wtedy, gdy każda encja tej publikacji znajduje się w rejestrze, więc nie wskazuje żadnej encji, której rejestr nie zawiera. Jest oznaczany tagiem commita, z którego został zbudowany, oraz tagiem latest i podpisywany bez klucza przez publikującego, tak jak każda encja publikacji, więc tożsamość publikującego pozwala go zweryfikować zgodnie z polityką zaufania rejestru; latest przechodzi na migawkę dopiero wtedy, gdy jest ona podpisana. Archiwum jest zapisywane w jednym stałym układzie — wpisy w rosnącej kolejności nazw, każdy z tym samym trybem, właścicielem i czasem modyfikacji — więc jeden commit zawsze daje to samo archiwum tar.

Jej jedynym czytelnikiem jest import, którego obszar roboczy nie wskazuje żadnego folderu katalogu: brak workspace.catalog_dirs, brak AGGREGA_CATALOG_DIRS i brak katalogu catalog/ w katalogu głównym obszaru roboczego. aggrega import, import w sesji edytora i narzędzie importu asystenta wykonują tę samą operację, więc każde z nich pozyskuje migawkę w ten sam sposób. Import pobiera ją z domyślnego rejestru obszaru roboczego przez tę samą bramkę ruchu wychodzącego i to samo logowanie co pull, weryfikuje jej podpis zgodnie z polityką zaufania tego rejestru, zanim cokolwiek zostanie zachowane, przechowuje ją w pamięci podręcznej artefaktów obszaru roboczego i odczytuje ją tam jako folder katalogu, powiązaną z jej skrótem — dzięki temu importerowi oferowane są Components katalogu, a --target tworzy szkic encji Manifest z jego encji Recipes, dokładnie tą samą ścieżką, którą przechodzi folder katalogu. Zapis, który import tworzy obok swoich szkiców, wskazuje migawkę przez skrót jej manifestu, więc późniejszy import tych samych szkiców odczytuje ten sam katalog bez żadnego żądania, a aggrega import --upgrade pobiera najnowszą migawkę i od tej chwili importuje względem niej. W trybie offline import, który musiałby pobrać migawkę, zatrzymuje się, podając, co należy uruchomić. Obszar roboczy, który wskazuje folder katalogu, importuje względem niego i nie pobiera żadnej migawki. Żadne inne polecenie nie odczytuje migawki: pull, kompilacja i walidacja rozwiązują każdą encję przez poziomy z §5 i przypinają ją w pliku blokady, a szkice importu odwołują się do encji katalogu przez nazwę, więc ich kompilacja rozwiązuje te encje w ten sam sposób.

9. Przypinanie wersji w pliku blokady i niezmienność artefaktów

Dyscyplina przypinania w pliku blokady wiąże każdą zależność z konkretnym artefaktem adresowanym treścią. Przy pierwszym rozwiązywaniu pliku blokady (aggrega pull) resolver odpytuje rejestr, wybiera wersję zgodnie z jedną z trzech form ograniczenia w URI (dokładna / zakres / bez wersji) i zapisuje przypiętą wersję + skrót w pliku <release-stem>.lock encji Release. Kolejne wywołania aggrega build używają przypiętych wartości niezależnie od zmienności rejestru; nowe wersje można publikować bez wpływu na istniejący plik blokady.

Model przypinania opiera się na jednej kluczowej regule: gdy name:version zostanie opublikowane w rejestrze i rozwiązuje się do skrótu D, to odwzorowanie jest trwałe. Ponowna publikacja tego samego name:version z inną treścią jest odrzucana w chwili wypychania. Samo aggrega push egzekwuje to przy każdej publikacji: rozwiązuje istniejący artefakt pod name:version w docelowym rejestrze; jeśli istnieje, a skrót zgadza się z treścią, która ma zostać wypchnięta, wypychanie niczego nie przesyła i dołącza jedynie to, czego tej publikacji jeszcze brakuje — jej datę publikacji oraz podpis, jeśli wypychanie podpisuje; jeśli istnieje, a skrót się różni, wypychanie zostaje przerwane błędem naruszenia niezmienności, przytaczającym oba skróty.

Niezmienność ma znaczenie ze względu na dwie konsekwencje:

  1. Przypięcia w pliku blokady są wiarygodne. Gdy plik blokady zapisuje mariadb:1.0.0 ze skrótem D, kompilacja pobierająca po skrócie otrzymuje bajty D. Bez niezmienności modyfikacja po stronie rejestru mogłaby podmienić bajty D pod przypięciem w pliku blokady, podważając stabilność między chwilą blokady a chwilą kompilacji. Na tej gwarancji opierają się powtarzalne kompilacje.
  2. Zmiany metadanych po publikacji mają jasną ścieżkę. Oznaczenia opublikowanej wersji jako przestarzałej, rotacji kluczy podpisujących czy uzupełnienia atestacji nie można dokonać przez modyfikację opublikowanego artefaktu (reguła tego zabrania). Należy to zrobić, publikując nową wersję poprawkową lub artefakt towarzyszący, który osobno zapisuje zmianę metadanych. Obie ścieżki są audytowalne — nowa wersja lub artefakt towarzyszący pojawia się jako odrębny wpis w rejestrze — i żadna nie zmienia bajtów pierwotnego artefaktu.

Reguła niezmienności obowiązuje jednakowo każdy artefakt Aggrega publikowany przez OCI (encje, SchemaLibrary, MappingLibrary, pluginy Wasm wskazywane przez pipeline[].plugin: encji Recipe / pipeline[].plugin: encji FeatureRecipe / plugins.{governance,linter,importer}[]: konfiguracji obszaru roboczego). Wszystko, co jest przypięte w pliku blokady przez name:version wraz ze skrótem treści, podlega niezmienności.

Niezmienność jest bezwarunkowa i żadna konfiguracja jej nie łagodzi. Nie istnieje flaga ani ustawienie konfiguracji obszaru roboczego, które zezwalałoby na nadpisanie, ponieważ rejestr nie udostępnia ścieżki nadpisania, którą operator mógłby włączyć. Zmieniona treść jest publikowana pod nową wersją, a aggrega lint --pre-publish sprawdza, czy podbicie wersji odpowiada klasyfikacji zmiany.

Ponowne rozwiązanie do nowszej wersji wymaga jawnego działania użytkownika: aggrega pull --upgrade --release <release> <uri> ponownie rozwiązuje pojedynczą zależność, zachowując wszystkie pozostałe przypięcia, a aggrega pull --upgrade --release <release> ponownie rozwiązuje wszystkie zależności względem bieżącego stanu rejestru. Zależności w formie zakresu i bez wersji rozwiązują się ponownie do najnowszej pasującej wersji; przypięcia w formie dokładnej nie zmieniają się, dopóki użytkownik jawnie nie zaktualizuje ich do innej dokładnej wersji. Plik blokady jest źródłem prawdy dla kompilacji; forma wpisana przez użytkownika wyraża ograniczenie wersji w czasie tworzenia.

10. Egzekwowanie kształtu nazw encji katalogu

Nazwy encji katalogu stosują wzorce właściwe dla każdego rodzaju encji — wymienione poniżej i opisane szczegółowo dla każdego rodzaju w przeglądzie dokumentacji encji. Stanowią one inną powierzchnię niż nazwy instancji, które programista zapisuje w encji Aggregate lub Release i które niezależnie od rodzaju mają jeden wspólny wzorzec; wzorzec ten opisano w ../language-reference/02-naming-conventions.md „Instance Names”. Pole metadata.name deklarowane w YAML katalogu nie zawsze jest identyczne z kanonicznym URI referencji encji: Component i Feature osadzają segmenty wydawcy i grupowania bezpośrednio w metadata.name; Recipe i FeatureRecipe deklarują metadata.name składające się wyłącznie z liścia, a ich kanoniczny dwusegmentowy URI łączy ten liść z spec.capability deklarowanym przez encję; każdy rodzaj biblioteki deklaruje w metadata.name token w PascalCase.

Kształty dla poszczególnych rodzajów encji:

  • Component — trzy segmenty w kebab-case {publisher}/{category}/{name} deklarowane w metadata.name. Przykład: core/datastore/postgres.
  • Feature — dwa segmenty w kebab-case {publisher}/{name} deklarowane w metadata.name. Przykład: core/data-masking.
  • Recipe — pojedynczy liść w kebab-case w metadata.name (np. postgres). Kanoniczny URI referencji {capability}/{name} (zgodnie z §6 powyżej) łączy zadeklarowane przez encję spec.capability z tym liściem; segment wiodący jest dopasowywany do spec.capability, a nie do położenia encji na dysku, więc przeniesienie pliku recipe.yaml nie zmienia sposobu odwoływania się do niego. Katalog biblioteki standardowej umieszcza encję w <catalog-root>/recipe/<capability>/<name>/<version>/recipe.yaml, tak aby drzewo odzwierciedlało współrzędną, ale to odzwierciedlenie jest konwencją katalogu, a nie źródłem URI. Referencja może też wskazywać recepturę samą nazwą — samym liściem, bez segmentu capability — co jest formą dominującą w praktyce i rozwiązuje się zawsze, gdy nazwę tę nosi w katalogu jedna receptura. W URI encji Recipe nie występuje segment wydawcy, a referencja zawierająca trzeci segment nie pasuje do żadnej receptury.
  • FeatureRecipe — pojedynczy liść w kebab-case w metadata.name (np. k8s-secret-from-parameter), symetrycznie do Recipe: kanoniczny URI {capability}/{name} z zadeklarowanego spec.capability i liścia, sam liść akceptowany w ten sam sposób, a drzewo <catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yaml odzwierciedla współrzędną zgodnie z konwencją.
  • Rodzaje bibliotek — SchemaLibrary, MappingLibrary, WorkloadLibrary i ArtifactLibrary — pojedynczy token w PascalCase w metadata.name pasujący do ^[A-Z][A-Za-z0-9]*$ (np. BaseComponents, AIDatastores, BaseWorkloads). Kształt jest taki sam dla każdego rodzaju biblioteki, więc przeniesienie wpisu między bibliotekami nigdy nie oznacza zmiany nazwy na inną konwencję. Koperta JSON Schema każdego rodzaju biblioteki również deklaruje ten wzorzec, niezależnie od opisanego poniżej sprawdzenia.

Dla Component, Feature, Recipe i FeatureRecipe JSON Schema dla metadata.name akceptuje dowolny niepusty ciąg znaków, więc w przypadku tych rodzajów kształt nie jest w żadnym stopniu strukturalny. Każdy udokumentowany kształt — w tym rodzajów bibliotek, których koperty również deklarują swój wzorzec — jest sprawdzany przez plugin dyscypliny publikowania, który przechowuje wzorce jako źródło prawdy w postaci wyrażeń regularnych, współdzielone z dystrybucją kompilatora. Żadnemu rodzajowi nie przypisano tu kształtu, który plugin następnie ignoruje.

Sprawdzenie jest opcjonalne: wykonuje je jedno polecenie i uruchamia się ono tylko wtedy, gdy autor o to poprosi. Dwa polecenia, o których najczęściej zakłada się, że je wykonują, tego nie robią:

  • aggrega lint zgłasza naruszenia kształtu nazw. Plugin porównuje metadata.name każdej encji ze wzorcem dla jej rodzaju. Sprawdzenie uruchamia się, gdy autor wywoła aggrega lint — dla pojedynczej encji, dla domknięcia zależności encji Release z --release albo dla każdej encji katalogu przy wywołaniu bez argumentu — a ten sam zestaw reguł jest dostępny z powierzchni narzędziowej dla edytorów udostępnianej przez CLI. Ustalenia mają charakter doradczy: są zgłaszane z ważnością warn i nie przerywają działania.
warn: E0278 name-shape: metadata.name "mariadbSynth" does not match the documented pattern for Recipe entities (^[a-z][a-z0-9-]*$)

Ustalenie zaczyna się od ważności i krótkiego kodu, pod którym zarejestrowano jego regułę, a który rozwija aggrega explain E0278. Ścieżka pliku, którego dotyczy problem, jest wypisywana nad ustaleniem, a uruchomienie dla całego katalogu kończy się liczbą sprawdzonych encji i zgłoszonych ustaleń doradczych.

  • aggrega build nie sprawdza kształtu nazw. Renderowany wynik nie zależy od nazw encji Aggrega, więc kompilacja katalogu zawierającego niezgodne nazwy nie emituje żadnego ostrzeżenia ani diagnostyki i kończy się sukcesem dokładnie tak jak w innym przypadku.
  • aggrega push również nie sprawdza kształtu nazw. Publikacja jest odrzucana z innych powodów — przede wszystkim z powodu opisanej wyżej reguły niezmienności, zgodnie z którą ponowna publikacja istniejącego name:version z inną zawartością zostaje przerwana. Gdy odmowa wskazuje aggrega lint --pre-publish, informuje autora, które polecenie należy uruchomić; push go nie uruchamia.

Ponieważ ani kompilacja, ani publikacja nie sprawdza kształtu, katalog, który chce przestrzegania konwencji, uruchamia aggrega lint celowo — w hooku pre-commit lub jako krok potoku. Należy pamiętać, że ustalenie dotyczące kształtu nazwy ma charakter doradczy: aggrega lint je zgłasza i mimo to kończy się sukcesem, więc potok, który ma blokować na podstawie konwencji, odczytuje zgłoszone ustalenia zamiast polegać na kodzie wyjścia.

Regułę wyłącza polityka na poziomie przestrzeni roboczej:

# .aggrega-config.yaml — lint section
lint:
publishing_discipline:
allow_nonstandard_names: true # default false

Po ustawieniu polityki reguła kształtu nazw nie zgłasza niczego. Można ją też ustawić dla pojedynczego wywołania za pomocą aggrega lint --allow-nonstandard-names lub ponownie wymusić jej wyłączenie za pomocą --no-allow-nonstandard-names. Uzasadnione zastosowania to katalogi, które nigdy nie zostaną opublikowane, eksperymenty z wieloma wydawcami oraz encje specjalnego przeznaczenia.

11. Rozwijanie encji Feature sterowane adnotacjami

Blok mappings.features.annotations w encji Manifest deklaruje powiązania między kluczami adnotacji a typami Feature oraz tabelę routingu pogrupowaną według filarów (maps.infra, maps.values), wskazującą właściwości schematu encji Feature, które może wypełniać każda adnotacja. Podfaza rozwijania adnotacji w ramach rozwiązywania przechodzi granice encji Release od zewnątrz do wewnątrz oraz podsystemy encji Aggregate od zewnątrz do wewnątrz, oblicza efektywne zbiory adnotacji dla każdego komponentu przez kaskadę i nadpisywanie z możliwością wyłączenia wartością null — dla całej wartości i dla poszczególnych podkluczy — oraz wstrzykuje syntetyczne dołączenia encji Feature niosące origin: annotation w swoim pochodzeniu IR. Pełny opis kształtu powiązań i sposobu ich tworzenia znajduje się w language-reference/entities/manifest.md i language-reference/providers/well-known-annotations.md; ta sekcja dokumentuje mechanizmy działające podczas ładowania katalogu i podczas inspekcji, na których opiera się ścieżka rozwijania.

Pamięć podręczna kompilacji schematów. spec.schema.{infra,values} każdej encji Feature jest kompilowany raz na budowanie i ponownie wykorzystywany w kolejnych przejściach kaskady. Powtarzana walidacja typów poszczególnych podkluczy względem tego samego schematu encji Feature (jeden zakres kaskady na komponent, przy setkach komponentów) odczytuje skompilowany schemat zamiast kompilować go ponownie. Między budowaniami nic nie jest przechowywane, więc zmieniony schemat encji Feature zostaje skompilowany od nowa przy następnym budowaniu.

Walidacja celów powiązań (ładowanie katalogu). Podczas ładowania katalogu kompilator przechodzi każde powiązanie features.annotations w encji Manifest i sprawdza, czy każda ścieżka kropkowa zadeklarowana w maps.infra i maps.values odpowiada właściwości, którą faktycznie deklaruje spec.schema.<pillar> wskazanej encji Feature. Powiązanie kierujące do ścieżki, której schemat encji Feature nie zawiera, zatrzymuje ładowanie katalogu z czytelnym błędem OPS_ERROR, podającym klucz powiązania, brakującą ścieżkę, URI encji Feature i lokalizację w źródle.

Lint nakładania się filarów schematu (ładowanie katalogu). Ostrzeżenie doradcze jest zgłaszane, gdy spec.schema encji Feature deklaruje tę samą nazwę właściwości zarówno w filarze infra, jak i values. Takie nakładanie się rzadko jest zamierzone — właściwości o tej samej nazwie w różnych filarach zaciemniają intencję autora (który filar zadziała, gdy adnotacja wskazuje wspólną nazwę?) i komplikują komunikaty diagnostyczne. Ostrzeżenie nie blokuje i nie można go wyłączyć: autor, który zamierzył nakładanie się, zachowuje je wraz z ostrzeżeniem, a autor, który go nie zamierzył, zmienia nazwę właściwości w jednym z filarów.

Lint nakładania się map powiązań (rozwiązywanie). Ostrzeżenie doradcze jest zgłaszane, gdy ścieżka podklucza występuje zarówno w maps.infra, jak i w maps.values w powiązaniach encji Manifest. Ścieżka obecna na listach obu filarów jest niespójna — pojedynczy podklucz adnotacji nie może kierować jednocześnie do obu filarów, a deterministyczne rozstrzyganie stosowane przez kompilator (ścieżka obecna na obu listach trafia do infra; adnotacja zapisana w encji Aggregate może kierować tylko przez values, więc zapisana tam adnotacja dla tej ścieżki jest odrzucana) jest siatką bezpieczeństwa, a nie zamierzonym kształtem. Ostrzeżenie nie blokuje; autorzy, którzy je zignorują, nadal otrzymują czyste budowanie, a rozstrzygnięcie jest widoczne w pochodzeniu IR.

Prezentacja pochodzenia w aggrega inspect. Polecenie inspect wyświetla jeden nawias dla każdego dołączenia encji Feature, zapisujący źródło każdego wypełnionego liścia:

  • [explicit] — encja Feature została dołączona jawnie przez blok features: w encji Aggregate lub Release.
  • [annotation: <key> from <source>] — każdy wypełniony liść pochodzi z tego samego klucza adnotacji. Nawias podaje klucz i miejsce, w którym zadeklarowano adnotację: plik oraz ścieżkę klucza z kropkami wewnątrz niego.
  • Nawiasy dla poszczególnych liści — kompozycja z obu stron, w której każdy wypełniony liść jest wyświetlany z własnym nawiasem źródła (część [explicit], część [annotation: <key> from <source>]). Ten kształt ujawnia scalanie, w którym dla każdego pola wygrywa wartość jawna: gdy jawne dołączenie i wkład z adnotacji dotyczą tej samej instancji encji Feature w tej samej encji Component, ale zapisują różne liście, oba wkłady pozostają na swoich liściach, a wynik inspect podaje źródło każdego liścia osobno.

Prezentacja inspect odczytuje mapy values_provenance i infra_provenance w IR, osobne dla każdego filaru — wypełniane podczas rozwijania adnotacji równolegle ze wstrzykiwaniem syntetycznych dołączeń — i emituje tę postać nawiasu, która najlepiej podsumowuje łączne źródło liści. Mechanizm inspect jest kanonicznym narzędziem introspekcji pozwalającym zrozumieć, dlaczego dane dołączenie encji Feature trafiło do danej encji Component i skąd pochodzą jego wartości.