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

Manifest

Koncepcyjna rola encji Manifest (Domena 4 — tabela mapowań wiążąca abstrakcyjne interfejsy z konkretnymi encjami Recipes) jest opisana w architecture/04-entity-taxonomy.md. Ta strona omawia powierzchnię tworzenia encji Manifest: jej miejsce obok encji Release, kształt płaskiego mapowania URI, kompozycję za pomocą extends, reguły skróconych URI, powiązania encji Feature sterowane adnotacjami oraz zarezerwowany dla platformy prefiks aggrega.ai/.

Manifest a Release: rozdział odpowiedzialności

Encje Manifest i Release mają rozłączne zakresy odpowiedzialności:

  • Manifest określa, która encja Recipe realizuje każdy typ katalogowy, a przez spec.capability tej encji Recipe — dostawcę (np. Helm, Helm-chart, Compose), który go renderuje. Jest to tabela mapowań — zatwierdzany w Git, osobny dla każdego projektu zapis tego, która konkretna encja Recipe implementuje każdy abstrakcyjny interfejs; wersje i skróty, których kompilacja wymaga od tych encji Recipes, są przypinane osobno, w pliku blokady każdej encji Release.
  • Release określa miejsce docelowe (np. fizyczny katalog wyjściowy dla generowania artefaktów GitOps). Jest to router wdrożeń — osobny dla każdego środowiska opis tego, gdzie trafiają skompilowane artefakty.

Schemat encji Release nie zawiera pola provider na żadnym poziomie zagnieżdżenia; wybór dostawcy należy wyłącznie do encji Manifest.

Ścieżka kompilacji. Gdy użytkownik uruchamia aggrega build --release release.yaml, kompilator ustala fizyczne artefakty, łącząc oba źródła:

  1. Odczyt miejsca docelowego. Kompilator przegląda granice encji Release — na przykład granica ovh-cluster-3 zawiera komponent user-db (typ: core/postgres:1.0.0).
  2. Przegląd encji Manifest. Kompilator otwiera Manifest, na który encja Release wskazuje za pomocą pola manifest:.
  3. Dwupoziomowe wyszukiwanie. Najpierw sprawdzany jest poziom name pod kątem "user-db". Jeśli wpis nie zostanie znaleziony, sprawdzany jest poziom type pod kątem "core/postgres:1.0.0" (z wersją), a następnie "core/postgres" (bez wersji).
  4. Rozwiązanie encji Recipe. Wartością pasującego wpisu jest URI encji Recipe; wskazana encja Recipe deklaruje w spec.capability, który dostawca ją renderuje.
  5. Generowanie wyniku. Kompilator zna teraz katalog docelowy (dist/boundaries/ovh-cluster-3/), dostawcę (renderowanie Helm przez Wasm) oraz artefakt (kod źródłowy encji Recipe). Granice GitOps typu ahead-of-time są respektowane od początku do końca.

Płaskie mapowanie URI

Blok mappings: encji Manifest to płaska mapa z URI typu komponentu na URI encji Recipe (oraz z URI typu funkcji na URI encji FeatureRecipe). Na poziomie encji Manifest mapowanie jest niezależne od możliwości; określenie możliwości wynika z pola spec.capability każdej rozwiązanej encji Recipe w czasie renderowania, a nie ze strukturalnego kształtu encji Manifest. Blok porządkuje mapowania pod dwoma kluczami najwyższego poziomu:

  • components.type mapuje URI typu komponentu na URI encji Recipe. Każda instancja komponentu zadeklarowanego typu jest rozwiązywana do wskazanej encji Recipe. Mapowanie jest jeden do jednego dla każdego typu komponentu. Klucz, który nie wskazuje dokładnego typu instancji, nadal do niej sięga przez bazę typu, jeśli żaden klucz nie wskazuje tego dokładnego typu i dla tej samej bazy nie zapisano innego klucza — więc klucz zapisany bez wersji (core/postgres) albo wskazujący inną wersję (core/postgres:1.0.0) może sięgnąć do instancji core/postgres:2.0.0 — ale wskazana przez niego encja Recipe musi implementować własną wersję każdej takiej instancji: instancja core/postgres:2.0.0 osiągnięta w ten sposób i zmapowana na encję Recipe deklarującą implements: core/postgres:1.0.0 zatrzymuje kompilację. Taką instancję należy zmapować kluczem wskazującym jej wersję (core/postgres:2.0.0) na encję Recipe, która ją implementuje.
  • features.type mapuje URI typu funkcji na URI encji FeatureRecipe. Każde dołączenie encji Feature zadeklarowanego typu jest rozwiązywane do wskazanej encji FeatureRecipe. Encje Features z poświadczeniami (oznaczone feature.aggrega.ai/kind: secret) znajdują się w tej samej mapie features.type co operacyjne encje Features — jest to ujednolicony model encji Feature.

