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

Component

Koncepcyjna rola encji Component (abstrakcyjnego interfejsu węzła obliczeniowego w Domenie 2) jest opisana w architecture/04-entity-taxonomy.md. Ta strona omawia powierzchnię tworzenia encji Component: taksonomię etykiet semantycznych (Semantic Label Taxonomy), za pomocą której architekci nakładają tożsamość kognitywną na operacyjną ontologię bazową, deklarację schema: dla filarów danych, deklaratywne tabele usesSchema i featuresSchema dla gniazd topologii i slotów dołączeń, wymogi obecności, mechanizm dziedziczenia extends: oraz blok reguł międzypolowych assertions:.

Taksonomia etykiet semantycznych (konwencja biblioteki standardowej)

Jeśli typy bazowe są czysto cloud-native, operacyjna i kognitywna inteligencja architektury jest nakładana wyłącznie przez semantyczne duck typing.

Rdzeń kompilatora w Go nie interpretuje tych etykiet. Kompilator buduje płaski graf reprezentacji pośredniej (IR), nie interpretując semantyki etykiet. Etykiety te stanowią konwencję biblioteki standardowej — niezmienne „markery genetyczne” tworzone przez architekta platformy w domenie 2. Dostarczają jawnych zaczepów semantycznych, których walidatory polityk Wasm i fizyczne Recipes operacyjne używają do zarządzania architekturą.

(A) Ogólna warstwa chmurowa Te etykiety opisują uniwersalne zachowania, pozwalając silnikom polityk i generowanym proxy L7 zarządzać standardowymi architekturami korporacyjnymi bez potrzeby natywnego rozumienia frameworków AI.

Prefiks etykietyDozwolone wartości (konwencja)Dlaczego Platform Ops tego potrzebuje (zaczep polityki)
tool.aggrega.ai/impactread-only, mutatingPozwala silnikom polityk oceniać autoryzację według zasady najmniejszych uprawnień. Narzędzia modyfikujące mogą automatycznie uruchamiać polityki wymagające dołączenia sidecarów ze ścisłą bramką zatwierdzania.
datastore.aggrega.ai/enginerelational, document, kv, vector, graph, semantic-memory, search (zbiór wartości stabilizuje się wraz z wypełnianiem katalogu)Pozwala silnikom polityk egzekwować bezpieczeństwo typów między węzłami (np. zapobiegać próbie wysłania przez agenta ładunków SQL do bazy wektorowej).
gateway.aggrega.ai/intelligencesemantic, l4-meshOkreśla, jakie funkcje router może fizycznie obsłużyć (np. zapobiega dołączeniu do standardowej siatki TCP encji Feature, która trasuje według modelu wskazanego w żądaniu, takiej jak łańcuch fallback).
dataplane.aggrega.ai/request-mirroringfull-rate, sampledPozwala encji Feature kopiującej ruch na żywo do drugiego miejsca docelowego wybrać proxy, które w ogóle potrafi kopiować, i odróżnić takie, które kopiuje każde pasujące żądanie, od takiego, w którym udział kopiowanych żądań można ustawić.
dataplane.aggrega.ai/caller-identityclient-certificate, injected-headerPozwala encji Feature, która wymaga identyfikacji pierwotnego wywołującego wobec usługi za proxy, wybrać komponent zdolny przekazać tę tożsamość i odczytać, jaki mechanizm ją przekazuje — przekazywane dalej szczegóły własnego certyfikatu TLS klienta albo nagłówek, który proxy samo składa po uwierzytelnieniu wywołującego.
dataplane.aggrega.ai/content-maskingentity-recognition, pattern-listPozwala encji Feature maskującej wrażliwy tekst wybrać komponent zdolny zastąpić go symbolem zastępczym w trasowanym ładunku czatu i uzupełnień, zanim tekst pójdzie dalej. Wartość określa wierność: przy entity-recognition komponent zastępuje dopasowania wzorców podanych w jego konfiguracji, a także typy encji wykrywane przez wywoływaną przez niego usługę rozpoznawania; przy pattern-list zastępuje wyłącznie dopasowania wzorców podanych w jego konfiguracji i nie wywołuje żadnej usługi rozpoznawania.
dataplane.aggrega.ai/prompt-guardpattern-list, classifierPozwala encji Feature sprawdzającej prompty modelu wybrać komponent zdolny przeanalizować trasowany ładunek czatu i uzupełnień oraz odrzucić żądanie na podstawie jego treści. Wartość określa wierność: przy pattern-list dopasowanie odbywa się względem wzorców podanych w jego konfiguracji, na ładunku modelu, a nie na dowolnym ciele HTTP; przy classifier werdykt wydaje wytrenowany klasyfikator tekstu, osiągany przez usługę wykrywania wywoływaną przez komponent, względem progu podanego w jego konfiguracji.
dataplane.aggrega.ai/upstream-tlstrust-anchorPozwala encji Feature, która wymaga, by proxy sprawdzało, z kim się komunikuje, wybrać komponent zdolny zweryfikować certyfikat upstreamu względem kotwicy zaufania dostarczanej przez Release.
dataplane.aggrega.ai/upstream-pinningpublic-keyPozwala encji Feature przypinającej, jaki klucz może przedstawić upstream, wybrać komponent zdolny odrzucić upstream, chyba że przedstawiony przez niego certyfikat zawiera jeden z kluczy publicznych dostarczanych przez Release. To inne stwierdzenie niż upstream-tls: przypięcie mówi, jakim kluczem certyfikat musi być, kotwica — co musi stwierdzać.
dataplane.aggrega.ai/period-budgetcost, tokensPozwala encji Feature ograniczającej, ile ruch może zużyć w danym okresie, wybrać komponent zdolny odrzucać żądania do modelu, gdy to, co zliczył w okresie, przekroczy limit ustawiony w jego konfiguracji. Wartość określa, co jest zliczane: cost — koszt ruchu, wyceniany według tabeli, którą komponent utrzymuje dla każdego modelu; tokens — tokeny, które odpowiedź każdego modelu raportuje jako odczytane, zapisane lub jedno i drugie, które komponent zlicza, niczego nie wyceniając.
dataplane.aggrega.ai/concurrency-captotal, per-targetPozwala encji Feature ograniczającej, ile żądań komponent obsługuje jednocześnie, wybrać komponent zdolny wstrzymać lub odrzucić żądanie powyżej limitu ustawionego w jego konfiguracji. Wartość określa, co zlicza jeden limit: total — każde żądanie przekazywane przez komponent, względem jednego limitu; per-target — żądania w toku do każdego celu upstream, do którego wysyła, z limitem dla każdego i bez limitu ich sumy.

Klucze dataplane.aggrega.ai/ nazywają pozycję na ścieżce ruchu, a nie rodzaj komponentu, więc proxy, brama ingress i service mesh opisują się w jednym słowniku, zamiast potrzebować każde własnego. Dwie właściwości tej rodziny warto przeczytać uważnie, ponieważ obie łatwo odwrócić:

  • Wartość niesie wierność, a nie tylko obecność zdolności. Dwa komponenty mogą oba lustrzanie kopiować żądania, a mimo to różnić się w sposób istotny dla encji Feature, więc rozróżnienie jest zawarte w wartości, a Feature wybiera potrzebną wierność. Komponent oferujący wyższą wierność ma wyższą wartość i żadnej innej.
  • Wartość stwierdza, co produkt potrafi zrobić, nigdy zaś, co wdrożenie włączyło. Obie rzeczy brzmią podobnie, a tylko pierwsza jest właściwością komponentu. Proxy, które potrafi zweryfikować certyfikat upstreamu, ma upstream-tls: trust-anchor niezależnie od tego, czy dane wdrożenie włącza tę kontrolę, ponieważ etykieta jest tym, według czego Feature wybiera, zanim cokolwiek zostanie skonfigurowane.

Komponent, który nie ma czego opisać na jednej z tych osi, nie ma tam żadnej wartości, zamiast najsłabszej, dokładnie jak w pozostałej części taksonomii: brak oznacza, że oś nie ma przedmiotu w tym komponencie, więc Feature wymagająca na niej dowolnej wartości słusznie nie zostaje dołączona.

(B) Wyspecjalizowana warstwa AI (tożsamość kognitywna) Te etykiety opisują kognitywną tożsamość obciążenia, pozwalając architekturze zabezpieczać nowoczesne frameworki AI.

Prefiks etykietyDozwolone wartości (konwencja)Dlaczego Platform Ops tego potrzebuje (zaczep polityki)
model.aggrega.ai/capabilitygenerative, embedding, transcriptionUżywane przez ciągi selektorów usesSchema (ewaluowane natywnie przez kompilator Go podczas analizy statycznej), aby zagwarantować, że programista przypadkowo nie skieruje generatywnego ładunku tekstowego do endpointu embeddingów.
model.aggrega.ai/apiopenai, anthropic, gemini, nativeOkreśla, jakie API modelu odpowiada pod adresem publikowanym przez komponent: openai, gdy jest to API OpenAI, własne API dostawcy lub jego implementacja w serwerze, anthropic, gdy jest to Messages API firmy Anthropic, własne API dostawcy lub jego implementacja w serwerze, gemini, gdy jest to Gemini API firmy Google, oraz native, gdy jest to własne API produktu i żadne z powyższych. Ma ją każdy komponent modelu, a także brama zdolna serwować API modelu, więc gniazdo wybierające component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api przyjmuje model lub taką bramę i odrzuca bramę niezdolną serwować żadnego, natomiast gniazdo wskazujące jedną wartość, np. model.aggrega.ai/api=anthropic, przyjmuje tylko to, co serwuje to API. Etykieta określa, co produkt serwuje, a nie co podłącza jedna encja Release: brama, której modele są podłączone do jej własnego gniazda, ma ją także wtedy, gdy nic nie jest podłączone. Etykieta jest ciągiem dopasowywanym przez selektor; nic nie sprawdza, co faktycznie odpowiada pod adresem.
agent.aggrega.ai/autonomyautonomous, copilotOkreśla ryzyko wykonania pętli kognitywnej, pozwalając politykom wymagać funkcji zatwierdzania przez człowieka dla w pełni autonomicznych agentów.

(C) Etykiety przekrojowe (zarządzanie, stan i sprzęt) To podstawowe znaczniki korporacyjne, które napędzają walidację Zero-Trust i trasowanie sprzętowe.

Prefiks etykietyDozwolone wartości (konwencja)Dlaczego Platform Ops tego potrzebuje (zaczep polityki)
component.aggrega.ai/hostingself-hosted, managed, external, mixedZapisuje, kto obsługuje zasób leżący u podstaw komponentu — oś granicy zaufania. Silniki polityk odczytują ją, aby obliczyć ryzyko eksfiltracji danych (np. dane wewnętrzne kierowane do zewnętrznego API managed opuszczają granicę operatora). Przekrojowo: te same wartości opisują zarówno zarządzaną bazę danych, zarządzane API modelu, jak i samodzielnie uruchamiany serwer inferencji. mixed oznacza komponent, którego encje Recipes obejmują więcej niż jeden model obsługi — magazyn danych hostowany samodzielnie przez swoje Recipes dla Helm i Compose, a zarządzany przez swoje Recipes dla RDS — więc model obsługi encji Release wynika z encji Recipe wybranej przez jej Manifest.
compliance.aggrega.ai/data-classpublic, internal, restrictedKlasa danych przechowywanych przez komponent. Kompilator przenosi ją do grafu kompilacji jako ciąg znaków i niczego nie szereguje; polityka, którą operator dołącza w roli ir-verdict, nadaje klasom kolejność we własnych ustawieniach i odczytuje etykietę wzdłuż tras wyliczanych przez kompilator — zatrzymując na przykład kompilację, w której komponent restricted dociera do komponentu innej klasy bez dołączonej na trasie encji Feature obniżającej klasyfikację (policy-data-class-route). Żaden Component biblioteki standardowej jej nie nosi: klasa jest stwierdzeniem o tym, jak dana organizacja używa komponentu, i nosi ją własny Component organizacji — na przykład specjalizacja przez extends.
compliance.aggrega.ai/contains-piitrue, falseJawnie oznacza workloady objęte zakresem GDPR/CCPA. Polityka dołączona przez operatora może ją odczytać, aby wymagać określonych encji Features na trasach, którymi przebiega ruch takiego workloadu — na przykład core/data-masking na bramie AI, przez którą wysyła on ruch do modeli; jest to kształt, który policy-data-class-route sprawdza dla klasy danych. Żaden Component biblioteki standardowej jej nie nosi; podobnie jak klasa danych, jest to stwierdzenie organizacji o jej własnych komponentach.
hardware.aggrega.ai/acceleratorgpu, tpu, npuUżywana przez DevOps w pliku Release. Jawnie kierują oni te komponenty do fizycznych granic pul sprzętowych (np. klastra z GPU) za pomocą mapy components: {}, a rola werdyktu zarządczego może wymuszać, by komponenty oznaczone etykietą GPU nigdy nie trafiały do granic bez GPU.
state.aggrega.ai/retentionretain, deleteRozwiązuje problem usuwania w AOT. Jeśli programista usunie bazę danych ze swojej encji Aggregate, orkiestrator GitOps fizycznie usunie dysk. Krok pipeline: encji Recipe może odczytać etykietę retain i dodać do wyrenderowanych artefaktów natywną ochronę orkiestratora (np. helm.sh/resource-policy: keep).
state.aggrega.ai/backup-tiermission-critical, standard, ephemeralPunkt zaczepienia dla dostępności SOC2. Informuje operacyjną encję FeatureRecipe, czy fizycznie wygenerować dla zasobu automatyczne konfiguracje migawek i kopii zapasowych woluminów.

