Component
Концептуальная роль сущности Component (абстрактного интерфейса вычислительного узла в Domain 2) описана в architecture/04-entity-taxonomy.md. На этой странице рассматриваются средства описания сущности Component: семантическая таксономия меток, с помощью которой архитекторы накладывают когнитивную идентичность поверх операционной базовой онтологии, объявление schema: для столпов данных, декларативные таблицы usesSchema и featuresSchema для топологических сокетов и слотов подключения, обязательные требования присутствия, механизм наследования extends: и блок межполевых правил assertions:.
Таксономия семантических меток (соглашение стандартной библиотеки)
Если базовые типы чисто облачные, то операционный и когнитивный интеллект архитектуры целиком надстраивается через семантическую утиную типизацию.
Ядро компилятора на Go не интерпретирует эти метки. Компилятор строит плоский граф промежуточного представления (IR), не интерпретируя семантику меток. Эти метки представляют соглашение стандартной библиотеки — неизменяемые «генетические маркеры», которые создаёт архитектор платформы в домене 2. Они дают явные семантические точки подключения, с помощью которых валидаторы политик на Wasm и физические операционные сущности Recipes управляют архитектурой.
(A) Общий облачный слой Эти метки описывают универсальное поведение и позволяют движкам политик и генерируемым прокси уровня L7 управлять стандартными корпоративными архитектурами, не разбираясь нативно в AI-фреймворках.
| Префикс метки | Допустимые значения (соглашение) | Зачем это нужно Platform Ops (точка подключения политик) |
|---|---|---|
tool.aggrega.ai/impact | read-only, mutating | Позволяет движкам политик оценивать авторизацию по принципу наименьших привилегий. Изменяющие инструменты могут автоматически запускать политики, требующие подключения строгих sidecar-контейнеров с этапом утверждения. |
datastore.aggrega.ai/engine | relational, document, kv, vector, graph, semantic-memory, search (набор значений стабилизируется по мере наполнения каталога) | Позволяет движкам политик обеспечивать типобезопасность между узлами (например, не дать агенту попытаться отправить SQL-запросы в векторную БД). |
gateway.aggrega.ai/intelligence | semantic, l4-mesh | Определяет, какие функции маршрутизатор способен физически поддерживать (например, не даёт сущности Feature, которая маршрутизирует по модели, указанной в запросе, — скажем, цепочке резервных вариантов, — подключиться к стандартной TCP-сети mesh). |
dataplane.aggrega.ai/request-mirroring | full-rate, sampled | Позволяет сущности Feature, которая копирует живой трафик во второй пункт назначения, выбрать прокси, способный копировать в принципе, и отличить прокси, копирующий каждый подходящий запрос, от прокси, у которого долю копируемых запросов можно настроить. |
dataplane.aggrega.ai/caller-identity | client-certificate, injected-header | Позволяет сущности Feature, которой нужно, чтобы исходный вызывающий был идентифицирован для сервиса за прокси, выбрать компонент, способный передать эту идентичность, и узнать, какой механизм её передаёт: пересылаемые далее сведения о собственном TLS-сертификате клиента или заголовок, который прокси формирует сам после аутентификации вызывающего. |
dataplane.aggrega.ai/content-masking | entity-recognition, pattern-list | Позволяет сущности Feature, маскирующей чувствительный текст, выбрать компонент, способный заменить его заполнителем в маршрутизируемых им полезных данных chat и completion до того, как текст пойдёт дальше. Значение указывает точность: при entity-recognition компонент заменяет совпадения с шаблонами из своей конфигурации, а также типы сущностей, которые обнаруживает вызываемый им сервис распознавания; при pattern-list он заменяет только совпадения с шаблонами из своей конфигурации и не вызывает сервис распознавания. |
dataplane.aggrega.ai/prompt-guard | pattern-list, classifier | Позволяет сущности Feature, проверяющей промпты моделей, выбрать компонент, способный анализировать маршрутизируемые им полезные данные chat и completion и отклонять запрос по его содержимому. Значение указывает точность: при pattern-list сопоставление идёт с шаблонами из его конфигурации, по полезным данным модели, а не по произвольному телу HTTP; при classifier вердикт выносит обученный классификатор текста через вызываемый компонентом сервис обнаружения, с порогом из его конфигурации. |
dataplane.aggrega.ai/upstream-tls | trust-anchor | Позволяет сущности Feature, требующей, чтобы прокси проверял, с кем он общается, выбрать компонент, способный проверить сертификат вышестоящего сервиса по якорю доверия, который предоставляет сущность Release. |
dataplane.aggrega.ai/upstream-pinning | public-key | Позволяет сущности Feature, закрепляющей, какой ключ может предъявить вышестоящий сервис, выбрать компонент, способный отклонить вышестоящий сервис, если предъявленный им сертификат не содержит один из открытых ключей, предоставленных сущностью Release. Это утверждение, отличное от upstream-tls: закрепление говорит, каким ключом должен быть сертификат, а якорь — что в нём должно быть указано. |
dataplane.aggrega.ai/period-budget | cost, tokens | Позволяет сущности Feature, ограничивающей, сколько трафик может потребить за период, выбрать компонент, способный отклонять запросы к моделям, как только подсчитанное им за период превысит лимит из его конфигурации. Значение указывает, что именно считается: cost — стоимость трафика по таблице цен, которую компонент ведёт для каждой модели; tokens — токены, которые, согласно ответу каждой модели, были прочитаны, записаны или и то и другое; компонент их считает и ничего не оценивает в деньгах. |
dataplane.aggrega.ai/concurrency-cap | total, per-target | Позволяет сущности Feature, ограничивающей число одновременно обрабатываемых компонентом запросов, выбрать компонент, способный задержать или отклонить запрос сверх лимита из его конфигурации. Значение указывает, что считает один лимит: total — все запросы, которые пересылает компонент, с одним лимитом; per-target — запросы в процессе выполнения к каждой вышестоящей цели, с отдельным лимитом для каждой и без лимита на их сумму. |
Ключи dataplane.aggrega.ai/ обозначают позицию на пути трафика, а не
вид компонента, поэтому прокси, входной шлюз и service mesh описывают
себя одним словарём, а не каждый своим. Два свойства этого
семейства стоит прочитать внимательно, потому что оба легко понять наоборот:
- Значение несёт точность, а не только наличие возможности. Два компонента могут оба зеркалировать запросы и всё же различаться так, что это важно для Feature, поэтому различие передаётся в значении, и Feature выбирает нужную ей точность. Компонент, предлагающий более высокую точность, несёт более сильное значение и никакое другое.
- Значение утверждает, что продукт способен делать, а не что включено
в конкретном развёртывании. Они читаются похоже, но свойством
компонента является только первое. Прокси, способный проверить сертификат вышестоящего сервиса, несёт
upstream-tls: trust-anchorнезависимо от того, включает ли конкретное развёртывание эту проверку, потому что по метке Feature делает выбор ещё до того, как что-либо настроено.
Компонент, которому нечего описать по одной из этих осей, не несёт там никакого значения, а не самое слабое, точно так же, как и в остальной таксономии: отсутствие означает, что у оси нет предмета на этом компоненте, поэтому Feature, требующая на ней любое значение, правильно не подключается.
(B) Специализированный AI-слой (когнитивная идентичность) Эти метки описывают когнитивную идентичность рабочей нагрузки и позволяют архитектуре защищать современные AI-фреймворки.
| Префикс метки | Допустимые значения (соглашение) | Зачем это нужно Platform Ops (точка подключения политик) |
|---|---|---|
model.aggrega.ai/capability | generative, embedding, transcription | Используется строками селекторов usesSchema (которые компилятор на Go вычисляет нативно при статическом анализе), чтобы гарантировать, что разработчик случайно не направит генеративные текстовые данные на эндпоинт эмбеддингов. |
model.aggrega.ai/api | openai, anthropic, gemini, native | Указывает, какой API модели отвечает по адресу, который публикует компонент: openai, если это OpenAI API — собственный у вендора или его реализация на сервере, anthropic, если это Messages API от Anthropic — собственный у вендора или его реализация на сервере, gemini, если это Gemini API от Google, и native, если это собственный API продукта и ни один из перечисленных. Её несёт каждый компонент модели, а также шлюз, способный обслуживать API модели, поэтому сокет с селектором component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api принимает модель или такой шлюз и отклоняет шлюз, не способный обслуживать ни один, а сокет с одним значением, например model.aggrega.ai/api=anthropic, принимает только то, что обслуживает этот API. Метка указывает, что обслуживает продукт, а не что подключено в одной сущности Release: шлюз, модели которого подключаются к его собственному сокету, несёт её, даже когда ничего не подключено. Метка — это строка, с которой сопоставляется селектор; ничто не проверяет, что на самом деле отвечает по адресу. |
agent.aggrega.ai/autonomy | autonomous, copilot | Определяет риск выполнения когнитивного цикла и позволяет политикам требовать функций утверждения человеком для полностью автономных агентов. |
(C) Сквозные метки (управление, состояние и оборудование) Это базовые корпоративные теги, на которых основаны проверка Zero-Trust и маршрутизация по оборудованию.
| Префикс метки | Допустимые значения (соглашение) | Зачем это нужно Platform Ops (точка подключения политик) |
|---|---|---|
component.aggrega.ai/hosting | self-hosted, managed, external, mixed | Фиксирует, кто эксплуатирует базовый ресурс компонента, — ось границы доверия. Движки политик читают её, чтобы вычислить риск утечки данных (например, внутренние данные, направленные в managed сторонний API, покидают границу оператора). Сквозная: одни и те же значения описывают управляемую базу данных, управляемый API модели и самостоятельно запущенный сервер инференса. mixed помечает компонент, чьи сущности Recipes охватывают более одного режима эксплуатации, — хранилище данных, которое его сущности Recipes для Helm и Compose запускают самостоятельно, а сущности Recipes для RDS делают управляемым, — так что режим эксплуатации Release следует за сущностью Recipe, которую выбирает его Manifest. |
compliance.aggrega.ai/data-class | public, internal, restricted | Класс данных, которые хранит компонент. Компилятор переносит его в граф сборки как строку и ничего не ранжирует; политика, которую оператор подключает на роли ir-verdict, задаёт порядок классов в собственных настройках и читает метку вдоль маршрутов, которые перечисляет компилятор, — останавливая, например, сборку, в которой компонент restricted достигает компонента другого класса без подключённой на маршруте рассекречивающей сущности Feature (policy-data-class-route). Ни одна сущность Component стандартной библиотеки её не несёт: класс — это утверждение о том, как ландшафт использует компонент, и его несёт собственная сущность Component ландшафта — например, специализация через extends. |
compliance.aggrega.ai/contains-pii | true, false | Явно помечает рабочие нагрузки как входящие в область GDPR/CCPA. Подключённая оператором политика может читать её, чтобы требовать определённые Features на маршрутах, по которым идёт трафик такой нагрузки, — например, core/data-masking на AI-шлюзе, через который она отправляет трафик к модели; именно такую форму policy-data-class-route проверяет для класса данных. Ни одна сущность Component стандартной библиотеки её не несёт; как и класс данных, это утверждение ландшафта о собственных компонентах. |
hardware.aggrega.ai/accelerator | gpu, tpu, npu | Используется DevOps в файле Release. Они явно направляют эти компоненты в границы физических пулов оборудования (например, в кластер с GPU) через словарь components: {}, а роль вердикта управления может следить, чтобы компоненты с меткой GPU никогда не размещались в границах без GPU. |
state.aggrega.ai/retention | retain, delete | Закрывает разрыв удаления при AOT. Если разработчик удаляет базу данных из своего Aggregate, оркестратор GitOps физически удалит диск. Шаг pipeline: сущности Recipe может прочитать метку retain и добавить к отрендеренным артефактам нативную для оркестратора защиту (например, helm.sh/resource-policy: keep). |
state.aggrega.ai/backup-tier | mission-critical, standard, ephemeral | Хук доступности SOC2. Сообщает операционной FeatureRecipe, нужно ли физически генерировать для ресурса конфигурации автоматических снимков и резервного копирования томов. |
(D) Динамический бизнес-контекст (каскадные аннотации) Если labels задают неизменяемую ДНК каталога, то динамические бизнес-контексты (например, область аудита SOC2 или учёт затрат FinOps) меняются в зависимости от того, кто развёртывает приложение и где оно работает. Ими управляют аннотации, динамически внедряемые через subsystems разработчика, границы операционной Release или плагин управления, подключённый в роли annotation-transform.
| Префикс аннотации | Допустимые значения (соглашение) | Зачем это нужно Platform Ops (точка подключения политик) |
|---|---|---|
business.aggrega.ai/cost-center | например, finance, ai-research | Требуется плагинам рендеринга Wasm, чтобы внедрять физические теги (например, теги AWS или метки K8s) в итоговые сгенерированные артефакты для панелей облачного биллинга. |
business.aggrega.ai/owner | например, team-alpha@corp.com | Маршрутизация реагирования на инциденты. Гарантирует, что инфраструктура сопоставлена с командой людей. |
compliance.aggrega.ai/frameworks | например, soc2, hipaa | Триггер области SOC2. Внедряется через Release окружения. Плагины Wasm читают эту строку, чтобы автоматически генерировать строгие сайдкары аудит-логирования и отключать отладочные порты, когда приложение входит в производственную границу соответствия требованиям. |
Таксономия — это соглашение каталога, а не правило компилятора. Предприятия могут игнорировать её, удалить или придумать собственный словарь меток (mycompany.com/custom-trait). Плагины Wasm оценивают любые ключи меток, которые создаёт предприятие.
Создание схем
Схема Component (и её аналог Feature, включая Features учётных данных с меткой feature.aggrega.ai/kind: secret) объявляет контракт валидации для заданных разработчиком values через блок spec.schema:. Блок принимает JSON Schema 2020-12, записанную либо в компактной сокращённой форме YAML (по умолчанию; около 15 ключевых слов, механически преобразуемых в JSON Schema во время компиляции), либо в полной форме JSON Schema YAML (подробная форма), с межд документными ссылками через $ref: на записи SchemaLibrary, общие для нескольких Components.
- Встроенная компактная форма (основной способ создания): встроенный блок YAML с листьями компактной формы непосредственно в YAML сущности Component. Подходит для подавляющего большинства содержимого схем каталога и занимает лишь долю строк полной JSON Schema. Словарь ключевых слов и соглашения о создании описаны в
vocabulary/compact-form-authoring.md. - Встроенная JSON Schema YAML: подробная форма, подходящая, когда схеме нужны ключевые слова JSON Schema 2020-12, которые компактная форма напрямую не поддерживает (
$dynamicRef, глубокиеunevaluatedProperties, сложная композицияnot:). Компактную форму и JSON Schema можно смешивать на границе любого узла в пределах одного блокаschema:через запасной выход$jsonschema:. - Междокументная ссылка (
$ref:на запись SchemaLibrary): нативная для JSON Schema ссылка$ref:, указывающая на запись SchemaLibrary по идентификатору (Datastores#/schemas/MariaDBValuesили аналогично). Корпоративные схемы на сотни строк, повторно используемые несколькими Components, хранятся в сущностях SchemaLibrary; использующая их сущность Component ссылается на запись, не встраивая содержимое. Сущность библиотеки и семантика разрешения описаны вentities/schemalibrary.mdиvocabulary/cross-document-ref.md.
Три формы выше задают содержимое столпов и доступны сущности Component, которая ничего не расширяет. Сущность Component, объявляющая extends:, вообще не задаёт содержимого столпов: она записывает литеральный маркер schema: inherited и получает блок столпов своей базы ровно в том виде, в каком его задала база. Этот маркер — единственное значение, которое schema: принимает в такой сущности Component. См. раздел «Создание каталога: расширение базовых Components» ниже.
Компилятор разрешает блок schema: — разворачивает компактную форму, разыменовывает URL в $ref:, применяет цепочки SchemaLibrary от библиотеки к библиотеке — и объединяет полученную JSON Schema с автоматически сгенерированными базами, выведенными из usesSchema и featuresSchema (см. раздел ниже), на этапе валидации сущности Component. Валидация выполняется по разрешённой схеме; способ создания непрозрачен для последующих стадий конвейера.
Созданные экземпляры проверяются по этой разрешённой схеме во время сборки: заданные разработчиком values экземпляра компонента и разрешённые оператором infra, а также values/infra любого подключения Feature должны соответствовать объявленным столпам — значение неверного типа, число вне диапазона, строка, не имеющая объявленного format, отсутствующее обязательное поле или (для values, проверяемых как закрытые) необъявленное свойство останавливают сборку в месте их задания, а не порождают сломанный манифест во время развёртывания. Столп, схема которого называет format, не проверяемый компилятором, — любой, кроме email, uri, hostname, ipv4, ipv6, uuid, date-time и date, включая password, — отклоняется при загрузке каталога с перечислением поддерживаемых имён; что проверяет каждое имя, описано в vocabulary/compact-form-authoring.md. Экземпляр сущности Component, которая через extends: расширяет базу, проверяется по блоку столпов базы, который расширяющая сущность Component наследует без изменений, — поэтому экземпляр базы и экземпляр любого её расширения подчиняются одному контракту столпов. Диагностика и правила для каждого столпа (в том числе как infra проверяется по объединению ключей сущности Component и провайдера) описаны в errors/fatal-halts.md, §«Authored values or infra do not conform to the declared schema (Заданные values или infra не соответствуют объявленной схеме)».
Объявленные значения по умолчанию материализуются в отрисованных столпах. Помимо валидации, default:, объявленный для поля values (или поля infra), подставляется в отрисованный столп во время сборки для каждого ключа, который автор опустил, — поэтому шаблон Recipe, читающий {{ .values.charset }}, получает объявленное в схеме utf8mb4, а не пустое значение. Значения, заданные автором, всегда имеют приоритет; вложенные объекты заполняются по каждому опущенному дочернему элементу. Поскольку материализация использует то же разрешение схемы, что и валидация, значения по умолчанию, достигнутые через междокументную $ref: в SchemaLibrary, тоже материализуются — как при ссылке на весь столп (values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}), так и в форме «база плюс вариант» (базовая $ref: рядом с соседними properties, каждое со своими значениями по умолчанию). Значения по умолчанию, объявленные только внутри локальной внутридокументной ссылки #/$defs/ или в ветви allOf / oneOf / anyOf, не материализуются; стандартная библиотека составляет столпы через междокументную $ref:, которая материализуется.
Столп values
Схема Component разделяет три столпа по принадлежности: values заполняет разработчик в Aggregate (когнитивное намерение — имя базы данных, версия, кодировка), infra заполняет оператор в Release (эксплуатационное определение размеров — вычисления, хранилище, HA), а provides задаёт Recipe (публичный контракт API — хост, порт, протокол). Разработчик никогда не видит infra; оператор никогда не видит values. Recipes используют оба столпа при базовом рендеринге, отображая абстрактные столпы в конкретную форму, которую ожидает их целевой провайдер. В этом разделе описана поверхность написания столпа values. Общая таксономия столпов и дисциплина каскада между столпами описаны в vocabulary/data-pillars.md.
values несёт когнитивное намерение разработчика — решения, описывающие, чем является или что делает приложение, а не как оно масштабируется или работает. Типичное содержимое values — имя базы данных, кодировка, версия движка, уровень логирования, флаги функций и параметры уровня приложения, которые меняются между версиями приложения, но остаются неизменными между окружениями. Оператор никогда не переопределяет values: (схема Release механически отклоняет блок values: согласно architecture/06-data-taxonomy-and-composition.md §8 Constraint 4); различия между окружениями передаются через Parameter Hoisting — Aggregate предоставляет типизированные parameters.*, шаблон values сущности Component ссылается на них, а Release задаёт значения параметров.
# Component schema declares the values shape:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-serverspec: 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Использование на стороне Recipe. Recipes читают разрешённые значения через .values.<field> в valuesMapping:, provides:, assertions: и других поверхностях шаблонов — матрица доступности по шаблонам приведена в entities/recipe.md. Компилятор объединяет схему values сущности Component со всеми схемами values: прикреплений Feature в том же узле Component, чтобы разрешённый контекст шаблона содержал каждое применимое поле.
Дисциплина между столпами. values — единственный столп, который разработчик пишет в Aggregate. Здесь место строго ориентированным на разработчика полям; эксплуатационные параметры (число реплик, границы CPU/памяти) относятся к столпу infra сущности Component, чтобы они находились в Release; публичный вывод (хост, порт) относится к provides сущности Recipe. Их смешение нарушает инвариант принадлежности; редкие случаи, когда намеренная передача данных между столпами оправдана, описаны в vocabulary/data-pillars.md, раздел «Cross-pillar mechanics».
Опора infra
Схема Component разделяет три опоры по принадлежности: values заполняет разработчик в Aggregate (когнитивное намерение — имя базы данных, версия, кодировка), infra заполняет оператор в Release (эксплуатационные размеры — вычисления, хранилище, HA; резервное копирование хранилища данных здесь не задаётся — это Feature core/backup, которую оператор прикрепляет в Release), а provides задаёт Recipe (публичный контракт API — хост, порт, протокол). Разработчик никогда не видит infra; оператор никогда не видит values. Recipes используют обе опоры при базовом рендеринге, отображая абстрактные опоры в конкретную форму, которую ожидает их целевой провайдер.
Для каждой независимой от возможностей сущности Component в стандартной библиотеке важны три соглашения об infra: запасной выход в виде открытой структуры для параметров, специфичных для провайдера, необязательное переопределение версии вышестоящего артефакта и словарь намерений для полей высокой доступности. Каноническая эталонная сущность Component — core/datastore/mariadb в каталоге стандартной библиотеки: её могут реализовать Helm Recipes, которые запускают официальный образ mariadb или передают пользовательский ресурс MariaDB контроллеру mariadb-operator, Terraform Recipes на основе AWS RDS, CloudFormation Recipes на основе той же поверхности RDS и Compose Recipes на основе локального контейнера, — и её блок infra иллюстрирует первый и третий шаблоны.
infra.overrides
Универсальные поля infra — compute, storage, ha — покрывают большую часть эксплуатационных размеров для всех провайдеров. Оставшаяся часть неустранимо специфична для провайдера: Kubernetes Recipe нужен nodeSelector, RDS Terraform Recipe нужен instance_class, CloudFormation RDS Recipe нужен DBInstanceClass, Compose Recipe нужно переопределение image. Схема Component предоставляет по-настоящему открытую карту как запасной выход, чтобы эти параметры проходили насквозь, не раздувая схему:
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Явное type: object с additionalProperties: true включает семантику открытой карты. Компилятор передаёт структуру без изменений; тело шаблона Recipe читает те ключи, о которых знает, и игнорирует остальные. Каждый Recipe документирует онтологию ключей переопределения в своём заголовочном комментарии, поэтому оператор, создающий Release для конкретной комбинации Component × Recipe, знает, какие параметры предоставляет Recipe.
Фрагмент Release с переопределениями:
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Разработчик никогда не видит overrides — он находится в Release, который относится к области оператора.
infra.source_version
Поле source сущности Recipe ссылается на вышестоящий артефакт определённой версии (Helm-чарт 25.0.8, модуль Terraform 4.2.0, тег образа OCI). Жёсткое задание версии внутри Recipe вынуждает сопровождающего каталога публиковать новый Recipe при каждом совместимом повышении вышестоящей версии. Схема Component предоставляет необязательное переопределение:
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.Recipe читает его через вспомогательную функцию optional в своём блоке source, поэтому при
отсутствии закрепления используется версия, для которой Recipe был написан:
source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "{{ optional .infra `source_version` `25.0.8` }}"Строки source сущности Recipe (и строковые подполя структурированной карты source:) вычисляются как шаблоны Go. Удалённая координата — например, version выше — вычисляется, когда aggrega pull закрепляет артефакт, по .values, .infra и .locals без корня .context; источник, указывающий путь в рабочем пространстве, вычисляется при рендеринге сущности в том же самодостаточном контексте, что и locals сущности Recipe, — .context.instance_id, .values, .infra и все разрешённые .locals узла. В обоих случаях .context.inject, .context.uses и .provides запрещены. Именно наличие .infra в этом контексте заставляет работать переопределение выше, а .locals позволяет Recipe вычислить фрагмент источника один раз и прочитать его здесь. Шаблон источника никогда не читает provides собственного узла: эта опора не входит в контекст, и шаблон, обращающийся к ней, останавливает сборку — это неизменное свойство поверхности, а не пробел, ожидающий доработки. Полные правила доступности см. в строке №5 матрицы раскрытия шаблонов. Изменение infra.source_version относительно значения по умолчанию в Recipe не гарантирует, что valuesMapping сущности Recipe совместим по формату с новой вышестоящей версией; это предупреждение содержится в description объявления source_version в схеме Component.
infra.ha.*
Поля высокой доступности используют словарь намерений, а не словарь механизмов:
infra: ha: enabled: { type: boolean, default: false } read_replicas: { type: integer, min: 0, default: 0 }infra.ha.enabled означает «сделать этот Component высокодоступным», а infra.ha.read_replicas — «мне нужно N копий только для чтения». Каждый Recipe сам решает, во что превращается намерение у его провайдера. Recipes стандартной библиотеки для core/datastore/mariadb под теми именами, под которыми их сопоставляет Manifest:
| Recipe | ha.enabled: true отображается в | ha.read_replicas: N отображается в |
|---|---|---|
helm/mariadb (StatefulSet на официальном образе mariadb) | запускает один сервер, поэтому сборка останавливается с указанием ключа | запускает один сервер, поэтому N больше 0 останавливает сборку |
helm/mariadb-cluster (пользовательский ресурс MariaDB, который согласует контроллер mariadb-operator) | включает автоматическое переключение при отказе (replication.primary.autoFailover: true); переключение идёт на реплику для чтения, поэтому N, равное 0, останавливает сборку | задаёт spec.replicas равным N + 1 и включает репликацию; provides.host становится Service <name>-primary |
terraform/mariadb-rds (AWS RDS) | задаёт multi_az = true для основного aws_db_instance | создаёт N отдельных ресурсов-реплик чтения aws_db_instance |
terraform/mariadb-rds-module, terraform/mariadb-rds-terraform-aws-modules (AWS RDS через модуль) | передаёт модулю multi_az = true | создаёт один экземпляр, поэтому N больше 0 останавливает сборку |
cloudformation/mariadb-rds (AWS RDS) | задаёт MultiAZ: true для AWS::RDS::DBInstance | создаёт один экземпляр, поэтому N больше 0 останавливает сборку |
compose/mariadb (локальный контейнер для разработки) | запускает один сервер, поэтому сборка останавливается с указанием ключа | запускает один сервер, поэтому N больше 0 останавливает сборку |
Словарь механизмов (infra.primary.replicas) естественно читается для одного провайдера (поды Kubernetes — реплики StatefulSet) и как категориальная ошибка для остальных: у RDS нет понятия «реплик» основного экземпляра, CloudFormation повторяет RDS, а у Compose вообще нет абстракции горизонтальных реплик. Словарь намерений переводим: у каждого провайдера есть какое-то понятие «сделать эту базу данных высокодоступной» и какое-то понятие «мне нужно N копий только для чтения», а Recipe выполняет перевод для конкретного провайдера. Если у реализации нет такого механизма, её Recipe может остановить сборку с указанием ключа, как это делают helm/mariadb и compose/mariadb для обоих ключей и одноэкземплярные RDS Recipes для реплик чтения.
infra.ha.read_replicas: 0 — значение по умолчанию; когда оба ключа имеют значения по умолчанию, helm/mariadb-cluster рендерит одноэкземплярную MariaDB без блока replication, а не репликацию поверх одного экземпляра. compose/mariadb запускает один сервер на локальном хосте Docker, поэтому infra.ha.enabled: true или ненулевое infra.ha.read_replicas останавливает сборку с указанием ключа, а сообщение указывает на helm/mariadb-cluster, который обеспечивает переключение при отказе и реплики для чтения.
Опора provides
provides — это публичный API, создаваемый автором Recipe: значения, которые разрешённый Recipe сущности Component передаёт нижестоящим вызывающим сторонам через их поверхность .context.uses.<alias>.provides.<provided-name> (или, если вызывающая сторона объявляет на ребре список разрешённых inject:, через её канал .context.inject). Схема Component объявляет форму (имена ключей и типы); блок provides: привязанного Recipe предоставляет значения. Разработчик, создающий Aggregate, видит форму provides на странице Component как контракт, на который могут полагаться вызывающие стороны; автор Recipe выполняет контракт для конкретной реализации, которую он оборачивает.
Выполнение контракта обеспечивается как Loud Guardrail: привязанный Recipe должен выдать каждый ключ provides, который объявляет его Component. Если привязанный Recipe опускает объявленный ключ, сборка останавливается и называет недостающий ключ, вместо того чтобы молча ничего не передать вызывающим сторонам, которые на него ссылаются. Выдавать дополнительные ключи сверх объявленного набора разрешено. Проверяется только наличие ключей: выдаваемые значения — это непрозрачные строки, которые компилятор передаёт дальше, поэтому их объявленные типы остаются контрактом, который читают вызывающие стороны, а не значением, которое проверяет компилятор.
# Component schema declares the provides contract:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-serverspec: 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/v1beta1kind: Recipemetadata: name: mariadb-bitnami version: 1.0.0spec: 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 }}"Разделение вычислений на provides и inject. Компилятор вычисляет шаблоны provides: на этапе вычисления provides в самодостаточном контексте шаблона (.context.instance_id, .context.rendered_name, если провайдер узла его сообщает, .values, .infra и разрешённые locals: сущности Recipe на том же узле) — состояние вызывающих сторон недоступно. Локальные значения узла разрешаются в преамбуле этого этапа, до его provides, что и позволяет шаблону provides: читать .locals. На следующем этапе, гидратации inject, компилятор обходит рёбра uses: и разрешает .context.uses.<alias>.provides.<provided-name> каждой вызывающей стороны по разрешённым значениям provides. Такое разделение гарантирует ацикличное разрешение: provides: не может ссылаться на вызывающую сторону, а inject: вызывающей стороны не может ссылаться на ещё не разрешённый результат провайдера до начала гидратации inject.
Эволюция контракта. Переименование или удаление поля provides — это критическое изменение для каждой вызывающей стороны, полагающейся на старое имя. Сигнал об эволюции контракта несёт metadata.version сущности Component (и объявление implements: сущности Recipe); нижестоящие вызывающие стороны, закреплённые за определённой мажорной версией, видят стабильную форму provides.
Описание со стороны Recipe. Грамматику написания шаблонов provides:, матрицу доступности для каждого шаблона и разобранные примеры маршрутизации между пространствами имён и между регионами см. в entities/recipe.md, раздел «The provides: block», и в architecture/06-data-taxonomy-and-composition.md §3.
Обязательное присутствие: features.aggrega.ai/requiredType.<label>
Сущность Component может объявить, что каждый её экземпляр обязан нести присоединение сущности Feature заданного типа. Это требование присутствия, и оно записывается как повторяемая аннотация в собственных метаданных сущности Component:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: 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-compliancespec: schema: values: processor_endpoint: { type: string, required: true }Ключ — это префикс features.aggrega.ai/requiredType., за которым следует выбранная вами метка; значение — URI типа Feature, который должно нести хотя бы одно присоединение. Метка называет требование в диагностике, которую выдаёт невыполненное требование, — выше это audit и compliance, — и в этом её единственная задача. Ключи с метками позволяют сущности Component объявить несколько требований сразу: аннотации представляют собой плоскую карту строк и не могут содержать повторяющийся ключ.
Компилятор проверяет каждое требование по итоговому набору присоединений экземпляра — после того как каскад 5-Tier Onion Model свернул все области: блоки features: уровня компонента и уровня подсистемы в сущности Aggregate, блоки features: уровня границы и уровня компонента в сущности Release, а также присоединения, созданные расширением на основе аннотаций. Требование удовлетворяет любое из них: правило проверяет, что присутствует, а не то, как оно туда попало. Поэтому сущность Component, требование которой выполнено лишь потому, что оператор задал аннотацию мониторинга в сущности Release, проходит проверку точно так же, как та, к которой разработчик присоединил Feature вручную.
Требование, которое не удовлетворяет ни одно присоединение, останавливает сборку с диагностикой, называющей экземпляр компонента, метку требования и требуемый тип. Значение аннотации — непрозрачная строка, поэтому ничто не проверяет её форму до того, как её прочтёт компилятор; значит, значение, не являющееся URI типа Feature, или ключ без метки после префикса останавливают сборку с отдельной диагностикой о том, что объявление некорректно. Эти две диагностики различаются намеренно: ошибочное объявление исправляется в сущности каталога, а невыполненное требование — присоединением Feature, и опечатка никогда не должна читаться как выполненное требование.
Обе диагностики описаны в errors/fatal-halts.md в разделе «Required feature not attached (Требуемая функция не присоединена)».
Требование — это не слот. Эти две поверхности отвечают на разные вопросы, и разница не косметическая:
слот featuresSchema | требование присутствия | |
|---|---|---|
| Объявляет | именованную точку привязки | ограничение на то, что должно присутствовать |
| Имя можно разыменовать | да — from: <slot> и .features.<slot>.provides.* | нет — метка называет требование, и только |
| Кратность | ровно одно заполнение на слот | хотя бы одно присоединение данного типа |
| Ограничивает заполнение | selector, inject, sensitive | ничем, кроме типа |
| Удовлетворяется свободным присоединением | нет — слот заполняется по имени | да — в любой области, под любым именем |
| Когда требование не выполнено | останавливает сборку, когда задано required: true и ничто не привязано к имени слота | останавливает сборку, когда ни одно присоединение не несёт этот тип |
Оба требования проверяются по одним и тем же входным данным — итоговому набору присоединений экземпляра, — и оба останавливают сборку со своей диагностикой, потому что задают им разные вопросы: привязана ли одна именованная точка привязки или несёт ли какое-либо присоединение именованный тип. Ни одно не отвечает за другое.
Используйте слот, когда сущности Recipe нужно прочитать то, что присоединено. Используйте требование, когда контракт сущности Component требует присутствия возможности и ему неважно, какой экземпляр её предоставляет. Сущность Component для обработки платежей, требующая core/audit-logging, получает журналирование аудита в каждом развёртывании, вспомнил ли разработчик его присоединить или нет; PCI-совместимая сущность Component, требующая core/pci-compliance, не может быть выпущена без Feature соответствия, присоединённой где-либо в развёртывании.
Наследование. Требование, объявленное в базовой сущности Component, наследуется каждой сущностью Component, которая делает extends: от неё, поскольку аннотации метаданных сливаются вдоль цепочки extends, и по каждому ключу побеждает потомок. Поэтому потомок может перенацелить унаследованное требование, повторно объявив ту же метку с другим типом, или добавить собственные требования под новыми метками; удалить требование, объявленное в базовой сущности, он не может.
Топологические сокеты: usesSchema
Сущность Component может объявлять топологические сокеты через блок usesSchema: — декларативную YAML-карту, параллельную featuresSchema. Каждая запись именует сокет, через который сущность Component принимает межкомпонентные зависимости, и определяет, какие формы сущностей Component разработчик может подключить к этому сокету. Компилятор автоматически генерирует правила валидации JSON Schema 2020-12 из объявленных сокетов и объединяет их с schema: сущности Component при разрешении сущности Component; разработчики не пишут вручную столп uses: внутри schema:, поскольку структура берётся из usesSchema.
# Component declares the sockets it accepts:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/ai-agent/orchestrator version: 1.0.0 labels: component.aggrega.ai/type: serverspec: 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 }Формы подключения — сокет принимает одну или несколько целей. В примерах выше каждый сокет подключён к одной цели, но сокет может разветвляться на несколько. Значение сокета записывается в одной из двух форм:
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 }] } }Псевдоним всегда отображается на объект записи и никогда — на голое имя цели: databases: { primary: orders-db } отклоняется при загрузке, как и объект записи без target:. Чтобы подключить одну цель, не придумывая псевдоним, используйте компактную форму — primary_datastore: [vector-db-instance], — которая называет цель один раз и выводит псевдоним из неё.
Каждая запись — элемент списка или псевдоним карты — становится одним ребром с сохранением порядка записи. selector: сокета применяется к каждой цели, подключённой через него (каждое ребро проверяется по типам независимо во время статического анализа), а required: true означает, что должна быть подключена хотя бы одна цель.
Семантика полей:
| Поле | Тип | По умолчанию | Значение |
|---|---|---|---|
required | bool | false | При true разработчик должен подключить к этому сокету хотя бы одну зависимость. При false сокет необязателен. |
selector | string | — | Селектор меток в грамматике, которую использует appliesTo сущности Feature, которому должна удовлетворять цель каждого ребра, подключённого через этот сокет. Он читается как записанная здесь строка и вычисляется по меткам цели во время статического анализа: цель, метки которой ему не удовлетворяют, останавливает сборку, как и селектор, отвергнутый грамматикой, — с указанием требования, которое не удалось прочитать. Пустой селектор не накладывает ограничений на цель. |
inject | string[] | — | Список разрешённых механизмов доставки inject (параллельно featuresSchema[].inject). Отсутствие или [] (пусто) означает «чёрный ящик» — блок inject: в записи uses: разработчика не допускается; доставкой управляет Recipe. [env, file, arg] (непустой) означает прозрачный режим — разработчик может определить, какой механизм доставляет значения provides зависимости. Применяется принудительно: см. ниже «Где применяется список разрешённых inject сокета». |
valueSchema | object | — | Необязательный контракт на уровне ребра для заданных разработчиком values на ребре, подключённом через этот сокет (записывается в сущности Aggregate). JSON Schema 2020-12 в тех же формах записи, что и schema:. Отсутствие означает, что сокет не объявляет контракт для values. |
infraSchema | object | — | Необязательный контракт на уровне ребра для заданного оператором infra на ребре, подключённом через этот сокет (записывается в сущности Release). Те же формы записи, что и у valueSchema. Отсутствие означает, что сокет не объявляет контракт для infra. |
featuresSchema | map | — | Слоты вложений, которые может заполнять каждое соединение через этот сокет, с ключами по имени слота; каждый слот принимает те же ключи, что и слот уровня Component. Отсутствие означает, что соединение через этот сокет не несёт вложений. См. ниже «Слоты, которые заполняет каждое соединение». |
Где применяется список разрешённых inject сокета. Список разрешённых — это заявление сокета о том, может ли потребитель вообще выбирать форму доставки и если да, то какие формы, — поэтому он проверяется для каждого ребра uses:, подключённого через сокет, как только доступны и ребро, и объявление сокета. Из одного правила следуют два отказа, и оба останавливают сборку:
- Ребро, задающее механизм, которого нет в списке разрешённых, останавливает сборку с указанием сокета, недопустимого механизма и того, что сокет разрешает. Все недопустимые механизмы на ребре сообщаются вместе.
- Ребро, задающее любую доставку через сокет, список разрешённых которого отсутствует или пуст, также останавливает сборку. Так работает объявление «чёрного ящика»: оно говорит «Recipe доставляет это внутренне; не задавайте доставку», и пустой список разрешённых не допускает ничего, а не допускает всё.
Сокет читается из той сущности, которая его объявила, и это не всегда компонент, к которому относится ребро: ребро, записанное в uses: вложения Feature, разрешается по usesSchema вложенной сущности Feature, а любое другое ребро — записанное в сущности Aggregate, подключённое из сущности Release или достигнутое через подагрегат — по схеме потребляющей сущности Component. Сокет, унаследованный через extends, читается точно так же, как объявленный самой сущностью.
Ребро, которое ничего не задаёт, не затрагивается ни одним из отказов, что бы ни объявлял сокет: чтение значений зависимости из .context.uses.<alias>.provides.<name> в потребляющей сущности Recipe не требует блока inject: и доступно всегда. Оба диагностических сообщения описаны в errors/fatal-halts.md.
Контракты соединения на уровне ребра — valueSchema и infraSchema. Помимо того, какие сущности Components могут подключаться к сокету, сокет может объявлять, какую конфигурацию несёт каждое соединение. Две необязательные схемы на уровне сокета валидируют конфигурацию соединения на каждом ребре, подключённом через сокет:
valueSchema— контракт для заданного разработчиком блокаvaluesна ребреuses: настройка отдельного соединения, которую разработчик выражает в сущности Aggregate (например, размер пула соединений или режим клиента).infraSchema— контракт для заданного оператором блокаinfraна ребреuses: эксплуатационное определение размеров отдельного соединения, которое оператор выражает в сущности Release.
Обе принимают JSON Schema 2020-12 в тех же формах содержимого, что и поле schema:: встроенная компактная форма, встроенный YAML JSON Schema или междокументная ссылка $ref: на запись SchemaLibrary. Это контракты на уровне ребра, которые проверяются для конфигурации каждого ребра независимо; они не включаются в собственную схему values потребляющей сущности Component. Сокет, не задающий схему на уровне ребра для столпа, не объявляет там контракта, и любая конфигурация для этого столпа не валидируется. Конфигурация на уровне ребра валидируется как закрытая, и валидация учитывает значения по умолчанию в обоих столпах: ключ, для которого схема задаёт default:, считается предоставленным, даже если автор его опустил.
Объявленный default: также материализуется в обоих столпах. Опущенный автором ключ попадает в контекст рендеринга потребляющей сущности Recipe со своим объявленным значением по умолчанию — точно так же, как опущенный ключ value или infra компонента, — поэтому достаточно объявить значение по умолчанию в сокете, и шаблону Recipe не нужно резервное выражение для него. Заданное значение всегда имеет приоритет над объявленным по умолчанию и заполняет только тот ключ, который задаёт: ребро, задающее один ключ контракта сокета, всё равно получает объявленные значения по умолчанию для остальных ключей контракта. Значения по умолчанию привязаны к рёбрам, поэтому неподключённый сокет ничего не добавляет.
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 }При таком объявленном сокете ребро, сущность Aggregate которого опускает pool_size, рендерит 10, а ребро, сущность Release которого опускает storage_class, рендерит standard. Заданное значение побеждает по каждому ключу в пределах своего столпа: сущность Aggregate, задающая pool_size: 42, рендерит 42, а tls_mode по-прежнему заполняется значением require; сущность Release, задающая storage_class: gp3, рендерит gp3, не затрагивая ни одного ключа разработчика.
Recipe для потребляющей сущности Component читает разрешённую конфигурацию ребра из обогащённого топологического канала по путям .context.uses.<alias>.values.<key> и .context.uses.<alias>.infra.<key> — см. vocabulary/topology-triad.md.
Слоты, которые заполняет каждое соединение, — featuresSchema сокета. Сокет также может объявлять слоты вложений, и тогда каждое соединение через него может нести в каждом из них собственное вложение: шлюз, обращающийся к нескольким моделям, хранит для каждой свои учётные данные, поскольку учётные данные относятся к соединению, а не к шлюзу.
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.Соединение заполняет слот, неся вложение под именем слота в собственном блоке features: — в записи соединения в Aggregate (Aggregate) или в Release (Release), — и это вложение становится одним из вложений потребляющего компонента с именем <alias>.<slot>.
Что именно делает объявление:
- Имена слотов образуют закрытый набор. В отличие от собственного
featuresSchemaсущности Component, который допускает свободное вложение под любым именем, слоты сокета — единственные имена, которые может нести соединение через него: любое другое имя останавливает сборку при загрузке, а сокет, не объявляющийfeaturesSchema, не допускает вложений на своих соединениях. Ad-hoc сокет — тот, который этотusesSchemaне объявляет, — не объявляет слотов, поэтому его соединения тоже их не несут. Каждое соединение заполняет свои слоты само: вложение более широкой области никогда не каскадируется на соединение, а ключ Release, записывающий составное имя вложения соединения, останавливает сборку. - Остальные ключи применяются к каждому соединению. Слот здесь принимает те же ключи, что и слот уровня Component, —
required,selector,inject,sensitive,description, — и каждое соединение проверяется по ним отдельно.selectorсопоставляется с метками сущности Feature, которой соединение заполняет слот, и недопустимое заполнение останавливает сборку с указанием на запись этого соединения в документе, где записано заполнение.required: trueобязательно для каждого соединения через сокет: соединение, оставившее слот пустым, останавливает сборку с указанием этого соединения, тогда как соседнее соединение, заполнившее слот, проходит.sensitiveчитается точно так же, как на слоте уровня Component: вложение, заполняющее слот, помечается как конфиденциальное в графе сборки и вaggrega inspect. На соединении, как и на компоненте, какие значения вложения скрываются как конфиденциальные, определяет только собственная схема присоединённой сущности Feature.injectприменяется к записи Workload, доставляющей материал слота: вложение соединения не несёт собственного блокаinject:— ни один из документов не допускает его в записи соединения, — поэтому Workload доставляет его, называя соединение рядом со слотом, и эта запись проверяется по списку разрешённых механизмов слота сокета точно так же, как запись, называющая слот уровня Component, проверяется по списку этого слота.
usesSchema сущности Feature не принимает featuresSchema: соединение, которое создаёт Feature, не несёт вложений, а Feature, объявляющая слоты на сокете, отклоняется при загрузке. Учётные данные, нужные такому соединению, — это слот в собственном featuresSchema сущности Feature.
Генерация схемы из usesSchema. Компилятор генерирует базовый фрагмент JSON Schema 2020-12 из объявленных сокетов и объединяет его с пользовательским объявлением schema: — по тому же принципу, что и featuresSchema. Сгенерированная схема никогда не записывается на диск; она существует только в памяти во время прохода валидации Component. Карта uses: разработчика в Aggregate проверяется по объединённой схеме; selector: каждого сокета вычисляется по меткам кандидатов Component во время статического анализа как межузловая проверка типобезопасности.
Семантика селектора — механизм Split Schema. usesSchema[].selector: — то, что делает топологию Aggrega чем-то большим, чем нетипизированная передача строк. Сокет, объявляющий selector: "datastore.aggrega.ai/engine=vector", принимает подключение только к Components с соответствующей парой ключ-значение в метках; агент, пытающийся подключить свой сокет primary_datastore к Component relational, не проходит Static Analyzer с понятной диагностикой нарушения селектора. Селектор — строка селектора меток в стиле Kubernetes: требования, соединённые запятой как И, в формах =, !=, in (...), notin (...), голый ключ и !key — та же грамматика, что использует Feature appliesTo; грамматику см. в vocabulary/modifier-system.md, а семантику движка — в architecture/13-catalog-and-registry.md §2 «Kubernetes-Style Selectors». Требование вне этих форм отклоняется, а не читается как какой-то другой селектор: пустое требование (запятая в начале, в конце или двойная), ключ, содержащий пробел или любой из символов =, !, (, ) и запятую, либо набор без закрывающей скобки останавливает каждую сборку, подключающую ребро через этот сокет, с указанием требования. Поэтому сокет, предназначенный для исключения фронтендов, записывается как selector: "tier!=frontend"; "!tier=frontend" отклоняется, потому что ! обозначает ключ метки и ничего больше.
Ad-hoc сокеты — что даёт объявление сокета и что автор может сделать без него. Автор Aggregate может записать на своём компоненте запись uses: под именем сокета, который этот usesSchema не объявляет, в том числе на Component, не объявляющем usesSchema вовсе. Ребро строится. Молчание каталога о сокете означает, что соединение не было предусмотрено, а не что оно запрещено, и топология приложения принадлежит разработчику.
Такой ad-hoc сокет теряет ровно то, что даёт объявленный, потому что всё это находится в записи usesSchema: нет selector, поэтому ничто не ограничивает, к какому компоненту может вести ребро, и межузловой проверке типобезопасности нечего вычислять; нет списка разрешённых механизмов inject:; нет valueSchema для ребра, поэтому у values: ребра нет контракта для проверки и нет объявленных значений по умолчанию для наследования. Теряется и infraSchema, хотя на таком сокете до этого контракта в любом случае ничего не доходит: infra ребра записывается в записи ребра Release, а запись Release может называть только сокет, который объявляет потребляющий Component. Неизменным остаётся то, что ребро может нести: from: каждой записи inject по-прежнему должен называть ключ, объявленный в schema.provides целевого Component, и цель по-прежнему должна существовать — оба нарушения останавливают сборку так же, как на объявленном сокете.
Понимайте «отсутствие allowlist для inject:» как отсутствие ограничения, а не как объявление blackbox, потому что они выглядят одинаково, а ведут себя противоположно. Ребро через ad-hoc сокет может свободно диктовать способ доставки: нет allowlist, за пределами которого мог бы оказаться механизм, и ни одна сущность не обещала обрабатывать значения внутри себя. Отказ для blackbox, описанный выше, применяется к сокету, который сущность объявила и оставила без allowlist для inject:, — это упущение является утверждением о соединении, которое сущность предусмотрела, а ad-hoc сокет такого утверждения не делает.
Доставка идёт тем же путём, и отрисованный артефакт не фиксирует никакой разницы. Блок inject ad-hoc ребра разрешается и доставляется точно так же, как у объявленного сокета: каждый ключ from: считывается из вычисленного provides цели и попадает в контекст внедрения потребляющего узла под ключом доставки, выбранным автором, а оттуда — в отрисованный артефакт. Путь доставки один, и ничто на нём не ветвится в зависимости от того, был ли сокет объявлен. Объявленный сокет может добавить содержимое — значения по умолчанию для ребра, которые заполняет его valueSchema или infraSchema, — поэтому там, где объявленный сокет не несёт такого контракта, одно и то же ребро отрисовывается одинаково при любом виде сокета. Объявление — это факт о соединении, а не входные данные для отрисовки.
values: ребра на ad-hoc сокете принимается и доходит до потребляющего Recipe по пути .context.uses.<alias>.values без валидации: без valueSchema, по которому можно его проверить, ни один ключ не проверяется и ни один не отклоняется. Это не особенность только ad-hoc сокетов — объявленный сокет, не задающий контракта для столпа, обращается с конфигурацией своего ребра так же. Ad-hoc сокет меняет лишь то, что контракт нельзя добавить без объявления сокета. .context.uses.<alias>.infra на таком ребре пуст, потому что поверхность, предоставляющая infra ребра, не может назвать необъявленный сокет.
Каждое ребро в выдаваемом графе фиксирует, к какому из двух видов оно относится, поэтому потребителю никогда не приходится это выводить, а организация, которая хочет, чтобы каждое соединение проходило через объявленный сокет, может потребовать этого в виде политики управления. Объявить сокет здесь по-прежнему лучше, и именно так поступает каталог стандартной библиотеки: объявленный сокет несёт selector, ограничивающий, к каким компонентам может вести ребро, allowlist inject:, контракт для каждого ребра с собственными значениями по умолчанию и описание — проверяемое на ревью утверждение о предусмотренном соединении, версионируемое вместе с сущностью, которая его делает. Ad-hoc форма — это запасной выход, а не новое поведение по умолчанию. Две поверхности намеренно так не открыты: uses вложения Feature может называть только сокет, который объявляет вложенная сущность Feature, а uses для каждого ребра в сущности Release может называть только сокет, который объявляет потребляющая сущность Component.
Рабочий пример examples/adhoc-uses-socket/ строит оба вида рёбер на одном потребителе и показывает два доставленных значения рядом в отрисованном выводе, а также остановку, которую вызывает необъявленный ключ from:.
Опечатки в именах сокетов выдаются как предупреждение, а не как остановка. Поскольку необъявленное имя сокета допустимо, имя сокета с опечаткой становится отдельным ad-hoc соединением, а не подключает сокет, который имел в виду автор, — и сборка остаётся успешной, хотя по нему ничего не передаётся. Компилятор сообщает об имени сокета, отличающемся на одну правку от имени, которое объявляет этот usesSchema, предупреждением с обоими написаниями — см. errors/warnings.md, «Uses-socket near-miss lint». Предупреждение никогда не меняет вердикт сборки; компилятор не контролирует, как автор называет сокет.
Соотношение usesSchema и featuresSchema. Обе являются декларативными таблицами, и обе несут allowlist inject: с одинаковой семантикой, но сокет и слот — разные вещи, и они не взаимозаменяемы. usesSchema управляет рёбрами между компонентами — графом топологии, — объявляя, какие сокеты несут контракт. featuresSchema управляет слотами вложений, а слот — это именованная точка привязки, а не перечисление: вложение под именем, которое не объявляет ни один слот, допустимо в собственном блоке компонента. (Слоты, которые сокет объявляет для своих соединений, — единственный закрытый набор, как сказано выше в разделе «Slots each connection fills».) В этом вопросе две поверхности сошлись — собственная запись uses: компонента под необъявленным именем сокета тоже допустима, — но они остаются различными: необъявленный слот — это свободное вложение в сущности Component, объявленные слоты которой не затрагиваются, а необъявленный сокет — это ребро без селектора и без контракта для ребра. Многие Components объявляют и то и другое; две таблицы компонуются независимо.
Слоты подключения: featuresSchema
Component может объявлять слоты подключения через блок featuresSchema. Каждый слот задаёт точку привязки, в которой Component ожидает подключения Feature, — корневой пароль, ключ API, токен аутентификации, привязку идентичности — и ограничивает, какая сущность Feature может его занять и как может доставляться материал заполнения.
Этот раздел посвящён собственным слотам сущности Component. Слоты, которые сокет объявляет для каждого соединения, напротив, образуют закрытый набор — см. «Slots each connection fills» в разделе Topology Sockets.
Объявление слота не закрывает поверхность подключений. Автор может подключить Feature под именем, которое не объявляет ни один слот, и такое подключение является свободным подключением: вполне допустимым, просто не привязанным к объявленному слоту. Именно эта открытость позволяет одной сущности каталога обслуживать две разные формы развёртывания без форка каталога:
- Для каждого потребителя. Каждый экземпляр заполняет слот собственной сущностью Feature, поэтому каждый потребитель получает собственные отрисованные учётные данные.
- Общая. Ни один экземпляр не заполняет слот; вместо этого одни учётные данные подключаются один раз на более широкой области (подсистема или граница сущности Release) и каскадно распространяются на каждый компонент в ней, так что каждый потребитель заполняется из этого единственного объявления. Что при этом отрисовывается, зависит от реализации: по одному Secret на потребителя, каждый с одним и тем же материалом, — при реализации, которая отрисовывает Secret; ничего — при реализации, которая направляет каждого потребителя на уже существующий Secret.
Автор выбирает между ними тем, что он подключает. Сущность каталога в обоих случаях одна и та же.
Одна форма на этой открытой поверхности приводит к остановке: заполнение, записанное на компоненте под другим именем. Если подключение, записанное на самом компоненте — в его собственном блоке features: в Aggregate или в записи сущности Release для этого компонента, — имеет имя, которое не объявляет ни один слот, и его Feature удовлетворяет selector слота, который на этом компоненте ничем не привязан после свёртки всех областей, сборка останавливается. Именно такую форму принимает заполнение, предназначенное для слота, если оно записано под неверным именем: без вмешательства оно стало бы свободным подключением, а слот остался бы пустым, и необязательный пустой слот собирается успешно и ничего не доставляет. Сообщение называет подключение, компонент, Feature и каждый пустой слот, которому эта Feature подходит; способ исправления — подключить её под именем слота. Это относится к любой Feature, а не только к учётным данным. Всё остальное на поверхности остаётся свободным: подключение, чья Feature не подходит ни одному объявленному слоту, дополнительное подключение после того, как каждый подходящий ему слот привязан, и подключение, которое компонент наследует от подсистемы или границы сущности Release, — поэтому описанная выше общая форма не затрагивается. Слот, не объявляющий selector, ничего не говорит о том, для какой Feature он предназначен, поэтому никакое подключение таким образом с ним не сопоставляется. Остановка описана в errors/fatal-halts.md в разделе «An attachment written under another name fits a slot its component leaves empty (Подключение, записанное под другим именем, подходит слоту, который его компонент оставляет пустым)».
Две формы сочетаются, и побеждает более близкая. Автор может сделать и то и другое одновременно: подключить Feature на более широкой области, чтобы она достигла каждого компонента в этой области, и заполнить слот на том единственном компоненте, которому нужно что-то другое. Побеждает заполнение на уровне компонента — поле за полем, поэтому в нём достаточно повторить только изменяемые поля, а остальные по-прежнему берутся из более широкого подключения. Соседние компоненты, не заполнявшие слот, сохраняют более широкое подключение без изменений. Полное правило приоритета, включая его взаимодействие с подключениями на основе аннотаций и с составными Aggregates, приведено в vocabulary/labels-and-annotations.md, раздел «Attachment precedence».
Определение схемы в сущности 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.Семантика полей:
| Поле | Тип | По умолчанию | Значение |
|---|---|---|---|
required | bool | false | Объявляет, что слот в итоге должен быть привязан. Сборка останавливается, если ничто не привязывает имя слота на экземпляре этой сущности Component; проверка выполняется по набору подключений, который экземпляр имеет после всего каскада подключений, — поэтому подключение, объявленное на области, от которой наследует экземпляр, удовлетворяет слоту точно так же, как заполнение, записанное на самом экземпляре. Диагностика называет компонент и слот. |
inject | string[] | — | Список разрешённых механизмов доставки inject. [] (пустой) означает «чёрный ящик» — Recipe управляет доставкой внутри, и материал никогда не доставляется в workload. [env, file] означает «прозрачный» — материал заполнения может доставляться через перечисленные механизмы. Та же семантика, что у usesSchema[].inject. |
description | string | — | Документация для людей, отображаемая в IDE и хабе. |
selector | string | — | Необязательный селектор меток в стиле Kubernetes, ограничивающий, какая Feature может заполнить этот слот, — аналог selector сокета usesSchema для слота, с той же грамматикой и тем же встроенным механизмом сопоставления меток. Вычисляется по собственным меткам подключённой Feature во время статического анализа; заполнение, метки которого ему не удовлетворяют, приводит к остановке, как и селектор, отвергнутый грамматикой, — с указанием требования, которое не удалось прочитать. Если опустить, заполнение не ограничивается. |
sensitive | bool | false | Объявляет, что всё, что привязывает этот слот, работает с секретным материалом. Это утверждение о точке привязки, а не о каком-либо конкретном заполнении; см. ниже «Объявление слота чувствительным». |
Слот ограничивает, какое заполнение может его привязать, а не то, что это заполнение настраивает. Контракта values или infra на уровне слота намеренно нет: этими опорами владеет собственная schema: подключённой Feature, поэтому у каждого контракта ровно одно место.
selector слота — это способ, которым Component сужает круг Feature, способных заполнить слот, — например, до Feature учётных данных конкретного провайдера (feature.aggrega.ai/kind=secret, provider=helm), — не называя FeatureRecipe, точно так же, как селектор сокета usesSchema сужает цель ребра зависимости. Компилятор вычисляет селектор по меткам подключённой Feature и ни по чему иному: он читает метки, которые несёт заполнение, и сообщает, допускает ли их селектор. Какие метки имеет смысл требовать — выбор автора каталога, а не правило, навязываемое компилятором.
Опечатки в именах слотов выдаются как рекомендация, а не как остановка. Поскольку необъявленное имя подключения допустимо, слот с опечаткой в имени становится свободным подключением, а не заполняет слот, который имел в виду автор. Компилятор сообщает об имени подключения, отстоящем на одну правку от объявленного имени слота, предупреждением с обоими вариантами написания — см. errors/warnings.md, «Attachment-slot near-miss lint». Предупреждение никогда не меняет результат сборки; компилятор не контролирует, как автор называет подключение. Имя, отстоящее на одну правку от слота, selector которого удовлетворяет Feature подключения, предупреждения не вызывает: если этот слот остаётся пустым, вместо этого о подключении сообщает описанная выше остановка, а если слот привязывает что-то другое, подключение является обычным дополнительным.
Объявление слота чувствительным
sensitive: true на слоте выражает собственное требование потребителя: всё, что привязывается к этой точке, обрабатывает секретный материал.
spec: featuresSchema: password: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env] description: "Optional database password credential."Это действительно иная информация, чем sensitive: true у листа схемы, а не удобный дубликат, и каталогу стандартной библиотеки нужны оба. Учётные данные, на которые можно сослаться, публикуют provides.name и provides.key — локатор ресурса и ключ данных внутри него, — и ни один из них не является чувствительным: имя Secret в Kubernetes публично, как и ключ внутри него. Тем не менее слот, который заполняют эти учётные данные, несомненно обрабатывает секретный материал. Лист говорит эти данные — секретный материал; слот говорит эта точка привязки обрабатывает секретный материал; эти два утверждения касаются разных вещей и могут выполняться независимо.
Практическое следствие в том, что требование следует за точкой привязки, а не за заполнением. Feature, которая вообще не объявляет чувствительных листов — потому что учётными данными владеет целевой движок и автор ничего не пишет, — всё равно привязывается к чувствительному слоту как чувствительное вложение, потому что так сказал слот. Верно и обратное: заполнение, объявляющее чувствительный лист, является чувствительным вложением, даже если оно привязывается к слоту, не делавшему такого объявления, или является свободным вложением, не привязанным ни к какому слоту.
Объявление следует каскаду вложений, а не какому-либо одному написанному блоку. Требование слота относится к тому заполнению, которое оказывается привязанным после свёртки всех областей, поэтому заполнение на уровне компонента, вытесняющее более широкое, наследует требование без изменений.
sensitive на слоте имеет тот же предел, что и ключевое слово уровня листа: оно аннотирует, но не шифрует, не проверяет, не отклоняет, не навязывает механизм доставки и не меняет ни одного отрисованного байта. Полное описание — в vocabulary/compact-form-authoring.md, раздел «What the keyword does not do».
sensitive и compliance.aggrega.ai/data-class — две разные оси, они документируются рядом и никогда не смешиваются. sensitive — булево значение на одном листе или одном слоте: эти данные или эта точка привязки обрабатывают секретный материал. compliance.aggrega.ai/data-class — градуированная метка на целом узле (public, internal, restricted), задающая данным, которые хранит компонент, идентичность в рамках управления. Одно относится к отдельным данным и бинарно, другое — к узлу и упорядочено; ни одно не заменяет другое, и сущность может нести оба. Метка описана в vocabulary/labels-and-annotations.md и architecture/08-credential-model.md, раздел «Data governance around credentials».
Проекция схемы из featuresSchema
Объявленные слоты проецируются во фрагмент JSON Schema 2020-12, описывающий форму блока вложений. По нему проверяются два вида заполнений: блок вложений компонента, который вносит импортированный модуль, — после построения импортирующей его композиции, — и вложение, объявленное в более широкой области, — относительно слота на каждом компоненте, которого оно достигает. Блок вложений компонента, который объявляет сама сущность Aggregate, вместо этого оценивается схемой документа Aggregate и списком разрешённых inject слота (см. ниже), а фрагмент устроен так, чтобы оба приходили к одному вердикту для любого заполнения. Проекция никогда не касается диска; она существует только в памяти, и в schema: сущности Component никогда не нужно вручную описывать столп вложений.
Входной featuresSchema:
featuresSchema: root_password: inject: [] user_password: inject: [env, file]Спроецированный фрагмент (в памяти; компактное представление):
# 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Два уровня независимы. Внешний объект открыт, поэтому объявленный слот никогда не запрещает вложения, которые сущность не перечислила. Собственный фрагмент каждого объявленного слота закрыт, поэтому заполнение, которое действительно привязывается к объявленному слоту, по-прежнему ограничено формой этого слота.
Фрагмент описывает только ФОРМУ. Он ничего не говорит о том, какие слоты должны быть привязаны, потому что слот, помеченный required, может быть привязан вложением, приходящим каскадом из более широкой области, — и тогда блок, который описывает этот фрагмент, остаётся пустым. Поэтому требование проверяется по набору вложений, который в итоге оказывается у компонента, а не по тому, что объявляет какой-либо один блок, и эти два вопроса никогда не противоречат друг другу, поскольку написанному блоку задаётся только один из них.
Допустимые ключи повторяют ключи, которые вложение может нести где угодно, поэтому ключ, допустимый на свободном вложении, остаётся допустимым и на заполнении слота. Каждый механизм доставки из разрешённого списка — это список записей доставки, той же формы, что inject: принимает везде; слот ограничивает, какие ИМЕНА механизмов могут появляться, а не то, как выглядит запись.
Где применяется разрешённый список inject
Разрешённый список связывает обе стороны слота, на двух разных этапах.
Для Workload сущности Recipe — на этапе отрисовки: Workload, ссылающаяся на слот через записи вложений своего контейнера, должна называть слот, который объявляет сущность, и выбирать механизм доставки, разрешённый списком inject этого слота; ссылка на слот blackbox (inject: []), на механизм вне разрешённого списка или на слот, который сущность никогда не объявляла, останавливает сборку. Диагностика называет Recipe, путь контейнера и проблемный слот и классифицируется как ошибка каталога — ошибся именно Recipe.
Для собственного вложения сущности Aggregate — при разрешении её вложений и до любой отрисовки: блок inject: на заполнении, привязанном к объявленному слоту, может называть только механизмы, разрешённые списком слота, а слот blackbox не разрешает ни одного — его пустой список говорит «Recipe доставляет это внутренне; не диктуйте доставку», и описание доставки для него останавливает сборку. Диагностика привязана к вложению и называет слот и проблемный механизм, а также механизмы, которые слот разрешает, если он разрешает хоть какие-то; она классифицируется как ошибка разработчика, потому что ошибся именно Aggregate. Пустой блок inject: {} не называет ни одного механизма, поэтому не диктует доставку и принимается в любом слоте, включая слот blackbox, — одинаково на компоненте, который объявляет Aggregate, на компоненте, который вносит импортированный модуль, и на вложении, объявленном в более широкой области. Свободное вложение — под именем, которое не объявляет ни один слот, — такого ограничения не несёт, потому что разрешённый список принадлежит слоту, а не блоку.
Сквозной путь через конвейер компиляции — как вложение Aggregate связывается с Feature учётных данных (например, core/secret-value), а затем с FeatureRecipe конкретного провайдера, которая доставляет учётные данные работающей рабочей нагрузке, — разобран в examples/05-credential-features.
Ключ, который предъявляет вызывающая сторона, и ключ, который проверяет сервер
Когда один компонент вызывает другой, проверяющий ключ, каждая сторона хранит ключ у себя, в слоте, который она объявляет сама. Это соглашение, которому следует каталог стандартной библиотеки; компилятор ничего из этого не навязывает — он проверяет слоты каждого компонента по собственным вложениям этого компонента, передаёт их строки дальше и никогда не сравнивает то, что хранит один компонент, с тем, что хранит другой.
- Ключ, который предъявляет вызывающая сторона, принадлежит ей. Он находится в слоте, который сокет вызывающей стороны объявляет для каждого соединения, — см. выше «Slots each connection fills», — поэтому вызывающая сторона, обращающаяся к нескольким целям, хранит по ключу для каждой. Сокет
modelкомпонентаcore/ai-agent/crewaiобъявляет этот слот какcredential, а его Recipes доставляют то, что его заполняет, какOPENAI_API_KEY. Сокетыmodelsкомпонентовcore/gateway/litellm,core/gateway/kongиcore/gateway/apisixтоже его объявляют, и их Recipes доставляют ключ каждого соединения в отдельной переменной, названной по псевдониму соединения, так что у каждой модели, которую обслуживает шлюз, свой ключ. Ключ, который Component вместо этого объявляет в собственном слоте, — это один ключ для всех его соединений. - Ключ, который проверяет сервер, — это собственный слот сервера.
core/ai-model/vllm,core/ai-model/teiиcore/ai-model/tgiкаждый объявляют необязательныйapi_key, и каждый из их Recipes доставляет то, что его заполняет, как переменную, из которой сервер читает свой ключ. Модель и шлюз LiteLLM объявляютapi_keyдля ключа, который LiteLLM называет мастер-ключом. - Ни одна сторона не видит вложений другой. Вложение на соединении — одно из вложений вызывающей стороны и попадает только в её рендеринг, а отрендеренный вывод сервера одинаков, что бы ни несли приходящие к нему соединения. Слот, помеченный
required, должен заполнить компонент, который его объявляет, а не подключённые к нему компоненты, и заполнение слота одной стороны ничего не заполняет на другой — поэтому объявление ключа на обеих сторонах является минимумом, а не дублированием. - Обе стороны читают один параметр, поэтому ключ, который предъявляет вызывающая сторона, и ключ, который проверяет сервер, не могут разойтись.
# Aggregate fragment — one parameter feeds both endsspec: 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Сервер, проверяющий один ключ, не может различить вызывающие стороны: vLLM, TEI и TGI проверяют каждый по одному ключу, поэтому все вызывающие стороны предъявляют один и тот же ключ, сколько бы соединений ни приходило к серверу. Ссылаются ли обе стороны на один секрет или каждая хранит свой, зависит от того, где каждый провайдер разрешает секрет по ссылке, а Manifest выбирает реализацию для каждой стороны — оба случая разобраны в Credential Model.
Учётные данные, которые компонент хранит для себя, — например, ключ, которым он подписывает собственные сессии, — это слот его собственного featuresSchema:, как и любой другой. Пароль, который он предъявляет хранилищу данных, доступному через один из его сокетов, — это описанный выше ключ вызывающей стороны, поэтому он находится на этом соединении как credential: его объявляет сокет backend компонента core/gateway/kong, и его Recipes синтеза рабочей нагрузки доставляют его как KONG_PG_PASSWORD, а сокет cache_store компонента core/gateway/litellm объявляет его для пароля, который семантический кеш предъявляет хранилищу, с доставкой как REDIS_PASSWORD. Когда одно соединение предъявляет пару — идентификатор ключа доступа и его секрет, — секретная половина является credential, а идентификатор — credential_id, как на сокете store компонента core/ai-agent/agenta-api.
Самовнедрение: spec.inject
Сущность Component может объявить массив верхнего уровня spec.inject:, который задаёт разрешённый список механизмов доставки при самовнедрении. Если он присутствует, разработчики могут использовать блок inject: на уровне компонента в сущности Aggregate, чтобы внедрять собственные ключи values: или provides: сущности Component непосредственно в её собственный канал доставки (переменные окружения её контейнера, монтируемые файлы или аргументы процесса). Если spec.inject: отсутствует или пуст, самовнедрение на уровне компонента запрещено — сущность Recipe управляет всеми внутренними связями, что соответствует шаблону «чёрного ящика», который usesSchema[].inject: [] и featuresSchema[].inject: [] применяют соответственно к межкомпонентной доставке и доставке учётных данных.
# Component declares its self-inject allowlist:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/web-server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: 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Каждый шаблон value: начинается с {{"{{"}}, а не с {{. Весь текст сущности Aggregate один раз читается как шаблон для интерполяции параметров, прежде чем выполняется разрешение самовнедрения, и в этот момент .values ещё не существует; экранирование возвращает {{ на место, чтобы его вычислило разрешение самовнедрения. См. Текст с собственными двойными фигурными скобками.
Семантика поля. spec.inject: — это массив имён механизмов. Определены три значения:
env— переменные окружения в контейнере.file— пути монтируемых файлов.arg— аргументы командной строки процесса.
Семантика в точности повторяет usesSchema[].inject и featuresSchema[].inject — тот же словарь, тот же шаблон «чёрного ящика» при отсутствии поля, та же форма записи на стороне Aggregate. Различается источник: usesSchema[].inject определяет, как provides межкомпонентной зависимости поступает в канал доставки потребителя; featuresSchema[].inject определяет, как учётные данные попадают в контейнер; spec.inject определяет, как собственные values и provides сущности Component попадают в её собственный контейнер.
Дисциплина написания. Сущность Component core/web-server, объявляющая spec.inject: [env, file], выбирает прозрачную доставку — автор сущности Aggregate определяет, какие имена переменных окружения несут какие значения. Сущность Component, объявляющая spec.inject: [] (или опускающая это поле), сохраняет доставку непрозрачной — valuesMapping: сущности Recipe решает, какие поля попадают в какие переменные контейнера, и разработчик не может переопределить это в Aggregate. Шаблон «чёрного ящика» подходит для сущностей Components со стабильным контрактом (сущность Component core/postgres-db, чья Recipe знает, как передать пароль БД в переменную окружения POSTGRES_PASSWORD); прозрачный шаблон подходит для сущностей Components, где намерение разработчика обоснованно затрагивает детали доставки (core/web-server, приложение которого читает LOG_LEVEL из нестандартного имени переменной, которое разработчик хочет настроить).
Режимы ошибок. Если Aggregate разработчика использует блок inject: для сущности Component, у которой spec.inject: отсутствует или пуст, сборка останавливается при загрузке рабочего пространства («Self-inject on a component without an allowlist (Самовнедрение в компоненте без списка разрешённых механизмов)»). Блок inject:, использующий механизм, которого нет в разрешённом списке, останавливает сборку по тому же условию с указанием механизма и тех, которые разрешает список («Self-inject mechanism not in the component’s allowlist (Механизм самовнедрения отсутствует в списке разрешённых для компонента)»). Конфликт ключей доставки между самовнедрением, межкомпонентным внедрением и внедрением учётных данных тоже останавливает сборку («Duplicate delivery key across inject sources (Дублирующийся ключ доставки в разных источниках внедрения)»). Формы сообщений для каждой ошибки см. в errors/fatal-halts.md.
Создание каталога: расширение базовых Components
Архитекторы платформы используют ключевое слово extends, чтобы надстраивать специализированные интерфейсы поверх корпоративных или общественных базовых определений. Расширение компонует структуру и наследует столпы данных целиком. Компилятор проходит цепочку от базы вниз; две половины ведут себя по-разному, и в этом различии заключается вся модель создания.
Что расширение компонует. Эти поверхности объединяются вдоль цепочки: по каждому ключу побеждает расширяющий Component, а списки конкатенируются начиная с базы, без дубликатов:
| Точка вывода | Как компонуется |
|---|---|
metadata.labels | объединяется по ключам; при общем ключе побеждает значение расширяющего Component |
metadata.annotations | объединяется по ключам с тем же приоритетом — именно поэтому требование присутствия из базы распространяется на каждый расширяющий её Component |
spec.featuresSchema | объединение слотов подключения; слот, который расширяющий Component объявляет заново, заменяет запись базы с тем же именем |
spec.usesSchema | объединение сокетов топологии, то же правило замены по имени |
spec.inject | два списка разрешённых механизмов самовнедрения конкатенируются, сначала записи базы, дубликаты отбрасываются |
spec.assertions | именованные правила накапливаются, сначала правила базы — и только эта поверхность не допускает замены по имени; см. «Наследование утверждений аддитивно» ниже |
Сокет, добавленный расширяющим Component, может нести собственные valueSchema и infraSchema для каждого ребра; это контракты на рёбрах этого сокета, а не дополнения к собственным столпам Component.
Остальная часть metadata: остаётся у документа, который её объявляет. labels и annotations — единственные метаданные, передающиеся вниз по цепочке. name, version, description, maintainers, license, repository, home и keywords принадлежат самому расширяющему Component и читаются точно так, как он их записал: Component, опускающий description:, не имеет описания, а не заимствует описание базы. Идентичность и происхождение принадлежат документу, который вы читаете, поэтому обёртку никогда не спутать с тем, что она оборачивает.
Что расширение наследует целиком. Три столпа данных — values, infra, provides — не компонуются. Расширяющий Component не записывает содержимое столпов: он пишет литеральный маркер schema: inherited и получает блок schema: своей базы точно в том виде, в каком его записала база. В цепочке любой глубины каждый Component несёт блок корня цепочки без изменений, поэтому aggrega inspect --resolved для листа показывает те же столпы, что и для корня.
Опубликованная схема Component определяет, какой из трёх возможных исходов допустим, и отклоняет два других при загрузке документа — с отдельной диагностикой для каждого, поскольку это разные ошибки:
extends:с содержимым столпов вschema:отклоняется. Контракт Component — это контракт его базы; второму, расходящемуся контракту негде существовать.extends:при полностью опущенномschema:отклоняется. При пропуске читатель не смог бы отличить унаследованный блок столпов от забытого.schema: inheritedбезextends:отклоняется. Маркер указывает, откуда берутся столпы, а у этого Component нет базы, из которой их взять.
Расширяющий Component не может изменить набор ключей. Он не объявляет ключей столпов, поэтому не может скрыть, удалить или сменить тип ключа, объявленного базой, и не добавляет собственных. Новый ключ столпа принадлежит тому Component, чьему контракту он принадлежит. Всё, что предоставляет база, все расширяющие её предоставляют идентично.
Специализация ужесточает ограничения через assertions:. Когда специализация должна допускать меньше, чем столпы её базы, — более узкий числовой диапазон, подмножество унаследованного enum:, — она указывает это в собственном блоке assertions:: правило в нём отклоняет значение, которое унаследованная схема принимает. Именно на этой поверхности выполняется ужесточение; см. «Блок assertions:» ниже.
Два последних абзаца — одно правило, и любая его половина по отдельности вводит в заблуждение: сужение набора ключей невозможно, ужесточение ограничений возможно. Если взять только первую, можно заключить, что специализация ничего не может ограничить; если только вторую — что она может изменить форму контракта. Ни то, ни другое не верно: набор ключей фиксирован базой, а допустимые в нём значения можно сузить предикатом.
Наследование утверждений аддитивно, а накопление идёт от корня. Экземпляр расширяющего Component проверяется по всем правилам, объявленным в его цепочке, а также по правилам, которые объявляет сам Component, причём унаследованные вычисляются первыми. В цепочке любой глубины правила накапливаются от корня вниз, поэтому, если экземпляр нарушает несколько правил, сообщается то, которое объявлено выше всего в цепочке, — первым отвечает самый фундаментальный контракт.
Поскольку наследование добавляет, а не заменяет, расширяющий Component не может повторно использовать имя унаследованного правила для объявления другого правила: это отклоняется при разрешении цепочки extends относительно каталога с диагностикой, называющей оба Components и общее имя. Для проверки нужен базовый Component, поэтому она срабатывает при валидации каталога или когда сборка разрешает цепочку, — валидация расширяющего документа отдельно её не обнаружит. Имя правила — стабильный идентификатор, поэтому ни удаление правила базы, ни его тихое переименование невозможны; исправление — переименование в расширяющем Component. Побайтовое повторение унаследованного правила под его собственным именем принимается как пустая операция, которой оно и является.
aggrega pull получает базу. База — зависимость каждой сущности Release, которая достигает сущности Component, расширяющей эту базу, независимо от того, называет ли её что-либо ещё. aggrega pull проходит каждый extends: до конца цепочки, получает из реестра базу, которой нет ни в одной директории каталога, и записывает каждую базу в lock-файл сущности Release со ссылкой из spec.extends сущности Component, которая её называет; сборка читает базу оттуда. Поэтому сущность Manifest сопоставляет только собственный тип обёртки и ничего больше — базе нужна собственная строка сопоставления только там, где сущность Aggregate также объявляет экземпляр базы. Команда aggrega validate для всего каталога читает базу так же, поэтому база, опубликованная в реестре, отклоняется там с указанием aggrega pull, пока pull её не получит.
Форматы содержимого схем см. в architecture/13-catalog-and-registry.md §3.
Пример A: базовый Component (корпоративная база) Архитектор платформы определяет базовый корпоративный сервер. Эта база задаёт обязательную метку облачного операционного примитива и устанавливает ограничения безопасности в схеме. Поскольку блок столпов наследуется без изменений, каждое ограничение здесь доходит до каждого расширяющего Component точно в записанном виде.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: 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 -}}Пример B: расширяющий Component (специализация базы)
Шлюз специализируется на основе этой базы. Он берёт столпы базы целиком, добавляет собственную структуру — метку, механизм самовнедрения, сокет топологии со слотом подключения на нём — и ужесточает унаследованный тайм-аут через утверждение. Он не повторяет правило базы audit-window-is-observable: это правило наследуется и вычисляется первым, поэтому экземпляр этого шлюза должен удовлетворять обеим границам — не менее 100 и не более 2000.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: 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 labelsspec: 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 -}}Recipe, реализующий этот интерфейс core/gateway/kong на основе физического чарта Helm, см. в entities/recipe, пример C (kong-gateway).
Блок assertions:
Component.spec.assertions: — необязательная карта именованных правил, выражающих архитектурные инварианты контракта Component: межполевые правила, которым должно удовлетворять описание разработчика независимо от того, какой Recipe привязывается к Component. Каждый ключ — идентификатор правила, который появляется в сообщении об ошибке; каждое значение — тело шаблона Go. Компилятор вычисляет их для каждого экземпляра после проверки по схеме и до привязки Recipe, в порядке их записи, и первое нарушенное правило останавливает сборку с собственным сообщением об ошибке этого правила согласно контракту 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 -}}Приведённое выше правило — свойство контракта Component: какой бы Recipe ни привязывался (чарт Bitnami, самописная альтернатива, будущая реализация), режим репликации требует как минимум двух вторичных реплик.
assertions: — место, где расширяющий Component ужесточает ограничения. Component, который extends: базовый, наследует блок разделов базового дословно и не объявляет собственного содержимого разделов, поэтому специализация, которая должна допускать меньше, чем унаследованная схема, формулирует ограничение здесь в виде предиката, а не суженного листа схемы, — как правило, отклоняющее значение, которое допускают унаследованные разделы. Разобранная пара примеров и полное описание наследования приведены выше в разделе «Создание каталога: расширение базовых Components»: правила накапливаются вдоль цепочки начиная с корня, а повторное использование унаследованного имени правила для другого правила отклоняется, а не заменяет его.
Компилятор не проверяет, могут ли два правила выполняться одновременно. Правило — это шаблонный предикат, а не ограничение, о котором рассуждает компилятор, поэтому пара правил, которым никакое значение не может удовлетворить одновременно (базовый требует не менее 100, а специализация — не более 50), не вызывает предупреждения при загрузке каталога. Это проявляется обычным образом: создаётся экземпляр, сборка останавливается на том из двух правил, которое сработает первым, и автор читает сообщение этого правила. Не рассчитывайте, что противоречие будет сообщено заранее; сверяйте ужесточение в специализации с тем, что уже требует её базовый Component.
Используйте assertions: для настоящих межполевых правил. Ограничения отдельных полей (диапазон, шаблон, enum) относятся к ключевым словам schema:; пользовательские предикаты для отдельных полей — к validate: компактной формы; условная форма (применяются ли ограничения поддерева) — к when:. Полную грамматику написания — поля контекста шаблона, соглашение о сообщениях {{ fail }}, фазу вычисления и разобранные примеры для ролей Component и Recipe — см. в templates/assertions-block.md.