Każdy blok przyjmuje również, obok type, poziom name, który mapuje konkretną nazwę instancji na URI encji Recipe (lub FeatureRecipe). Poziom nazw ma pierwszeństwo przed poziomem typów: instancja wymieniona w components.name jest rozwiązywana do tej encji Recipe, a każda inna instancja tego samego typu — przez components.type. Wyraża to nadpisanie dla pojedynczej instancji — dwie instancje jednego typu komponentu mogą być wdrażane przez dwie różne encje Recipes (na przykład większość instancji bazy danych używa encji Recipe zmapowanej zbiorczo, a jedna instancja jest przypięta do innej fizycznej implementacji), bez rozwidlania typu komponentu ani duplikowania encji Manifest. Nadpisanie działa jednolicie: nazwana instancja zarówno jest renderowana przez nadpisującą encję Recipe, jak i przypina z niej swoje źródło. features.name to symetryczny poziom dla dołączeń encji Feature, kluczowany własną nazwą dołączenia — kluczem, pod którym jest ono zapisane w features: komponentu — a nigdy nazwą komponentu, do którego jest dołączone. Przykład nadpisania encji Recipe dla instancji przedstawia od początku do końca minimalny przypadek z dwiema instancjami.

Dołączenie, które niesie połączenie, jest kluczowane nazwą, jaką przyjmuje w komponencie konsumującym: <alias>.<slot>, czyli alias, pod którym zapisano połączenie, kropka i slot, który wypełnia dołączenie (zob. wpis połączenia w encji Aggregate). Dzięki temu poświadczenie jednego połączenia może być zrealizowane inaczej niż każde inne dołączenie tego samego typu:

spec:
mappings:
features:
type:
core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
name:
# The credential the "gpt" connection carries in its "credential" slot.
gpt.credential: helm/k8s-external-secret:1.0.0

Wpis jest przypinany i weryfikowany jak każdy inny wpis poziomu nazw, co opisuje następny akapit. Encja Feature wskazana przez dołączenie również jest przypinana i weryfikowana, dokładnie tak jak encja Feature dołączenia zapisanego w samym komponencie, pod wpisem połączenia napisanym przez autora — zob. Plik blokady.

Klucz name musi wskazywać coś, co zawiera kompilacja. Poziom jest dopasowywany po dokładnej nazwie, więc klucz components.name, który nie jest instancją komponentu w kompilacji, albo klucz features.name, który nie jest w niej dołączeniem — najczęściej nazwa komponentu, na którym znajduje się dołączenie, wpisana tam, gdzie powinna być własna nazwa dołączenia — nie byłby przez nic uwzględniany, a instancje, dla których był przeznaczony, po cichu rozwiązywałyby się przez poziom type. Zamiast tego kompilacja zatrzymuje się na takim kluczu, zanim cokolwiek zostanie wyrenderowane, wskazując Manifest, klucz, nazwy tego rodzaju, które kompilacja zawiera, oraz nazwę, o którą prawdopodobnie chodziło — zob. A Manifest name mapping names nothing in the build (mapowanie Manifest nie wskazuje niczego w kompilacji).

Realizacja powiązana nazwą jest przypinana i weryfikowana tak samo jak powiązana typem. aggrega pull pozyskuje każdą encję Recipe i FeatureRecipe wiązaną przez którykolwiek poziom — z katalogu, pamięci podręcznej lub rejestru — i zapisuje każdą w pliku blokady encji Release wraz z rozwiązaną wersją i skrótem treści, pod wiążącym ją wpisem mapowania: manifest.spec.mappings.components.name.<instance> dla wpisu poziomu nazw, obok manifest.spec.mappings.components.type.<type> dla wpisu poziomu typów. aggrega build sprawdza każdą z nich względem jej przypięcia. Plik blokady, który nie zawiera wiersza dla realizacji wiązanej przez encję Manifest, zatrzymuje kompilację jako nieaktualny, wskazując realizację i wiążący ją wpis; realizacja, której treść zmieniła się od pobrania, zatrzymuje ją w ten sam sposób, wskazując oba skróty. W obu przypadkach aggrega pull --release <release> zapisuje realizację w jej obecnym stanie. Podobnie jak wpis type, wpis name jest przypinany niezależnie od tego, czy encja Release deklaruje instancję o tej nazwie, więc wpis name wskazujący encję Recipe, której nie zawiera żaden katalog ani rejestr, zatrzymuje pobieranie; wpis name niewskazujący żadnej instancji zawartej w kompilacji również jest przypinany i zatrzymuje kompilację, jak opisano w poprzednim akapicie.

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: production-manifest
version: 1.0.0
spec:
mappings:
components:
type:
# Component-type → Recipe URI. A Recipe URI is at most two segments: an
# optional leading capability, then the recipe name. The bare one-segment
# form (last line) is the common case.
core/datastore/postgres: helm/postgres:1.2.0
core/api-server: helm/api-helm:0.5.0
core/python-worker: standard-python-worker:2.0.0
features:
type:
# Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones.
core/data-masking: helm/data-masking-litellm:1.0.0
core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0