(D) Dynamiczny kontekst biznesowy (kaskadowe adnotacje) Podczas gdy labels definiują niezmienne DNA katalogu, dynamiczne konteksty biznesowe (takie jak zakres audytu SOC2 czy śledzenie kosztów FinOps) zmieniają się w zależności od tego, kto wdraża aplikację i gdzie ona działa. Są one regulowane przez adnotacje wstrzykiwane dynamicznie przez subsystems programisty, granice operacyjnej encji Release lub plugin zarządczy dołączony w roli annotation-transform.

Prefiks adnotacjiDozwolone wartości (konwencja)Dlaczego Platform Ops tego potrzebuje (zaczep polityki)
business.aggrega.ai/cost-centernp. finance, ai-researchWymagana przez pluginy renderujące Wasm do wstrzykiwania fizycznego tagowania (np. tagów AWS lub etykiet K8s) do końcowych generowanych artefaktów na potrzeby paneli rozliczeń chmurowych.
business.aggrega.ai/ownernp. team-alpha@corp.comKierowanie reagowania na incydenty. Gwarantuje, że infrastruktura jest przypisana do zespołu ludzi.
compliance.aggrega.ai/frameworksnp. soc2, hipaaWyzwalacz zakresu SOC2. Wstrzykiwana przez encję Release środowiska. Pluginy Wasm odczytują ten ciąg znaków, aby automatycznie generować ścisłe sidecary logowania audytowego i wyłączać porty debugowania, gdy aplikacja wchodzi w produkcyjną granicę zgodności.

Taksonomia jest konwencją katalogu, a nie regułą kompilatora. Przedsiębiorstwa mogą ją zignorować, usunąć lub wymyślić własne słownictwo etykiet (mycompany.com/custom-trait). Pluginy Wasm oceniają dowolne klucze etykiet, które utworzy przedsiębiorstwo.

Tworzenie schematów

Schemat Component (oraz jego odpowiednik Feature, w tym encje Features poświadczeń oznaczone etykietą feature.aggrega.ai/kind: secret) deklaruje kontrakt walidacji dla tworzonych przez programistę values za pomocą bloku spec.schema:. Blok przyjmuje JSON Schema 2020-12 wyrażony albo w skróconej formie zwartej YAML (domyślnej; około 15 słów kluczowych, mechanicznie przekształcanych do JSON Schema w czasie kompilacji), albo w pełnym YAML JSON Schema (forma rozwlekła), z odwołaniami międzydokumentowymi przez $ref: do wpisów SchemaLibrary współdzielonych przez wiele encji Components.

  • Wbudowana forma zwarta (domyślna powierzchnia tworzenia): osadzony blok YAML zawierający liście formy zwartej bezpośrednio w YAML encji Component. Mieści zdecydowaną większość treści schematów katalogu w ułamku liczby wierszy pełnego JSON Schema. Słownik słów kluczowych i konwencje tworzenia opisuje vocabulary/compact-form-authoring.md.
  • Wbudowany YAML JSON Schema: forma rozwlekła, odpowiednia, gdy schemat potrzebuje słów kluczowych JSON Schema 2020-12, których forma zwarta nie obsługuje bezpośrednio ($dynamicRef, głębokie unevaluatedProperties, złożona kompozycja not:). Formę zwartą i JSON Schema można mieszać na granicy dowolnego węzła w obrębie jednego bloku schema: za pomocą furtki $jsonschema:.
  • Odwołanie międzydokumentowe ($ref: do wpisu SchemaLibrary): natywne dla JSON Schema $ref: wskazujące wpis SchemaLibrary według tożsamości (Datastores#/schemas/MariaDBValues lub podobnie). Schematy korporacyjne liczące setki wierszy i używane ponownie przez wiele encji Components znajdują się w encjach SchemaLibrary; konsumująca encja Component odwołuje się do wpisu bez wstawiania jego treści. Encję biblioteki i semantykę rozwiązywania opisują entities/schemalibrary.md oraz vocabulary/cross-document-ref.md.

Trzy powyższe formy służą do tworzenia treści filarów i są dostępne dla encji Component, która niczego nie rozszerza. Encja Component deklarująca extends: nie tworzy żadnej treści filarów: zapisuje dosłowny znacznik schema: inherited i otrzymuje blok filarów swojej bazy dokładnie w takiej postaci, w jakiej utworzyła go baza. Ten znacznik jest jedyną wartością, jaką schema: przyjmuje w takiej encji Component. Zob. „Tworzenie katalogu: rozszerzanie bazowych encji Components” poniżej.

Kompilator rozwiązuje blok schema: — rozwijając formę zwartą, dereferencjonując adresy URL $ref:, stosując łańcuchy biblioteka–biblioteka SchemaLibrary — i unifikuje wynikowy JSON Schema z automatycznie generowanymi bazami wyprowadzonymi z usesSchema i featuresSchema (zob. sekcję poniżej) podczas przebiegu walidacji encji Component. Walidacja odbywa się względem rozwiązanego schematu; ścieżka tworzenia jest nieprzejrzysta dla dalszych etapów potoku.

Utworzone instancje są walidowane względem tego rozwiązanego schematu w czasie budowania: tworzone przez programistę values instancji komponentu i rozwiązane przez operatora infra, a także values/infra w każdym dołączeniu Feature, muszą być zgodne z zadeklarowanymi filarami — wartość złego typu, liczba spoza zakresu, ciąg znaków niezgodny z zadeklarowanym format, brak wymaganego pola lub (dla values, walidowanego jako zamknięty) niezadeklarowana właściwość zatrzymuje budowanie w miejscu źródła zamiast tworzyć uszkodzony manifest w czasie wdrożenia. Filar, którego schemat podaje format niesprawdzany przez kompilator — cokolwiek poza email, uri, hostname, ipv4, ipv6, uuid, date-time i date, w tym password — jest odrzucany przy wczytywaniu katalogu z listą obsługiwanych nazw; co sprawdza każda nazwa, opisuje vocabulary/compact-form-authoring.md. Instancja encji Component, która extends: bazę, jest walidowana względem bloku filarów bazy, dziedziczonego bez zmian przez rozszerzającą encję Component — dlatego instancja bazy i instancja czegokolwiek, co ją rozszerza, podlegają temu samemu kontraktowi filarów. Diagnostykę i reguły dla poszczególnych filarów (w tym sposób walidacji infra względem sumy kluczy encji Component i dostawcy) opisuje errors/fatal-halts.md §„Authored values or infra do not conform to the declared schema (Utworzone values lub infra nie są zgodne z zadeklarowanym schematem)”.

Zadeklarowane wartości domyślne materializują się w renderowanych filarach. Poza walidacją default: zadeklarowany w polu values (lub w polu infra) jest wstawiany do renderowanego filaru w czasie budowania dla każdego klucza pominiętego przez autora — dzięki temu szablon Recipe odczytujący {{ .values.charset }} otrzymuje zadeklarowane w schemacie utf8mb4 zamiast pustej wartości. Wartości podane przez autora zawsze mają pierwszeństwo; zagnieżdżone obiekty są uzupełniane dla każdego pominiętego elementu podrzędnego. Ponieważ materializacja używa tego samego rozwiązywania schematu co walidacja, materializują się także wartości domyślne osiągane przez międzydokumentowe $ref: do SchemaLibrary — zarówno odwołanie do całego filaru (values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}), jak i kształt baza-plus-wariant (bazowe $ref: obok sąsiednich properties, z których każde ma własne wartości domyślne). Wartości domyślne zadeklarowane wyłącznie w lokalnym odwołaniu wewnątrzdokumentowym #/$defs/ lub w gałęzi allOf / oneOf / anyOf nie są materializowane; biblioteka standardowa składa filary przez międzydokumentowe $ref:, które jest materializowane.

Filar values

Schemat encji Component rozdziela trzy filary według własności: values wypełnia Developer w encji Aggregate (intencja poznawcza — nazwa bazy danych, wersja, zestaw znaków), infra wypełnia Operator w encji Release (wymiarowanie operacyjne — moc obliczeniowa, pamięć masowa, HA), a provides ustawia Recipe (publiczny kontrakt API — host, port, protokół). Developer nigdy nie widzi infra; Operator nigdy nie widzi values. Encje Recipes konsumują oba filary podczas renderowania bazowego, odwzorowując abstrakcyjne filary na konkretny kształt oczekiwany przez docelowego dostawcę. Ta sekcja opisuje powierzchnię tworzenia filaru values. Szerszą taksonomię filarów i dyscyplinę kaskady między filarami opisuje vocabulary/data-pillars.md.

values zawiera intencję poznawczą Developera — wybory opisujące, czym aplikacja jest lub co robi, a nie jak jest wymiarowana lub uruchamiana. Nazwa bazy danych, zestaw znaków, wersja silnika, poziom logowania, flagi funkcji oraz ustawienia warstwy aplikacji, które zmieniają się między wersjami aplikacji, ale pozostają stałe między środowiskami, to typowa treść values. Operator nigdy nie nadpisuje values: (schemat encji Release mechanicznie odrzuca blok values: zgodnie z architecture/06-data-taxonomy-and-composition.md §8 Constraint 4); zmienność między środowiskami przepływa przez Parameter Hoisting — encja Aggregate udostępnia typowane parameters.*, szablon values encji Component się do nich odwołuje, a encja Release dostarcza wartości parametrów.

# Component schema declares the values shape:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
charset: { type: string, default: utf8mb4, enum: [utf8mb4, latin1, ascii] }
engine_version: { type: string, default: "10.11" }
log_level: { type: string, default: info, enum: [debug, info, warn, error] }
# Aggregate fragment — the developer fills values:
components:
customer-db:
type: core/datastore/mariadb
values:
database_name: customers
charset: utf8mb4
engine_version: "{{ .parameters.mariadb_version }}" # Parameter Hoisting
log_level: info

Konsumpcja po stronie encji Recipe. Encje Recipes odczytują rozwiązane wartości przez .values.<field> w valuesMapping:, provides:, assertions: i innych powierzchniach szablonów — macierz dostępności dla poszczególnych szablonów zawiera entities/recipe.md. Kompilator unifikuje schemat values encji Component ze schematami values: dołączonych encji Feature w tym samym węźle Component, dzięki czemu rozwiązany kontekst szablonu zawiera każde mające zastosowanie pole.

Dyscyplina między filarami. values to jedyny filar, który Developer tworzy w encji Aggregate. Należą tu wyłącznie pola przeznaczone dla dewelopera; parametry operacyjne (liczby replik, limity CPU/pamięci) należą do filaru infra encji Component, aby znajdowały się w encji Release; publiczne wyjście (host, port) należy do provides encji Recipe. Mieszanie ich narusza niezmiennik własności; rzadkie przypadki, w których celowe przekazywanie między filarami jest uzasadnione, opisuje vocabulary/data-pillars.md „Cross-pillar mechanics”.

Filar infra

Schemat encji Component rozdziela trzy filary według własności: values wypełnia Developer w encji Aggregate (intencja poznawcza — nazwa bazy danych, wersja, zestaw znaków), infra wypełnia Operator w encji Release (wymiarowanie operacyjne — moc obliczeniowa, pamięć masowa, HA; kopii zapasowej magazynu danych nie wymiaruje się tutaj — jest nią Feature core/backup, który Operator dołącza w encji Release), a provides ustawia encja Recipe (publiczny kontrakt API — host, port, protokół). Developer nigdy nie widzi infra; Operator nigdy nie widzi values. Encje Recipes konsumują oba filary podczas renderowania bazowego, odwzorowując abstrakcyjne filary na konkretny kształt, którego oczekuje ich docelowy provider.

Trzy konwencje dotyczące infra mają znaczenie dla każdej agnostycznej wobec możliwości encji Component w bibliotece standardowej: otwarta struktura jako furtka dla ustawień specyficznych dla providera, opcjonalne nadpisanie wersji artefaktu upstream oraz słownictwo oparte na intencji dla pól wysokiej dostępności. Kanoniczną referencyjną encją Component jest core/datastore/mariadb w katalogu biblioteki standardowej — implementowalna przez encje Recipes Helm, które uruchamiają oficjalny obraz mariadb lub przekazują zasób niestandardowy MariaDB kontrolerowi mariadb-operator, encje Recipes Terraform dla AWS RDS, encje Recipes CloudFormation dla tej samej powierzchni RDS oraz encje Recipes Compose dla lokalnego kontenera — a jej blok infra ilustruje pierwszy i trzeci wzorzec.

infra.overrides

Uniwersalne pola infra — compute, storage, ha — obejmują większość wymiarowania operacyjnego u różnych providerów. Pozostała część jest nieredukowalnie specyficzna dla providera: encja Recipe dla Kubernetes potrzebuje nodeSelector, encja Recipe Terraform dla RDS potrzebuje instance_class, encja Recipe CloudFormation dla RDS potrzebuje DBInstanceClass, a encja Recipe Compose potrzebuje nadpisania image. Schemat encji Component udostępnia prawdziwie otwartą mapę jako furtkę, dzięki której te ustawienia przepływają bez rozdmuchiwania schematu:

