Umowy społeczne
Aggrega jest z założenia kompilatorem bez własnego zdania. Zgodnie z niezmiennikami założycielskimi opisanymi w architecture/05-invariants.md kompilator parsuje YAML, przechodzi grafy, oblicza przecięcia etykiet i przekazuje ciągi znaków między komponentami — ale nie kontroluje tego, co programiści umieszczają w values, parameters, infra, provides ani locals; nie egzekwuje konwencji nazewnictwa, konwencji portów ani etykiet semantycznych wymyślonych przez architekta; nie odgaduje przeznaczenia komponentu na podstawie nazw. Wiele dyscyplin, które brzmią jak reguły kompilatora, to w rzeczywistości umowy społeczne: dobre praktyki utrzymywane przez konwencję autorską, a nie przez schemat czy egzekwowanie w czasie działania.
Warto jasno powiedzieć, gdzie kończy się ta neutralność, ponieważ jest to jedna granica i łatwo ją nadinterpretować. Kilka kluczy należy do samej Aggrega — są zarezerwowane, a dopuszczalne dla nich wartości zapisano w opublikowanym schemacie — i te schemat sprawdza, tak jak sprawdza każde inne zadeklarowane pole. Zadeklarowanie zbioru wartości klucza zdefiniowanego przez samą platformę nie oznacza, że kompilator wczytuje znaczenie w to, co napisano; to platforma określa, co oznacza jej własny klucz. Wszystko, co autor zapisze pod własnym kluczem, pozostaje dokładnie tak samo niekontrolowane, jak opisuje to ta strona.
Ta strona jest kanonicznym spisem umów społecznych języka. Autorzy, którzy poznają umowy z tej strony, mogą zrozumieć, dlaczego kompilator akceptuje kompilację niepoprawną z punktu widzenia konwencji (akceptuje — kompilator nie interpretuje konwencji) i do kogo należy wychwycenie naruszenia (dyscyplina autorska, uwaga recenzenta lub plugin lintera uruchamiany przez aggrega lint).
Trzy klasy dyscypliny
Dyscypliny w Aggrega dzielą się na trzy klasy według tego, w jaki sposób dyscyplina jest egzekwowana. Klasyfikacja ma znaczenie, ponieważ każda klasa ma inny tryb awarii w razie naruszenia dyscypliny.
Egzekwowane przez schemat
Dyscyplinę egzekwuje walidacja JSON Schema 2020-12 w czasie wczytywania (JSON Schema koperty encji oraz deklaracje schema: na poziomie filarów w encjach Component i Feature). Naruszenie powoduje krytyczne zatrzymanie, zanim kompilacja pójdzie dalej; kompilator odmawia kontynuowania. Autor, który próbuje naruszyć dyscyplinę egzekwowaną przez schemat, widzi jawny błąd walidacji wskazujący pole i ograniczenie.
Przykłady: wymagane pola koperty encji (apiVersion / kind / metadata.name / metadata.version); wyrażenie regularne SemVer dla metadata.version; zamknięty zbiór wartości zastrzeżonej etykiety component.aggrega.ai/type; mechaniczny zakaz bloków values: w schemacie encji Release (zgodnie z niezmiennikiem 5); odrzucenie połączenia extends z aggregate w encji Release (niezmiennik jednego źródła prawdy); reguły kształtu encji Recipe egzekwujące kontrakt kompozycji rodzajów wejść.
Dyscypliny egzekwowane przez schemat to najsilniejsze gwarancje, jakie daje język. Kompilator odmawia renderowania czegokolwiek, co je narusza.
Egzekwowane przez plugin polityki
Dyscyplinę egzekwuje wtyczka Wasm uruchamiana w jednym z udokumentowanych punktów gniazd (rola zarządcza label-transform podczas budowy topologii; rola zarządcza ir-verdict podczas analizy statycznej; gniazdo lintera poza głównym przebiegiem). Naruszenie powoduje albo zatrzymujący kompilację błąd polityki (gniazda w głównym przebiegu), albo ostrzeżenie doradcze (gniazda poza głównym przebiegiem), zależnie od semantyki bramkowania gniazda.
Dyscyplina jest egzekwowana w ten sposób tylko tam, gdzie działa sprawdzający ją plugin: środowisko uruchomieniowe Wasm wywołuje pluginy w udokumentowanych punktach gniazd, a dyscyplina, której nie sprawdza żaden plugin, pozostaje konwencją. Linter publikacji, uruchamiany przez aggrega lint, sprawdza część jednej konwencji z tej strony — zob. Konwencje sprawdzane przez regułę lintera. Żadna reguła lintera publikacji nie sprawdza hermetyczności (Sprig FuncMap udostępnia funkcje pomocnicze łamiące deterministyczność wyniku, zgodnie z zastrzeżeniem o determinizmie w templates/sprig-functions.md) ani nazewnictwa zasobów chmurowych (encje Recipes, których wyjścia valuesMapping: odwołują się do pól nazw zasobów chmurowych bez interpolacji release_name / instance_id, zgodnie z entities/recipe.md, „Cloud-resource naming discipline”); własny plugin lintera może sprawdzać jedno i drugie.
Opis powierzchni kontraktu wtyczek Wasm i kryterium ich umieszczania (gniazdo lintera a role zarządcze wydające werdykt) znajduje się w plugins/plugin-contract.md.
Utrzymywane konwencją
Dyscyplinę podtrzymuje wyłącznie dyscyplina autorów oraz uwaga recenzentów. Kompilator jej nie egzekwuje; żaden schemat nie odrzuca naruszenia; żadna wtyczka Wasm go nie oznacza. Autorzy poznają dyscyplinę z dokumentacji, przestrzegają jej, ponieważ zależy od niej kształt architektury, i polegają na przeglądzie PR w wyłapywaniu uchybień. Naruszenie nie daje żadnego sygnału w czasie kompilacji — kompilacja się udaje, wyrenderowany wynik działa, o ile kompilator wie, a naruszenie dyscypliny ujawnia się dopiero wtedy, gdy od konwencji zależą narzędzia na dalszym etapie lub zachowanie w czasie działania.
Dyscypliny utrzymywane konwencją to kluczowa lista, którą autorzy muszą poznać z dokumentacji. Kompilator ich nie interpretuje; błąd w nich nie psuje kompilacji, ale psuje kształt architektury, od którego zależy Aggrega. Większość tej strony dokumentuje właśnie je.
Konwencje
Poniższe umowy społeczne są utrzymywane konwencją. Każdy wpis wskazuje dyscyplinę, miejsce, w którym konwencja jest udokumentowana, oraz skutki jej naruszenia. Każdy wpis zachowuje swój numer, gdziekolwiek się znajduje: umowa 3, dyscyplina zarezerwowanych prefiksów, jest sprawdzana przez regułę lintera dla kluczy adnotacji i opisana w sekcji Konwencje sprawdzane przez regułę lintera.
1. Wybór typu operacyjnego pasującego do komponentu
Zarezerwowana etykieta component.aggrega.ai/type określa, czym jest komponent, wybierając wartość z zamkniętego zbioru uniwersalnych prymitywów chmurowych: server, worker, task, function, stateful-server, resource. Przynależność do tego zbioru jest egzekwowana przez schemat, a nie utrzymywana konwencją. Aggrega definiuje ten klucz i akceptowane przez niego wartości, schemat encji Component je wylicza, a dokument zawierający cokolwiek innego jest odrzucany podczas wczytywania — E0215, warunek entity-envelope-invalid, wskazuje etykietę i wymienia dopuszczalne wartości. Tego odrzucenia niniejszy wpis nie obejmuje.
Konwencją pozostaje to, która z wartości pasuje do danego komponentu. Nic nie sprawdza, czy relacyjna baza danych ma etykietę stateful-server, a nie server, ani czy konsument kolejki to worker, a nie task; selektor ocenia dowolną znalezioną wartość, nie przypisując jej znaczenia. Architekt tworzący encję Component wybiera wartość opisującą, jak infrastruktura ma ją traktować, a dalsze selektory, pluginy polityk i pluginy renderujące Wasm zakładają, że ten wybór jest rzetelny.
Klasyfikacja według własnej osi. Zamknięty zbiór dotyczy wyłącznie tego jednego zarezerwowanego klucza. Katalog potrzebujący klasyfikacji, której Aggrega nie definiuje — poziomu, strefy danych, klasy usługi lub drobniejszego podziału prymitywów operacyjnych — dodaje własny klucz etykiety obok zarezerwowanego. Schemat encji Component akceptuje dowolny dodatkowy klucz etykiety z wartością tekstową i odczytuje go ten sam mechanizm selektorów, więc acme.aggrega.ai/storage-tier: oltp występuje obok component.aggrega.ai/type: stateful-server, a appliesTo encji Feature lub selector gniazda może wskazywać dowolny z nich. Rozszerzanie odbywa się na własnym kluczu, nigdy na wartości wewnątrz klucza Aggrega.
Udokumentowano w: architecture/02-ecosystem-philosophy.md (ontologia operacyjna) + labels-and-annotations.md (dyscyplina prefiksów) + errors/sentinels.md (E0215).
Skutki naruszenia: wartość ze zbioru, która nie pasuje do komponentu, wprowadza w błąd wszystko, co czyta tę etykietę. Magazyn danych z etykietą server jest odrzucany przez encję Feature lub gniazdo wybierające stateful-server — zatrzymanie wskazuje selektor, a nie błędną etykietę — a plugin polityki lub plugin renderujący, który czyta etykietę, traktuje go jak bezstanowe obliczenia. Tam, gdzie widzą go tylko tacy czytelnicy, kompilacja się udaje; błąd ujawnia się dopiero, gdy wyrenderowane artefakty trafią do klastra.
2. Rozdział .context.annotations.* na trzy kubełki
Kaskadowane adnotacje trafiają do trzech nazwanych kubełków — .context.annotations.release, .context.annotations.catalog, .context.annotations.aggregate — z których każdy niesie inną intencję. Cel dyscypliny: release to „gdzie działa ten komponent, zarządzane przez Ops”; catalog to „czym jest ten komponent, tworzone przez architekta”; aggregate to „co robi ten komponent, tworzone przez dewelopera”.
Kompilator nie egzekwuje granic kubełków. Wszystkie trzy mają płaski kształt string → string; szablon encji Recipe może odczytać każdy z nich i nic nie stoi na przeszkodzie, by adnotacja granicy encji Release została zinterpretowana jako metadane kognitywne albo adnotacja katalogu została skierowana do infra:. Rozdział utrzymują autorzy zapisujący adnotacje we właściwym kubełku oraz recenzenci wychwytujący przecieki między kubełkami.
Udokumentowano w: labels-and-annotations.md (Rozdział na trzy kubełki jest umową społeczną).
Skutki naruszenia: logika kierowania zależna od rozróżnienia intencji kubełków (np. encja Recipe kierująca .context.annotations.release.aggrega.ai/region do pola region w Terraform) po cichu pobiera dowolną adnotację z kubełka, niezależnie od intencji autora. Kompilacja się udaje; wyrenderowany wynik może zawierać semantycznie błędne wartości.
4. Samowystarczalność provides: w encji Recipe
Szablony provides: encji Recipe domykają się wyłącznie nad danymi własnego węzła — .values, .infra, .context.instance_id, .context.rendered_name (gdy dostawca węzła go zgłasza), rozwiązanymi .locals węzła oraz statycznymi ciągami. Odwołania do .context.inject i .context.uses są zabronione, ponieważ ewaluacja provides uruchamia te szablony w dowolnej kolejności; odczyt danych innych węzłów uzależniłby ją od kolejności iteracji topologicznej, czego projekt celowo unika. .locals należy do dozwolonej powierzchni: zmienne lokalne węzła rozwiązują się w preambule tego samego etapu, przed jego provides, i są lokalne dla węzła, więc ich odczyt nie wpływa na kolejność. Użycie klucza, którego blok locals nie deklaruje, zatrzymuje kompilację.
To reguła złożona z dwóch połówek, z których każda wskazuje, gdzie jest sprawdzana. Pierwszą sprawdza kompilator: ewaluacja provides sprawdza każdy szablon względem pozytywnej listy dozwolonych korzeni zdefiniowanych przez jego kontekst, zanim szablon zostanie wykonany, więc odczyt .context.inject / .context.uses zatrzymuje kompilację z jawnym błędem zamiast renderować pustą wartość; reguła jest też udokumentowana w templates/expansion-matrix.md, wiersz 6. Drugą utrzymuje konwencja: szerszy wzorzec (provides jest publiczne; locals jest prywatne) opiera się na konwencji.
Udokumentowano w: templates/expansion-matrix.md, wiersz 6 + vocabulary/data-pillars.md „provides: i locals: — oblicze publiczne a prywatne”.
Skutki naruszenia: kompilator wykrywa zabronione odwołania występujące bezpośrednio w provides: i zatrzymuje kompilację podczas ewaluacji szablonów. Szersza dyscyplina rozdziału publicznego i prywatnego (nie należy ujawniać stanu wewnętrznego przez klucze provides:) jest wyłącznie konwencją — autorzy traktujący provides: jako wewnętrzną przestrzeń nazw encji Recipe tworzą kontrakty, od których zależą wywołujący; refaktoryzacja staje się zmianą łamiącą zgodność.
5. Determinizm — niehermetyczne funkcje pomocnicze w szablonach ścieżki renderowania
Niezmiennik deterministycznego wyniku w Aggrega (Niezmiennik 8 w architecture/05-invariants.md) wymaga, aby identyczne bajtowo wejście dawało identyczny bajtowo wynik. Pełna mapa FuncMap biblioteki Sprig udostępnia funkcje pomocnicze odczytujące stan otoczenia (odczyt czasu zegarowego now / date; generatory losowe randAlpha / uuidv4; odczyt środowiska env / expandenv; resolwery sieciowe getHostByName). Autorzy, którzy wywołują te funkcje w szablonie wpływającym na renderowany wynik, łamią kontrakt determinizmu.
Kompilator nie wykrywa ani nie blokuje użycia niehermetycznych funkcji pomocniczych. FuncMap biblioteki Sprig udostępnia je zgodnie z templates/sprig-functions.md „Zastrzeżenie dotyczące determinizmu”; dyscyplinę utrzymują autorzy, unikając tych funkcji w szablonach ścieżki renderowania, oraz recenzenci, wychwytujący ich użycie podczas przeglądu PR.
Udokumentowano w: templates/sprig-functions.md „Zastrzeżenie dotyczące determinizmu”.
Skutek naruszenia: wynik kompilacji różni się między uruchomieniami dla tego samego wejścia. Niezgodność wychodzi na jaw przy porównaniu GitOps, gdy narzędzia niższego poziomu (ArgoCD, Flux) wykrywają nieoczekiwany dryf między zatwierdzonym manifestem a stanem klastra, albo podczas audytu, gdy dwie kompilacje tego samego wejścia dają różne artefakty.
Żadna reguła lintera publikacji nie sprawdza szablonów pod kątem wywołań niehermetycznych funkcji pomocniczych. Nazwa funkcji pomocniczej jest zapisana w szablonie, więc własny plugin lintera może ją znaleźć (zob. Konwencje sprawdzane przez regułę lintera).
6. Granice filarów (drogowskazy, nie mury)
Granice filarów są dyscypliną autorską, a nie ograniczeniem wymuszanym przez język. Silnik szablonów dopuszcza odczyty między filarami w każdym miejscu, o ile nie zabraniają ich wprost reguły samowystarczalności (np. provides: i source: w encji Recipe odczytujące .context.inject / .context.uses). Autorzy powinni:
- Odczytywać
.valuesdla ładunku kognitywnego (intencji zapisanej przez programistę). - Odczytywać
.infradla wymiarowania fizycznego (wymiarowania zapisanego przez Ops). - Odczytywać
.context.uses.<alias>.provides.<key>dla ciągów wskaźnikowych między komponentami. - Odczytywać
.context.injectdla kanału dostarczania po hydratacji.
Silnik szablonów nie blokuje odczytu. Szablon encji Recipe, który odczytuje .infra.replicas, aby sterować polem values:, działa; nic nie uniemożliwia trasy między filarami. Celem dyscypliny są drogowskazy — granice opisują intencję autorską (kto jest właścicielem danych), a nie ograniczenie w czasie wykonania.
Udokumentowano w: vocabulary/data-pillars.md „Granice filarów i dyscyplina autorska”.
Skutek naruszenia: przeciekanie między filarami — ładunek kognitywny programisty zawiera szczegóły wymiarowania fizycznego albo wymiarowanie zapisane przez Ops zawiera metadane kognitywne. Kompilacja się udaje; podział autorstwa na cztery domeny z czasem się zaciera, gdy autorzy idą na skróty między filarami; utrzymanie staje się trudniejsze, w miarę jak słabnie odpowiedniość między filarami a przepływem danych.
7. Dwuźródłowa semantyka containers.<name>.variables w encji Workload
Mapa variables: łączy dwa odrębne źródła danych za pomocą wyrażeń szablonów Go: literały z filaru programisty (wpisy odczytujące .values / .infra / .locals) oraz dane z kanału między komponentami (wpisy odczytujące .context.inject.env.<KEY>). Autorzy wybierają jedno źródło dla każdego wpisu w zależności od tego, czy wartość jest lokalna dla komponentu, czy wyprowadzona z innego komponentu.
Kompilator nie rozróżnia tych dwóch źródeł; oba trafiają do tej samej listy Kubernetes env: w renderowanym obiekcie Deployment. Dwuźródłowa semantyka istnieje wyłącznie na etapie tworzenia — dyscyplina polega na nazywaniu intencji (ten wpis jest lokalny dla komponentu; tamten jest wyprowadzony z innego komponentu), aby przyszli opiekunowie mogli odczytać, które wpisy zależą od których wyników hydratacji inject.
Udokumentowano w: entities/workload.md, „Field-semantics essentials” (variables).
Skutek naruszenia: autorzy, którzy nie rozróżniają tych dwóch źródeł, tracą ślad „które wpisy są powiązane z provides: którego celu”. Refaktoryzacja kluczy provides: celu po cichu psuje każdy wpis variables: wywołującego, który czytał przez kanał inject.
8. Dyscyplina nazewnictwa zasobów chmurowych
Encje Recipes, które generują nazwy zasobów chmurowych (nazwy kubełków S3, identyfikatory baz danych RDS, nazwy ról IAM, nazwy stosów CloudFormation — każde pole, którego wartość zajmuje globalną przestrzeń nazw u dostawcy chmury), muszą wstawiać {{ .metadata.release_name }} i/lub {{ .context.instance_id }} do renderowanej nazwy, aby uniknąć kolizji, gdy ta sama encja Recipe działa w wielu encjach Releases lub instancjach komponentu.
Kompilator nie sprawdza wyników valuesMapping: pod kątem pól z nazwami zasobów chmurowych pozbawionych tych interpolacji. Dyscyplinę utrzymują autorzy encji Recipe (którzy wiedzą, które pola nazywają globalnie unikalne zasoby u docelowego dostawcy) oraz recenzenci (wychwytujący wzorce zasobów bez unikalnych nazw podczas przeglądu PR).
Udokumentowano w: entities/recipe.md „Dyscyplina nazewnictwa zasobów chmurowych”.
Skutek naruszenia: dwie encje Releases tej samej encji Aggregate (prod-billing i staging-billing) próbują wdrożyć zasób o tej samej globalnej nazwie; drugie wdrożenie kończy się błędem w czasie wykonania z powodu odrzucenia po stronie chmury. Kompilacja Aggrega się udaje; błąd wdrożenia wychodzi na jaw dopiero przy zastosowaniu drugiej encji Release.
Żadna reguła lintera publikacji nie sprawdza, czy pola nazw zasobów chmurowych zawierają wymagane interpolacje; własny plugin lintera może to robić (zob. Konwencje sprawdzane przez regułę lintera).
9. Ziarnistość encji Component — jedna spójna usługa na encję Component
Encja Component modeluje jedną spójną usługę — pojedynczą udostępnianą usługę albo obciążenie (obciążenia) jednej usługi wraz z jej wewnętrznymi obciążeniami pomocniczymi. Gdy chart łączy usługi, których inny komponent mógłby sensownie użyć (use) samodzielnie — zwłaszcza zewnętrzną infrastrukturę, taką jak baza danych, pamięć podręczna czy broker komunikatów, którą Aggrega już modeluje jako osobną encję Component — biblioteka standardowa składa encje Components dla poszczególnych usług w moduł podagregatu (spec.aggregates + exportedComponents), zamiast opakowywać cały produkt jako jedną nieprzejrzystą encję Component. Dyscyplina: wiele obciążeń w jednej encji Component jest w porządku; to niezależna użyteczność wyznacza granicę, która dzieli encję Component na stos.
Kompilator jest agnostyczny wobec tej ziarnistości. Renderuje wszystko, co przechodzi walidację schematu — nie sprawdza, ile usług łączy encja Recipe danej encji Component ani czy któraś z nich jest niezależnie użyteczna. Autor, który opakowuje produkt złożony z pięciu usług jako jedną encję Component, tworzy encję Component, którą kompilator akceptuje i renderuje bez zastrzeżeń; konwencję utrzymują dyscyplina autorska i uwaga recenzentów.
Udokumentowano w: ../../architecture/06-data-taxonomy-and-composition.md (Jedna spójna usługa na encję Component — granica pojedynczego obciążenia).
Skutek naruszenia: monolityczne opakowanie wielu usług kompiluje się poprawnie, ale połączone usługi są niewidoczne dla topologii, selektora i polityk — nie można ich niezależnie skalować, zastępować ani od nich zależeć. Późniejsza refaktoryzacja monolitu na encje Components dla poszczególnych usług jest zmianą łamiącą zgodność dla każdego konsumenta, który odwoływał się do pojedynczego opakowanego węzła.
Dlaczego istnieją konwencje
Każda z tych konwencji jest z założenia dyscypliną autorską, choć schemat lub polityka Wasm mogłyby egzekwować dowolną z nich. Uzasadnienie dla poszczególnych typów umów:
Rozszerzalność. Dyscyplina zarezerwowanych prefiksów (umowa 3) opisuje słownictwo biblioteki standardowej, a nie całość dopuszczalnego słownictwa. Katalogi korporacyjne tworzą własne prefiksy i klucze etykiet, aby rozszerzać bibliotekę standardową; wymuszanie konwencji prefiksów schematem zamieniłoby „dyscyplinę biblioteki standardowej” w „jedyny dozwolony kształt języka” — a to jest właśnie mur, którego architektura celowo unika. Oś typu operacyjnego (umowa 1) zachowuje tę samą rozszerzalność na innej płaszczyźnie: zarezerwowany klucz zdefiniowany przez Aggrega ma zamknięty zbiór wartości wymuszany schematem, a katalog rozszerza go, dodając obok własny klucz etykiety, a nie wartość wewnątrz klucza Aggrega. Schemat sprawdza zbiór wartości jednego klucza, który do niego należy; otwarty pozostaje każdy inny klucz i to tam żyje własne słownictwo katalogu.
Czystość AOT. Dyscyplina nazewnictwa zasobów chmurowych (umowa 8) i dyscyplina determinizmu (umowa 5) wymagają analizy zawartości szablonów, aby ustalić, czy pole jest nazwą zasobu chmurowego albo wywołaniem niehermetycznej funkcji pomocniczej. Czystość AOT (niezmiennik 2) chroni kompilator przed zależnością od stanu w czasie wykonania; statyczna analiza szablonów jest wykonalna (plugin lintera odczytuje szablony encji w takiej postaci, w jakiej je napisano), ale przeprowadzanie jej w rdzeniu kompilatora wiązałoby wewnętrzną logikę kompilatora z autorskimi zagadnieniami poszczególnych dziedzin. Architektura przenosi te kontrole z kompilatora do pluginów Wasm zgodnie z niezmiennikiem 6 (granica ABI Wasm).
Elastyczność tworzenia. Dyscyplina granic filarów (umowa 6) i dwuźródłowa semantyka variables (umowa 7) opisują wzorce tworzenia, a nie ograniczenia czasu wykonania. Ta sama składnia szablonu może wyrazić wzorzec zgodny z dyscypliną albo ją naruszający; uczynienie z dyscypliny kontroli w czasie wykonania wymagałoby od kompilatora interpretowania intencji autora, do której nie ma dostępu. Architektura traktuje konwencję jako dokumentację, z której autorzy się uczą, a nie jako niezmiennik czasu wykonania. Tu mieści się również granulacja encji Component (umowa 9): przedsiębiorstwa mogą opakować produkt z dowolną granulacją preferowaną przez ich katalog, a kompilator — neutralny wobec treści i bez własnego zdania zgodnie z niezmiennikiem 1 — nie ma możliwości ustalenia, czy dołączone obciążenie jest używalne niezależnie, dlatego granica jednej spójnej usługi pozostaje dyscypliną autorską, a nie murem schematu. Wybór typu operacyjnego (umowa 1) ma ten sam kształt: schemat ustala, jakie wartości istnieją, ale to, która z nich opisuje dany komponent, jest oceną modelowania dotyczącą tego, jak infrastruktura musi go traktować, i nic w encji Recipe ani w bloku values nie mówi kompilatorowi, czy ta ocena była trafna.
Egzekwowanie w dwóch połówkach. Samowystarczalność provides: w encji Recipe (umowa 4) jest częściowo wymuszana przez kompilator — ścieżka renderowania wykrywa odczyty .context.inject / .context.uses w szablonach provides: i przerywa działanie. Szersza dyscyplina publiczne-kontra-prywatne (nie ujawniaj stanu wewnętrznego) opiera się na konwencji, ponieważ kompilator nie potrafi bez intencji autora ustalić, które ciągi powinny pozostać wewnętrzne dla encji Recipe.
Te trzy drogi mają znaczenie, ponieważ każda wskazuje, gdzie spoczywa odpowiedzialność za wychwytywanie naruszeń. Egzekwowane przez schemat: kompilator. Egzekwowane przez plugin polityki: plugin, który to sprawdza, tam, gdzie działa. Utrzymywane konwencją: autorzy i recenzenci. Autorzy, którzy przyswoją sobie te drogi, rozumieją, które błędy wychwyci kompilator, a które po cichu przejdą dalej, do narzędzi niższego szczebla lub do czasu wykonania.
Konwencje sprawdzane przez regułę lintera
Linter publikacji, uruchamiany przez aggrega lint, częściowo sprawdza jedną konwencję z tej strony: klucze adnotacji z umowy 3, poniżej. Jego ustalenie ma charakter doradczy, a część konwencji, do której nie sięga, jest utrzymywana konwencją, tak jak powyższe wpisy.
Żadna reguła lintera publikacji nie sprawdza żadnej innej konwencji z tej strony. Dwie z nich może sprawdzić reguła lintera, ponieważ naruszenie jest zapisane w encji: determinizm (umowa 5) — szablon wywołujący niehermetyczną funkcję pomocniczą — oraz nazewnictwo zasobów chmurowych (umowa 8) — wyjście valuesMapping: nazywające zasób chmurowy bez interpolacji release_name / instance_id. To samo dotyczy kluczy etykiet pod zarezerwowanymi prefiksami (umowa 3). Przestrzeń robocza może dołączyć własne pluginy lintera w plugins.linter, obok lintera publikacji, aby sprawdzać dowolną z nich; The discipline rules wymienia reguły, które ma linter publikacji.
Pozostałe konwencje (1, 2, 4, 6, 7, 9) zależą od tego, co autor miał na myśli, a tego żadna reguła nie odczyta z tego, co zostało napisane. Rozdział koszyków wynika z rozszerzalności (katalogi przedsiębiorstw go nadpisują) — egzekwowanie przez schemat kolidowałoby z tą elastycznością. To, co pozostaje z osi typu operacyjnego po tym, jak schemat ustali zbiór wartości — wybór prymitywu pasującego do komponentu — zależy od intencji autora: kompilator nie odróżni dobrze dobranego typu operacyjnego od źle dobranego, ponieważ oba są wartościami, które akceptuje. Dyscyplina granic filarów i dwuźródłowa semantyka variables zależą od intencji autora — kompilator nie może ustalić intencji na podstawie samej składni szablonu. Samowystarczalność provides: w encji Recipe jest częściowo egzekwowana; szersza dyscyplina rozdziału części publicznej i prywatnej zależy od tego, które klucze autor zamierzał zachować jako wewnętrzne, czego nic w encji Recipe nie określa. Granularność encji Component również zależy od intencji autora — to, czy dołączony workload jest samodzielnie użyteczny, jest oceną modelowania, której kompilator nie odczyta z treści encji Recipe.
3. Dyscyplina zarezerwowanych prefiksów
Klucze adnotacji i etykiet mają kształt <namespace>/<name>. Pięć zarezerwowanych prefiksów niesie określone zasady tworzenia: aggrega.ai/ (tylko platforma), feature.aggrega.ai/ (oficjalne skróty encji Feature), component.aggrega.ai/ (cechy wewnętrzne encji Component), aggregate.aggrega.ai/ (tożsamość modułu Aggregate) oraz <any-other-domain>/ (przedsiębiorstwo / społeczność).
Kompilator nie odrzuca adnotacji zapisanej pod zarezerwowanym prefiksem w encji katalogu lub w encji Release; kompilację zatrzymuje tylko powiązanie adnotacji w encji Manifest lub etykieta wyjściowa encji Recipe, która zajmuje klucz pod aggrega.ai/. Przedsiębiorstwo, które deklaruje aggrega.ai/internal-billing-tag: "..." poza słownikiem platformy, tworzy adnotację akceptowaną przez kompilator i kaskadowaną przez system kubełków; późniejsze aktualizacje platformy wprowadzające rzeczywisty aggrega.ai/internal-billing-tag kolidują z nią po cichu.
Udokumentowano w: labels-and-annotations.md (Dyscyplina prefiksów) + providers/well-known-annotations.md.
Skutki naruszenia: własne adnotacje pod zarezerwowanymi prefiksami kolidują z przyszłymi adnotacjami platformy o tej samej nazwie; oczekiwane zachowanie platformy po cichu nadpisuje wartość nadaną przez przedsiębiorstwo lub współistnieje z nią, zależnie od kolejności.
Linter publikacji, uruchamiany przez aggrega lint, zgłasza jako ustalenie doradcze (E0277) klucz adnotacji encji katalogu pod aggrega.ai/, który nie jest jedną z dobrze znanych adnotacji platformy, oraz klucz pod feature.aggrega.ai/ w encji innej niż Feature. Klucze etykiet, pozostałe zarezerwowane prefiksy oraz adnotacje spoza metadata.annotations encji — na przykład te, które zapisuje encja Release — nie są sprawdzane, więc w ich przypadku dyscyplina pozostaje konwencją.
Odsyłacze
architecture/05-invariants.md— osiem założycielskich niezmienników, na których opiera się ujęcie Aggrega „kompilator jest neutralny wobec treści”; każda konwencja pozostaje w napięciu z co najmniej jednym z nich.architecture/02-ecosystem-philosophy.md— pełne uzasadnienie projektowe ontologii operacyjnej.vocabulary/labels-and-annotations.md— rozdział na trzy kategorie jako umowa społeczna; dyscyplina zastrzeżonych prefiksów.vocabulary/data-pillars.md— granice filarów jako drogowskazy; ujęcieprovides:ilocals:jako części publicznej i prywatnej.templates/sprig-functions.md— zastrzeżenie dotyczące determinizmu, wymieniające niehermetyczne funkcje pomocnicze.entities/recipe.md— dyscyplina nazewnictwa zasobów chmurowych + przykłady.entities/workload.md— semantyka podwójnego źródłavariables:w encji Workload.templates/expansion-matrix.md— samowystarczalnośćprovides:w encji Recipe jako reguła egzekwowana przez kompilator.plugins/plugin-contract.md— kryterium umieszczania w gnieździe lintera.cli/aggrega-lint.md— reguły lintera publikacji oraz dołączanie własnych linterów.