Określanie możliwości w czasie renderowania. Wpis encji Manifest wiąże typ komponentu z URI encji Recipe. URI encji Recipe ma co najwyżej dwa segmenty — opcjonalną początkową możliwość, a następnie nazwę receptury — oraz opcjonalny :version; resolver dzieli tylko na pierwszym /, więc odwołanie z trzecim segmentem nie wskazuje żadnej receptury i zatrzymuje rozwiązywanie. W czasie renderowania resolver ładuje encję Recipe przez bezpośrednie wyszukanie URI w pliku blokady i katalogu, a pole spec.capability każdej encji Recipe określa grupowanie wysyłki według pary (ścieżka, możliwość). Strukturalny kształt encji Manifest pozostaje płaski niezależnie od tego, ilu dostawców obsługuje szerszy katalog.

Bezpośrednie wyszukiwanie URI

Wartością mapowania encji Manifest jest URI encji Recipe. Kompilator rozwiązuje URI bezpośrednio w pliku blokady i katalogu, zwracając pasującą encję Recipe. Nie iteruje on po deklaracjach spec.implements w poszukiwaniu encji Recipe, która „implementuje” typ komponentu. Każdy wpis encji Manifest wiąże napisany przez programistę typ komponentu z konkretnym URI encji Recipe; wybór jest jawny i jednoznaczny w treści encji Manifest.

spec.implements to kontrola spójności tabeli mapowań. Wartość spec.implements rozwiązanej encji Recipe MUSI odpowiadać kluczowi typu komponentu encji Manifest dla danego wpisu mapowania — lub bazie, którą ten klucz extends, na dowolnej głębokości łańcucha, ponieważ encja Recipe napisana dla bazy implementuje wszystko, co ją rozszerza. Wartość niepasująca do żadnego z nich powoduje OPS_ERROR z czytelną diagnostyką wskazującą wpis encji Manifest, rozwiązaną encję Recipe i sprzeczną wartość spec.implements. Kontrola uruchamia się raz dla każdego wpisu mapowania encji Manifest, na złożonej encji Manifest i przed rozwiązaniem jakiejkolwiek encji Recipe — jest statyczna, deterministyczna i nie przechodzi niczego poza własnym łańcuchem extends mapowanego typu. Klucz components.type, który dociera do instancji komponentu w wersji, której nie wskazuje, jest oceniany jeszcze raz dla tej instancji w ten sam sposób, przy czym w miejscu klucza stoi własny typ instancji w wersji, w jakiej kompilacja ją kompiluje, jak opisuje Płaskie mapowanie URI. Zob. ../vocabulary/inheritance-and-interface.md, aby dowiedzieć się, czego encja Recipe bazy oszczędza specjalizacji, a czego nie.

Uruchamia ją każde polecenie odczytujące zależności encji Release, a każde samo decyduje, co oznacza wykryty problem: aggrega build i aggrega pull zatrzymują się, ponieważ oba wytwarzają coś, czego będzie się dalej używać, natomiast aggrega validate i aggrega lint zgłaszają go wraz z pozostałymi wynikami i kończą się kodem niezerowym, a edytor publikuje go jako jedną diagnostykę spośród innych. Wyjątkiem w ocenie instancji jest aggrega lint: ocenia on wpisy mapowania, a nie instancje, do których docierają, więc tego nie zgłasza, podczas gdy aggrega build, aggrega pull i aggrega validate --release zgłaszają. Zob. ../errors/fatal-halts.md, gdzie opisano diagnostykę i sposób naprawy.

Kontrola spójności to jedyne miejsce mapowania, które odczytuje łańcuch extends. Wybór encji Recipe pozostaje dokładny względem klucza mapowania: typ komponentu rozszerzający zmapowaną bazę nadal potrzebuje tu własnego wpisu i nie otrzymuje wpisu przez dziedziczenie.