infra:
# ... universal fields ...
# Provider-specific overrides. Accepts any nested structure.
# Each Recipe documents which keys it reads.
overrides:
type: object
additionalProperties: true # genuinely open map: arbitrary nested structure permitted

Jawne type: object z additionalProperties: true włącza semantykę otwartej mapy. Kompilator przekazuje strukturę bez zmian; treść szablonu encji Recipe odczytuje klucze, które zna, i ignoruje pozostałe. Każda encja Recipe dokumentuje ontologię kluczy nadpisań w komentarzu nagłówkowym, dzięki czemu Operator tworzący encję Release dla konkretnej kombinacji Component × Recipe wie, jakie ustawienia udostępnia dana encja Recipe.

Fragment encji Release używający nadpisań:

components:
main-db:
infra:
compute: { cpu: "2", memory: 8Gi }
storage: { size: 40Gi, type: balanced-csi }
overrides:
nodeSelector:
kubernetes.io/hostname: cluster1-worker1
service_type: LoadBalancer
metrics:
enabled: true
image:
repository: bitnamilegacy/mysqld-exporter

Developer nigdy nie widzi overrides — znajduje się ono w encji Release, która jest domeną Operatora.

infra.source_version

Pole source encji Recipe wskazuje artefakt upstream w określonej wersji (chart Helm 25.0.8, moduł Terraform 4.2.0, tag obrazu OCI). Zakodowanie wersji na sztywno w encji Recipe zmusza opiekuna katalogu do publikowania nowej encji Recipe przy każdym zgodnym podbiciu wersji upstream. Schemat encji Component udostępnia opcjonalne nadpisanie:

infra:
source_version:
type: string
description: |
Source artifact version. A Recipe versions its artifact from this key
where its source resolution reads it, and is unaffected where it does not.
Changing from the version a Recipe was authored against does not
guarantee value mapping compatibility.

Encja Recipe odczytuje je za pomocą funkcji pomocniczej optional w swoim bloku source, więc brak przypięcia oznacza przejście do wersji, dla której encja Recipe została napisana:

source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "{{ optional .infra `source_version` `25.0.8` }}"

Ciągi source encji Recipe (oraz podpola o wartościach tekstowych strukturalnej mapy source:) są ewaluowane jako szablony Go. Zdalna współrzędna — taka jak version powyżej — jest ewaluowana, gdy aggrega pull przypina artefakt, względem .values, .infra i .locals, bez korzenia .context; źródło wskazujące ścieżkę w przestrzeni roboczej jest ewaluowane podczas renderowania encji, względem tego samego samowystarczalnego kontekstu co locals encji Recipe — .context.instance_id, .values, .infra oraz całe rozwiązane .locals węzła. W obu przypadkach .context.inject, .context.uses i .provides są zabronione. To obecność .infra w tym kontekście sprawia, że powyższe nadpisanie działa, a .locals pozwala encji Recipe obliczyć fragment źródła raz i odczytać go tutaj. Szablon źródła nigdy nie odczytuje provides własnego węzła: ten filar nie jest częścią kontekstu, a szablon, który próbuje po niego sięgnąć, zatrzymuje kompilację — jest to stała właściwość tej powierzchni, a nie luka czekająca na dalsze prace. Pełne reguły dostępności opisuje wiersz nr 5 macierzy rozwijania szablonów. Zmiana infra.source_version z wartości domyślnej encji Recipe nie gwarantuje, że valuesMapping encji Recipe jest zgodne na poziomie formatu z nową wersją upstream; to ostrzeżenie zawiera description deklaracji source_version w schemacie encji Component.

infra.ha.*

Pola wysokiej dostępności używają słownictwa intencji, a nie słownictwa mechanizmu:

infra:
ha:
enabled: { type: boolean, default: false }
read_replicas: { type: integer, min: 0, default: 0 }

infra.ha.enabled oznacza „zapewnij wysoką dostępność tej encji Component”, a infra.ha.read_replicas oznacza „chcę N kopii tylko do odczytu”. Każda encja Recipe decyduje, czym staje się ta intencja u jej providera. Encje Recipes biblioteki standardowej dla core/datastore/mariadb, pod nazwami, pod którymi mapuje je Manifest:

Recipeha.enabled: true odwzorowuje się naha.read_replicas: N odwzorowuje się na
helm/mariadb (StatefulSet na oficjalnym obrazie mariadb)uruchamia jeden serwer, więc kompilacja zatrzymuje się ze wskazaniem kluczauruchamia jeden serwer, więc N większe od 0 zatrzymuje kompilację
helm/mariadb-cluster (zasób niestandardowy MariaDB uzgadniany przez kontroler mariadb-operator)włącza automatyczne przełączanie awaryjne (replication.primary.autoFailover: true); przełącza na replikę do odczytu, więc N równe 0 zatrzymuje kompilacjęustawia spec.replicas na N + 1 i włącza replikację; provides.host staje się usługą Service <name>-primary
terraform/mariadb-rds (AWS RDS)ustawia multi_az = true na głównym aws_db_instancetworzy N osobnych zasobów repliki odczytu aws_db_instance
terraform/mariadb-rds-module, terraform/mariadb-rds-terraform-aws-modules (AWS RDS przez moduł)przekazuje multi_az = true do modułutworzy jedną instancję, więc N większe od 0 zatrzymuje kompilację
cloudformation/mariadb-rds (AWS RDS)ustawia MultiAZ: true na AWS::RDS::DBInstancetworzy jedną instancję, więc N większe od 0 zatrzymuje kompilację
compose/mariadb (lokalny kontener deweloperski)uruchamia jeden serwer, więc kompilacja zatrzymuje się ze wskazaniem kluczauruchamia jeden serwer, więc N większe od 0 zatrzymuje kompilację

Słownictwo mechanizmu (infra.primary.replicas) brzmi naturalnie dla jednego providera (pody Kubernetes są replikami StatefulSet), a gdzie indziej jest błędem kategorii — RDS nie ma pojęcia „replik” na instancji głównej, CloudFormation odzwierciedla RDS, a Compose w ogóle nie ma abstrakcji replik poziomych. Słownictwo intencji daje się przełożyć: każdy provider ma jakieś pojęcie „zapewnij wysoką dostępność tej bazy danych” i jakieś pojęcie „chcę N kopii tylko do odczytu”, a encja Recipe zawiera przełożenie specyficzne dla providera. Gdy realizacja nie ma takiego mechanizmu, jej encja Recipe może zatrzymać kompilację ze wskazaniem klucza, jak robią to helm/mariadb i compose/mariadb dla obu kluczy oraz jednoinstancyjne encje Recipes RDS dla replik do odczytu.

infra.ha.read_replicas: 0 jest wartością domyślną; gdy oba klucze mają wartości domyślne, helm/mariadb-cluster renderuje jednoinstancyjną bazę MariaDB bez bloku replication, a nie replikację na jednej instancji. compose/mariadb uruchamia jeden serwer na lokalnym hoście Docker, więc infra.ha.enabled: true lub niezerowe infra.ha.read_replicas zatrzymuje kompilację ze wskazaniem klucza, a komunikat odsyła do helm/mariadb-cluster, który zapewnia przełączanie awaryjne i repliki do odczytu.

Filar provides

provides to publiczne API tworzone przez autora encji Recipe — wartości, które rozwiązana encja Recipe danej encji Component przekazuje wywołującym w dół łańcucha przez ich powierzchnię .context.uses.<alias>.provides.<provided-name> (lub, gdy wywołujący deklaruje na krawędzi listę dozwolonych inject:, przez jego potok .context.inject). Schemat encji Component deklaruje kształt (nazwy kluczy oraz typy); blok provides: powiązanej encji Recipe dostarcza wartości. Programista tworzący encję Aggregate widzi kształt provides na stronie encji Component jako kontrakt, na którym wywołujący mogą polegać; autor encji Recipe wypełnia ten kontrakt dla konkretnej implementacji, którą opakowuje.

Wypełnienie kontraktu jest egzekwowane jako Loud Guardrail: powiązana encja Recipe musi wytworzyć każdy klucz provides, który deklaruje jej encja Component. Jeśli powiązana encja Recipe pomija zadeklarowany klucz, kompilacja zostaje przerwana ze wskazaniem brakującego klucza, zamiast po cichu nie dostarczyć niczego wywołującym, którzy się do niego odwołują. Wytwarzanie dodatkowych kluczy poza zadeklarowanym zbiorem jest dozwolone. Sprawdzana jest wyłącznie obecność kluczy — wytworzone wartości to nieprzezroczyste ciągi znaków, które kompilator przekazuje dalej, więc ich zadeklarowane typy pozostają kontraktem odczytywanym przez wywołujących, a nie wartością walidowaną przez kompilator.

# Component schema declares the provides contract:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
provides:
host: { type: string }
port: { type: integer }
database: { type: string }
# Recipe fulfills the contract:
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-bitnami
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "25.0.8"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
database: "{{ .values.database_name }}"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

Podział ewaluacji na provides i inject. Kompilator ewaluuje szablony provides: na etapie ewaluacji provides względem samowystarczalnego kontekstu szablonu (.context.instance_id, .context.rendered_name, o ile dostawca węzła ją zgłasza, .values, .infra oraz rozwiązane locals: encji Recipe w tym samym węźle) — żaden stan wywołującego nie jest widoczny. Zmienne lokalne węzła są rozwiązywane w preambule tego etapu, przed jego provides, dzięki czemu szablon provides: może odczytać .locals. Na etapie hydratacji inject, który następuje potem, kompilator przechodzi po krawędziach uses: i rozwiązuje .context.uses.<alias>.provides.<provided-name> każdego wywołującego względem rozwiązanych wartości provides. Rozdzielenie obu etapów gwarantuje acykliczne rozwiązywanie: provides: nie może odwoływać się do wywołującego, a inject: wywołującego nie może odwoływać się do jeszcze nierozwiązanego wyjścia dostawcy, dopóki nie zostanie uruchomiona hydratacja inject.

Ewolucja kontraktu. Zmiana nazwy lub usunięcie pola provides jest zmianą niekompatybilną dla każdego wywołującego, który polega na starej nazwie. metadata.version encji Component (oraz deklaracja implements: encji Recipe) przenosi sygnał ewolucji kontraktu; wywołujący niższego poziomu przypięci do konkretnej wersji głównej widzą stabilny kształt provides.

Nauka po stronie encji Recipe. Gramatykę tworzenia szablonów provides:, macierz dostępności dla poszczególnych szablonów oraz przykłady routingu między przestrzeniami nazw i między regionami opisują entities/recipe.md, sekcja „The provides: block”, oraz architecture/06-data-taxonomy-and-composition.md §3.

Wymogi obecności: features.aggrega.ai/requiredType.<label>

Encja Component może zadeklarować, że każda jej instancja musi mieć dołączenie Feature danego typu. Jest to wymóg obecności, który definiuje się jako powtarzalną adnotację we własnych metadanych encji Component:

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/payment-processor
version: 1.0.0
labels:
component.aggrega.ai/type: server
annotations:
features.aggrega.ai/requiredType.audit: core/audit-logging
features.aggrega.ai/requiredType.compliance: core/pci-compliance
spec:
schema:
values:
processor_endpoint: { type: string, required: true }

Kluczem jest prefiks features.aggrega.ai/requiredType., po którym następuje wybrana etykieta; wartością jest URI typu Feature, który musi mieć co najmniej jedno dołączenie. Etykieta nazywa wymaganie w komunikacie diagnostycznym generowanym przy niespełnionym wymogu — powyżej audit i compliance — i to jest jej jedyne zadanie. Klucze z etykietami pozwalają encji Component zadeklarować kilka wymogów naraz: adnotacje są płaską mapą łańcuchów i nie mogą zawierać zduplikowanego klucza.

Kompilator ocenia każdy nakaz względem końcowego zestawu dołączeń instancji, po tym jak kaskada 5-Tier Onion Model złożyła wszystkie zakresy: bloki features: w encji Aggregate na poziomie komponentu i podsystemu, bloki features: w encji Release na poziomie granicy i komponentu oraz dołączenia powstałe w wyniku rozwijania sterowanego adnotacjami. Każde z nich spełnia nakaz — reguła sprawdza, co jest obecne, a nigdy, jak się tam znalazło. Dlatego encja Component, której nakaz jest spełniony tylko dlatego, że operator ustawił adnotację monitorowania w encji Release, przechodzi dokładnie tak samo jak taka, do której programista ręcznie dołączył encję Feature.

Wymóg, którego nie spełnia żadne dołączenie, zatrzymuje kompilację z komunikatem diagnostycznym podającym instancję komponentu, etykietę wymagania i wymagany typ. Wartość adnotacji jest nieprzezroczystym łańcuchem, więc nic nie weryfikuje jej postaci, zanim odczyta ją kompilator; wartość niebędąca URI typu Feature albo klucz bez etykiety po prefiksie zatrzymuje więc kompilację z osobnym komunikatem diagnostycznym informującym, że deklaracja jest błędna. Oba przypadki są celowo rozróżnione: błędną deklarację poprawia się w encji katalogu, a niespełnione wymaganie rozwiązuje się przez dołączenie Feature — literówka nigdy nie może zostać odczytana jako spełnione wymaganie.

