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

Status języka

Ta strona jest kanonicznym źródłem informacji o tym, które elementy Aggrega są dostępne do użycia już dziś, które są udokumentowane, ale kompilator jeszcze ich nie obsługuje, a które są planowane w przyszłej iteracji. Uzupełnia rozdziały poświęcone poszczególnym obszarom, zbierając w jednym miejscu stan gotowości całego języka.

Z tej strony korzystają dwie grupy czytelników. Autorzy piszący po raz pierwszy sprawdzają ją, zanim zaczną pisać z użyciem nieznanego elementu, aby potwierdzić, że element ten już dziś generuje wyrenderowane wyniki. Osoby szukające informacji referencyjnych sprawdzają ją, gdy używany element zachowuje się w nieoczekiwany sposób — na przykład gdy YAML przechodzi walidację, ale nie powstają żadne wyniki, jest to pierwsze miejsce, w którym należy sprawdzić status danego elementu. Powracający czytelnicy zaglądają tu również, aby ustalić, które elementy zmieniły etykietę statusu od ich ostatniej lektury. Rozdziały poświęcone poszczególnym obszarom i opisy encji wyjaśniają, jak dany element ma działać; ta strona mówi, czy już działa.

Taksonomia statusów

Każdy element języka opisany na tej stronie ma jedną z czterech etykiet statusu:

  • available. Schemat akceptuje dany element; kompilator go przetwarza; zachowanie odpowiada udokumentowanemu kontraktowi. Autorzy korzystający z elementu available otrzymują udokumentowany kontrakt.

  • accepted but inert. Schemat akceptuje dany element — tworzenie z jego użyciem przechodzi walidację — ale kompilator jeszcze na niego nie reaguje. Użycie elementu accepted but inert daje poprawny składniowo build bez żadnego wyrenderowanego efektu dla tego elementu; kompilator może wyemitować ostrzeżenie wskazujące nieaktywny element (zalecany wzorzec), ale niektóre obecne elementy są pomijane po cichu, bez ostrzeżenia. Wpisy w poszczególnych sekcjach poniżej opisują konkretne zachowanie.

  • accepted but blocked. Schemat akceptuje dany element — tworzenie z jego użyciem przechodzi walidację — ale kompilator przerywa build zamiast go wyrenderować. Użycie elementu accepted but blocked kończy się niepowodzeniem podczas renderowania z jawnym błędem, który wskazuje, co należy napisać zamiast tego. Blokada może być trwała, gdy to, co napisano, jest niejednoznacznością, której kompilator nie rozstrzygnie w imieniu autora, ponieważ wybranie jednej interpretacji mogłoby dostarczyć coś, o co nie proszono; może też obowiązywać tylko do czasu udostępnienia zachowania stojącego za danym elementem. W obu przypadkach etykieta obiecuje to samo: schemat go przyjmuje, build go odrzuca, a błąd informuje, jak to naprawić.

  • planned. Element jest udokumentowany zgodnie z projektem, ale ani schemat, ani kompilator jeszcze go nie akceptują. Użycie elementu planned kończy się niepowodzeniem na etapie walidacji schematu. Strona przedstawia planowane elementy, aby autorzy mogli z góry uwzględnić ich brak, zamiast odkrywać lukę w czasie budowania.

Etykiety statusu są określane względem bieżącej wersji kompilatora. Elementy w trakcie aktywnego rozwoju mogą zmieniać etykiety; wpisy w poszczególnych sekcjach opisują plan zmiany, jeśli jest znany.

Rodzaje wejść encji Recipe

