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
availableotrzymują 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 inertdaje 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 blockedkoń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
plannedkoń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 URIsource:, ewaluuje szablonvaluesMapping(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 deklarujeworkload: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ącaworkload:dla providera, który nie implementuje syntezy workloadów, zatrzymuje się przy renderowaniu z błędemCATALOG_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.workloadi.source; otrzymują informacje o pochodzeniu scalone zmetadata.labelsimetadata.annotationsw 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:wboundaries/<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 wboundaries/<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 drzewiemodules/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 wentities/recipe.md, w części „ThevaluesMappingfield — 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) przezin:i zawiera dokładnie jedno z dwóch:from:(odwołanie do klucza provides) lubvalue:(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łasnyminjectkomponentu. Literał należy do własnegoinjectkomponentu, który go dostarcza. W połączeniuuseswartośćvalue:zatrzymuje kompilację, jak opisuje Aninject:entry on a connection carries a literal (Wpis w połączeniu zawiera literał), a we własnyminjectdołączenia również zatrzymuje kompilację, jak opisuje Aninject: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
injectMappingprzed 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 krokipipeline: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 warunekwhen: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 poleformencji 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ą dostawcyhelmzworkload:.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 plikdocker-compose.yamldla 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 blokmodule, którego pliki znajdują się we własnym katalogu komponentu wmodules/. 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.annotationsw 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 jawnenull, kieruje każdy podklucz przez deklaracjęmapspowiązania z egzekwowaniem zgodności strony i filaru (strona Aggregate uruchamiamaps.values; strona Release uruchamiamaps.infra), waliduje typy poszczególnych liści względemspec.schemadocelowej encji Feature i wstrzykuje syntetyczne dołączenia Feature, które graf IR oznacza jakoorigin: annotation. Kompozycja międzystronna scala wartości per filar i per pole podczas budowania IR, przy czym jawna wartość wygrywa dla danego pola;aggrega inspectwyś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 prefiksaggrega.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-pulllubauto_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.--verifysprawdza 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-kindsraportuje, które rodzaje przyjmuje. Zob.cli/aggrega-push.md.aggrega lint— dostępne. Uruchamia reguły dyscypliny publikowania z poziomem ważnościwarndla całego katalogu, domknięcia zależności encji Release lub jednej encji; dla jednej encji--pre-publishdodaje 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 jsonemituje 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 przezaggrega registry update.aggrega registry— dostępne. Zarządza rejestrami i ich polityką zaufania do podpisów;registry addrejestruje rejestr, aregistry updatebuduje lokalny indeks, który przeszukujeaggrega search.aggrega push-artifact— dostępne. Publikuje samodzielny artefakt danych (np. pakiet dokumentacji) w rejestrze OCI, obok publikującego encje poleceniapush.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 loginiaggrega 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: clijest rozwiązywany i rejestrowany jako podpolecenieaggrega, dzięki czemu zainstalowane rozszerzenie działa jakoaggrega <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ą--examplezapisuje 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 plikuentity.lockobok 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 buildprzyjmuje--ir-graph, podobnie jakaggrega inspectwywołane dla encji Release orazaggrega 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 przezaggrega/irGraph, a narzędziacli-inspect,cli-buildicli-validateserwera MCP przyjmują ją jako swój argumentir_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 dovalues/infra/providesżadnego klucza głównego, którego encja Recipe bazy nie mogłaby przetworzyć; encja Component deklarującaextendsz własnym schematem jest odrzucana na kopercie swojego dokumentu. Encja Manifest nadal mapuje rozszerzający typ własnym wpisem, a sprawdzenie mapowania akceptuje go, gdyimplementsmapowanej 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.