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

Powierzchnia publikacji

Każdy plik YAML katalogu Aggrega zawiera jednolity zestaw pól metadanych, które opisują encję na potrzeby dystrybucji katalogowej: kto ją utrzymuje, na jakiej licencji jest udostępniana, gdzie znajduje się jej kod źródłowy i jakie słowa kluczowe pozwalają ją odnaleźć. Razem pola te tworzą powierzchnię publikacji — słownik metadanych, na którym polegają wydawcy katalogów i konsumenci narzędziowi, odrębny od mechanizmu metadata.labels / metadata.annotations po stronie treści, opisanego w labels-and-annotations.md.

Ta strona opisuje pola powierzchni publikacji, inwentarz pól opisu w całym korpusie (opisy koperty, instancji i poszczególnych pól), zamierzone zastosowanie pola maintainera i jego zweryfikowanego konsumenta oraz asymetrie pól wymaganych w poszczególnych encjach (które pola każda encja wymaga obecnie i gdzie asymetrie są zamierzone).

Pola powierzchni publikacji

Poniższe pola występują w każdej encji domeny 2 (Component, Feature) i domeny 3 (Recipe, FeatureRecipe, Plugin), a także w encji Aggregate jako module wielokrotnego użytku. Występują również w encjach Manifest i Release, ze zredukowaną semantyką (przypisanie do obszaru roboczego zamiast publikacji w katalogu).

PoleTypPrzeznaczenieOdbiorca
descriptionstringCzytelne dla człowieka podsumowanie encjiKarty podpowiedzi w edytorze (aggrega serve); narzędzie describe wywoływane przez asystenta (aggrega mcp); przeszukiwalna adnotacja w opublikowanym artefakcie (aggrega push); aggrega inspect
maintainerstablica obiektówWłaściciel encji (nazwa, e-mail, URL)Blok catalog_metadata węzła w IR, w węzłach Component
licensestringZgodność prawna (zwykle identyfikator SPDX)Blok catalog_metadata węzła w IR, w węzłach Component
repositorystring (URL)Repozytorium Git ze źródłamiBlok catalog_metadata węzła w IR, w węzłach Component — nic innego go nie odczytuje
homestring (URL)URL dokumentacji / wikiBlok catalog_metadata węzła w IR, w węzłach Component — nic innego go nie odczytuje
keywordstablica stringówTagi wyszukiwaniaBlok catalog_metadata węzła w IR, w węzłach Component — żaden indeks wyszukiwania ich nie wykorzystuje

Wszystkie sześć pól jest opcjonalnych w każdej encji, która je zawiera. Autor katalogu, który pominie cały zestaw, tworzy poprawny YAML — powierzchnia publikacji jest przeznaczona dla encji dystrybuowanych w katalogu; encje do użytku wewnętrznego mogą ją pominąć bez konsekwencji.

Kolumna „Odbiorca” jest wyczerpująca dla tego, co jest dostępne obecnie, a dwie jej konsekwencje warto wyraźnie wskazać, ponieważ zmieniają to, co warto tworzyć:

  • description to jedyne pole z więcej niż jednym odbiorcą. aggrega serve umieszcza je w karcie podpowiedzi dla encji Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest i czterech rodzajów bibliotek (SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) — ale nie dla Plugin ani Release. Narzędzie describe udostępniane przez aggrega mcp zwraca je dla encji dowolnego rodzaju. aggrega push zapisuje je w opublikowanym artefakcie jako przeszukiwalną adnotację. aggrega inspect wypisuje je pod nagłówkiem encji dla każdego rodzaju i nie wypisuje żadnego innego pola powierzchni publikacji.
  • repository, home i keywords są walidowane i przenoszone, ale poza IR nic ich nie odczytuje. Nie wykorzystuje ich żadna lista, strona katalogu ani indeks wyszukiwania. Ich wypełnienie zapisuje informację o pochodzeniu, która podróżuje z encją i jest czytelna w wyjściu IR oraz dla polityki nadzoru; nie sprawia jednak, że encję można gdziekolwiek znaleźć.