spec.implements podpowiada również kandydatów. Instancja, której typ nie ma mapowania w encji Manifest, zatrzymuje kompilację z OPS_ERROR, który wymienia jako kandydatów do przypięcia receptury, których spec.implements może implementować ten typ; uzupełnianie w edytorze dla wartości mapowania umieszcza te same pasujące receptury na początku. Oba mechanizmy porównują spec.implements z samym żądanym typem, więc receptura implementująca jedną z baz tego typu nie jest proponowana jako kandydat, choć mapowanie zostałoby uznane za spójne. Tak więc spec.implements deklaruje, co receptura może implementować, i wspiera wybór człowieka — w kontroli spójności, diagnostyce braku mapowania i uzupełnianiu — ale nigdy nie rozstrzyga kompilacji. Mapowanie encji Manifest to jawny wybór wdrożenia dokonany przez użytkownika, przypięty w pliku blokady dla odtwarzalności; katalog nigdy nie wybiera wdrożenia w imieniu użytkownika.

Trzy formy segmentu wersji w URI

URI encji Recipe w encji Manifest może zawierać wersję w jednej z trzech form:

  • Dokładna — helm/postgres:1.2.0. Plik blokady musi przypinać dokładnie tę wersję; przy pierwszym rozwiązywaniu pliku blokady resolver przypina tę wersję; jeśli katalog lub rejestr nie zawiera tej wersji w chwili rozwiązywania, ładowanie przestrzeni roboczej zatrzymuje się z błędem.
  • Zakres — helm/postgres:^1.2.0. Zakres semver ze standardową regułą MVS; przy pierwszym rozwiązywaniu pliku blokady resolver przypina najwyższą dostępną wersję spełniającą zakres.
  • Bez wersji — helm/postgres. Brak przyrostka :version; przy pierwszym rozwiązywaniu pliku blokady resolver przypina najnowszą dostępną wersję.

Kolejne kompilacje używają wersji przypiętej w pliku blokady niezależnie od formy wpisanej przez użytkownika. 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 — plik blokady jest źródłem prawdy dla kompilacji; forma wpisana przez użytkownika to sposób, w jaki użytkownik wyraża ograniczenie wersji podczas tworzenia.

Odwołania kwalifikowane możliwością

Tożsamość encji Recipe w katalogu jest zawężona do możliwości: dwa recipe mogą mieć wspólne metadata.name i wersję, deklarując różne wartości spec.capability. Tożsamość w rejestrze to recipe/{capability}/{name}:{version}, wyprowadzana z rodzaju recipe, jego spec.capability bez przypięcia wersji, które może zawierać, i jego nazwy; drzewo katalogu biblioteki standardowej odzwierciedla tę współrzędną w recipe/{capability}/{name}/ zgodnie z konwencją. Wartość mapowania w encji Manifest wskazuje recipe z jedną z dwóch precyzji:

  • Goła — mariadb:1.0.0. Rozwiązuje się, gdy dokładnie jeden recipe w katalogu ma tę nazwę; w praktyce forma dominująca.
  • Kwalifikowana możliwością — compose/mariadb:1.0.0. Segment przed pierwszym / wskazuje spec.capability danego recipe bez przypięcia wersji — przypięcie zapisane w referencji jest odrzucane (E0095). Wymagana, gdy więcej niż jeden recipe ma tę samą nazwę: goła referencja pasująca do dwóch recipe jest niejednoznaczna i głośno zatrzymuje rozwiązywanie, zamiast po cichu wybrać jeden z nich.

URI encji Recipe nie ma dalszych pozycji. Resolver dzieli tylko na pierwszym /, więc compose/mariadb wskazuje możliwość compose i recipe mariadb, a referencja trzysegmentowa nie pasuje do żadnego recipe przy żadnej precyzji.

Opisane wyżej formy segmentu wersji dotyczą obu kształtów.

Encje opublikowane w rejestrze w mapowaniach

Do encji pobieranej z rejestru, a nie z lokalnego katalogu, odwołuje się dokładnie tą samą tożsamością, której używa encja lokalna: referencja nie zawiera hosta rejestru ani segmentu rodzaju encji. Resolver uzupełnia oba — host z domyślnego rejestru skonfigurowanego w przestrzeni roboczej, segment rodzaju z miejsca referencji w schemacie — zgodnie z regułami Context-Aware Shorthand URIs opisanymi niżej. Gdy kopii nie ma ani w lokalnym katalogu, ani w pamięci podręcznej, aggrega pull — lub kompilacja uruchomiona z --auto-pull — pobiera encję z wyprowadzonej lokalizacji, zapisuje ją w pamięci podręcznej i przypina rozwiązaną wersję oraz skrót treści w pliku blokady; kolejne kompilacje korzystają z pamięci podręcznej bez dostępu do sieci.