Oba komunikaty diagnostyczne są opisane w errors/fatal-halts.md „Required feature not attached (Wymagana funkcja nie została dołączona)”.

Wymóg nie jest slotem. Te dwa mechanizmy odpowiadają na różne pytania, a różnica nie jest kosmetyczna:

slot featuresSchemawymóg obecności
Deklarujenazwany punkt powiązaniaograniczenie dotyczące tego, co musi być obecne
Nazwę można dereferencjonowaćtak — from: <slot> i .features.<slot>.provides.*nie — etykieta nazywa wymaganie i nic więcej
Krotnośćdokładnie jedno wypełnienie na slotco najmniej jedno dołączenie danego typu
Ogranicza wypełnienieselector, inject, sensitivenic poza typem
Spełniany przez swobodne dołączenienie — slot wypełnia się po nazwietak — w dowolnym zakresie, pod dowolną nazwą
Gdy żądanie nie jest spełnionezatrzymuje, gdy ustawiono required: true i nic nie wiąże nazwy slotuzatrzymuje, gdy żadne dołączenie nie ma danego typu

Oba żądania są sprawdzane względem tych samych danych wejściowych — końcowego zbioru dołączeń instancji — i oba zatrzymują kompilację z własnym komunikatem diagnostycznym, ponieważ zadają mu różne pytania: czy jeden nazwany punkt powiązania jest powiązany, a czy jakieś dołączenie ma nazwany typ. Żadne z nich nie zastępuje drugiego.

Slotu należy użyć, gdy Recipe musi odczytać, co zostało dołączone. Wymogu należy użyć, gdy kontrakt encji Component wymaga obecności danej możliwości, a nie ma znaczenia, która instancja ją dostarcza. Encja Component do przetwarzania płatności, która wymaga core/audit-logging, otrzymuje logowanie audytowe w każdym wdrożeniu niezależnie od tego, czy programista pamiętał o jego dołączeniu; encja Component zgodna z PCI, która wymaga core/pci-compliance, nie może zostać wdrożona bez dołączenia Feature zgodności gdzieś we wdrożeniu.

Dziedziczenie. Wymóg zadeklarowany w bazowej encji Component dziedziczy każda encja Component, która ją rozszerza przez extends:, ponieważ adnotacje metadanych są scalane wzdłuż łańcucha rozszerzeń, przy czym dla każdego klucza wygrywa potomek. Potomek może zatem przekierować odziedziczony wymóg, ponownie deklarując tę samą etykietę z innym typem, albo dodać własne wymogi pod nowymi etykietami; nie może jednak usunąć wymogu zadeklarowanego w bazie.

Gniazda topologii: usesSchema

Encja Component może deklarować gniazda topologiczne w bloku usesSchema: — deklaratywnej mapie YAML równoległej do featuresSchema. Każdy wpis nazywa gniazdo, przez które encja Component przyjmuje zależności między komponentami, i określa, jakie kształty encji Component programista może podłączyć do tego gniazda. Kompilator automatycznie generuje reguły walidacji JSON Schema 2020-12 z zadeklarowanych gniazd i scala je z schema: encji Component podczas rozwiązywania encji Component; programiści nie piszą ręcznie filaru uses: wewnątrz schema:, ponieważ struktura pochodzi z usesSchema.

# Component declares the sockets it accepts:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/ai-agent/orchestrator
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
primary_datastore:
required: true
selector: "datastore.aggrega.ai/engine=vector"
inject: [env]
cache:
required: false
selector: "datastore.aggrega.ai/engine=kv"
inject: [env, file]
log_destination:
required: false
selector: "component.aggrega.ai/category=messaging"
inject: []
# Aggregate fragment — developer wires the sockets:
components:
agent:
type: core/ai-agent/orchestrator
uses:
primary_datastore:
main: { target: vector-db-instance }
log_destination:
audit: { target: audit-sink }

Formy podłączania — gniazdo przyjmuje jeden lub wiele celów. Powyższe przykłady podłączają każde gniazdo do jednego celu, ale gniazdo może rozgałęziać się na kilka. Wartość gniazda zapisuje się w jednej z dwóch form:

uses:
# Compact form — a list of target names. Each entry produces an edge
# whose alias equals its target. Use it for the single-target case, and
# when one socket connects to several peers of the same shape.
shards: [orders-db, customers-db, inventory-db]
# Verbose form — an alias-keyed map. Each alias maps to an entry object
# carrying its own `target:`, and may carry its own inject directives.
# Use when the connections need distinct names or per-edge inject.
databases:
primary: { target: orders-db, inject: { env: [{ in: DB_URL, from: url }] } }
replica: { target: orders-db-ro, inject: { env: [{ in: DB_REPLICA_URL, from: url }] } }

Alias zawsze wskazuje obiekt wpisu, nigdy samą nazwę celu: databases: { primary: orders-db } jest odrzucane przy wczytywaniu, podobnie jak obiekt wpisu bez target:. Aby podłączyć pojedynczy cel bez wymyślania aliasu, należy użyć formy zwartej — primary_datastore: [vector-db-instance] — która nazywa cel raz i wyprowadza z niego alias.

Każdy wpis — element listy lub alias mapy — staje się jedną krawędzią, zachowaną w kolejności zapisu. selector: gniazda dotyczy każdego celu podłączonego przez nie (każda krawędź jest sprawdzana pod kątem typów niezależnie podczas analizy statycznej), a required: true oznacza, że musi być podłączony co najmniej jeden cel.

Semantyka pól:

PoleTypDomyślnieZnaczenie
requiredboolfalsePrzy true programista musi podłączyć do tego gniazda co najmniej jedną zależność. Przy false gniazdo jest opcjonalne.
selectorstring—Selektor etykiet, w gramatyce używanej przez appliesTo encji Feature, który musi spełniać cel każdej krawędzi podłączonej przez to gniazdo. Jest odczytywany jako zapisany tu ciąg i ewaluowany względem etykiet celu podczas analizy statycznej: cel, którego etykiety go nie spełniają, zatrzymuje kompilację, podobnie jak selektor odrzucony przez gramatykę, z nazwaniem wymagania, którego nie dało się odczytać. Pusty selektor nie nakłada na cel żadnego ograniczenia.
injectstring[]—Lista dozwolonych mechanizmów dostarczania inject (równoległa do featuresSchema[].inject). Brak lub [] (pusta) oznacza czarną skrzynkę — we wpisie uses: programisty nie jest dozwolony blok inject:; dostarczanie kontroluje encja Recipe. [env, file, arg] (niepusta) oznacza przezroczystość — programista może wskazać, który mechanizm dostarcza wartości provides zależności. Egzekwowane: zob. „Gdzie egzekwowana jest lista dozwolonych inject gniazda” poniżej.
valueSchemaobject—Opcjonalny kontrakt na poziomie krawędzi dla values pisanych przez programistę na krawędzi podłączonej przez to gniazdo (zapisywanych w encji Aggregate). JSON Schema 2020-12 w tych samych formach zapisu co schema:. Pominięcie oznacza, że gniazdo nie deklaruje kontraktu values.
infraSchemaobject—Opcjonalny kontrakt na poziomie krawędzi dla infra pisanego przez operatora na krawędzi podłączonej przez to gniazdo (zapisywanego w encji Release). Te same formy zapisu co valueSchema. Pominięcie oznacza, że gniazdo nie deklaruje kontraktu infra.
featuresSchemamap—Sloty dołączeń, które może wypełnić każde połączenie podłączone przez to gniazdo, kluczowane nazwą slotu; każdy slot przyjmuje te same klucze co slot na poziomie encji Component. Pominięcie oznacza, że połączenie przez to gniazdo nie niesie dołączenia. Zob. „Sloty wypełniane przez każde połączenie” poniżej.

Gdzie egzekwowana jest lista dozwolonych inject gniazda. Lista dozwolonych to deklaracja gniazda, czy konsument może w ogóle wybrać formę dostarczania, a jeśli tak, to które formy — dlatego jest sprawdzana względem każdej krawędzi uses: podłączonej przez gniazdo, gdy dostępne są już zarówno krawędź, jak i deklaracja gniazda. Z jednej reguły wynikają dwie odmowy i obie zatrzymują kompilację:

  • Krawędź wskazująca mechanizm, którego lista dozwolonych nie zawiera, zatrzymuje kompilację z nazwaniem gniazda, niedozwolonego mechanizmu i tego, na co gniazdo zezwala. Wszystkie niedozwolone mechanizmy na krawędzi są zgłaszane razem.
  • Krawędź wskazująca jakiekolwiek dostarczanie przez gniazdo, którego lista dozwolonych jest nieobecna lub pusta, również zatrzymuje kompilację. Tak działa deklaracja czarnej skrzynki: mówi „encja Recipe dostarcza to wewnętrznie; nie wskazuj sposobu dostarczania”, a pusta lista dozwolonych nie zezwala na nic, zamiast zezwalać na wszystko.

Gniazdo jest odczytywane z tej encji, która je zadeklarowała, a nie zawsze jest to komponent, z którego wychodzi krawędź: krawędź zapisana w uses: dołączenia encji Feature jest rozwiązywana względem usesSchema dołączonej encji Feature, a każda inna krawędź — zapisana w encji Aggregate, podłączona z encji Release lub osiągnięta przez podagregat — względem schematu konsumującej encji Component. Gniazdo odziedziczone przez extends jest odczytywane dokładnie tak jak gniazdo zapisane przez samą encję.

Krawędź, która niczego nie wskazuje, nie podlega żadnej z odmów, niezależnie od deklaracji gniazda: odczyt wartości zależności z .context.uses.<alias>.provides.<name> w konsumującej encji Recipe nie wymaga bloku inject: i jest zawsze dostępny. Obie diagnostyki opisano w errors/fatal-halts.md.

Kontrakty połączeń na poziomie krawędzi — valueSchema i infraSchema. Poza określaniem, które encje Components mogą być podłączone do gniazda, gniazdo może deklarować, jaką konfigurację niesie każde połączenie. Dwa opcjonalne schematy na poziomie gniazda walidują konfigurację połączenia na każdej krawędzi podłączonej przez gniazdo:

  • valueSchema to kontrakt dla pisanego przez programistę bloku values na krawędzi uses — dostrajania na poziomie połączenia, które programista wyraża w encji Aggregate (na przykład rozmiar puli połączeń lub tryb klienta).
  • infraSchema to kontrakt dla pisanego przez operatora bloku infra na krawędzi uses — wymiarowania operacyjnego na poziomie połączenia, które operator wyraża w encji Release.

Oba przyjmują JSON Schema 2020-12 w tych samych formach kształtu treści co pole schema: — wbudowana forma zwarta, wbudowany YAML JSON Schema lub międzydokumentowe $ref: do wpisu SchemaLibrary. Są to kontrakty na poziomie krawędzi, walidowane niezależnie względem konfiguracji każdej krawędzi; nie są składane do własnego schematu values konsumującej encji Component. Gniazdo, które pomija schemat krawędzi dla danego filaru, nie deklaruje tam kontraktu, a każda konfiguracja zapisana dla tego filaru pozostaje niewalidowana. Konfiguracja krawędzi jest walidowana w sposób zamknięty, a walidacja w obu filarach uwzględnia wartości domyślne: klucz, któremu schemat nadaje default:, liczy się jako podany, nawet gdy autor go pominie.

Zadeklarowane default: także się materializuje, w obu filarach. Klucz pominięty przez autora trafia do kontekstu renderowania konsumującej encji Recipe z zadeklarowaną wartością domyślną, dokładnie tak jak pominięty klucz value lub infra komponentu — wystarczy więc zadeklarować wartość domyślną w gnieździe, a szablon encji Recipe nie potrzebuje dla niej wyrażenia zastępczego. Zapisana wartość zawsze wygrywa z zadeklarowaną domyślną i wypełnia tylko podany klucz: krawędź zapisująca jeden klucz kontraktu gniazda nadal otrzymuje zadeklarowane wartości domyślne pozostałych kluczy tego kontraktu. Wartości domyślne przypisane są do krawędzi, więc niepodłączone gniazdo nie wnosi niczego.

spec:
usesSchema:
databases:
required: true
selector: "datastore.aggrega.ai/engine=relational"
inject: [env]
valueSchema: # developer per-edge values, authored in the Aggregate
pool_size: { type: integer, minimum: 1, maximum: 100, default: 10 }
tls_mode: { type: string, enum: [disable, require, verify-full], default: require }
infraSchema: # operator per-edge infra, authored in the Release
storage_class: { type: string, default: standard }

Przy tak zadeklarowanym gnieździe krawędź, której encja Aggregate pomija pool_size, renderuje 10, a krawędź, której encja Release pomija storage_class, renderuje standard. Zapis wygrywa per klucz, w obrębie własnego filaru: encja Aggregate ustawiająca pool_size: 42 renderuje 42, podczas gdy tls_mode nadal przyjmuje require, a encja Release ustawiająca storage_class: gp3 renderuje gp3, nie naruszając żadnego z kluczy programisty.

Encja Recipe konsumującej encji Component odczytuje rozwiązaną konfigurację krawędzi ze wzbogaconego potoku topologii pod .context.uses.<alias>.values.<key> i .context.uses.<alias>.infra.<key> — zob. vocabulary/topology-triad.md.