Wycofanie (deprecation) nie jest polem powierzchni publikacji. Encję oznacza się jako wycofaną, zapisując dla niej znacznik w rejestrze po publikacji — podpisany znacznik zawierający poziom ważności (warning, error lub retracted), powód i zamiennik, weryfikowany przy pobieraniu. Każde narzędzie odczytujące plik lockfile zgłasza go wtedy; build.halt_on_deprecated_severity decyduje jedynie o tym, czy zatrzymuje on także kompilację. Znacznika nigdy nie umieszcza się w YAML samej encji, a powód jest strukturalny: opublikowany artefakt jest niezmienny, więc flaga zamrożona w nim w chwili publikacji nie mogłaby wyrazić decyzji podjętej później. Informacja o wycofaniu, którą aggrega inspect wypisuje dla encji katalogowej, pochodzi ze znacznika, dla każdego rodzaju rozwiązywanego po nazwie.

Wykorzystanie w IR — blok catalog_metadata węzła

Kompilator przenosi pola powierzchni publikacji z każdej encji Component do bloku catalog_metadata odpowiadającego jej węzła, widocznego w grafie IR zwracanym przez uruchomienie (aggrega inspect <release> --ir-graph). Blok zawiera maintainers, license, repository, home i keywords — pięć pól przenoszonych przez IR; description do nich nie należy. Narzędzia zbudowane na kontrakcie grafu IR odczytują metadane stamtąd, zamiast ponownie czytać YAML katalogu.

Tylko węzły Component. Blok jest wypełniany przez wyszukanie typu komponentu węzła w katalogu jako encji Component, więc powierzchnia publikacji encji Feature, Recipe, FeatureRecipe czy Plugin nigdy nie trafia do IR — te encje zawierają pola i pola te przechodzą walidację, ale nie powstaje z nich żaden węzeł IR.

catalog_metadata znika całkowicie z JSON-a IR, gdy każde pole powierzchni publikacji w źródłowej encji Component jest puste lub zerowe: blok jest pomijany, a nie emitowany z pustymi wartościami. To samo wejście daje więc to samo zwarte wyjście, dzięki czemu diff IR pozostaje stabilny między uruchomieniami.

Polityka nadzoru może odczytać ten blok. Plugin podłączony w plugins.governance w roli ir-verdict otrzymuje cały graf IR, węzeł po węźle, łącznie z blokiem catalog_metadata każdego węzła Component — dzięki temu polityka może zaakceptować lub odrzucić kompilację na podstawie license, repository, home, keywords lub maintainers węzła. Ten zasięg dotyczy wyłącznie gniazda nadzoru: plugin renderujący dostawcy otrzymuje ograniczoną projekcję węzła, która nie obejmuje catalog_metadata, więc pluginy renderujące nie mogą odczytać tych pól.

Trzy typy opisów

Pole description występuje jednolicie w kopercie, ale korpus zawiera także ciągi o charakterze opisów wewnątrz deklaracji schematów (opisy poszczególnych pól) oraz wewnątrz treści filarów (opisy poszczególnych instancji). Współistnieją trzy odrębne typy opisów; poniższa tabela je rozróżnia.

TypGdzie się znajdujeAutorPrzeznaczenie
Opis kopertymetadata.description w każdej encjiWydawca kataloguPodsumowanie encji jako całości, wyświetlane w kartach podpowiedzi edytora i umieszczane w opublikowanym artefakcie
Opis instancjiPole description obok deklaracji instancji (np. featuresSchema.<slot>.description, usesSchema.<socket>.description)Autor schematuOpis slotu / gniazda / portu dla autorów encji konsumujących, którzy czytają deklarację
Opis polaAdnotacja description: z JSON Schema 2020-12 wewnątrz treści schema: / featuresSchema: / usesSchema: (w formie zwartej lub w pełnym YAML JSON Schema)Autor schematuDokumentacja poszczególnych pól, która podróżuje razem ze schematem

