Gniazdo, którego nikt nie zadeklarował, dostarczające prawdziwe wartości
Ten przykład uczy jednego zdania i obu jego połówek:
Konsument może wymyślić połączenie. Może jednak konsumować tylko to, co deklaruje producent.
Autor encji Aggregate zapisuje wpis uses: we własnym komponencie pod nazwą gniazda,
której nie deklaruje żadna encja katalogu. Krawędź zostaje zbudowana i dostarcza — wartość
trafia do wyrenderowanego artefaktu dokładnie tak, jak trafiłaby przez zadeklarowane gniazdo. Jednak
klucze, które ta krawędź może przenosić, nadal deklaruje cel: jeśli wskaże się klucz, którego
cel nie deklaruje, kompilacja zostaje przerwana.
Wszystko tutaj jest rozwiązywane z katalogu biblioteki standardowej. Przestrzeń robocza nie definiuje żadnej własnej encji Component, Feature ani Recipe.
Stos
Trzy komponenty, z których jeden jest połączony na dwa różne sposoby:
| instancja | typ | czym jest |
|---|---|---|
db | core/datastore/mariadb | baza danych |
model | core/ai-model/anthropic | endpoint modelu; realizacja w formie referencji, więc nie uruchamia się dla niego żadna moc obliczeniowa |
web | core/devtool/adminer | konsola, konsumująca oba |
core/devtool/adminer deklaruje dokładnie jedno gniazdo:
usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: [env]To wszystko, co przewidział jego autor. Konsola obsługująca bazę danych to połączenie, które miał na myśli; konsola przenosząca endpoint modelu w swoim środowisku — nie.
Co zapisuje encja Aggregate
aggregate-delivers.yaml łączy obie krawędzie z jednego bloku uses::
web: type: core/devtool/adminer uses: databases: # DECLARED — the socket the Component's usesSchema names db: target: db inject: env: - in: ADMINER_DEFAULT_SERVER from: host
assistant: # AD-HOC — declared nowhere model: target: model inject: env: - in: ASSISTANT_ENDPOINT from: endpoint - in: ASSISTANT_MODEL from: modelassistant nie występuje w żadnym usesSchema, ani w tej encji Component, ani w żadnej innej. Mimo to
jest dozwolone: milczenie katalogu o gnieździe oznacza, że połączenia nie
przewidziano, a nie że jest zabronione, a deweloper jest właścicielem topologii własnej
aplikacji.
Gniazdo ad hoc traci dokładnie to, co przeniósłby brakujący wpis usesSchema
— nie ma selector, więc nic nie ogranicza, do którego komponentu może sięgać
krawędź, a międzywęzłowe sprawdzanie bezpieczeństwa typów nie ma czego oceniać; nie ma
listy dozwolonych inject:; nie ma valueSchema ani infraSchema na poziomie krawędzi, więc
values: i infra: krawędzi nie mają kontraktu, względem którego można je sprawdzić, ani zadeklarowanych
wartości domyślnych do odziedziczenia. Konfiguracja krawędzi zapisana w takim gnieździe jest akceptowana
i przekazywana bez sprawdzania, tak jak zachowuje się każde gniazdo bez kontraktu dla danego
filaru — zadeklarowane gniazdo, które nie definiuje valueSchema, jest w tej samej
sytuacji.
Nie traci natomiast tego, co krawędź może przenosić. endpoint i model
to klucze, które core/ai-model/anthropic deklaruje w swoim filarze provides.
Generowanie przykładu
Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.
Należy zapisać przykład w nowym folderze nazwanym tak jak on:
aggrega scaffold --example adhoc-uses-socketNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd adhoc-uses-socketKompilacja
aggrega build --release release-delivers.yaml --auto-pullWyrenderowane wyjście i plik blokady są generowane, a nie dostarczane: ten przykład zatwierdza swoje dane wejściowe i generuje ponownie całą resztę. --auto-pull rozwiązuje plik blokady podczas kompilacji; jednorazowe wcześniejsze aggrega pull --release release-delivers.yaml robi to samo i pozwala kolejnym kompilacjom działać bez żadnej flagi. Encje katalogu są rozwiązywane z hub.aggrega.ai, domyślnego rejestru wskazanego w .aggrega-config.yaml, więc ani kompilacja, ani aggrega inspect nie potrzebują flagi --catalog.
Z asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.
Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `adhoc-uses-socket`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `adhoc-uses-socket` i bez `dir`: zapisze ono przykład w nowym folderze `adhoc-uses-socket`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `adhoc-uses-socket`, `release` ustawionym na `release-delivers.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Powiedz mi, które pliki zapisało budowanie; znajdują się w `adhoc-uses-socket/dist/`.Odczyt wyjścia
dist/compose/docker-compose.yaml, usługa web:
web: image: adminer:4 environment: ADMINER_DESIGN: pepa-linha-dark ADMINER_DEFAULT_SERVER: db ASSISTANT_ENDPOINT: https://api.anthropic.com ASSISTANT_MODEL: claude-sonnet-4-5 [… omitted: the service's ports, provenance labels, networks, depends_on and healthcheck]Cztery zmienne, z czego trzy dostarczone przez krawędzie, a wyjście nie rejestruje, które gniazdo zostało zadeklarowane:
ADMINER_DEFAULT_SERVER: dbdotarło przezdatabases, zadeklarowane gniazdo. Jego wartością jestprovides.hostencji Recipe bazy danych — nazwa usługi Compose.ASSISTANT_ENDPOINTiASSISTANT_MODELdotarły przezassistant, gniazdo ad hoc, przenoszącprovides.endpointiprovides.modelencji Recipe modelu.
Znajdują się w jednej mapie, w kolejności autora, bez znacznika, bez adnotacji i bez różnicy w kolejności między nimi. O to właśnie chodzi: gniazdo ad hoc to coś innego przy deklarowaniu, a nie przy dostarczaniu. Istnieje jedna ścieżka dostarczania i obie krawędzie z niej korzystają.
ASSISTANT_ENDPOINT warto też odczytać jako fakt kompilacji ahead-of-time.
Kompilator nie kontaktował się z Anthropic, aby ustalić https://api.anthropic.com;
encja Recipe wyemitowała go jako deterministyczny łańcuch wskaźnika pochodzący z infra.endpoint
komponentu modelu, a kompilator przekazał ten łańcuch bez
interpretowania go. Sam Adminer nie odczytuje żadnej ze zmiennych ASSISTANT_* —
to deweloper wybrał te klucze dostarczania, a kontener konsoli przenosi je dla
tego, co je tam odczytuje.
Graf emitowany przez kompilację rejestruje to rozróżnienie, choć wyrenderowany
artefakt tego nie robi: każda krawędź ma pole socket_declaration o wartości
declared lub ad-hoc, więc organizacja, która chce, aby każde połączenie przechodziło
przez gniazdo zadeklarowane przez jej architektów, wyraża to jako politykę nadzoru,
zamiast polegać na tym, że kompilator będzie miał własne zdanie. Zob.
architecture/11-governance-and-compliance.md.
Próba kontrolna: czego konsument nadal nie może wymyślić
aggregate-undeclared-key.yaml to aggregate-delivers.yaml z jedną zmianą.
Krawędź ad hoc żąda trzeciego klucza:
- in: ASSISTANT_API_KEY from: api_keycore/ai-model/anthropic deklaruje w swoim filarze provides klucze endpoint i model
i nic więcej. Kompilacja powinna zakończyć się niepowodzeniem:
aggrega build --release release-negative-undeclared-key.yaml --auto-pull# [… omitted: a refused: line carrying the message below]# [DEVELOPER_ERROR E0156] .spec.components.web.uses.assistant.model# invalid inject key: the from-key must name a provides key its source publishes# (Aggregate adhoc-uses-socket-undeclared-key,# at .spec.components.web.uses.assistant.model, "env", "ASSISTANT_API_KEY", "api_key",# "core/ai-model/anthropic", "endpoint", "model")Przerwanie jest lekcją, a warte uwagi jest to, gdzie następuje:
błędna ścieżka wskazuje gniazdo ad hoc, uses.assistant, i kończy się na
połączeniu, a nie na wpisie dostarczania w nim. Klucz from: jest
sprawdzany względem zadeklarowanych provides docelowej encji Component na każdej krawędzi, a
to, że gniazdo jest ad hoc, niczego w tym sprawdzeniu nie zmienia. Autor, który może wymyślić
nazwę gniazda, nadal nie może wymyślić klucza wyjściowego w cudzym komponencie.
Najpierw pojawia się odmowa, potem encja Aggregate i ścieżka, w której zapisano
krawędź, mechanizm i klucz dostarczania, pod którym zapisano wpis, błędny
klucz, typ komponentu, względem którego go rozwiązano, oraz zadeklarowane klucze tego typu
w kolejności posortowanej — dzięki temu poprawka wynika z samego komunikatu. Docelowa
encja Component, która w ogóle nie deklaruje provides, tak samo odrzuca każde odwołanie from: do
niej; po prostu nie ma zadeklarowanych kluczy do wymienienia, więc komunikat kończy się
po typie komponentu.
Którą formę zapisać
Zadeklarowanie gniazda w katalogu pozostaje lepszą drogą i tak właśnie postępuje
katalog biblioteki standardowej. Zadeklarowane gniazdo ma selector, który
ogranicza, do których komponentów może sięgać krawędź, listę dozwolonych inject:,
kontrakt krawędzi z własnymi wartościami domyślnymi oraz opis — podlegającą przeglądowi
deklarację przewidzianego połączenia, wersjonowaną razem z encją, która ją składa.
Gniazdo ad hoc nie ma niczego z tych rzeczy, a krawędź jest tylko tak bezpieczna jak autor,
który ją zapisał.
Forma ad hoc to furtka na przypadek pokazany w tym przykładzie: połączenie, którego autor katalogu nie przewidział, potrzebne jednemu wdrożeniu, gdy czekanie na zmianę w katalogu oznaczałoby czekanie z wydaniem. Należy po nią sięgać ze świadomością jej kosztów.
Dwa koszty warto wyraźnie wskazać:
- Błędnie zapisana nazwa gniazda jest dozwolonym gniazdem ad hoc, a nie błędem. Zapisanie
databseszamiastdatabasesdaje udaną kompilację, w której nic nie płynie przez zamierzone gniazdo. Kompilator zgłasza nazwę gniazda różniącą się o jedną edycję od zadeklarowanej jako ostrzeżenie podające obie pisownie — zob. errors/warnings.md „Uses-socket near-miss lint” — ale jest to ostrzeżenie i nigdy nie zmienia wyniku kompilacji. - Dwie powierzchnie celowo nie są w ten sposób otwarte.
usesw dołączeniu encji Feature może wskazywać tylko gniazdo deklarowane przez dołączoną encję Feature, auseskrawędzi w encji Release może wskazywać tylko gniazdo deklarowane przez konsumującą encję Component. Operator konfiguruje i łączy w ramach architektury; nie jest jej autorem.release-delivers.yamlzawiera więcinfra:i nic o gniazdach — gniazdoassistantnależy do autora encji Aggregate i tylko do niego.
Pełny kontrakt opisano w
entities/component.md „Topology Sockets: usesSchema” oraz
architecture/07-dependency-resolution.md.