Sloty wypełniane przez każde połączenie — featuresSchema gniazda. Gniazdo może też deklarować sloty dołączeń, a wtedy każde połączenie podłączone przez nie może nieść w każdym z nich własne dołączenie: brama łącząca się z kilkoma modelami przechowuje dla każdego inne poświadczenie, ponieważ poświadczenie należy do połączenia, a nie do bramy.

spec:
usesSchema:
models:
selector: "component.aggrega.ai/category=ai-model"
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: The credential the consumer presents to the component this connection reaches.

Połączenie wypełnia slot, przenosząc dołączenie pod nazwą slotu we własnym bloku features: — we wpisie połączenia w encji Aggregate (Aggregate) lub w encji Release (Release) — a dołączenie staje się jednym z dołączeń konsumującego komponentu o nazwie <alias>.<slot>.

Co deklaracja robi, w ścisłym ujęciu:

  • Nazwy slotów tworzą zbiór zamknięty. W przeciwieństwie do własnego featuresSchema encji Component, które dopuszcza swobodne dołączenie pod dowolną nazwą, sloty gniazda są jedynymi nazwami, jakie może przenosić połączenie przez to gniazdo: każda inna nazwa zatrzymuje kompilację podczas ładowania, a gniazdo niedeklarujące featuresSchema nie dopuszcza żadnych dołączeń na swoich połączeniach. Gniazdo ad hoc — takie, którego ten usesSchema nie deklaruje — nie deklaruje slotów, więc jego połączenia również żadnych nie przenoszą. Każde połączenie wypełnia swoje sloty samo: dołączenie w szerszym zakresie nigdy nie przechodzi kaskadowo na połączenie, a klucz w encji Release zapisujący złożoną nazwę dołączenia połączenia zatrzymuje kompilację.
  • Pozostałe klucze wiążą każde połączenie ze slotem. Slot przyjmuje tu te same klucze co slot na poziomie encji Component — required, selector, inject, sensitive, description — i każde połączenie jest z nimi sprawdzane osobno. selector jest dopasowywany do etykiet encji Feature, którą połączenie wypełnia slot, a wypełnienie, którego nie dopuszcza, zatrzymuje kompilację, ze wskazaniem wpisu tego połączenia w dokumencie, który zapisał wypełnienie. required: true obowiązuje każde połączenie podłączone przez gniazdo: połączenie pozostawiające slot pusty zatrzymuje kompilację, ze wskazaniem tego połączenia, podczas gdy sąsiednie połączenie wypełniające slot przechodzi. sensitive jest odczytywany dokładnie tak jak w slocie na poziomie encji Component: dołączenie wypełniające slot jest oznaczane jako wrażliwe w grafie kompilacji i w aggrega inspect. Na połączeniu, tak jak na komponencie, o tym, które wartości dołączenia są ukrywane jako wrażliwe, decyduje wyłącznie własny schemat dołączonej encji Feature. inject wiąże wpis encji Workload, który dostarcza materiał slotu: dołączenie połączenia nie przenosi własnego bloku inject: — żaden z dokumentów nie dopuszcza go we wpisie połączenia — więc encja Workload dostarcza go, wskazując połączenie obok slotu, a ten wpis jest sprawdzany z listą dozwolonych slotu gniazda dokładnie tak, jak wpis wskazujący slot na poziomie encji Component jest sprawdzany z listą tego slotu.

usesSchema encji Feature nie przyjmuje featuresSchema: połączenie tworzone przez Feature nie przenosi dołączeń, a Feature deklarujący sloty w gnieździe jest odrzucany podczas ładowania. Poświadczenie potrzebne takiemu połączeniu jest slotem we własnym featuresSchema encji Feature.

Generowanie schematu z usesSchema. Kompilator generuje bazowy fragment JSON Schema 2020-12 z zadeklarowanych gniazd i łączy go z deklaracją schema: użytkownika — według tego samego wzorca, którego używa featuresSchema. Wygenerowany schemat nigdy nie trafia na dysk; istnieje tylko w pamięci podczas przebiegu walidacji encji Component. Mapa uses: programisty w encji Aggregate jest walidowana względem scalonego schematu; selector: każdego gniazda jest ewaluowany względem etykiet kandydujących encji Component podczas analizy statycznej jako kontrola bezpieczeństwa typów między węzłami.

Semantyka selektora — mechanizm Split Schema. usesSchema[].selector: sprawia, że topologia Aggrega to coś więcej niż nietypowane przekazywanie ciągów. Gniazdo deklarujące selector: "datastore.aggrega.ai/engine=vector" przyjmuje tylko połączenia z encjami Components oznaczonymi pasującą parą klucz-wartość; agent próbujący podłączyć swoje gniazdo primary_datastore do komponentu relational nie przechodzi analizatora statycznego, otrzymując czytelny komunikat o naruszeniu selektora. Selektor jest ciągiem selektora etykiet w stylu Kubernetes — wymaganiami łączonymi przecinkiem (AND) w formach =, !=, in (...), notin (...), samego klucza i !key — w tej samej gramatyce, której używa appliesTo encji Feature; gramatykę opisuje vocabulary/modifier-system.md, a semantykę silnika architecture/13-catalog-and-registry.md §2 „Kubernetes-Style Selectors”. Wymaganie spoza tych form jest odrzucane, a nie odczytywane jako inny selektor: puste wymaganie (przecinek na początku, na końcu lub podwójny), klucz zawierający białe znaki lub którykolwiek ze znaków =, !, (, ) i przecinek albo zbiór bez nawiasu zamykającego zatrzymuje każdą kompilację, która podłącza krawędź przez to gniazdo, ze wskazaniem wymagania. Gniazdo mające wykluczać frontendy zapisuje się więc jako selector: "tier!=frontend"; "!tier=frontend" jest odrzucane, ponieważ ! wskazuje klucz etykiety i nic więcej.

Gniazda ad hoc — co daje zadeklarowanie gniazda i co autor może zrobić bez niego. Autor encji Aggregate może zapisać wpis uses: na własnym komponencie pod nazwą gniazda, której ten usesSchema nie deklaruje, również na encji Component, która w ogóle nie deklaruje usesSchema. Krawędź zostaje zbudowana. Milczenie katalogu na temat gniazda oznacza, że połączenia nie przewidziano, a nie że jest zabronione, a topologia aplikacji należy do programisty.

Gniazdo ad hoc traci dokładnie to, co zapewnia gniazdo zadeklarowane, ponieważ wszystko to znajduje się we wpisie usesSchema: brak selector, więc nic nie ogranicza, do którego komponentu może sięgać krawędź, a kontrola bezpieczeństwa typów między węzłami nie ma czego ewaluować; brak listy dozwolonych inject:; brak valueSchema dla krawędzi, więc values: krawędzi nie ma kontraktu, względem którego byłoby sprawdzane, ani zadeklarowanych wartości domyślnych do odziedziczenia. Traci też infraSchema, choć na takim gnieździe i tak nic do tego kontraktu nie dociera: infra krawędzi zapisuje się we wpisie krawędzi encji Release, a wpis encji Release może wskazywać tylko gniazdo, które deklaruje konsumująca encja Component. Niezmienione pozostaje to, co krawędź może przenosić: from: każdego wpisu inject musi nadal wskazywać klucz deklarowany przez schema.provides docelowej encji Component, a cel musi nadal istnieć — oba przypadki zatrzymują kompilację tak jak na zadeklarowanym gnieździe.

Zapis „brak listy dozwolonych inject:” należy odczytywać jako brak ograniczenia, a nie jako deklarację blackbox, ponieważ obie sytuacje wyglądają podobnie, a działają przeciwnie. Krawędź przez gniazdo ad hoc może swobodnie narzucać sposób dostarczania: nie ma listy dozwolonych, poza którą mógłby znaleźć się mechanizm, i żadna encja nie obiecała obsłużyć wartości wewnętrznie. Opisane wyżej odrzucenie blackbox dotyczy gniazda, które encja zadeklarowała i pozostawiła bez listy dozwolonych inject: — to pominięcie jest stwierdzeniem o połączeniu, które encja przewidziała, a gniazdo ad hoc żadnego takiego stwierdzenia nie zawiera.

Dostarczanie przebiega tą samą ścieżką, a wyrenderowany artefakt nie zapisuje żadnej różnicy. Blok inject krawędzi ad hoc jest rozwiązywany i dostarczany dokładnie tak jak w zadeklarowanym gnieździe: każdy klucz from: jest odczytywany z ewaluowanego provides celu i trafia do kontekstu wstrzykiwania konsumującego węzła pod kluczem dostarczania wybranym przez autora, a stamtąd do wyrenderowanego artefaktu. Istnieje jedna ścieżka dostarczania i nic na niej nie rozgałęzia się zależnie od tego, czy gniazdo zadeklarowano. Zadeklarowane gniazdo może dodać treść — wartości domyślne krawędzi uzupełniane przez jego valueSchema lub infraSchema — więc tam, gdzie zadeklarowane gniazdo nie ma takiego kontraktu, ta sama krawędź renderuje się identycznie przy obu rodzajach gniazda. Deklaracja jest faktem dotyczącym połączenia, a nie danymi wejściowymi dla tego, co jest renderowane.

values: krawędzi na gnieździe ad hoc jest akceptowane i trafia do konsumującej encji Recipe w .context.uses.<alias>.values bez walidacji: bez valueSchema, względem którego można by je zmierzyć, żaden klucz nie jest sprawdzany ani odrzucany. Nie jest to cecha wyłącznie gniazd ad hoc — zadeklarowane gniazdo, które nie definiuje kontraktu dla danego filaru, traktuje swoją konfigurację krawędzi tak samo. Gniazdo ad hoc zmienia to, że kontraktu nie można dodać bez zadeklarowania gniazda. .context.uses.<alias>.infra jest na takiej krawędzi puste, ponieważ powierzchnia dostarczająca infra krawędzi nie może wskazać niezadeklarowanego gniazda.

Każda krawędź w emitowanym grafie zapisuje, którym z tych dwóch rodzajów jest, więc konsument nigdy nie musi tego wnioskować, a organizacja, która chce, by każde połączenie przechodziło przez zadeklarowane gniazdo, może tego wymagać jako polityki zarządczej. Zadeklarowanie gniazda tutaj pozostaje lepszą drogą i tak właśnie postępuje katalog biblioteki standardowej: zadeklarowane gniazdo niesie selector ograniczający, do których komponentów krawędź może sięgać, listę dozwolonych inject:, kontrakt dla krawędzi z własnymi wartościami domyślnymi oraz opis — weryfikowalne stwierdzenie przewidzianego połączenia, wersjonowane razem z encją, która je tworzy. Forma ad hoc jest furtką, a nie nowym domyślnym zachowaniem. Dwie powierzchnie celowo nie są w ten sposób otwarte — uses załącznika encji Feature może wskazywać wyłącznie gniazdo zadeklarowane przez dołączoną encję Feature, a uses dla krawędzi w encji Release może wskazywać wyłącznie gniazdo zadeklarowane przez konsumującą encję Component.

Przykład examples/adhoc-uses-socket/ buduje oba rodzaje krawędzi na jednym konsumencie i pokazuje obie dostarczone wartości obok siebie w wyrenderowanym wyniku, wraz z zatrzymaniem, które powoduje niezadeklarowany klucz from:.

Literówki w nazwach gniazd są zgłaszane jako ostrzeżenie, a nie zatrzymanie. Ponieważ niezadeklarowana nazwa gniazda jest dozwolona, błędnie zapisana nazwa gniazda staje się osobnym połączeniem ad hoc zamiast podłączać gniazdo, o które autorowi chodziło — a build pozostaje zielony, choć nic przez nie nie przepływa. Kompilator zgłasza nazwę gniazda, która jest o jedną edycję od nazwy zadeklarowanej w tym usesSchema, jako ostrzeżenie podające obie pisownie — zob. errors/warnings.md „Uses-socket near-miss lint”. Ostrzeżenie nigdy nie zmienia werdyktu builda; kompilator nie kontroluje, jak autor nazywa gniazdo.

Relacja usesSchema a featuresSchema. Obie są tabelami deklaratywnymi i obie niosą listę dozwolonych inject: o identycznej semantyce, ale gniazdo i slot to różne rzeczy i nie są wymienne. usesSchema reguluje krawędzie między komponentami — graf topologii — deklarując, które gniazda niosą kontrakt. featuresSchema reguluje sloty załączników, a slot jest nazwanym punktem wiązania, a nie wyliczeniem: załącznik pod nazwą, której nie deklaruje żaden slot, jest dozwolony we własnym bloku komponentu. (Sloty deklarowane przez gniazdo dla jego połączeń stanowią jedyny zamknięty zbiór, jak podaje wyżej „Slots each connection fills”.) Obie powierzchnie zbiegły się w tym punkcie — własny wpis uses: komponentu pod niezadeklarowaną nazwą gniazda również jest dozwolony — ale pozostają odrębne: niezadeklarowany slot to wolny załącznik na encji Component, której zadeklarowane sloty pozostają nienaruszone, natomiast niezadeklarowane gniazdo to krawędź bez selektora i bez kontraktu dla krawędzi. Wiele encji Components deklaruje obie; te dwie tabele składają się niezależnie.