Trzy typy dzielą słowo „description”, ale znajdują się na strukturalnie odrębnych poziomach. Opis koperty dotyczy encji jako całości; opis instancji dotyczy deklaracji wewnątrz slotu schematu; opis pola dotyczy konkretnej wartości wewnątrz typowanego schematu. Autorzy piszący encję Component:

  • Ustawiają metadata.description raz dla samej encji Component.
  • Ustawiają featuresSchema.admin_password.description raz dla każdego slotu poświadczeń deklarowanego przez encję Component.
  • Ustawiają adnotacje description: dla poszczególnych pól wewnątrz bloku schema: — w formie zwartej (port: { type: integer, description: "..." }) lub w pełnym YAML JSON Schema — aby udokumentować każde pole dla każdego, kto czyta schemat encji Component.

Trzy typy nie dziedziczą się kaskadowo i nie kolidują ze sobą, a każdy trafia na inną powierzchnię — albo na żadną:

  • Opis koperty — karty podpowiedzi edytora, przeszukiwalne adnotacje opublikowanego artefaktu oraz aggrega inspect, zgodnie z kolumną Konsument powyżej.
  • Opis pola — pojawia się dosłownie we fragmencie schematu, który renderuje karta podpowiedzi encji Component lub Feature. Fragment obejmuje wyłącznie spec.schema i jest obcinany do pierwszych wierszy, więc opis położony głębiej w bloku — lub znajdujący się wewnątrz featuresSchema: albo usesSchema: — się w nim nie pojawia.
  • Opis instancji — deklarowany i przenoszony razem z encją; żadna dostarczana powierzchnia nie renderuje go samodzielnie. aggrega inspect wyświetla gniazda i sloty funkcji encji Component bez ich opisów.

Przeznaczenie pola maintainers

Pole maintainers zawiera tablicę obiektów, z których każdy ma name, email i url. Przeznaczenie i zweryfikowany konsument:

Przeznaczenie (informacyjne + pochodzenie w IR). Pole ma charakter informacyjny na potrzeby publikowania katalogu: jego intencją architektoniczną jest odpowiedź na pytanie „kto odpowiada za tę encję katalogu” — sygnał własności, który podróżuje razem z encją. Żadna powierzchnia nie prezentuje go jako listy kontaktów i żadne wbudowane sprawdzenie niczego z nim nie porównuje.

Zweryfikowany konsument (catalog_metadata dla każdego węzła). Kompilator przenosi metadata.maintainers każdej encji Component do catalog_metadata.maintainers odpowiadającego jej węzła w IR, widocznego w grafie zwracanym przez aggrega inspect <release> --ir-graph, gdy źródłowa encja Component je zadeklarowała. To jedyny czytelnik tego pola. Polityka zarządzania dołączona w plugins.governance w roli ir-verdict widzi je właśnie tam, więc regułę dotyczącą własności — każda encja wskazuje co najmniej jednego opiekuna, domena opiekuna należy do zatwierdzonego zbioru — można wyrazić względem IR, a nie względem YAML katalogu. Żadna taka reguła nie jest dostarczana; to gniazdo jest miejscem, w którym należy ją umieścić.

Kompilator nie wymusza ani nie waliduje zawartości opiekunów poza strukturalnym kształtem JSON Schema (name wymagane; email i url opcjonalne, oba typu string). To, czy wymienieni opiekunowie faktycznie są właścicielami encji, czy ich adres e-mail jest osiągalny, czy commit w repozytorium jest podpisany przez jednego z nich — to kwestie zarządzania katalogiem i żadne dostarczane sprawdzenie nie ocenia żadnej z nich. Należą one do polityki zarządzania dołączanej przez operatora, a nie do kompilatora.

Asymetrie pól wymaganych

Rodzaje encji Aggrega mają w swoich schematach JSON Schema nieco różne zestawy pól wymaganych. Większość asymetrii jest zamierzona i odzwierciedla rolę encji.

Pola wymagane dla poszczególnych encji (z pominięciem apiVersion / kind / metadata.name / metadata.version, których jednakowo wymaga każda encja):