Encja Recipe składa swoje wyjście z trzech rodzajów wejść — pozyskanych (sourced), syntetyzowanych (synthesized) i artefaktów (artifacts) — opisanych w 16-recipe-input-composition.md. Status poszczególnych rodzajów wejść:

  • source: + valuesMapping: (sourced) — dostępne. Kompilator rozwiązuje URI source:, ewaluuje szablon valuesMapping (inline, plikowy $import: lub biblioteczny $import:) i przekazuje wynik docelowemu providerowi do renderowania. Obsługiwane przez providery helm, helm-chart, compose, terraform i cloudformation.

  • workload: (synthesized) — dostępne. Encja Recipe deklaruje workload: inline (skalar blokowy zawierający YAML encji Workload) albo przez $import: (ścieżka pliku). Kompilator parsuje szablonową encję Workload, waliduje ją względem wbudowanego schematu Workload i przekazuje ją do syntezatora workloadów docelowego providera. Obsługiwane przez providery helm i compose. Provider helm-chart jawnie odsyła autorów do providera helm w przypadku syntetyzowanych manifestów K8s. Encja Recipe deklarująca workload: dla providera, który nie implementuje syntezy workloadów, zatrzymuje się przy renderowaniu z błędem CATALOG_ERROR.

  • artifacts: (artefakty) — dostępne. Pole jest mapą nazwanych wpisów; każdy wpis jest tworzony inline lub ładowany przez $import: dla danego wpisu. Wpisy są obliczane po sparsowaniu encji Workload i rozwiązaniu źródła, więc dostępny jest dla nich pełny kontekst szablonu — łącznie z .workload i .source; otrzymują informacje o pochodzeniu scalone z metadata.labels i metadata.annotations w dokumentach, które zawierają metadane (klucze niebezpieczne ze względu na zestaw znaków — recipe-uri, boundary-path, sync-wave — jako adnotacje, czyli ten sam podział, który stosują providery helm), i są emitowane jako osobne pliki obok wyniku encji Recipe renderowanego ze źródła lub syntetyzowanego z encji Workload. Provider — rozdział według providera: płaski provider helm emituje samodzielne pliki w katalogu nazwanym od komponentu, który je zadeklarował, wewnątrz katalogu wyjściowego granicy, ponieważ klucz określa nazwę pliku i nic nie mówi o tym, który komponent go zapisał; provider compose kieruje swoje emisje przez scalanie na końcu encji Release; provider helm-chart oblicza każdy wpis z ogranicznikami Aggrega [[ ]], aby składnia {{ }} Helma w tym samym pliku przetrwała do dalszego renderowania, a następnie umieszcza każdy wpis zgodnie z formą, w jakiej został utworzony — wpis ładowany przez $import: w boundaries/<bp>/charts/<nodeID>/templates/<authored-key> (pliki pakietu zagnieżdżone pod tym kluczem), obok własnych szablonów źródłowego chartu, a wpis z treścią inline w boundaries/<bp>/charts/<nodeID>/<authored-key>, czyli w katalogu głównym chartu, gdzie własne szablony chartu odczytują go przez .Files.Get / .Files.Glob; provider terraform zapisuje każdy wpis dosłownie we własnym katalogu komponentu w drzewie modules/ granicy; provider cloudformation scala każdy wpis, będący fragmentem stosu, z pojedynczym stosem składanym dla tego katalogu wyjściowego. Kolizje nazw plików między pochodzeniami rodzajów wejścia (wynik renderowany ze źródła, syntetyzowany z encji Workload lub emitowany jako artefakt) są wychwytywane w czasie renderowania przez detektor kolizji między pochodzeniami i powodują CATALOG_ERROR wskazujący wszystkich współtwórców.

Zobacz entities/recipe.md, aby poznać powierzchnię tworzenia encji Recipe i reguły składania rodzajów wejść; errors/fatal-halts.md, aby poznać reguły kształtu encji Recipe; oraz sekcję Providers poniżej, aby zobaczyć macierz dla poszczególnych providerów.

Języki mapowania