Gniazda dołączeń: featuresSchema

Encja Component może deklarować gniazda dołączeń w bloku featuresSchema. Każde gniazdo nazywa punkt wiązania, w którym Component oczekuje dołączenia encji Feature — hasło roota, klucz API, token uwierzytelniający, powiązanie tożsamości — i ogranicza, która Feature może je związać oraz jak może być dostarczany materiał wypełnienia.

Ta sekcja dotyczy własnych gniazd encji Component. Gniazda deklarowane przez socket dla każdego połączenia tworzą natomiast zbiór zamknięty — zob. „Slots each connection fills” w sekcji Topology Sockets.

Zadeklarowanie gniazda nie zamyka powierzchni dołączeń. Autor może dołączyć encję Feature pod nazwą, której nie deklaruje żadne gniazdo, a takie dołączenie jest dołączeniem swobodnym: w pełni dozwolonym, po prostu niezwiązanym z zadeklarowanym gniazdem. Ta otwartość pozwala jednej encji katalogu obsłużyć dwa różne kształty wdrożenia bez rozwidlania katalogu:

  • Dla każdego konsumenta. Każda instancja wypełnia gniazdo własną encją Feature, więc każdy konsument otrzymuje własne wyrenderowane poświadczenie.
  • Współdzielone. Żadna instancja nie wypełnia gniazda; zamiast tego jedno poświadczenie jest dołączane raz w szerszym zakresie (podsystemu lub granicy encji Release) i kaskadowo trafia do każdego komponentu w tym zakresie, więc każdy konsument jest wypełniany z tej jednej deklaracji. To, co zostaje wyrenderowane, zależy od realizacji: jeden Secret na konsumenta, każdy z tym samym materiałem, przy realizacji renderującej Secret; żaden przy realizacji, która kieruje każdego konsumenta do już istniejącego Secretu.

Autor wybiera między nimi tym, co dołącza. Encja katalogu jest w obu przypadkach taka sama.

Jeden kształt na tej otwartej powierzchni zatrzymuje kompilację: wypełnienie zapisane na komponencie pod inną nazwą. Gdy dołączenie zapisane na samym komponencie — w jego własnym bloku features: w encji Aggregate lub we wpisie encji Release dla tego jednego komponentu — nosi nazwę, której nie deklaruje żadne gniazdo, a jego Feature spełnia selector gniazda, którego nic nie wiąże na tym komponencie po złożeniu wszystkich zakresów, kompilacja zostaje zatrzymana. Taki kształt przyjmuje wypełnienie przeznaczone dla gniazda zapisane pod złą nazwą: pozostawione bez zmian byłoby dołączeniem swobodnym, a gniazdo pozostałoby puste, zaś puste gniazdo opcjonalne kompiluje się bez błędów i niczego nie dostarcza. Komunikat podaje dołączenie, komponent, encję Feature i każde puste gniazdo, do którego ta Feature pasuje, a rozwiązaniem jest dołączenie jej pod nazwą gniazda. Dotyczy to każdej encji Feature, nie tylko poświadczeń. Cała reszta powierzchni pozostaje swobodna: dołączenie, którego Feature nie pasuje do żadnego zadeklarowanego gniazda, dodatkowe dołączenie, gdy każde pasujące gniazdo jest już związane, oraz dołączenie dziedziczone przez komponent z podsystemu lub granicy encji Release — więc opisany wyżej kształt współdzielony pozostaje nienaruszony. Gniazdo bez selector nic nie mówi o tym, dla której encji Feature jest przeznaczone, więc żadne dołączenie nie jest w ten sposób z nim porównywane. Zatrzymanie opisano w errors/fatal-halts.md pod „An attachment written under another name fits a slot its component leaves empty (Dołączenie zapisane pod inną nazwą pasuje do gniazda, które jego komponent pozostawia puste)”.

Oba kształty można łączyć, a wygrywa bliższy. Autor może zrobić oba naraz: dołączyć encję Feature w szerszym zakresie, tak aby dotarła do każdego komponentu w tym zakresie, i wypełnić gniazdo na jednym komponencie, który potrzebuje czegoś innego. Wygrywa wypełnienie w zakresie komponentu — pole po polu, więc wystarczy powtórzyć w nim pola, które zmienia, a pozostałe nadal pochodzą z szerszego dołączenia. Sąsiednie komponenty, które nie wypełniły gniazda, zachowują szersze dołączenie bez zmian. Pełna reguła pierwszeństwa, w tym jej interakcja z dołączeniami sterowanymi adnotacjami i ze złożonymi encjami Aggregates, znajduje się w vocabulary/labels-and-annotations.md „Attachment precedence”.

Definicja schematu w encji Component:

spec:
featuresSchema:
root_password:
inject: []
description: Root database password. Recipe controls delivery (Black-Box).
user_password:
inject: [env, file]
description: Application user password, auto-generated if omitted.
replication_password:
inject: []
description: Replication password for HA setups.

Semantyka pól:

PoleTypDomyślnieZnaczenie
requiredboolfalseDeklaruje, że gniazdo musi ostatecznie zostać związane. Kompilacja zostaje zatrzymana, gdy nic nie wiąże nazwy gniazda na instancji tej encji Component, przy czym sprawdzany jest zbiór dołączeń, który instancja ma po całej kaskadzie dołączeń — więc dołączenie zadeklarowane w zakresie, z którego instancja dziedziczy, spełnia gniazdo dokładnie tak jak wypełnienie zapisane na samej instancji. Diagnostyka podaje komponent i gniazdo.
injectstring[]—Lista dozwolonych mechanizmów dostarczania inject. [] (pusta) oznacza czarną skrzynkę — Recipe steruje dostarczaniem wewnętrznie, a materiał nigdy nie jest dostarczany do workloadu. [env, file] oznacza przezroczystość — materiał wypełnienia może być dostarczany wymienionymi mechanizmami. Ta sama semantyka co usesSchema[].inject.
descriptionstring—Dokumentacja dla ludzi, renderowana przez IDE i hub.
selectorstring—Opcjonalny selektor etykiet w stylu Kubernetes ograniczający, która Feature może wypełnić to gniazdo — odpowiednik selector socketu usesSchema dla gniazda, z tą samą gramatyką i tym samym natywnym mechanizmem dopasowywania etykiet. Jest obliczany względem własnych etykiet dołączonej encji Feature podczas analizy statycznej; wypełnienie, którego etykiety go nie spełniają, zatrzymuje kompilację, podobnie jak selektor odrzucony przez gramatykę, z podaniem wymagania, którego nie udało się odczytać. Pominięcie nie nakłada na wypełnienie żadnego ograniczenia.
sensitiveboolfalseDeklaruje, że cokolwiek wiąże to gniazdo, obsługuje materiał tajny. Jest to stwierdzenie o punkcie wiązania, a nie o konkretnym wypełnieniu; zob. „Deklarowanie gniazda jako wrażliwego” poniżej.

Gniazdo ogranicza, które wypełnienie może je związać, a nie to, co wypełnienie konfiguruje. Celowo nie istnieje kontrakt values ani infra na poziomie gniazda: tymi filarami zarządza własny schema: dołączonej encji Feature, więc każdy kontrakt ma dokładnie jedno miejsce.

Za pomocą selector gniazda Component zawęża, która Feature może wypełnić gniazdo — na przykład do encji Feature poświadczenia specyficznej dla dostawcy (feature.aggrega.ai/kind=secret, provider=helm) — bez nazywania encji FeatureRecipe, dokładnie tak jak selektor socketu usesSchema zawęża cel krawędzi zależności. Kompilator oblicza selektor wyłącznie względem etykiet dołączonej encji Feature: odczytuje etykiety wypełnienia i zgłasza, czy selektor je dopuszcza. To, których etykiet warto wymagać, jest wyborem autora katalogu, a nie regułą narzucaną przez kompilator.

Literówki w nazwach gniazd są zgłaszane jako ostrzeżenie, a nie zatrzymanie. Ponieważ niezadeklarowana nazwa dołączenia jest dozwolona, błędnie zapisana nazwa gniazda staje się dołączeniem swobodnym zamiast wypełniać gniazdo, które autor miał na myśli. Kompilator zgłasza nazwę dołączenia odległą o jedną edycję od zadeklarowanej nazwy gniazda jako ostrzeżenie podające obie pisownie — zob. errors/warnings.md „Attachment-slot near-miss lint”. Ostrzeżenie nigdy nie zmienia wyniku kompilacji; kompilator nie kontroluje, jak autor nazywa dołączenie. Nazwa odległa o jedną edycję od gniazda, którego selector spełnia Feature dołączenia, nie wywołuje ostrzeżenia: jeśli to gniazdo pozostaje puste, dołączenie zgłasza opisane wyżej zatrzymanie, a jeśli gniazdo wiąże coś innego, dołączenie jest zwykłym dodatkowym dołączeniem.

Deklarowanie slotu jako wrażliwego

sensitive: true na slocie wyraża własne żądanie konsumenta: cokolwiek wiąże ten punkt, obsługuje materiał tajny.

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: "Optional database password credential."

Jest to informacja rzeczywiście inna niż sensitive: true liścia schematu, a nie jego wygodny duplikat, i katalog biblioteki standardowej potrzebuje obu. Poświadczenie, do którego można się odwołać, publikuje provides.name i provides.key — lokalizator zasobu i klucz danych w nim — i żadne z nich nie jest wrażliwe: nazwa obiektu Secret w Kubernetes jest publiczna, podobnie jak klucz w nim. A jednak slot, który to poświadczenie wypełnia, bez wątpienia obsługuje materiał tajny. Liść mówi ta dana jest materiałem tajnym; slot mówi ten punkt wiązania obsługuje materiał tajny; oba twierdzenia dotyczą różnych rzeczy i mogą być prawdziwe niezależnie.

Praktyczna konsekwencja jest taka, że żądanie podąża za punktem wiązania, a nie za wypełnieniem. Encja Feature, która nie deklaruje żadnego wrażliwego liścia — bo poświadczeniem zarządza silnik docelowy, a autor nic nie pisze — nadal wiąże wrażliwy slot jako wrażliwe dołączenie, bo tak orzekł slot. Działa to też w drugą stronę: wypełnienie deklarujące wrażliwy liść jest wrażliwym dołączeniem nawet wtedy, gdy wiąże slot bez takiej deklaracji, lub gdy jest wolnym dołączeniem niewiążącym żadnego slotu.

Deklaracja podąża za kaskadą dołączeń, a nie za jakimkolwiek pojedynczym napisanym blokiem. Żądanie slotu dotyczy tego wypełnienia, które pozostaje związane po złożeniu wszystkich zakresów, więc wypełnienie na poziomie komponentu, które wypiera szersze, dziedziczy żądanie bez zmian.

sensitive na slocie ma to samo ograniczenie co słowo kluczowe na poziomie liścia — oznacza, a nie szyfruje, nie waliduje, nie odrzuca, nie wymusza mechanizmu dostarczania ani nie zmienia żadnego wyrenderowanego bajtu. Pełny opis znajduje się w vocabulary/compact-form-authoring.md „What the keyword does not do”.

sensitive i compliance.aggrega.ai/data-class to dwie różne osie, opisywane obok siebie i nigdy nieutożsamiane. sensitive to wartość logiczna na jednym liściu lub jednym slocie: ta dana lub ten punkt wiązania obsługuje materiał tajny. compliance.aggrega.ai/data-class to stopniowana etykieta na całym węźle — public, internal, restricted — nadająca danym przechowywanym przez komponent tożsamość w zakresie ładu danych. Jedna jest per dana i binarna, druga per węzeł i uporządkowana; żadna nie zastępuje drugiej, a encja może mieć obie. Etykieta jest opisana w vocabulary/labels-and-annotations.md oraz architecture/08-credential-model.md „Data governance around credentials”.

Projekcja schematu z featuresSchema

Zadeklarowane sloty są rzutowane na fragment JSON Schema 2020-12 opisujący kształt bloku dołączeń. Walidowane są względem niego dwa rodzaje wypełnień: blok dołączeń komponentu wnoszonego przez importowany moduł, gdy zostanie zbudowana kompozycja, która go importuje, oraz dołączenie zadeklarowane w szerszym zakresie — względem slotu każdego komponentu, do którego dociera. Blok dołączeń komponentu deklarowanego przez samą encję Aggregate jest natomiast mierzony schematem dokumentu encji Aggregate i listą dozwolonych inject slotu (zob. niżej), a fragment jest ukształtowany tak, by oba dawały ten sam werdykt dla każdego wypełnienia. Projekcja nigdy nie trafia na dysk; istnieje wyłącznie w pamięci, a schema: encji Component nigdy nie musi ręcznie opisywać filaru dołączeń.

Wejściowy featuresSchema:

featuresSchema:
root_password:
inject: []
user_password:
inject: [env, file]

Rzutowany fragment (w pamięci; reprezentacja w formie zwartej):

# The OUTER object is open: an attachment under a name no slot declares is
# admitted, because a free attachment is legal authoring.
root_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
# inject admits only an empty block — inject: [] means the Recipe controls
# delivery, so a fill may name no mechanism
inject: {}
user_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
inject:
env: { type: array }
file: { type: array }
# arg is absent — not in the inject allowlist

