Сокет, который никто не объявлял, доставляет реальные значения
Этот пример учит одному правилу и обеим его половинам:
Потребитель может придумать соединение. Потреблять он может только то, что объявляет поставщик.
Автор сущности 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Отрисованный вывод и файл блокировки генерируются, а не поставляются: этот пример фиксирует свои входные данные и генерирует всё остальное заново. --auto-pull разрешает файл блокировки во время сборки; однократный запуск 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 стоит рассмотреть и как факт компиляции ahead-of-time. Компилятор не обращался к 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.