Recipes (oraz FeatureRecipes) wiążą się z jednym polem mapowania, które przekłada kontekst Aggrega na słownik wartości używany przez bazowy provider. Pole valuesMapping: obsługuje trzy tryby tworzenia, wybierane na podstawie kształtu zawartości:

  • valuesMapping: — tryby 1–3 dostępne. Tryb 1: szablon Go podany inline (skalar blokowy). Tryb 2: plikowy $import: (mapa zawierająca wyłącznie $import: ze ścieżką do pliku lokalnego). Tryb 3: biblioteczny $import: (mapa zawierająca wyłącznie $import: z odwołaniem do tożsamości przez samą nazwę, wskazującym wpis encji MappingLibrary, <Library>#/mappings/<entry>, opcjonalnie z dolnym ograniczeniem wersji :<version>). Kompilator wybiera tryb na podstawie kształtu zawartości — skalar blokowy oznacza tryb 1, $import: ze ścieżką do pliku tryb 2, a $import: z odwołaniem do biblioteki przez samą nazwę tryb 3. Wszystkie trzy tryby wyliczają rozwiązany szablon Go względem kontekstu szablonu encji Recipe podczas mapowania wartości (biblioteka pomocnicza Sprig jest wstępnie zarejestrowana); tryb 3 rozwiązuje wpis względem lokalnego katalogu oraz bibliotek przypiętych w pliku blokady, a odwołanie zawierające hosta jest odrzucane. Mechanizm wyboru trybu i przykłady opisano w entities/recipe.md, w części „The valuesMapping field — three authoring modes”.

Powierzchnię tworzenia encji Recipe i projekt języka mapowania opisano w entities/recipe.md, a encję biblioteki, na której opiera się tryb 3, w entities/mappinglibrary.md.

Składnia inject

Blok inject: ma jedną składnię w każdym miejscu — we własnym inject komponentu, w połączeniu uses i w dołączeniu.

  • Lista wpisów dla każdego mechanizmu ([{in: ..., from: ...}], [{in: ..., value: ...}]) — dostępne. Każdy mechanizm dostarczania jest listą; każdy wpis podaje swój lokalny identyfikator (nazwę zmiennej środowiskowej, ścieżkę pliku, flagę argumentu) przez in: i zawiera dokładnie jedno z dwóch: from: (odwołanie do klucza provides) lub value: (ciąg literalny). Mechanizm zapisany jako mapa zamiast listy albo wpis zawierający oba słowa kluczowe zatrzymuje kompilację na kopercie dokumentu encji Aggregate, wskazując ścieżkę.

  • value: tylko we własnym inject komponentu. Literał należy do własnego inject komponentu, który go dostarcza. W połączeniu uses wartość value: zatrzymuje kompilację, jak opisuje An inject: entry on a connection carries a literal (Wpis w połączeniu zawiera literał), a we własnym inject dołączenia również zatrzymuje kompilację, jak opisuje An inject: entry on an attached Feature carries a literal (Wpis w dołączonej encji Feature zawiera literał): oba dostarczają tylko klucze publikowane przez inną encję, wskazane za pomocą from:.

Pełną specyfikację Injection Contract, w tym semantykę kontekstu o dwóch stanach, reguły kolizji kluczy i przykłady, zawiera vocabulary/topology-triad.md.

Silnik szablonów

Silnik szablonów Go w Aggrega ewaluuje szablony Recipe i FeatureRecipe względem kontekstu szablonu w fazie właściwej dla danego miejsca, opisanej w macierzy rozwijania szablonów. Biblioteka pomocnicza Sprig jest wstępnie rejestrowana obok własnych funkcji pomocniczych Aggrega na każdej powierzchni ewaluowanej przez renderer, z jednym wyjątkiem: rozwiązywanie ustrukturyzowanej współrzędnej source: rejestruje wyłącznie funkcje pomocnicze Aggrega — dostępne są tam optional i capitalizedWords, a funkcje Sprig nie, więc wywołanie Sprig w polu source: lub we wpisie locals: w encji zawierającej ustrukturyzowane source: zatrzymuje kompilację na etapie parsowania. Zob. errors/fatal-halts.md, gdzie ta powierzchnia ma własną sekcję. Ewaluacja, parsowanie i integracja ze Sprig są już dostępne.

Zachowanie przy brakującym kluczu — tolerowane w szablonach wartości; ścisłe missingkey=error w szablonach ścieżek, w asercjach i we współrzędnej source:. Szablony wartości są ewaluowane z opcją Go missingkey=zero, więc szablon odwołujący się do niepowiązanego klucza (np. .values.unset_field) nie zgłasza błędu, a odczyt renderuje się jako pusty. Idiomy katalogów, takie jak {{ .values.optional_field | default "fallback" }}, nadal działają w tej polityce, ponieważ nieustawiona wartość jest dla default traktowana jako pusta. Szablony ścieżek (directory: / subDirectory: na granicach Release) są ewaluowane z missingkey=error względem zamkniętej listy dozwolonych kluczy — ciche błędy ścieżek tworzą uszkodzone układy systemu plików, które operatorzy odkrywają dopiero po kompilacji, a ścisłość wychwytuje błąd wcześniej. Dwie kolejne powierzchnie stosują tę samą ścisłą politykę, z tego samego powodu: pusty wynik renderowania dałby tam błędny werdykt lub błędne przypięcie zamiast pola, które autor może odczytać. Są to wpis assertions: w encji Component, Feature, Recipe lub FeatureRecipe oraz pola szablonowe ustrukturyzowanego bloku source: w encji Recipe lub FeatureRecipe. errors/fatal-halts.md omawia politykę każdej powierzchni po kolei i podaje formy uwzględniające obecność klucza, które działają w polityce ścisłej.

Wartość zastępcza uwzględniająca obecność klucza za pomocą optional. Gdy autor encji Recipe musi odróżnić „klucz nieobecny” od „klucz obecny z wartością zerową / pustą / false” — rozróżnienia, którego default ze Sprig nie potrafi dokonać — renderer udostępnia funkcję pomocniczą optional: {{ optional .infra "replicas" 1 }} zwraca podane przez autora infra.replicas (w tym podane 0), gdy jest obecne, a wraca do 1 tylko wtedy, gdy klucza brak. Pełną semantykę opisano w templates/sprig-functions.md.

Składanie nazw za pomocą capitalizedWords. Gdy cel akceptuje w nazwach, którymi adresuje zasoby, wyłącznie litery i cyfry, {{ capitalizedWords .context.instance_id }} odczytuje identyfikator jako słowa rozdzielone dowolnymi znakami spoza tego alfabetu i zamienia pierwszą literę każdego słowa na wielką, więc payments-db daje PaymentsDb. Składanie usuwa wszystkie separatory, więc dwa identyfikatory różniące się tylko interpunkcją dają tę samą nazwę; kompilacja, która wyemitowałaby dwa zasoby pod jedną nazwą, zostaje zatrzymana i wskazuje oba identyfikatory. Pełną semantykę opisano w templates/sprig-functions.md.

Egzekwowanie kontraktu parametrów w warstwie deklaracji. Wymagane parametry, których encja Release nie dostarcza, powodują jawne błędy w warstwie kontraktu parametrów — pierwszej rzeczy sprawdzanej przez rozwiązywanie — z informacją o pochodzeniu file:line wskazującą parametr i kontrakt. Naruszenia typów / ograniczeń są zgłaszane w ten sam sposób. Na tym polega właściwe egzekwowanie brakujących kluczy: typy są sprawdzane tam, gdzie wyrażona jest intencja programisty (deklaracja parameters: w encji Aggregate), a nie później, w czasie ewaluacji szablonów. Zob. entities/aggregate.md §„Typed parameter contracts”.

Jedna gramatyka deklaracji dla parameters: w encji Aggregate. Każde miejsce parametru zapisuje się jako obiekt kontraktu typowanego (key: { type: <type>, default: <value>, ... }). Skrócona forma z samym skalarem (key: <value>) jest odrzucana na kopercie dokumentu encji Aggregate z błędem, który wskazuje parametr i informuje, że oczekiwano obiektu. Słownictwo kontraktu typowanego czyni semantykę type:, required: i ograniczeń jawną w warstwie deklaracji; wypełnianie w encji Release nadal używa wartości skalarnych zgodnie z typem zadeklarowanym w kontrakcie.

Macierz ewaluacji dla poszczególnych miejsc szablonów opisano w templates/expansion-matrix.md, a przegląd szablonów w 05-templates.md.

Fazy potoku kompilacji

Potok kompilacji Aggrega jest opisany w ../architecture/10-compilation-pipeline.md. Status poszczególnych faz:

  • Rozwiązywanie, budowa topologii, finalizacja grafu, analiza statyczna i renderowanie — dostępne.
  • Mapowanie wstrzyknięć (przechwytywanie injectMapping przed renderowaniem) i każdy podetap renderowania bazowego — publikacja wartości lokalnych, mapowanie wartości, synteza workloadów, ewaluacja artefaktów, renderowanie przez providera, renderowanie funkcji oraz generowanie zasobów przez encję FeatureRecipe dla poświadczeń — dostępne.
  • Potok pluginów (wykonywanie Wasm w pipeline:) — dostępny. W encji Recipe lub FeatureRecipe deklarującej niepuste kroki pipeline: każdy krok jest wykonywany w zadeklarowanej kolejności: kompilator wywołuje wskazany w kroku plugin Wasm na wyrenderowanym wyjściu, stosuje zwrócone operacje JSON Patch do wskazanych dokumentów i emituje efekty uboczne kroku. Krok, którego warunek when: renderuje się jako fałszywy, jest pomijany jako przejście bez zmian i pozostawia zbiór dokumentów nienaruszony. Autorzy, którzy potrzebują mutacji w stylu JSONPatch (wstrzykiwanie sidecara Envoy, VolumeMount dla sekretu itp.), realizują je za pomocą tego mechanizmu.

Providers

Biblioteka standardowa Aggrega zawiera pięciu dostawców renderowania — helm, helm-chart, compose, terraform i cloudformation. Status poszczególnych dostawców:

  • helm — dostępny. Dostępne są zarówno tryb źródłowy (renderowanie chartów Helm za pomocą Helm SDK), jak i tryb syntetyzowany (Workload → obiekt kontrolera wybierany przez pole form encji Workload — Deployment, StatefulSet, DaemonSet, Job lub CronJob — oraz Services i PVC).
  • helm-chart — dostępny. Dostępny jest tryb źródłowy (kompozycja umbrella chart). Syntetyzowany rodzaj wejścia nie dotyczy tego dostawcy; autorzy potrzebujący syntezy manifestów K8s używają dostawcy helm z workload:.
  • compose — dostępny. Dostępne są zarówno tryb źródłowy (nakładka fragmentów compose), jak i tryb syntetyzowany (Workload → usługa compose + wolumeny + sieci). Wynikowy plik docker-compose.yaml dla każdej granicy jest składany przez kompozytor na poziomie encji Release.
  • terraform — dostępny. Dostępne są zarówno tryb źródłowy, jak i artefakty; każda granica otrzymuje jedną konfigurację główną, aggrega.modules.tf, deklarującą każdy komponent jako blok module, którego pliki znajdują się we własnym katalogu komponentu w modules/. Syntetyzowany rodzaj danych wejściowych nie ma zastosowania do tego dostawcy.
  • cloudformation — dostępny. Dostępne są zarówno tryb źródłowy, jak i artefakty (fragmenty stosu); wszystkie komponenty renderowane do jednego katalogu wyjściowego są składane w jeden szablon stosu, emitowany jako czysty JSON. Syntetyzowany rodzaj danych wejściowych nie ma zastosowania do tego dostawcy.

Renderowanie typu Provider jest obsługiwane przez encję Plugin z pluginType: provider; opis tworzenia encji Plugin renderującej providery znajduje się w entities/plugin.md, a strony referencyjne poszczególnych providerów w 06-providers.md.

Rozwijanie sterowane adnotacjami

Encje Manifests zawierają sekcję powiązań features.annotations:, która mapuje klucze adnotacji na typy Feature, oraz tabelę routingu pogrupowaną według filarów (maps.infra / maps.values), wskazującą, które właściwości schematu Feature może wypełniać każde powiązanie. Opisano to w entities/manifest.md i providers/well-known-annotations.md; miejsce w potoku — w ../architecture/10-compilation-pipeline.md; mechanizmy ładowania katalogu i etapu inspekcji — w ../architecture/13-catalog-and-registry.md §“Annotation-driven Feature expansion”.

  • Powiązania features.annotations w encji Manifest — dostępne. Podetap rozwijania adnotacji w ramach rozwiązywania jest dostępny w pełnym zakresie. Przechodzi on przez granice encji Release (od zewnętrznych do wewnętrznych) i podsystemy encji Aggregate (od zewnętrznych do wewnętrznych), wyznacza efektywny zestaw adnotacji dla każdego komponentu przez kaskadę i nadpisywanie z możliwością rezygnacji przez null dla całej wartości i dla poszczególnych podkluczy, parsuje każdą wartość adnotacji jako skalar, ustrukturyzowaną mapę lub jawne null, kieruje każdy podklucz przez deklarację maps powiązania z egzekwowaniem zgodności strony i filaru (strona Aggregate uruchamia maps.values; strona Release uruchamia maps.infra), waliduje typy poszczególnych liści względem spec.schema docelowej encji Feature i wstrzykuje syntetyczne dołączenia Feature, które graf IR oznacza jako origin: annotation. Kompozycja międzystronna scala wartości per filar i per pole podczas budowania IR, przy czym jawna wartość wygrywa dla danego pola; aggrega inspect wyświetla nawiasy pochodzenia dla każdego liścia. Ścieżkę zabezpieczają walidacja celów powiązań podczas ładowania katalogu, lint nakładania się filarów schematu oraz lint nakładania się map powiązań. Sam prefiks aggrega.ai/ jest odrzucany podczas ładowania encji Manifest, gdy zostanie użyty jako klucz powiązania — ten prefiks jest zarezerwowany dla adnotacji natywnych platformy; powiązania używają feature.aggrega.ai/ lub własnej domeny.

Dopasowywanie wersji

Encje Recipes i FeatureRecipes deklarują interfejs encji Component lub Feature, który implementują, za pomocą słowa kluczowego implements:. implements: nigdy nie wybiera encji Recipe: robi to mapowanie encji Manifest, a instancja, której typu nie obejmuje żadne mapowanie, zatrzymuje kompilację z błędem, który jako kandydatów wymienia encje Recipes, których implements: może implementować ten typ. To, czym steruje implements:, to sprawdzenie, czy encja Recipe każdego wpisu mapowania w encji Manifest implementuje mapowany typ lub typ bazowy, który ten typ rozszerza przez extends. Mapowany typ to klucz wpisu, a w przypadku klucza components.type także typ każdej instancji komponentu, do której klucz dociera w wersji, której klucz nie wskazuje — każdej instancji, do której dociera, w przypadku klucza zapisanego bez wersji — w wersji, w jakiej kompilacja kompiluje tę instancję: w wersji wskazanej przez instancję lub, dla instancji niewskazującej żadnej, w najwyższej wersji tej encji Component, jaką zawiera katalog. Status poszczególnych form:

  • Dokładna (core/api-server:1.0.0) — dostępna. Mapowany typ musi mieć dokładnie tę wersję.
  • Zakres zgodny co do wersji głównej (core/api-server:^1.0.0) — dostępny. Forma z daszkiem jest ograniczeniem SemVer (w przykładzie >=1.0.0, <2.0.0); wersja mapowanego typu musi je spełniać.
  • Bez wersji (core/api-server) — dostępna. Spełnia ją dowolna wersja typu.

Wpis mapowania, którego implements: encji Recipe nie pasuje ani do mapowanego typu, ani do żadnego z jego typów bazowych, zatrzymuje kompilację z OPS_ERROR, wskazując wpis, encję Recipe i jej wartość implements:. Instancja komponentu, do której klucz dociera w innej wersji i której wersji nie spełnia implements: encji Recipe, zatrzymuje kompilację z tym samym OPS_ERROR, wskazując instancję, jej typ — a dla instancji niewskazującej wersji także wersję, w jakiej została skompilowana — klucz, encję Recipe i jej wartość implements:. Forma z daszkiem jest kanonicznym sposobem zapisu dopasowania zgodnego co do wersji głównej.

Projekt implements: opisano w vocabulary/inheritance-and-interface.md, a kształt warstwy mapowań dla każdej encji Manifest w entities/manifest.md.

Koperta metadanych

Koperty encji katalogu zawierają metadata.labels, metadata.annotations oraz (w encji Release) metadata.environment. Status poszczególnych elementów:

Dostępność metadata.labels i metadata.annotations — w siedmiu rodzajach. Koperty encji, które zawierają te pola, to Component (etykiety wymagane, z wymaganym kluczem component.aggrega.ai/type, adnotacje opcjonalne), Feature (oba opcjonalne), cztery rodzaje bibliotek SchemaLibrary, MappingLibrary, WorkloadLibrary i ArtifactLibrary (oba opcjonalne) oraz Aggregate (tylko etykiety, opcjonalne). Pozostałe encje — Recipe, FeatureRecipe, Manifest, Release, Plugin — nie akceptują metadata.labels ani metadata.annotations na poziomie koperty.

metadata.environment w encji Release — wymagane. Schemat encji Release wymienia environment jako wymagane pole metadata; kompilacja umieszcza jego wartość w wyrenderowanych danych wyjściowych jako etykietę aggrega.ai/environment. Pięć praktycznych zastosowań opisanych w sekcji Environment Metadata (przypisywanie kosztów OTel/FinOps, filtrowanie śladów i logów OTel, kierowanie operatorów Kubernetes, rozróżnianie produkcji w wielu regionach, określanie zakresu zgodności) przedstawiono w entities/release.md.

Zasady wielkości liter w nazwach pól, które dotyczą kluczy metadata, opisano w 02-naming-conventions.md, a kształty kopert akceptowane obecnie przez każdą encję — na stronach referencyjnych poszczególnych encji.

Polecenia CLI

CLI Aggrega rejestruje potok budowania oraz introspekcję. Status poszczególnych poleceń:

  • aggrega build — dostępne. Odczytuje plik encji Release, rozwiązuje encje Aggregate + Manifest, uruchamia potok kompilacji i zapisuje wyrenderowane artefakty do katalogów wyjściowych granic. Gdy istnieje plik blokady, weryfikuje względem niego zależności; gdy go brak, zatrzymuje się z prośbą o wykonanie pull albo najpierw go wypełnia, jeśli żąda tego --auto-pull lub auto_pull.
  • aggrega inspect — dostępne. Sprawdza encję katalogu, plik encji, encję opublikowaną w rejestrze lub encję Release i raportuje jej rozwiązany kształt. Zob. cli/aggrega-inspect.md.
  • aggrega pull — dostępne. Rozwiązuje wszystkie zależności encji Release i zapisuje plik blokady dla danej encji Release, przypinający każdą encję katalogu i artefakt źródłowy do wersji i skrótu treści, a każde zewnętrzne wejście, którego żąda renderowanie encji Release, do skrótu treści; buforuje pobraną treść w .aggrega/cache. --verify sprawdza istniejący plik blokady względem bieżącego stanu. Zob. cli/aggrega-pull.md.
  • aggrega push — dostępne. Publikuje encję katalogu w rejestrze OCI; aggrega push --list-kinds raportuje, które rodzaje przyjmuje. Zob. cli/aggrega-push.md.
  • aggrega lint — dostępne. Uruchamia reguły dyscypliny publikowania z poziomem ważności warn dla całego katalogu, domknięcia zależności encji Release lub jednej encji; dla jednej encji --pre-publish dodaje kontrolę podbicia wersji względem aktualnie opublikowanej wersji encji, a niezgodność zatrzymuje działanie. Reguły są dostarczane jako opcjonalny plugin Wasm. Zob. cli/aggrega-lint.md.
  • aggrega serve — dostępne. Długo działający demon kompilatora jako usługi, komunikujący się przez JSON-RPC 2.0 po stdin/stdout, przeznaczony do integracji z edytorami i IDE. Zob. cli/aggrega-serve.md, gdzie opisano obsługiwane metody.
  • aggrega version — dostępne. Wypisuje wersję CLI; -o json emituje obiekt wersji czytelny maszynowo.
  • aggrega validate — dostępne. Sprawdza poprawność całego katalogu, encji Release lub pojedynczej encji, raportując diagnostykę bez renderowania artefaktów.
  • aggrega search — dostępne. Przeszukuje lokalny indeks skonfigurowanych rejestrów w poszukiwaniu opublikowanych encji; indeks jest budowany i odświeżany przez aggrega registry update.
  • aggrega registry — dostępne. Zarządza rejestrami i ich polityką zaufania do podpisów; registry add rejestruje rejestr, a registry update buduje lokalny indeks, który przeszukuje aggrega search.
  • aggrega push-artifact — dostępne. Publikuje samodzielny artefakt danych (np. pakiet dokumentacji) w rejestrze OCI, obok publikującego encje polecenia push.
  • aggrega sign — dostępne. Podpisuje jeden lub więcej już opublikowanych artefaktów i dołącza ich podpisy.
  • aggrega deprecate — dostępne. Dołącza podpisany znacznik wycofania do już opublikowanego artefaktu.
  • aggrega login i aggrega logout — dostępne. Uwierzytelniają w rejestrze OCI i zapisują poświadczenie albo usuwają zapisane poświadczenie.
  • aggrega auth — dostępne. Zarządza lokalną tożsamością używaną do podpisywania artefaktów.
  • aggrega config — dostępne. Sprawdza konfigurację obszaru roboczego i nią zarządza; podpolecenia pokazują efektywną scaloną konfigurację i pochodzenie każdego ustawienia, tworzą konfigurację roboczą z rejestrem i jego polityką zaufania do podpisów oraz zamrażają efektywną konfigurację krytyczną dla budowania w obszarze roboczym, tak aby budował się identycznie bez polegania na globalnej konfiguracji maszyny.
  • aggrega get-schema — dostępne. Wypisuje JSON Schema dla rodzaju encji lub kontraktu.
  • aggrega plugin — dostępne. Sprawdza pluginy Wasm, które CLI potrafi rozwiązać; podpolecenia wyświetlają ich listę, dodają i usuwają skonfigurowane pluginy, synchronizują rekordy pluginu zarządzane maszynowo i generują ich widok katalogowy.
  • aggrega cache — dostępne. Sprawdza i utrzymuje pamięci podręczne na dysku; podpolecenia raportują status, przycinają, usuwają wpisy i czyszczą.
  • aggrega mcp — dostępne. Uruchamia serwer Model Context Protocol przez stdio lub przez HTTPS dla klienta na innej maszynie, udostępniając introspekcję kompilatora integracjom z asystentami AI.
  • aggrega completion — dostępne. Generuje skrypt autouzupełniania powłoki dla CLI.
  • Podpolecenia rozszerzeń CLI — dostępne. Plugin Wasm opublikowany jako gość pluginType: cli jest rozwiązywany i rejestrowany jako podpolecenie aggrega, dzięki czemu zainstalowane rozszerzenie działa jako aggrega <extension> obok poleceń wbudowanych.
  • aggrega import — dostępne. Przekształca obce deklaratywne źródło definicji agentów (Langflow, Flowise, n8n) w robocze pliki autorskie encji Aggregate i Component, z deterministyczną, ocenianą pod kątem pewności decyzją o ponownym użyciu katalogu zapisaną dla każdego węzła. Mapowanie specyficzne dla formatu dostarcza plugin importera, który obszar roboczy rozwiązuje dla formatu źródła — taki, który zawiera jego katalog, lub jeden z importerów Langflow, Flowise i n8n kompilatora, budowanych i publikowanych z każdym wydaniem kompilatora. Plik binarny zawiera ich encje Plugin, ale nie ich moduły, więc obsługują swoje formaty w każdym obszarze roboczym: pierwszy import, który potrzebuje modułu nieobecnego na maszynie, pobiera go z domyślnego rejestru obszaru roboczego, weryfikuje i przechowuje w pamięci podręcznej treści dla wszystkich kolejnych importów. Źródło jest parsowane parserem, który katalog obszaru roboczego udostępnia dla jego składni, lub — gdy katalog żadnego nie udostępnia — parserem wbudowanym w kompilator, więc obszar roboczy, którego katalog nie zawiera parsera, importuje przez jeden z nich.
  • aggrega scaffold — dostępne. Tworzy szkic dokumentu startowego dla dowolnego rodzaju encji na podstawie schematu tego rodzaju — z każdym wymaganym polem i symbolem zastępczym tam, gdzie potrzebna jest wartość — i zapisuje go na standardowe wyjście; z opcją --example zapisuje w nowym katalogu jeden z uruchamialnych przykładów z dokumentacji, odczytany z podpisanego pakietu dokumentacji.
  • aggrega explain — dostępne. Wyjaśnia warunek zatrzymania wskazywany przez krótki kod (np. E0007) lub kod opisowy.
  • aggrega edit-document — dostępne. Stosuje do dokumentu jedną ograniczoną, ustrukturyzowaną edycję — dodanie komponentu, dołączenie encji Feature, podłączenie połączenia lub ustawienie jednej wartości — zachowując każdy bajt, którego nie dotyka.
  • aggrega pin — dostępne. Zapisuje w pliku entity.lock obok encji Recipe lub FeatureRecipe przypięcie treści dla każdego wejścia, które encja odczytuje spoza własnego dokumentu.
  • aggrega skills — dostępne. Instaluje umiejętność Aggrega w asystencie AI.

Zob. 07-cli.md, gdzie znajduje się przegląd CLI, oraz indeks dokumentacji języka, gdzie znajdują się strony referencyjne wszystkich poleceń.

Edytory i inne frontendy

Każdy frontend pokazuje to, co skompilował plik binarny aggrega; żaden nie ma własnego kompilatora. Status poszczególnych powierzchni:

  • Kontrakt grafu IR — dostępny. Schemat grafu IR, czyli kontrakt, według którego każdy frontend odczytuje graf, jest dostarczany jako część dystrybucji schematów Aggrega; zob. dokumentację referencyjną schematu IR.
  • Odczyt grafu z polecenia — dostępny. aggrega build przyjmuje --ir-graph, podobnie jak aggrega inspect wywołane dla encji Release oraz aggrega validate --release; flaga ta, oprócz tego, co polecenie już generuje, zapisuje na stdout w formacie JSON graf rozwiązany w danym uruchomieniu. Sesja demona odczytuje ten sam graf przez aggrega/irGraph, a narzędzia cli-inspect, cli-build i cli-validate serwera MCP przyjmują ją jako swój argument ir_graph.
  • Graf topologii w Visual Studio Code — dostępny. Rozszerzenie Aggrega dla Visual Studio Code rysuje graf IR wybranej encji Release jako interaktywny graf i dołącza z niego Features, o jedno i drugie prosząc demona aggrega serve.
  • Bezgłowy tryb strumieniowy CLI — planowany. Tryb bezgłowy emituje graf IR jako JSON rozdzielany znakami nowej linii na stdout, aby frontend mógł go odczytywać w miarę zmian topologii. Obecnie dostarczany jest jeden dokument na wywołanie, a nie strumień: żadne polecenie nie emituje sekwencji grafów na jednym stdout w miarę zmian topologii.

Zob. ../architecture/15-editors-assistants-and-frontends.md, aby dowiedzieć się, jak edytor, asystent i demon docierają do kompilatora.

Kierunki projektowe

Powyższa taksonomia statusów klasyfikuje stan poszczególnych powierzchni w całym języku; ta sekcja odnotowuje status szerszych kierunków projektowych opisanych w rozdziałach o architekturze.

Zgodność w skali całego środowiska nie jest planowanym kierunkiem: jednorazowe sformułowanie reguły ładu tak, aby obowiązywała każdą kompilację w przestrzeni roboczej, jest już dziś dostępne dzięki gniazdu ładu. Wtyczka podłączona pod kluczem plugins.governance konfiguracji przestrzeni roboczej ocenia każdą kompilację w tej przestrzeni — rola werdyktu odrzuca graf lub wyrenderowany artefakt naruszający regułę, a rola transformacji dostarcza pochodne metadane, których programista nigdy nie wpisuje. Zob. ../architecture/11-governance-and-compliance.md.

  • Parzystość interfejsów i automatyczna implementacja — dostępne. Encja Recipe napisana dla bazowej encji Component obsługuje każdą encję Component, która ją rozszerza, na dowolnej głębokości łańcucha, a architekt nie musi tworzyć zduplikowanej encji Recipe. Rozszerzająca encja Component zapisuje schema: inherited, więc nie dodaje do values / infra / provides żadnego klucza głównego, którego encja Recipe bazy nie mogłaby przetworzyć; encja Component deklarująca extends z własnym schematem jest odrzucana na kopercie swojego dokumentu. Encja Manifest nadal mapuje rozszerzający typ własnym wpisem, a sprawdzenie mapowania akceptuje go, gdy implements mapowanej encji Recipe wskazuje ten typ lub dowolny typ bazowy, który on rozszerza. Opisano w ../architecture/02-ecosystem-philosophy.md.
  • Ghost Infrastructure Tracker — dostępny. Zabezpieczenie na etapie renderowania emituje ostrzeżenie, gdy klucz zadeklarowany przez autora dociera do węzła, a żaden szablon zadeklarowany przez powiązaną encję Recipe go nie odczytuje, dzięki czemu wartość zadeklarowana przez autora i po cichu pominięta przez szablon zostaje wskazana, a nie utracona. Jest to część tego samego projektu dopasowywania kształtów, która działa na etapie renderowania. Zob. errors/warnings.md.

Rozdziały o architekturze opisują powierzchnie projektowe; ta strona śledzi status implementacji.