Oba poziomy są niezależne. Obiekt zewnętrzny jest otwarty, więc zadeklarowany slot nigdy nie zabrania dołączeń, których encja nie wyliczyła. Fragment każdego zadeklarowanego slotu jest zamknięty, więc wypełnienie, które wiąże zadeklarowany slot, nadal jest ograniczone do kształtu tego slotu.

Fragment opisuje wyłącznie KSZTAŁT. Nie zawiera żadnej informacji o tym, które sloty muszą być związane, ponieważ slot oznaczony jako required może zostać związany przez dołączenie spływające kaskadowo z szerszego zakresu — co pozostawia blok opisywany przez ten fragment pustym. Wymaganie jest więc sprawdzane względem zbioru dołączeń, jaki ostatecznie ma komponent, a nie względem tego, co deklaruje pojedynczy blok, i oba pytania nigdy sobie nie przeczą, bo napisanemu blokowi zadaje się tylko jedno z nich.

Dozwolone klucze odzwierciedlają klucze, które dołączenie może mieć w dowolnym miejscu, więc klucz dozwolony w wolnym dołączeniu pozostaje dozwolony w wypełnieniu slotu. Każdy dozwolony mechanizm dostarczania to lista wpisów dostarczania — ten sam kształt, jaki inject: przyjmuje wszędzie; slot zawęża, jakie NAZWY mechanizmów mogą wystąpić, a nie to, jak wygląda wpis.

Gdzie egzekwowana jest lista dozwolonych inject

Lista dozwolonych wiąże obie strony slotu, na dwóch różnych etapach.

Względem encji Workload z encji Recipe, na etapie renderowania: Workload, który odwołuje się do slotu przez wpisy dołączeń kontenera, musi wskazywać slot zadeklarowany przez encję i musi wybrać mechanizm dostarczania dozwolony przez listę inject slotu; odwołanie do slotu typu blackbox (inject: []), do mechanizmu spoza listy dozwolonych lub do slotu, którego encja nigdy nie zadeklarowała, zatrzymuje kompilację. Diagnostyka wskazuje Recipe, ścieżkę kontenera i błędny slot i jest klasyfikowana jako błąd katalogu — to Recipe popełnia błąd.

Względem własnego dołączenia encji Aggregate, gdy rozwiązywane są jej dołączenia i przed jakimkolwiek renderowaniem: blok inject: na wypełnieniu wiążącym zadeklarowany slot może wskazywać tylko mechanizmy dozwolone przez listę slotu, a slot typu blackbox nie dopuszcza żadnego — jego pusta lista mówi „Recipe dostarcza to wewnętrznie; nie narzucaj dostarczania”, a opisanie dla niego dostarczania zatrzymuje kompilację. Diagnostyka jest umiejscowiona na dołączeniu i wskazuje slot oraz błędny mechanizm, wraz z mechanizmami dozwolonymi przez slot, jeśli jakieś dopuszcza; jest klasyfikowana jako błąd dewelopera, bo to Aggregate popełnia błąd. Pusty blok inject: {} nie wskazuje żadnego mechanizmu, więc nie narzuca dostarczania i jest akceptowany w każdym slocie, łącznie ze slotem typu blackbox — tak samo w komponencie deklarowanym przez encję Aggregate, w komponencie wnoszonym przez importowany moduł, jak i w dołączeniu zadeklarowanym w szerszym zakresie. Wolne dołączenie — pod nazwą, której nie deklaruje żaden slot — nie podlega takiemu ograniczeniu, bo lista dozwolonych należy do slotu, a nie do bloku.

Pełny przepływ przez potok kompilacji — jak dołączenie w Aggregate łączy się z encją Feature poświadczenia (taką jak core/secret-value), a następnie z FeatureRecipe specyficznym dla dostawcy, który dostarcza poświadczenie do działającego workloadu — jest omówiony w examples/05-credential-features.

Klucz przedstawiany przez wywołującego i klucz weryfikowany przez serwer

Gdy jeden komponent wywołuje inny, który sprawdza klucz, każda strona przechowuje klucz po swojej stronie, w slocie, który sama deklaruje. Jest to konwencja, której przestrzega katalog biblioteki standardowej; kompilator niczego z tego nie wymusza — sprawdza sloty każdego komponentu względem własnych załączników tego komponentu, przekazuje ich ciągi znaków dalej i nigdy nie porównuje tego, co przechowuje jeden komponent, z tym, co przechowuje inny.

  • Klucz przedstawiany przez wywołującego należy do wywołującego. Znajduje się w slocie, który gniazdo wywołującego deklaruje dla każdego połączenia — zob. „Sloty wypełniane przez każde połączenie” powyżej — więc wywołujący, który łączy się z kilkoma celami, przechowuje po jednym kluczu dla każdego z nich. Gniazdo model komponentu core/ai-agent/crewai deklaruje ten slot jako credential, a jego encje Recipes dostarczają to, co go wypełnia, jako OPENAI_API_KEY. Gniazda models komponentów core/gateway/litellm, core/gateway/kong i core/gateway/apisix również go deklarują, a ich encje Recipes dostarczają klucz każdego połączenia w osobnej zmiennej, nazwanej od aliasu połączenia, dzięki czemu każdy model obsługiwany przez bramę ma własny klucz. Klucz, który encja Component deklaruje zamiast tego we własnym slocie, jest jednym kluczem dla wszystkich nawiązywanych przez nią połączeń.
  • Klucz weryfikowany przez serwer jest własnym slotem serwera. core/ai-model/vllm, core/ai-model/tei i core/ai-model/tgi deklarują opcjonalny api_key, a każdy z ich Recipes dostarcza to, co go wypełnia, jako zmienną, z której serwer odczytuje swój klucz. Model i brama LiteLLM deklarują api_key dla klucza, który LiteLLM nazywa swoim kluczem głównym (master key).
  • Żadna ze stron nie widzi załączników drugiej. Załącznik na połączeniu jest jednym z załączników wywołującego i trafia wyłącznie do renderowania wywołującego, a wyrenderowany wynik serwera jest taki sam bez względu na to, co niosą połączenia do niego docierające. Slot oznaczony jako required jest zobowiązaniem komponentu, który go deklaruje, nigdy komponentów z nim połączonych, a wypełnienie slotu po jednej stronie niczego nie wypełnia po drugiej — dlatego zadeklarowanie klucza po obu stronach jest minimum, a nie duplikatem.
  • Obie strony odczytują jeden parametr, więc klucza przedstawianego przez wywołującego i klucza weryfikowanego przez serwer nie da się zapisać rozbieżnie.
# Aggregate fragment — one parameter feeds both ends
spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
agent:
type: core/ai-agent/crewai
# values (role, goal, backstory, …) elided
uses:
model:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

Serwer, który sprawdza jeden klucz, nie potrafi odróżnić swoich wywołujących: vLLM, TEI i TGI sprawdzają każdy pojedynczy klucz, więc każdy wywołujący przedstawia ten sam klucz, niezależnie od liczby połączeń docierających do serwera. To, czy obie strony odwołują się do jednego sekretu, czy każda przechowuje własny, wynika z tego, gdzie każdy dostawca rozwiązuje sekret przez odwołanie, a encja Manifest wybiera realizację dla każdej strony — Model poświadczeń omawia oba przypadki.

Poświadczenie, które komponent przechowuje dla siebie — na przykład klucz, którym podpisuje własne sesje — jest slotem jego własnego featuresSchema: jak każdy inny. Hasło, które przedstawia magazynowi danych osiąganemu przez jedno z jego gniazd, jest opisanym wyżej kluczem wywołującego, więc znajduje się na tym połączeniu jako credential: gniazdo backend komponentu core/gateway/kong je deklaruje, a jego encje Recipes syntezujące obciążenia dostarczają je jako KONG_PG_PASSWORD; gniazdo cache_store komponentu core/gateway/litellm deklaruje je dla hasła, które jego pamięć podręczna semantyczna przedstawia magazynowi, dostarczanego jako REDIS_PASSWORD. Gdy jedno połączenie przedstawia parę — identyfikator klucza dostępu i jego sekret — połowa sekretna to credential, a połowa identyfikująca to credential_id, jak w gnieździe store komponentu core/ai-agent/agenta-api.

Samowstrzykiwanie: spec.inject

Encja Component może zadeklarować na najwyższym poziomie tablicę spec.inject:, która stanowi listę dozwolonych mechanizmów dostarczania przy samowstrzykiwaniu. Gdy jest obecna, programiści mogą w encji Aggregate użyć bloku inject: na poziomie komponentu, aby wstrzyknąć własne klucze values: lub provides: encji Component bezpośrednio do jej własnego kanału dostarczania (zmiennych środowiskowych jej kontenera, montowanych plików lub argumentów procesu). Gdy spec.inject: nie występuje lub jest puste, samowstrzykiwanie na poziomie komponentu jest zabronione — encja Recipe kontroluje całe wewnętrzne okablowanie, zgodnie ze wzorcem czarnej skrzynki (Black-Box), który usesSchema[].inject: [] i featuresSchema[].inject: [] stosują odpowiednio do dostarczania między komponentami i dostarczania poświadczeń.

# Component declares its self-inject allowlist:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/web-server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
inject: [env, file]
schema:
values:
log_level: { type: string, default: info }
tls_enabled: { type: boolean, default: false }
provides:
health_endpoint: { type: string }
# Aggregate fragment — developer dictates self-inject delivery:
components:
api:
type: core/web-server
values:
log_level: debug
tls_enabled: true
inject:
env:
- in: LOG_LEVEL
value: '{{"{{"}} .values.log_level }}'
- in: TLS_ENABLED
value: '{{"{{"}} .values.tls_enabled }}'
file:
- in: /etc/web/health-probe
from: health_endpoint