# Aggregate fragment — a registry-published Component as the type:
components:
db:
type: core/datastore/mariadb:1.0.0

Ponieważ host i segment rodzaju encji są wyprowadzane, a nie pisane przez autora, wpisanie któregokolwiek z nich do referencji nie wskazuje opublikowanej encji — daje tożsamość, której nie ma żaden wpis katalogu. Referencja do encji Component lub Feature to dosłownie jej metadata.name plus opcjonalne :version, niezależnie od tego, czy encja rozwiązuje się z lokalnego katalogu, z pamięci podręcznej, czy z rejestru. Przestrzeń robocza korzystająca z prywatnego rejestru podaje ten host we własnej konfiguracji, a nie w każdej referencji.

Kontrola kompletności

Po rozwiązaniu wszystkich mapowań kompilator sprawdza, czy każda instancja komponentu i dołączenia (credential Feature jest dołączeniem jak każde inne) w encji Aggregate dewelopera ma rozwiązany Recipe lub FeatureRecipe. Niezmapowane encje powodują krytyczne zatrzymanie z jawną diagnostyką, która wymienia każdą brakującą encję i podpowiada, jaki klucz components.type lub features.type dodać, aby uzupełnić lukę.

Kotwice YAML dla zwięzłych manifestów

Aby uniknąć rozrostu YAML przy dużych zbiorach mapowań, Manifest obsługuje opcjonalny blok defs: na standardowe kotwice YAML (& i *):

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: global-base-manifest
version: 1.0.0
defs:
- &python_worker_recipe "helm/standard-python-worker:2.0.0"
spec:
mappings:
components:
type:
core/python-worker: *python_worker_recipe
core/postgres: helm/postgres:1.2.0

Negocjacja Feature

Uzgadnianie możliwości korzysta z tego samego płaskiego mapowania URI:

  1. Deweloper dołącza core/data-masking do komponentu w encji Aggregate, pod własną nazwą w mapie features: tego komponentu.
  2. Kompilator wyszukuje core/data-masking w mapie features.type encji Manifest.
  3. Jeśli wyszukiwanie zwraca URI encji FeatureRecipe (np. helm/data-masking-litellm:1.0.0), możliwość istnieje, a potok tego FeatureRecipe wykonuje się w zdefiniowanej kolejności.
  4. Jeśli features.type nie zawiera pasującego wpisu, kompilator zatrzymuje kompilację i wymienia niezmapowaną encję Feature.

Manifest akceptuje także blok features.annotations — równoległą powierzchnię tworzenia, która pozwala podsystemowi encji Release lub Aggregate dołączać Features według klucza adnotacji zamiast deklaracji dla poszczególnych komponentów. Kształt powiązania, podział side-vs-pillar określający, która powierzchnia tworzenia korzysta z których ścieżek routingu, zasada pierwszeństwa jawnego dołączenia oraz reguła domyślnych wartości schematu opisane są w osobnej sekcji Annotation-Driven Feature Bindings poniżej.

Kompozycja za pomocą extends

Encja Manifest może zadeklarować pojedyncze odwołanie extends: wskazujące bazową encję Manifest, której mappings dziedziczy. Odwołanie nie jest URI i nigdy nie jest rozwiązywane przez katalog: encja Manifest należy do strony wdrożenia i jest tworzona obok encji Release, a nie publikowana, więc wartość to albo ścieżka względna do pliku encji Manifest — ./base-manifest.yaml — albo samo metadata.name encji Manifest znajdującej się we własnym katalogu encji Release. Ścieżka względna musi prowadzić do encji Manifest wewnątrz przestrzeni roboczej — albo, jeśli encja Release została wskazana poza przestrzenią roboczą (w wierszu poleceń lub w konfiguracji przestrzeni roboczej), wewnątrz katalogu zawierającego tę encję Release, a w przypadku encji Manifest wskazanej samodzielnie w wierszu poleceń poza przestrzenią roboczą — wewnątrz katalogu zawierającego tę encję Manifest: ścieżka, która z niego wychodzi lub którą poza niego wyprowadza dowiązanie symboliczne, jest odrzucana, zanim wskazany przez nią plik zostanie odczytany (zob. errors/fatal-halts.md §„A reference to another file leads out of the directory it must stay inside (Odwołanie do innego pliku prowadzi poza katalog, w którym musi pozostać)”). Mapowania potomne nadpisują bazowe w przypadku kolizji kluczy, co umożliwia wzorce nakładek środowiskowych (zgodność staging/prod z precyzyjnymi różnicami dla poszczególnych środowisk) oraz wzorce programowania lokalnego bez kopiowania całości.

