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).
| Pole | Typ | Przeznaczenie | Odbiorca |
|---|---|---|---|
description | string | Czytelne dla człowieka podsumowanie encji | Karty podpowiedzi w edytorze (aggrega serve); narzędzie describe wywoływane przez asystenta (aggrega mcp); przeszukiwalna adnotacja w opublikowanym artefakcie (aggrega push); aggrega inspect |
maintainers | tablica obiektów | Właściciel encji (nazwa, e-mail, URL) | Blok catalog_metadata węzła w IR, w węzłach Component |
license | string | Zgodność prawna (zwykle identyfikator SPDX) | Blok catalog_metadata węzła w IR, w węzłach Component |
repository | string (URL) | Repozytorium Git ze źródłami | Blok catalog_metadata węzła w IR, w węzłach Component — nic innego go nie odczytuje |
home | string (URL) | URL dokumentacji / wiki | Blok catalog_metadata węzła w IR, w węzłach Component — nic innego go nie odczytuje |
keywords | tablica stringów | Tagi wyszukiwania | Blok 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ć:
descriptionto jedyne pole z więcej niż jednym odbiorcą.aggrega serveumieszcza 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ędziedescribeudostępniane przezaggrega mcpzwraca je dla encji dowolnego rodzaju.aggrega pushzapisuje je w opublikowanym artefakcie jako przeszukiwalną adnotację.aggrega inspectwypisuje je pod nagłówkiem encji dla każdego rodzaju i nie wypisuje żadnego innego pola powierzchni publikacji.repository,homeikeywordssą 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.
| Typ | Gdzie się znajduje | Autor | Przeznaczenie |
|---|---|---|---|
| Opis koperty | metadata.description w każdej encji | Wydawca katalogu | Podsumowanie encji jako całości, wyświetlane w kartach podpowiedzi edytora i umieszczane w opublikowanym artefakcie |
| Opis instancji | Pole description obok deklaracji instancji (np. featuresSchema.<slot>.description, usesSchema.<socket>.description) | Autor schematu | Opis slotu / gniazda / portu dla autorów encji konsumujących, którzy czytają deklarację |
| Opis pola | Adnotacja description: z JSON Schema 2020-12 wewnątrz treści schema: / featuresSchema: / usesSchema: (w formie zwartej lub w pełnym YAML JSON Schema) | Autor schematu | Dokumentacja 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.descriptionraz dla samej encji Component. - Ustawiają
featuresSchema.admin_password.descriptionraz dla każdego slotu poświadczeń deklarowanego przez encję Component. - Ustawiają adnotacje
description:dla poszczególnych pól wewnątrz blokuschema:— 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.schemai jest obcinany do pierwszych wierszy, więc opis położony głębiej w bloku — lub znajdujący się wewnątrzfeaturesSchema:albousesSchema:— się w nim nie pojawia. - Opis instancji — deklarowany i przenoszony razem z encją; żadna dostarczana powierzchnia nie renderuje go samodzielnie.
aggrega inspectwyś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):
| Encja | Dodatkowe pola wymagane | Uzasadnienie |
|---|---|---|
| Component | metadata.labels.component.aggrega.ai/type | Wymó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ę |
| Recipe | spec.capability, spec.implements | Capability warunkuje przekazanie do providera; implements warunkuje powiązanie z encją Component |
| FeatureRecipe | spec.capability, spec.implements | Tak jak dla encji Recipe |
| Plugin | metadata.pluginType, spec.abiVersion | Typ 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 |
| Manifest | spec.mappings | Warstwy mapowań są jedynym celem encji Manifest |
| Release | spec.aggregate, spec.manifest (encja Release deklarująca extends nie zapisuje aggregate i może pominąć manifest); metadata.environment | Pierwsze 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ógmetadata.labels.component.aggrega.ai/typew encji Component oraz deklaracjeschema/usesSchema/featuresSchema.entities/release.md— polemetadata.environmentencji 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 uruchamiaaggrega 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.