Każdy szablon value: zaczyna się od {{"{{"}}, a nie od {{. Cały tekst encji Aggregate jest raz odczytywany jako szablon na potrzeby interpolacji parametrów, zanim nastąpi rozwiązywanie samowstrzykiwania, a w tym momencie .values jeszcze nie istnieje; escapowanie przywraca {{, aby rozwiązywanie samowstrzykiwania mogło je ewaluować. Zob. Tekst zawierający własne podwójne nawiasy klamrowe.

Semantyka pola. spec.inject: to tablica nazw mechanizmów. Zdefiniowano trzy wartości:

  • env — zmienne środowiskowe w kontenerze.
  • file — ścieżki montowanych plików.
  • arg — argumenty wiersza poleceń procesu.

Semantyka dokładnie odpowiada usesSchema[].inject i featuresSchema[].inject — to samo słownictwo, ten sam wzorzec czarnej skrzynki przy pominięciu, ten sam kształt zapisu po stronie encji Aggregate. Różnica dotyczy źródła: usesSchema[].inject określa, jak provides zależności między komponentami trafia do kanału dostarczania konsumenta; featuresSchema[].inject określa, jak poświadczenie trafia do kontenera; spec.inject określa, jak własne values i provides encji Component trafiają do jej własnego kontenera.

Dyscyplina tworzenia. Encja Component core/web-server deklarująca spec.inject: [env, file] wybiera przejrzyste dostarczanie — autor encji Aggregate decyduje, które nazwy zmiennych środowiskowych przenoszą które wartości. Encja Component deklarująca spec.inject: [] (lub pomijająca to pole) zachowuje nieprzejrzyste dostarczanie — valuesMapping: encji Recipe decyduje, które pola trafiają do których zmiennych kontenera, a programista nie może tego nadpisać w encji Aggregate. Wzorzec czarnej skrzynki pasuje do encji Components o stabilnym kontrakcie (encja Component core/postgres-db, której Recipe wie, jak przekazać hasło bazy danych do zmiennej środowiskowej POSTGRES_PASSWORD); wzorzec przejrzysty pasuje do encji Components, w których intencja programisty w uzasadniony sposób określa szczegóły dostarczania (core/web-server, którego aplikacja odczytuje LOG_LEVEL z niestandardowej nazwy zmiennej, którą programista chce dostosować).

Tryby błędów. Encja Aggregate programisty używająca bloku inject: w encji Component, której spec.inject: nie istnieje lub jest puste, zatrzymuje kompilację podczas ładowania przestrzeni roboczej („Self-inject on a component without an allowlist (Samowstrzykiwanie w komponencie bez listy dozwolonych mechanizmów)”). Blok inject: używający mechanizmu spoza listy dozwolonych zatrzymuje ją z tego samego powodu, wskazując mechanizm i te, na które lista pozwala („Self-inject mechanism not in the component’s allowlist (Mechanizm samowstrzykiwania spoza listy dozwolonych komponentu)”). Kolizja kluczy dostarczania między samowstrzykiwaniem, wstrzykiwaniem między komponentami i wstrzykiwaniem poświadczeń również ją zatrzymuje („Duplicate delivery key across inject sources (Zduplikowany klucz dostarczania w różnych źródłach wstrzykiwania)”). Kształty komunikatów poszczególnych błędów opisano w errors/fatal-halts.md.

Tworzenie katalogu: rozszerzanie bazowych Components

Architekci platformy używają słowa kluczowego extends, aby nakładać wyspecjalizowane interfejsy na bazowe definicje firmowe lub społecznościowe. Rozszerzanie komponuje strukturę i dziedziczy filary danych w całości. Kompilator przechodzi łańcuch od bazy w dół; obie połowy zachowują się inaczej, a ta różnica stanowi cały model tworzenia.

Co rozszerzanie komponuje. Te miejsca są scalane wzdłuż łańcucha: dla każdego klucza wygrywa rozszerzająca encja Component, a listy są łączone od bazy, bez duplikatów:

MiejsceSposób komponowania
metadata.labelsscalane per klucz; przy wspólnym kluczu wygrywa wartość rozszerzającej encji Component
metadata.annotationsscalane per klucz, z tym samym pierwszeństwem — dlatego wymóg obecności z bazy dociera do każdej encji Component, która ją rozszerza
spec.featuresSchemasuma slotów dołączania; slot ponownie zadeklarowany przez rozszerzającą encję Component zastępuje wpis bazy o tej nazwie
spec.usesSchemasuma gniazd topologii, z tą samą regułą zastępowania według nazwy
spec.injectobie listy dozwolonych mechanizmów self-inject są łączone, najpierw wpisy bazy, duplikaty są pomijane
spec.assertionsnazwane reguły kumulują się, najpierw reguły bazy — i tylko to jedno miejsce nie dopuszcza zastępowania według nazwy; zob. „Dziedziczenie asercji jest addytywne” poniżej

Gniazdo dodane przez rozszerzającą encję Component może mieć własne valueSchema i infraSchema dla poszczególnych krawędzi; są to kontrakty na krawędziach tego gniazda, a nie uzupełnienia własnych filarów encji Component.

Pozostała część metadata: należy do dokumentu, który ją deklaruje. labels i annotations to jedyne metadane przekazywane w dół łańcucha. name, version, description, maintainers, license, repository, home i keywords należą do rozszerzającej encji Component i są odczytywane dokładnie tak, jak je zapisała — encja Component, która pomija description:, nie ma opisu, zamiast pożyczać go od bazy. Tożsamość i pochodzenie należą do czytanego dokumentu, dzięki czemu opakowanie nigdy nie zostanie pomylone z tym, co opakowuje.

Co rozszerzanie dziedziczy w całości. Trzy filary danych — values, infra, provides — nie są komponowane. Rozszerzająca encja Component nie zawiera treści filarów: zapisuje dosłowny znacznik schema: inherited i otrzymuje blok schema: swojej bazy dokładnie w takiej postaci, w jakiej baza go zapisała. W łańcuchu o dowolnej głębokości każda encja Component ma niezmieniony blok korzenia łańcucha, więc aggrega inspect --resolved dla liścia pokazuje te same filary co dla korzenia.

Opublikowany schemat encji Component określa, który z trzech możliwych wariantów jest dozwolony, a pozostałe dwa odrzuca podczas ładowania dokumentu — z osobną diagnostyką dla każdego, bo to różne błędy:

  • extends: z treścią filarów pod schema: jest odrzucane. Kontrakt encji Component jest kontraktem jej bazy; drugi, rozbieżny kontrakt nie ma gdzie się znaleźć.
  • extends: z całkowicie pominiętym schema: jest odrzucane. Pominięcie nie pozwoliłoby czytelnikowi odróżnić odziedziczonego bloku filarów od zapomnianego.
  • schema: inherited bez extends: jest odrzucane. Znacznik wskazuje, skąd pochodzą filary, a ta encja Component nie ma bazy, z której mogłaby je wziąć.

Rozszerzająca encja Component nie może zmieniać zbioru kluczy. Nie deklaruje kluczy filarów, więc nie może ukryć, usunąć ani zmienić typu klucza zadeklarowanego przez bazę i nie dodaje własnych. Nowy klucz filaru należy umieścić w encji Component, do której kontraktu należy. Wszystko, co udostępnia baza, każda rozszerzająca ją encja udostępnia identycznie.

Specjalizacja zawęża ograniczenia przez assertions:. Gdy specjalizacja musi dopuszczać mniej niż filary jej bazy — węższy zakres liczbowy, podzbiór odziedziczonego enum: — wyraża to we własnym bloku assertions:: reguła w tym bloku odrzuca wartość, którą odziedziczony schemat akceptuje. To jest miejsce, w którym odbywa się zawężanie; zob. „The assertions: block” poniżej.

Dwa ostatnie akapity to jedna reguła, a każda połowa osobno wprowadza w błąd: zawężenie zbioru kluczy jest niemożliwe, zaostrzenie ograniczeń jest możliwe. Biorąc tylko pierwszą, można wywnioskować, że specjalizacja niczego nie może ograniczyć; biorąc tylko drugą — że może zmieniać kontrakt. Żadne z nich nie jest prawdą: zbiór kluczy ustala baza, a dopuszczalne w nim wartości można zawęzić predykatem.

Dziedziczenie asercji jest addytywne, a kumulacja zaczyna się od korzenia. Instancja rozszerzającej encji Component jest sprawdzana względem każdej reguły zadeklarowanej w jej łańcuchu oraz reguł zadeklarowanych przez samą encję, przy czym odziedziczone są wartościowane najpierw. W łańcuchu o dowolnej głębokości reguły kumulują się od korzenia w dół, więc gdy instancja nie spełniłaby kilku reguł, zgłaszana jest ta zadeklarowana najwyżej w łańcuchu — najbardziej podstawowy kontrakt odpowiada pierwszy.

Ponieważ dziedziczenie dodaje, a nie zastępuje, rozszerzająca encja Component nie może użyć odziedziczonej nazwy reguły do zadeklarowania innej reguły: jest to odrzucane podczas rozwiązywania łańcucha extends względem katalogu, z diagnostyką wskazującą obie Components i wspólną nazwę. Sprawdzenie wymaga bazowej encji Component, więc zgłaszane jest podczas walidacji katalogu lub gdy kompilacja rozwiązuje łańcuch — walidacja samego rozszerzającego dokumentu tego nie wykryje. Nazwa reguły jest stabilnym identyfikatorem, więc ani usunięcie reguły bazy, ani jej ciche przemianowanie nie wchodzi w grę; poprawką jest zmiana nazwy w rozszerzającej encji Component. Powtórzenie odziedziczonej reguły bajt w bajt pod jej własną nazwą jest akceptowane jako operacja bez skutku.

aggrega pull pobiera bazę. Baza jest zależnością każdej encji Release, która dociera do encji Component rozszerzającej tę bazę, niezależnie od tego, czy cokolwiek innego ją wskazuje. aggrega pull podąża za każdym extends: do końca łańcucha, pobiera z rejestru bazę, której nie zawiera żaden katalog encji, i zapisuje każdą bazę w pliku blokady encji Release, z odwołaniem ze spec.extends encji Component, która ją wskazuje; kompilacja odczytuje bazę stamtąd. Dzięki temu encja Manifest mapuje tylko własny typ wrappera i nic więcej — baza potrzebuje własnego wiersza mapowania tylko tam, gdzie encja Aggregate deklaruje również instancję bazy. Polecenie aggrega validate dla całego katalogu odczytuje bazę w ten sam sposób, więc baza opublikowana w rejestrze jest tam odrzucana, ze wskazaniem aggrega pull, dopóki pull jej nie pobierze.

Formaty treści schematów opisano w architecture/13-catalog-and-registry.md §3.

Przykład A: bazowa encja Component (firmowa definicja bazowa) Architekt platformy definiuje podstawowy serwer firmowy. Ta baza ustawia wymaganą etykietę operacyjnego prymitywu chmurowego i ustala ograniczenia bezpieczeństwa w schemacie. Ponieważ blok filarów jest dziedziczony bez zmian, każde ograniczenie z tego miejsca dociera do każdej rozszerzającej encji Component dokładnie w zapisanej postaci.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/base-enterprise-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
inject: [env]
schema:
values:
# The corporate baseline constraint. Every Component extending this base
# receives this leaf verbatim; none of them can restate or loosen it.
tls_enabled: { type: boolean, enum: [true], default: true }
# An open range at the baseline. A specialization that needs a tighter
# bound expresses it as an assertion, not as a redeclared schema leaf.
timeout_ms: { type: integer, default: 5000 }
assertions:
# A baseline invariant. It is evaluated for instances of this Component AND
# for instances of every Component extending it, under this same name.
audit-window-is-observable: |
{{- if lt (int .values.timeout_ms) 100 -}}
{{- fail "the corporate baseline needs timeout_ms of at least 100 so requests are observable" -}}
{{- end -}}

Przykład B: rozszerzająca encja Component (specjalizacja definicji bazowej) Brama jest specjalizacją tej definicji bazowej. Przejmuje filary bazy w całości, dodaje własną strukturę — etykietę, mechanizm self-inject, gniazdo topologii ze slotem dołączania — i zaostrza odziedziczony limit czasu przez asercję. Nie powtarza reguły audit-window-is-observable z bazy: ta reguła jest dziedziczona i wartościowana najpierw, więc instancja tej bramy musi spełnić oba ograniczenia — co najmniej 100 i co najwyżej 2000.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/gateway/kong
version: 1.0.0
labels:
# Every Component declares the reserved base-ontology key, including one
# that extends: the envelope requires it on the document itself.
component.aggrega.ai/type: "server"
api.aggrega.ai/protocol: "http" # merged with the base's labels
spec:
extends: core/base-enterprise-server
schema: inherited # values, infra and provides are the base's, verbatim
inject: [file] # concatenates with the base's [env] -> [env, file]
usesSchema: # a socket of its own; the base declared none
backend:
required: true
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]
featuresSchema: # a slot each connection through it fills
credential:
sensitive: true
inject: [env]
description: Password the gateway presents to the configuration backend this connection reaches.
assertions:
# The tightening. The inherited schema admits any integer for timeout_ms;
# this gateway admits only 2000 or less, so the rule rejects a value the
# inherited pillar block would accept.
timeout-within-gateway-budget: |
{{- if gt (int .values.timeout_ms) 2000 -}}
{{- fail "the gateway must answer within 2000ms: set timeout_ms to 2000 or less" -}}
{{- end -}}

Encję Recipe implementującą interfejs core/gateway/kong na podstawie fizycznego chartu Helm opisano w entities/recipe, przykład C (kong-gateway).

Blok assertions:

Component.spec.assertions: to opcjonalna mapa nazwanych reguł wyrażających niezmienniki architektoniczne kontraktu encji Component — reguły międzypolowe, które muszą być spełnione przez zapis programisty niezależnie od tego, która encja Recipe wiąże się z encją Component. Każdy klucz jest identyfikatorem reguły pojawiającym się w komunikacie o błędzie; każda wartość jest treścią szablonu Go. Kompilator wartościuje je dla każdej instancji po walidacji schematu, a przed wiązaniem encji Recipe, w kolejności zapisu, a pierwsza niespełniona reguła zatrzymuje kompilację z własnym komunikatem błędu tej reguły, zgodnie z kontraktem Loud Guardrails.

spec:
assertions:
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt (int .values.secondary.replicaCount) 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}

Powyższa reguła jest własnością kontraktu encji Component — niezależnie od tego, jaka encja Recipe zostanie powiązana (chart Bitnami, ręcznie przygotowana alternatywa, przyszła implementacja), tryb replikacji wymaga co najmniej dwóch replik pomocniczych.

assertions: to miejsce, w którym rozszerzająca encja Component zaostrza ograniczenia. Encja Component, która rozszerza bazę przez extends:, dziedziczy blok filarów bazy dosłownie i nie deklaruje własnej treści filarów, więc specjalizacja, która musi dopuszczać mniej niż odziedziczony schemat, wyraża to ograniczenie tutaj jako predykat, a nie jako zawężony liść schematu — regułę odrzucającą wartość akceptowaną przez odziedziczone filary. Przykładowa para oraz pełne zachowanie dziedziczenia opisano powyżej w sekcji „Tworzenie katalogu: rozszerzanie bazowych Components”: reguły kumulują się wzdłuż łańcucha od korzenia, a użycie odziedziczonej nazwy reguły dla innej reguły jest odrzucane, zamiast pozwolić jej zastąpić oryginał.

Kompilator nie sprawdza, czy dwie reguły mogą zostać spełnione jednocześnie. Reguła jest predykatem szablonu, a nie ograniczeniem, o którym kompilator wnioskuje, więc para reguł, których żadna wartość nie spełnia naraz — baza wymagająca co najmniej 100 i specjalizacja wymagająca co najwyżej 50 — nie powoduje ostrzeżenia podczas ładowania katalogu. Ujawnia się w zwykły sposób: gdy powstaje instancja, kompilacja zatrzymuje się na tej z dwóch reguł, która zadziała pierwsza, a autor czyta komunikat tej reguły. Nie należy oczekiwać, że sprzeczność zostanie zgłoszona z góry; zaostrzenia w specjalizacji należy sprawdzać względem tego, czego baza już wymaga.

assertions: należy używać do rzeczywistych reguł międzypolowych. Ograniczenia pojedynczych pól (zakres, wzorzec, enum) należą do słów kluczowych schema:; niestandardowe predykaty pojedynczych pól należą do validate: w formie zwartej; warunkowy kształt (czy ograniczenia poddrzewa mają zastosowanie) należy do when:. Pełną gramatykę tworzenia — pola kontekstu szablonu, konwencję komunikatów {{ fail }}, fazę wartościowania oraz przykłady obejmujące role encji Component i Recipe — opisano w templates/assertions-block.md.