Сокет, який ніхто не оголошував, що доставляє реальні значення
Цей приклад навчає одного правила — і обох його половин:
Споживач може вигадати з’єднання. Споживати він може лише те, що оголошує постачальник.
Автор сутності Aggregate пише запис uses: у власному компоненті під іменем сокета,
якого не оголошує жодна сутність каталогу. Ребро будується і доставляє — значення
потрапляє до згенерованого артефакту точно так само, як через оголошений сокет. Проте
ключі, які може передавати це ребро, як і раніше оголошує ціль: назвіть ключ, якого
ціль не оголошує, і збірка зупиниться.
Усе тут розв’язується з каталогу стандартної бібліотеки. Робочий простір не створює жодної власної сутності Component, Feature чи Recipe.
Стек
Три компоненти, і один із них під’єднано двома різними способами:
| екземпляр | тип | що це |
|---|---|---|
db | core/datastore/mariadb | база даних |
model | core/ai-model/anthropic | кінцева точка моделі; реалізація у формі посилання, тож для неї не запускаються обчислення |
web | core/devtool/adminer | консоль, що споживає обидва |
core/devtool/adminer оголошує рівно один сокет:
usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: [env]Це все, що передбачив його автор. Консоль перед базою даних — це з’єднання, яке він мав на увазі; консоль, що несе кінцеву точку моделі у своєму середовищі, — ні.
Що пише Aggregate
aggregate-delivers.yaml під’єднує обидва ребра з одного блоку 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 не з’являється в жодному usesSchema — ні в цій сутності Component, ні в будь-якій іншій. Проте
це допустимо: мовчання каталогу про сокет означає, що з’єднання не було
передбачено, а не що його заборонено, і розробник сам володіє топологією власного
застосунку.
Ad-hoc сокет втрачає саме те, що містив би відсутній запис usesSchema
— немає selector, тож ніщо не обмежує, якого компонента може досягти
ребро, а перевірці безпеки типів між вузлами нічого оцінювати; немає
дозволеного списку inject:; немає valueSchema чи infraSchema для окремого ребра, тож
values: та infra: окремого ребра не мають контракту для перевірки й оголошених
значень за замовчуванням для успадкування. Конфігурацію окремого ребра, написану на такому сокеті, приймають,
і вона передається неперевіреною — так поводиться кожен сокет без контракту для цього
стовпа: оголошений сокет, що не задає valueSchema, перебуває в тому самому
становищі.
Чого він не втрачає — це того, що може передавати ребро. endpoint і model
— обидва ключі, які core/ai-model/anthropic оголошує у своєму стовпі provides.
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example adhoc-uses-socketПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd adhoc-uses-socketЗбирання
aggrega build --release release-delivers.yaml --auto-pullЗгенерований результат і lock-файл генеруються, а не постачаються: цей приклад комітить свої вхідні дані й генерує все інше заново. --auto-pull розв’язує lock-файл під час збірки; одноразовий запуск aggrega pull --release release-delivers.yaml заздалегідь робить те саме й дає змогу наступним збіркам працювати взагалі без прапорця. Сутності каталогу розв’язуються з hub.aggrega.ai — реєстру за замовчуванням, який називає .aggrega-config.yaml, — тож ні збірці, ні aggrega inspect не потрібен прапорець --catalog.
З ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.
Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека робочого простору ще не містить теки `adhoc-uses-socket`, викличте один раз інструмент `scaffold`, задавши для `example` значення `adhoc-uses-socket` і не задаючи `dir`: він запише приклад у нову теку `adhoc-uses-socket`. Потім викличте інструмент `build`, задавши для `workspace_root` значення `adhoc-uses-socket`, для `release` — `release-delivers.yaml`, для `auto_pull` — true і для `write` — true. Скажіть мені, які файли записала збірка; вони лежать у `adhoc-uses-socket/dist/`.Читаємо результат
dist/compose/docker-compose.yaml, сервіс 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]Чотири змінні, три з них доставлено ребрами, і результат не фіксує, який сокет було оголошено:
ADMINER_DEFAULT_SERVER: dbнадійшло черезdatabases, оголошений сокет. Його значення —provides.hostсутності Recipe бази даних, ім’я сервісу Compose.ASSISTANT_ENDPOINTіASSISTANT_MODELнадійшли черезassistant, ad-hoc сокет, і несутьprovides.endpointтаprovides.modelсутності Recipe моделі.
Вони розташовані в одній мапі, у порядку автора, без жодної позначки, анотації чи різниці в порядку між ними. У цьому й суть: ad-hoc сокет відрізняється тим, як його оголошують, а не тим, як він доставляє. Шлях доставки один, і обидва ребра йдуть ним.
ASSISTANT_ENDPOINT варто також прочитати як факт компіляції наперед.
Компілятор не звертався до Anthropic, щоб дізнатися https://api.anthropic.com;
Recipe видав його як детермінований рядок-вказівник, узятий з infra.endpoint компонента
моделі, а компілятор маршрутизував цей рядок, не
інтерпретуючи його. Сам Adminer не читає жодної зі змінних ASSISTANT_* — ці
ключі доставки обрав розробник, а контейнер консолі несе їх для
того, хто їх там читатиме.
Граф, який видає збірка, фіксує цю відмінність, хоча згенерований
артефакт — ні: кожне ребро має поле socket_declaration зі значенням
declared або ad-hoc, тож організація, яка хоче, щоб кожне з’єднання проходило
через сокет, оголошений її архітекторами, виражає це як політику управління,
а не покладається на те, що компілятор матиме власну позицію. Див.
architecture/11-governance-and-compliance.md.
Контроль: чого споживач і далі не може вигадати
aggregate-undeclared-key.yaml — це aggregate-delivers.yaml з однією зміною.
Ad-hoc ребро запитує третій ключ:
- in: ASSISTANT_API_KEY from: api_keycore/ai-model/anthropic оголошує endpoint і model у своєму стовпі provides
— і нічого більше. Збірка має завершитися помилкою:
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")Зупинка і є уроком, а де вона спрацьовує — це те, на що варто звернути увагу:
проблемний шлях називає ad-hoc сокет, uses.assistant, і зупиняється на
з’єднанні, а не на записі доставки всередині нього. Ключ from:
перевіряється за оголошеними provides цільової сутності Component на кожному ребрі, і те,
що сокет ad-hoc, нічого в цій перевірці не змінює. Автор, який може вигадати
ім’я сокета, і далі не може вигадати вихідний ключ у чужому компоненті.
Спершу йде відмова, потім Aggregate і шлях, на якому було задано
ребро, механізм і ключ доставки, під яким написано запис, хибний
ключ, тип компонента, щодо якого його розв’язано, і оголошені ключі цього типу
у відсортованому порядку — тож виправлення видно з самого повідомлення. Цільова
сутність Component, яка взагалі не оголошує provides, так само відхиляє кожне посилання from: на
неї; просто немає оголошених ключів для переліку, тож повідомлення закінчується
після типу компонента.
Що обрати
Оголошення сокета в каталозі лишається кращим шляхом, і саме так робить
каталог стандартної бібліотеки. Оголошений сокет має selector, що
обмежує, яких компонентів може досягти ребро, дозволений список inject:,
контракт для окремого ребра з власними значеннями за замовчуванням і опис — придатне до рецензування
твердження про передбачене з’єднання, версіоноване разом із сутністю, що його робить.
Ad-hoc сокет не має нічого з цього, і ребро безпечне лише настільки, наскільки безпечний автор,
який його написав.
Ad-hoc форма — це запасний вихід для випадку, який показує цей приклад: з’єднання, якого автор каталогу не передбачив, потрібне одному розгортанню, де очікування на зміну каталогу означало б очікування з випуском. Вдавайтеся до неї, знаючи її ціну.
Дві ціни варто назвати прямо:
- Ім’я сокета з помилкою — це допустимий ad-hoc сокет, а не помилка. Якщо написати
databsesзамістьdatabases, збірка буде зеленою, але через потрібний сокет нічого не передаватиметься. Компілятор повідомляє про ім’я сокета, що відрізняється від оголошеного на одну правку, як про пораду, що називає обидва написання — див. errors/warnings.md «Uses-socket near-miss lint» — але це попередження, і воно ніколи не змінює вердикт збірки. - Дві поверхні навмисно так не відкрито.
usesприєднання сутності Feature може називати лише сокет, який оголошує приєднана Feature, аusesокремого ребра в сутності Release може називати лише сокет, який оголошує споживча сутність Component. Оператор конфігурує й під’єднує в межах архітектури; він її не створює. Томуrelease-delivers.yamlміститьinfra:і нічого про сокети — сокетassistantналежить автору Aggregate, і лише йому.
Повний контракт див. у
entities/component.md «Topology Sockets: usesSchema» і
architecture/07-dependency-resolution.md.