EncjaDodatkowe pola wymaganeUzasadnienie
Componentmetadata.labels.component.aggrega.ai/typeWymóg etykiety jest kluczowy dla dopasowania selektorów: adnotacje usesSchema x-aggrega-selector: filtrują docelowe Components według tej etykiety; bez niej encja Component jest odrzucana podczas wczytywania
Feature—Brak wymogu zarezerwowanej etykiety; Features są identyfikowane przez nazwę + wydawcę
Recipespec.capability, spec.implementsCapability warunkuje przekazanie do providera; implements warunkuje powiązanie z encją Component
FeatureRecipespec.capability, spec.implementsTak jak dla encji Recipe
Pluginmetadata.pluginType, spec.abiVersionTyp gniazda implementowany przez plugin (część bloku adresowania, dostarczająca segment <pluginType> wyprowadzonej współrzędnej plugin/<pluginType>/<name>) oraz docelowa wersja ABI; lokalizacja .wasm jest wyprowadzana z tej tożsamości, a nie zapisywana przez autora; plugin renderujący dla providera (pluginType: provider) dodatkowo zawiera swój kontrakt translacji w spec.provider
Aggregate—Encja Aggregate, która nie deklaruje żadnego z components, subsystems ani aggregates, wczytuje się i kompiluje, ale niczego nie renderuje
Manifestspec.mappingsWarstwy mapowań są jedynym celem encji Manifest
Releasespec.aggregate, spec.manifest (encja Release deklarująca extends nie zapisuje aggregate i może pominąć manifest); metadata.environmentPierwsze dwa wiążą budowanie z konkretnymi encjami Aggregate + Manifest; środowisko jest oznaczane na wyrenderowanym wyniku jako etykieta aggrega.ai/environment

Wymóg etykiety Component jest kluczowy

Etykieta component.aggrega.ai/type jest jedyną etykietą, której Aggrega wymaga na jakiejkolwiek encji. Wymóg istnieje, ponieważ mechanizm usesSchema biblioteki standardowej filtruje kandydatów docelowych za pomocą adnotacji x-aggrega-selector: zawierających ciągi selektorów, takie jak "component.aggrega.ai/type=database" — selektor sprawdza etykiety celu, aby ustalić, czy typ pasuje do typów akceptowanych przez gniazdo. Schemat encji Component to egzekwuje: encja Component bez tej etykiety jest odrzucana podczas wczytywania (E0215), ze wskazaniem brakującego klucza.

Wymóg ten nie dotyczy więc powierzchni publikacji (etykieta nie służy do wyszukiwania w katalogu), lecz topologii: ma ją każda encja Component, łącznie z Components do użytku wewnętrznego, które nie są przeznaczone do dystrybucji w katalogu.

Pole metadata.environment encji Release jest wymagane

Schemat encji Release wymaga metadata.environment — ciągu, który kompilacja oznacza na wyrenderowanym wyniku jako etykietę aggrega.ai/environment.

Pozostałe asymetrie

Pozostałe asymetrie (pola wymagane encji Recipe a Component, wymóg mappings w encji Manifest) odzwierciedlają rolę każdej encji. Autorzy oczekujący jednolitego kontraktu pól wymaganych dla wszystkich rodzajów encji go nie znajdą; asymetrie są zamierzone zgodnie z projektem opartym na rolach.

Odsyłacze

  • labels-and-annotations.md — mechanizm metadanych po stronie treści, uzupełniający powierzchnię publikacji.
  • entities/component.md — wymóg metadata.labels.component.aggrega.ai/type w encji Component oraz deklaracje schema / usesSchema / featuresSchema.
  • entities/release.md — pole metadata.environment encji Release i wymóg jego podania.
  • 10-status.md — stan koperty metadanych.
  • architecture/02-ecosystem-philosophy.md — ścisły podział API (Strict API Partitioning) i założenia projektowe pakietu metadanych korporacyjnych (Enterprise Metadata Suite).
  • architecture/13-catalog-and-registry.md §„Lockfile pinning and artifact immutability” + §„Catalog entity name-shape enforcement” — co reguła niezmienności odrzuca w momencie publikacji oraz gdzie sprawdzane są kształty nazw dla poszczególnych rodzajów encji: plugin dyscypliny publikacji zgłasza je doradczo, gdy autor uruchamia aggrega lint, a ani budowanie, ani publikacja ich nie sprawdzają.
  • architecture/11-governance-and-compliance.md §„Inheritance and publishing discipline” — które reguły ładu należą do pluginu dyscypliny publikacji, a które zamiast tego rozstrzyga z założenia dziedziczenie rozszerzającej encji Component.