Niezmienniki architektury
Te osiem niezmienników to założycielskie reguły Aggrega. Obowiązują we wszystkich wydaniach, w rdzeniu kompilatora, w warstwie schematów, w katalogu i na powierzchni pluginów Wasm. Każda decyzja projektowa, każda funkcja i każda utworzona encja ich przestrzega.
Inne rozdziały architektury odwołują się do niezmienników według numeru. Gdy późniejszy rozdział mówi „zgodnie z niezmiennikiem 2” albo „według reguły String Pipe (niezmiennik 3)”, odsyła właśnie tutaj.
1. Kompilator jest neutralny wobec treści, bez własnego zdania i agnostyczny wobec intencji użytkownika
Kompilator Aggrega jest routerem tekstu typu Ahead-Of-Time (AOT). Parsuje YAML, przechodzi grafy, oblicza przecięcia etykiet i przesyła ciągi znaków ze źródeł do ujść. Nie pilnuje, co autorzy umieszczają w values, parameters, infra, provides czy locals. Nie egzekwuje konwencji nazewnictwa, konwencji portów ani etykiet semantycznych, które wymyśla Architect.
Wiele reguł, które brzmią jak reguły kompilatora — kontrakt Zero-Port, styl katalogu Naked-Base / Flavored-Edges, wybór prymitywu operacyjnego pasującego do danego komponentu — to umowy społeczne: dobre praktyki z furtkami, podtrzymywane przez architektów platformy tworzących katalog biblioteki standardowej. Kompilator ich nie interpretuje.
Ten niezmiennik dotyczy tego, co kompilator wnioskuje z tworzonej przez ciebie treści, i ten zakres stanowi całą jego treść. Kilka kluczy należy do samego Aggrega — są zarezerwowane, a akceptowane przez nie wartości zapisano w opublikowanym schemacie — i schemat sprawdza je tak samo jak każde inne zadeklarowane pole. component.aggrega.ai/type jest jednym z nich: jego zbiór wartości jest zamknięty, a dokument zawierający wartość spoza niego zostaje odrzucony przy wczytywaniu. To platforma określa, co oznacza jej własny klucz, a nie kompilator wczytuje znaczenie w napisany przez ciebie ciąg znaków; każdy twój własny klucz pozostaje dokładnie tak niepilnowany, jak mówi ten niezmiennik. Katalog klasyfikujący komponenty według osi, której Aggrega nie definiuje, tworzy własny klucz etykiety, który schemat akceptuje z dowolną wartością tekstową i który każda powierzchnia selektorów odczytuje identycznie.
To, co kompilator faktycznie wymusza, jest wąskie: walidacja schematów, parsowanie YAML, budowa grafu, ewaluacja szablonów i zwykłe trasowanie tekstu w ramach kontraktu wstrzykiwania. Cała reszta to konwencja, egzekwowana na etapie tworzenia katalogu lub w opcjonalnym gnieździe nadzoru Wasm.
Przedsiębiorstwa tworzące własne katalogi wewnętrzne mają wyraźną swobodę łamania konwencji biblioteki standardowej. Kompilator akceptuje wszystko, co napiszą, pod warunkiem że przejdzie to walidację schematu. Architektura promuje dobre praktyki; nie buduje więzień.
2. Czystość AOT: kompilator nie ma dostępu do informacji z czasu wykonania
Aggrega jest kompilatorem Ahead-Of-Time. W czasie kompilacji:
- Nie uwierzytelnia się w interfejsach API chmury.
- Nie pobiera bieżących adresów IP, nazw DNS ani adresów URL generowanych przez chmurę.
- Nie rozwiązuje sekretów do postaci jawnego tekstu — sekrety pozostają wskaźnikami metadanych w całej reprezentacji pośredniej (Intermediate Representation).
- Nie zna stanu klastrów ani usług docelowych w czasie wykonania.
- Nie może pobrać danych, które jeszcze nie istnieją (punktów końcowych powstających po aprowizacji, dynamicznie przydzielanych portów, automatycznie generowanych nazw zasobów).
Wszystko, co zależy od stanu w czasie wykonania, jest wyrażane jako deterministyczny ciąg wskaźnika — stabilna nazwa DNS, ciąg interpolacji Terraform, odwołanie do zasobu CloudFormation — dostarczany przez encję Ops Recipe. Kompilator przekazuje wskaźnik dalej, nie rozwiązując go. Środowisko wykonawcze (klaster, menedżer stanu IaC) rozwiązuje ostateczne dane fizyczne.
To jest prawdziwe odwrócenie sterowania (True Control Inversion): programiści określają Injection Contract w encji Aggregate, kompilator z wyprzedzeniem łączy deterministyczne wskaźniki, a środowisko wykonawcze rozwiązuje ostateczne dane fizyczne. Wymagania, które naprawdę potrzebują rozwiązywania w czasie wykonania, należą do potoku Wasm encji Ops Recipe, a nie do rdzenia kompilatora.
3. String Pipe: kompilator nie potrafi wywnioskować znaczenia
Kompilator nie interpretuje znaczenia przekazywanych wartości. Gdy encja Component A używa encji Component B, kompilator pobiera wartość skalarną, którą Recipe encji Component B produkuje przez provides — ciąg znaków, liczbę lub wartość logiczną — i przekazuje ją do kontekstu Recipe encji Component A, deterministycznie zamienioną na ciąg znaków na granicy wstrzykiwania. Nie ma znaczenia, czy ta wartość jest nazwą FQDN, lokalną nazwą hosta, literałem IP, numerem portu czy sformatowanym przez Wasm DSN: kompilator nie sprawdza trasowalności, poprawności protokołu ani adekwatności semantycznej.
Wynikają z tego dwie konsekwencje:
- Kompilator nie zgaduje przeznaczenia komponentu na podstawie nazwy. Komponent o nazwie
database-productionnie jest rozpoznawany jako baza danych. Semantyczne etykiety typu, takie jakcomponent.aggrega.ai/type(jeśli występują), są nieprzezroczystymi metadanymi używanymi do dopasowywania etykiet, a nie logiką rozgałęzień kompilatora. - Kompilator nie odróżnia nazwy hosta od nazwy bazy danych, numeru portu ani dowolnej nieprzezroczystej wartości. Wszystkie są wpisami skalarnymi w kontekście wstrzykiwania, dostarczanymi jako ciągi znaków.
Triada topologii — provides w wytwarzającej encji Recipe, uses w konsumującej encji Aggregate, inject na krawędzi — to Injection Contract. Kompilator ocenia etykiety i przekazuje ciągi znaków; interpretacja jest umową autorską między encjami Recipe i Component.
4. Żadnej infrastruktury widmo: kompilator nigdy nie wymyśla zasobów obliczeniowych ani funkcji
Kompilator nigdy po cichu nie wstrzykuje zasobów obliczeniowych, encji Features, adnotacji, proxy trasujących ani żadnego innego zasobu, którego autor nie zadeklarował jawnie. Naruszenia zasad wywołują głośne bariery ochronne (Loud Guardrails) — kompilacja zatrzymuje się z konkretnym błędem, który mówi autorowi, co poprawić w napisanym przez niego dokumencie — a nie ciche mutacje, które w czasie debugowania tworzą zagadki infrastrukturalne.
Zasoby trafiają do grafu poprzez jawne deklaracje w czasie tworzenia:
- Encja Aggregate programisty (komponenty, krawędzie
uses, dołączenia encji Feature). - Dołączenia encji Feature w encji Release (dodatki na poziomie operatora).
- Rozwinięcie sterowane adnotacjami (encja Manifest deklaruje powiązania adnotacja → Feature; adnotacja na encji Component lub na granicy jest jawną deklaracją).
- Wytwarzanie zasobów na poziomie encji Recipe: renderowanie
sourceencji Recipe wytwarza główny artefakt; syntezaworkloademituje kształt wdrożenia właściwy dla dostawcy (specyfikacja Pod, usługa Compose itp.); wpisyartifacts:(wbudowane lub wczytane przez$import:) emitują pomocnicze manifesty właściwe encji Recipe; generowanie zasobów encji FeatureRecipe emituje pomocnicze zasoby dla każdej encji Feature, wyzwalane jawnym dołączeniem encji Feature.
Ścieżki na poziomie encji Recipe to deklaracje z czasu tworzenia oddalone o jeden krok: autor encji Recipe pisze source / workload / artifacts / valuesMapping względem kontraktu encji Component, a encja Aggregate programisty wybiera, które encje Components biorą udział. Zasób pojawiający się w wyrenderowanym wyniku daje się prześledzić wstecz albo do deklaracji w encji Aggregate, w encji Release lub w powiązaniu adnotacji, albo do treści encji Recipe wybranej przez typy komponentów encji Aggregate.
Synteza przekształca kształty zadeklarowane przez autora w formaty wyjściowe właściwe dla dostawcy. Specyfikacja encji Workload napisana jako mapa kontenerów może zostać wyrenderowana jako specyfikacja Pod w Kubernetes, blok usługi Compose lub moduł Terraform — przekształcenie jest sterowane przez dostawcę, ale zasoby dają się prześledzić wstecz do deklaracji encji Workload autora.
Gniazdo zarządzania przenosi rolę dla każdego dołączenia i to rola — a nie rodzaj wtyczki — określa, co dołączenie może zrobić z kompilacją. Wtyczka zarządzania dołączona w roli werdyktu — przeglądająca graf IR (ir-verdict) lub wyrenderowane artefakty (render-verdict) — może odrzucić kompilację, ale nie może jej zmienić. Jeśli taki werdykt chce, by dodano zasób, przerywa kompilację ze wskazówką naprawczą, tak aby autor sam dodał zasób; host odczytuje wynik werdyktu wyłącznie jako akceptację lub odrzucenie i nigdy nie stosuje go jako zmiany, więc nieproszone przepisanie grafu do stanu zgodności — dokładnie ta infrastruktura widmo, której zakazuje ten niezmiennik — nie może pochodzić z roli werdyktu. Wtyczka zarządzania dołączona w roli transformacji (label-transform lub annotation-transform) jest wąskim, jawnym wyjątkiem: operator, który ją dołącza — opcjonalnie, poprzez konfigurację plugins.governance obszaru roboczego — zadeklarował tę transformację, więc wprowadzane przez nią zmiany są jawną deklaracją o tym samym statusie co rozwinięcie sterowane adnotacjami, a nie cichym wstrzyknięciem. Różnicą jest zaproszenie: niezamówiony werdykt nie może przepisać kompilacji, a jawnie dołączona transformacja może, bo operator o nią poprosił. Ponieważ transformacja kształtuje wyrenderowany wynik, jest przypinana w pliku blokady jak każda wtyczka kształtująca wynik — stosowana transformacja jest ustalana w chwili pull, więc jej zmiana oznacza ponowne wykonanie pull, a nie ciche przesunięcie między kompilacjami; werdykt nie kształtuje żadnego wyniku i nie jest przypinany.
5. Encja Aggregate jest powierzchnią tworzenia; encja Release nie może deklarować values:
Schemat encji Release mechanicznie zakazuje bloku values:. Operatorzy nie mogą z poziomu encji Release zapisywać values w encji Component ani w encji Feature. To egzekwowanie przez schemat na poziomie JSON Schema — nie umowa społeczna ani konwencja — i jest ono głośne: każdy dokument encji jest przy wczytywaniu walidowany względem schematu swojego rodzaju, więc encja Release zawierająca values: zatrzymuje kompilację z diagnostyką wskazującą plik i problematyczny klucz, zamiast zostać po cichu zignorowana.
Nie oznacza to, że wartości są identyczne we wszystkich środowiskach. Obsługiwaną ścieżką zmienności per środowisko jest wynoszenie parametrów (Parameter Hoisting):
- Programista udostępnia w encji Aggregate typowane pole
parameters.*. - Szablon
valuesencji Component odwołuje się do niego:storage_size: "{{ .parameters.db_size }}". - Encja Release wypełnia parametr:
parameters: { db_size: "100Gi" }. - Wyrenderowany wynik odzwierciedla wartość właściwą dla środowiska.
Encja Aggregate pozostaje jedynym źródłem prawdy o tym, które wartości są udostępniane do zmienności per środowisko (deklaracja parameters) i jak trafiają do wartości komponentu (odwołanie w szablonie). Encja Release wypełnia; nie nadpisuje.
Ten sam niezmiennik chronią dwa inne ograniczenia:
- Gdy encja Release używa
extends, deklarowanie wskaźnikaaggregate:jest zabronione przez schemat. Potomna encja Release musi wdrażać tę samą intencję programisty (Developer Intent) co jej encja nadrzędna. - Encja Release nie może wprowadzać zasobów obliczeniowych, których encja Aggregate nie zadeklarowała, ani przekierowywać krawędzi zadeklarowanej przez programistę. W obrębie gniazd zadeklarowanych przez Architect encja Release może łączyć i konfigurować krawędzie między istniejącymi komponentami: ustawia
infradla krawędzi na krawędzi połączonej przez programistę albo łączy z istniejącym komponentem krawędź prowadzącą do zadeklarowanego, lecz niepowiązanego gniazda. Nie może deklarowaćvaluesdla krawędzi (te pozostają w encji Aggregate), wiązać gniazda, którego nie deklarujeusesSchemaencji Component, ani kierować krawędzi do komponentu, który nie istnieje — każdy z tych przypadków zatrzymuje kompilację. Warto zauważyć, o którą deklarację chodzi w środkowej części zdania: gniazdo musi występować wusesSchemakatalogowej encji Component. Autor encji Aggregate może nazwać gniazdo, którego jego typ komponentu nie deklaruje, a powierzchnia encji Release celowo nie jest otwarta w ten sam sposób — operator łączy i konfiguruje w obrębie architektury, zamiast ją wymyślać.
Konfiguracja połączenia dla krawędzi ma zakres konsumenta: values i infra przenoszone na krawędzi pojawiają się wyłącznie w kontekście renderowania węzła, który utworzył krawędź, nigdy w kontekście celu. Wyrenderowany wynik komponentu jest zatem niezmienny względem połączeń, które nawiązują z nim inne komponenty — połączenie lub skonfigurowanie krawędzi do celu nigdy nie zaburza tego, co renderuje encja Recipe celu. Jedynym miejscem, w którym te połączenia są widoczne, jest encja Feature dołączona do celu: jej encja FeatureRecipe może odczytać, które komponenty używają celu, więc emitowane przez nią zasoby — na przykład zasada dopuszczająca dokładnie zadeklarowanych wywołujących — podążają za połączeniami, a własny wynik celu nie. Nawet tam values i infra dla krawędzi pozostają przy konsumencie.
6. Granica ABI WebAssembly: inteligencja specyficzna dla domeny żyje w Wasm
Binarny host w Go nie zawiera żadnej logiki specyficznej dla chmury ani infrastruktury. Cała inteligencja specyficzna dla domeny, renderowanie szablonów i formatowanie żyją wyłącznie wewnątrz wtyczek WebAssembly wykonywanych przez wbudowane środowisko uruchomieniowe Wazero. Host Go orkiestruje potok i przekazuje ładunki przez ABI do gości Wasm jako wskaźniki pamięci, w kodowaniu, które niesie każde gniazdo.
Wynikają z tego dwa wnioski:
- Logika specyficzna dla encji Provider (renderowanie specyficzne dla Helm, formatowanie specyficzne dla Terraform, scalanie specyficzne dla Compose) nigdy nie żyje w rdzeniu kompilatora Go. Kompilator rozwiązuje nazwę dostawcy, którą encja Recipe deklaruje w
spec.capability, do obsługującej ją encji Plugin renderowania dostawcy i przekazuje węzeł do tej wtyczki; samo tłumaczenie odbywa się w całości w gościu Wasm. Host nie zawiera kodu Go dla poszczególnych dostawców w przypadku dostawcy standardowego, więc w procesie nie ma niczego, do czego można by się cofnąć — nazwa dostawcy, która nie rozwiązuje się do żadnej obsługującej ją encji Plugin, zatrzymuje kompilację, zamiast renderować jakiś wbudowany domyślny wynik. - Logika zasad (reguły bezpieczeństwa, kontrole zgodności, obliczenia FinOps) nigdy nie żyje w rdzeniu kompilatora Go. Zasady należą do gniazda zarządzania Wasm, które przedsiębiorstwa włączają opcjonalnie — wtyczki dołączonej w roli werdyktu (
ir-verdict/render-verdict), by zaakceptować lub odrzucić kompilację, albo w roli transformacji (label-transform/annotation-transform), by kształtować etykiety lub adnotacje.
Granica ABI utrzymuje rdzeń Go zwartym, audytowalnym i niezależnym od chmury. Zamiana logiki renderowania dostawcy to zamiana artefaktu Wasm, a nie ponowna kompilacja samego Aggrega.
7. Rozdzielenie odpowiedzialności (podział na cztery domeny) — wskazówka, nie więzienie
Wytyczne projektowe Aggrega dzielą tworzenie na cztery domeny:
- Developer Intent — Aggregate.
- Platform Architect — encje katalogowe Component i Feature.
- Platform Ops — Recipe, FeatureRecipe, Plugin (w tym encja Plugin renderowania dostawcy).
- Platform Operator — Manifest, Release.
Typowe, dobrze działające wdrożenie stosuje ten podział: programiści piszą intencję aplikacji, a nie fizyczną infrastrukturę; zespół Ops pisze fizyczną infrastrukturę, a nie logikę aplikacji. Aggrega zaprojektowano do używania w ten sposób, a oficjalna dokumentacja, przykłady i katalog biblioteki standardowej są tworzone zgodnie z tym podziałem.
Podział na cztery domeny jest wskazówką i ramą projektową, a nie egzekwowaniem przez kompilator. Kompilator (zgodnie z niezmiennikiem 1) jest bez własnego zdania. Użytkownicy mogą swobodnie:
- Łączyć role (jedna osoba pisze zarówno encje Aggregates, jak i Recipes).
- Mieszać odpowiedzialności (Architects wpisują na stałe etykiety zgodności bezpośrednio w encjach Components
core/*, gdy wymagają tego katalogi przedsiębiorstwa). - Przekraczać granice domen (programiści używają wynoszenia parametrów, by wstrzykiwać kwestie infrastrukturalne do encji Aggregate, gdy wymaga tego starszy kod).
Kompilator akceptuje każdy wzorzec tworzenia, który przechodzi walidację schematu. Architektura promuje dobre praktyki; ograniczenia na poziomie schematu (takie jak zakaz values: w encji Release z niezmiennika 5) to jedyne przekroczenia domen, które kompilator faktycznie odrzuca. Każde inne rozdzielenie jest umową społeczną utrzymywaną przez autorów katalogów oraz, tam gdzie przedsiębiorstwa je włączą, przez gniazdo zarządzania Wasm.
8. Deterministyczny wynik
Przy identycznym wejściu kompilator wytwarza wynik identyczny co do bajtu. Dwie kompilacje tych samych encji Aggregate + Release + Manifest względem tego samego katalogu dają wyrenderowane artefakty, które są równe bajt po bajcie.
To kontrakt, na którym polegają narzędzia GitOps i procesy przeglądu oparte na różnicach. Pull request, który nie zmienił wejścia, nie powinien wytwarzać żadnej różnicy w wyrenderowanym wyniku. Pull request, który zmienił wejście, powinien pokazywać tylko różnicę wynikającą z tej zmiany — bez fałszywych zmian kolejności, bez fluktuacji znaczników czasu, bez artefaktów iteracji map.
Deterministyczny wynik jest utrzymywany dzięki trzem zasadom:
- Mapy uporządkowane przez autora: każda mapa, której kolejność iteracji mogłaby wpływać na wyrenderowany wynik, używa kontenera uporządkowanej mapy, tak aby iteracja podążała za kolejnością deklaracji autora, a nie za kolejnością skrótów.
- Żadnej treści zależnej od zegara ani losowej w wyrenderowanych artefaktach, chyba że autor jawnie wstrzyknął ją przez wejście szablonu.
- Renderowanie jest czyste: to samo wywołanie gościa Wasm z tym samym wejściem daje ten sam wynik.
Flaga --trace kompilatora (zob. language-reference/cli/aggrega-build.md) daje autorom i operatorom powierzchnię weryfikacji tego niezmiennika. Dwie kompilacje tego samego wejścia z włączonym --trace wytwarzają zrzuty śladu identyczne co do bajtu; każda różnica w danym przebiegu lokalizuje regresję. Determinizm nie jest tylko właściwością z chwili wydania — można go obserwować w każdym stanie pośrednim kompilatora dzięki układowi śladu dla poszczególnych węzłów.
Deterministyczny wynik to kontrakt, dzięki któremu Aggrega można bezpiecznie używać jako źródła prawdy w pętli GitOps.
Zakres niezmienności na poziomach rozwiązywania
Gwarancja wyniku identycznego co do bajtu obejmuje artefakty przypięte w pliku blokady — encje rozwiązywane przez artefakty rejestru, których skróty zapisuje plik blokady (poziom rejestru w trzypoziomowym modelu rozwiązywania encji). Gdy kompilacja odczytuje pliki, które encja Release wskazuje ścieżką (ścieżki lokalne zaczynające się od ./ lub ../), lub encje w katalogach katalogowych obszaru roboczego (catalog_dirs:, na poziomie obszaru roboczego i pamięci podręcznej), niezmienność zależy od tego, czy te pliki pozostaną niezmienione między kompilacjami. Plik blokady zapisuje encję z katalogu katalogowego obszaru roboczego za pomocą skrótu jej dokumentu i deklarowanych przez nią plików, więc kompilacja zatrzymuje się na encji zmienionej od czasu pull, zamiast ją renderować — z jednym wyjątkiem: encja Recipe lub FeatureRecipe, którą encja Manifest nazywa odwołaniem będącym zarazem nazwą encji Component lub Feature, jest zapisywana pod tym odwołaniem jako Component lub Feature, więc jej wejścia są utrzymywane tylko przez przypięcia obok niej w pliku blokady, a zmiana jej własnego dokumentu nie zostaje wykryta. Utrzymanie plików w niezmienionym stanie należy do systemu kontroli wersji (zwykle Git).
Odwołanie do ścieżki lokalnej, którego bazowy plik zmienia się między dwiema kompilacjami, wytwarza uprawnioną różnicę w wyrenderowanym wyniku, mimo że kształt wejścia kompilatora się nie zmienił — gwarancja deterministycznego wyniku zostaje zachowana (to samo wejście w bajtach → ten sam wynik w bajtach), ale wejścia się różnią, ponieważ zmienił się plik lokalny. Katalogi, które potrzebują niezmienności między kompilacjami dla każdego źródła, pobierają artefakty z rejestru do pamięci podręcznej przypiętej w pliku blokady, zamiast odczytywać je ze ścieżki lokalnej lub z katalogu obszaru roboczego; plik blokady jest kotwicą tożsamości bajtowej.