Semantyka scalania. Gdy lokalna encja Manifest rozszerza bazową encję Manifest, kompilator wykonuje płytką zamianę kluczy na każdym poziomie — słowniki type i name są scalane niezależnie, a nie głęboko — co gwarantuje wyszukiwanie w słowniku w czasie O(1) i zapewnia przewidywalne zachowanie dziedziczenia. W obrębie każdego poziomu klucze potomne nadpisują klucze nadrzędne.

Wzorzec pomostu dla programowania lokalnego. Typowym zastosowaniem extends jest zamiana encji FeatureRecipe poświadczeń na potrzeby lokalnego prototypowania bez modyfikowania encji Aggregate. W środowisku produkcyjnym bazowa encja Manifest mapuje encję Feature poświadczeń core/aws-secrets-manager na produkcyjną encję FeatureRecipe na poziomie features.type. Na potrzeby lokalnego prototypowania zespół platformy udostępnia local-manifest, który rozszerza bazę i precyzyjnie nadpisuje mapowanie encji Feature poświadczeń tak, by używało host-env-injector — lokalnej encji FeatureRecipe, która dostarcza poświadczenie do pliku Compose jako odwołanie do zmiennej, np. ${SECRET_NAME}, które Docker Compose podstawia ze środowiska powłoki lub pliku .env podczas uruchamiania stosu. Programista otrzymuje standardowy lokalny przepływ pracy, a encja Aggregate pozostaje agnostyczna wobec możliwości w środowisku produkcyjnym.

Skrócone URI zależne od kontekstu

Kompilator Aggrega stosuje wnioskowanie zależne od kontekstu (Context-Aware Inference) przy rozwiązywaniu URI OCI w encjach Manifests. Jeśli inżynier pominie w pełni kwalifikowaną nazwę domeny (FQDN) i typ encji architektonicznej, kompilator automatycznie użyje domyślnego rejestru (skonfigurowanego w .aggrega-config.yaml) i wywnioskuje typ encji na podstawie miejsca, w którym ciąg znajduje się w schemacie.

Reguły wnioskowania:

  1. Domyślna domena: każdy URI bez domeny (np. python-worker-helm:1.0) otrzymuje prefiks ze skonfigurowanej wartości default_registry (domyślnie: hub.aggrega.ai/).
  2. Kontekstowe rozwinięcie encji: kompilator dołącza właściwą ścieżkę encji na podstawie ścisłego słownika schematu:
    • Ciągi w Aggregate.spec.components[].type są rozwijane do /component/.
    • Ciągi w Aggregate.spec.aggregates[].type są rozwijane do /aggregate/.
    • Ciągi w Manifest.spec.mappings.components.type lub Manifest.spec.mappings.components.name są rozwijane do /recipe/.
    • Ciągi w Manifest.spec.mappings.features.type lub Manifest.spec.mappings.features.name są rozwijane do /featurerecipe/. Obejmuje to encje Features poświadczeń (oznaczone etykietą feature.aggrega.ai/kind: secret) — używają one tej samej ścieżki FeatureRecipe.
    • Ciągi przypisane do pipeline[].plugin są rozwijane do /plugin/.
  3. Pierwszeństwo trzech poziomów: przed zastosowaniem wnioskowania OCI kompilator przeszukuje katalogi katalogu przestrzeni roboczej i pamięć podręczną artefaktów (poziom przestrzeni roboczej i pamięci podręcznej), zgodnie z definicją w trzypoziomowym modelu rozwiązywania encji. Wnioskowanie OCI ma zastosowanie tylko wtedy, gdy encja dociera do poziomu rejestru. Klucz ani wartość mapowania nigdy nie są odczytywane jako ścieżka pliku: encja Recipe lub FeatureRecipe utworzona lokalnie znajduje się w katalogu katalogu — catalog/ w katalogu głównym przestrzeni roboczej lub jednym z wymienionych w workspace.catalog_dirs — i jest wskazywana przez swoją referencję.

Skróty w praktyce:

# Capability-qualified — required when two recipes share the name "postgres":
"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:
"core/postgres": "postgres:2.0"
# Found in a local catalog directory or the cache; failing both, `aggrega pull`
# (or a build run with --auto-pull) fetches it from the registry location derived
# from the configured default registry and the Recipe kind.
# A private registry is named in workspace configuration, not in the reference.

Brak prefiksu ops/. Nazwy encji Recipe nie mają prefiksu ops/ — katalog typu encji recipe/ w taksonomii OCI już identyfikuje domenę, a encje Recipes są publikowane pod recipe/{capability}/{name} bez dodatkowych prefiksów. Encje Manifests odwołują się do encji Recipes przez {capability}/{name} lub przez samą nazwę w przypadku wnioskowania zależnego od kontekstu. Pełną taksonomię OCI opisuje architecture/13-catalog-and-registry.md §6.

Powiązania Feature sterowane adnotacjami

Blok features.annotations encji Manifest deklaruje powiązania między kluczami adnotacji a typami Feature oraz ścieżki routingu, przez które każde powiązanie przesyła wartość adnotacji. Powiązanie jest powierzchnią autorską służącą do kompresowania powtarzalnych dołączeń Feature dla poszczególnych komponentów — wzorca, w którym dziesiątki komponentów w obrębie granicy niosą identyczny blok features: — do pojedynczych deklaracji adnotacji na granicach encji Release lub w podsystemach encji Aggregate.

Kształt schematu:

spec:
mappings:
features:
type:
core/rewrite-host: helm/rewrite-host-helm:1.0.0
core/db-pool: helm/db-pool-helm:1.0.0
annotations:
feature.aggrega.ai/rewrite-host:
feature: core/rewrite-host
maps:
infra:
- upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool:
feature: core/db-pool
maps:
values:
- pool # Aggregate-side: routes annotation value into values.pool

Powiązanie zawiera pole feature wskazujące docelowy typ Feature oraz blok maps grupujący trasy podkluczy w postaci ścieżek z kropkami według docelowego filaru. Pole feature odwołuje się do typu Feature, który musi również występować w sąsiedniej sekcji features.type (w której znajduje się powiązanie wersji encji FeatureRecipe). Blok maps deklaruje dwie listy kluczowane filarami — maps.infra i maps.values — z których każda zawiera ciągi ścieżek z kropkami wskazujące właściwości spec.schema.<pillar>.<path> docelowej encji Feature. Powiązanie musi zadeklarować co najmniej jedną ścieżkę łącznie w obu listach (JSON Schema wymusza minProperties: 1 dla maps).

Polimorfizm encji Provider dla tego samego klucza adnotacji — np. feature.aggrega.ai/rewrite-host wiązany z core/k8s-dns-resolver we wdrożeniu Kubernetes, ale z core/compose-bridge w lokalnym wdrożeniu Compose — wyraża się przez wybór różnych typów Feature w różnych encjach Manifests; każdy Manifest wiąże adnotację z jednym Feature, a FeatureRecipe wybranego Feature zawiera implementację specyficzną dla dostawcy.

Podział strona–filar. Niezmiennik Aggregate-as-Authoring-Surface ogranicza każdą stronę autorską do ścieżek routingu jednego filaru. Adnotacje po stronie encji Aggregate są kierowane wyłącznie przez ścieżki maps.values; adnotacje po stronie encji Release są kierowane wyłącznie przez ścieżki maps.infra. Powiązanie deklarujące ścieżki w obu filarach obsługuje kompozycję między stronami: adnotacja po stronie encji Aggregate uruchamia podzbiór filaru values; adnotacja po stronie encji Release dla tego samego klucza uruchamia podzbiór filaru infra; oba wkłady składają się w jedno dołączenie Feature na parę (Component, Feature) z wypełnionymi oboma filarami. Niezgodność strona–filar — np. adnotacja po stronie encji Aggregate dla powiązania deklarującego tylko maps.infra — zatrzymuje kompilację z czytelną diagnostyką podającą klucz adnotacji, filar routingu, stronę autorską i lokalizację w źródle, przypisaną do domeny dokumentu, w którym zapisano wartość adnotacji.

Walidacja celów ścieżek. Podczas ładowania katalogu kompilator sprawdza, czy każda ścieżka z kropkami zadeklarowana w maps.infra i maps.values odpowiada właściwości, którą faktycznie deklaruje spec.schema.<pillar> docelowej encji Feature. Powiązanie kierujące do ścieżki, której schemat Feature nie wymienia, zatrzymuje ładowanie katalogu z czytelnym błędem OPS_ERROR, podającym powiązanie, docelową encję Feature oraz filar i ścieżkę routingu. Kształty schematu wykraczające poza proste przechodzenie po właściwościach ($ref, patternProperties, kompozycja oneOf / anyOf / allOf) kończą statyczne sprawdzenie w danej gałęzi, pozostawiając wykrycie ewentualnej niezgodności dalszej walidacji schematu.

Kształty wartości adnotacji. Powiązanie przyjmuje wartości adnotacji w trzech kształtach. Skalarna — pojedyncza wartość YAML (ciąg, liczba, wartość logiczna). Wartość skalarna w połączeniu z powiązaniem deklarującym dokładnie jedną ścieżkę łącznie w obu filarach kieruje wartość do tej jednej ścieżki; wartość skalarna w połączeniu z powiązaniem deklarującym więcej niż jedną ścieżkę oznacza niejednoznaczny routing i zatrzymuje kompilację z czytelną diagnostyką, przypisaną do domeny dokumentu, w którym zapisano wartość adnotacji. Strukturalna — mapa YAML, której każdy podklucz najwyższego poziomu odpowiada wpisowi ścieżki z kropkami w maps.infra lub maps.values; każdy podklucz jest kierowany do swojego zadeklarowanego filaru niezależnie, a podział strona–filar obowiązuje dla każdego podklucza. Jawne YAML null — rezygnuje z odziedziczonego powiązania w zakresie kaskady (przy czym null dla podklucza wewnątrz wartości strukturalnej rezygnuje z pojedynczych podkluczy, a sąsiednie pozostają). Kanoniczne omówienie wartości strukturalnych — scalanie kaskadowe per podklucz, kompozycja między stronami, walidacja typów per podklucz, łagodna dyscyplina domyślna dla pól schematu bez zadeklarowanego type — znajduje się w providers/well-known-annotations.md §„Structured annotation values”.

Jawne dołączenie wygrywa przy kolizji kluczy. Gdy komponent encji Release lub komponent encji Aggregate ma zarówno jawny wpis features:, jak i adnotację rozwijaną do tego samego klucza Feature, jawny wpis zostaje zachowany, a rozwinięcie adnotacji dla tego klucza w tym komponencie nie ma efektu. Syntetyczne dołączenie nigdy nie nadpisuje instancji Feature zadeklarowanej przez autora. Autorzy mogą więc stosować rozwijanie adnotacji dla większości komponentów i precyzyjnie nadpisywać pojedyncze komponenty, zapisując jawny wpis features: z tym samym kluczem — jawny wpis zawiera dostosowanie dla danego komponentu, a adnotacja kaskadowo trafia bez zmian do wszystkich pozostałych komponentów.

Jawny wkład wygrywa per liść przy kompozycji między stronami. Gdy jawne dołączenie i wkład adnotacji wypełniają tę samą instancję Feature, ale zapisują różne liście, oba wkłady pozostają, a wynikowa encja Feature zawiera oba liście z pochodzeniem rejestrowanym per liść. Gdy jawne dołączenie i wkład adnotacji dotyczą tego samego liścia w tym samym filarze, wygrywa wkład jawny, a IR zapisuje pochodzenie pominiętej adnotacji jako znacznik nadpisania na tym liściu. Ładowanie katalogu ujawnia to nadpisanie w czasie kompilacji jako doradcze ostrzeżenie lint, podające klucz i źródło pominiętej adnotacji.

Wartości domyślne schematu w czasie rozwijania. Syntetyczne dołączenie Feature utworzone przez rozwinięcie adnotacji zawiera tylko liście wypełniane przez wartość adnotacji poprzez zadeklarowane ścieżki powiązania. Wartości domyślne zadeklarowane w spec.schema docelowej encji Feature nie są scalane z syntetycznym dołączeniem w czasie rozwijania. Materializacja wartości domyślnych należy do warstwy renderowania encji FeatureRecipe i jest stosowana jednakowo do dołączeń jawnych i syntetycznych, dzięki czemu obie ścieżki dają ten sam wynik dla tej samej efektywnej konfiguracji.

Rozdział przestrzeni nazw adnotacji:

PrefiksWłaścicielPrzeznaczenie
aggrega.ai/Wyłącznie platforma AggregaNatywne adnotacje platformy odczytywane bezpośrednio przez dostawcę (np. aggrega.ai/namespace).
feature.aggrega.ai/Oficjalna biblioteka standardowaSkróty adnotacji Feature powiązane w encji Manifest.
{any-other-domain}/Przedsiębiorstwo / społecznośćNiestandardowe skróty adnotacji Feature.

Rezerwacja prefiksu aggrega.ai/

Wiązania features.annotations w encji Manifest nie mogą używać samego prefiksu aggrega.ai/ — jest on zarezerwowany dla natywnych adnotacji platformy emitowanych przez kompilator (etykiet OTel i pochodzenia itp.). Podprefiksy z zakresem (component.aggrega.ai/*, compliance.aggrega.ai/*, korporacyjny acme.aggrega.ai/*) pozostają dostępne dla autorów. Zestaw adnotacji zarezerwowanych przez platformę opisano w providers/well-known-annotations.