Manifest
Концептуальная роль сущности Manifest (домен 4 — таблица сопоставлений, привязывающая абстрактные интерфейсы к конкретным сущностям Recipes) описана в architecture/04-entity-taxonomy.md. На этой странице рассматривается то, как создаётся Manifest: как он соотносится с сущностью Release, форма плоского сопоставления URI, композиция через extends, правила сокращённой записи URI, привязки Feature на основе аннотаций и зарезервированный платформой префикс aggrega.ai/.
Manifest и Release: разделение ответственности
Сущности Manifest и Release несут непересекающиеся обязанности:
- Сущность Manifest определяет, какой Recipe реализует каждый тип каталога, а через
spec.capabilityэтого Recipe — провайдер (например, Helm, Helm-chart, Compose), который его рендерит. Это таблица сопоставлений — фиксируемая в Git запись для каждого проекта о том, какой конкретный Recipe реализует каждый абстрактный интерфейс; версии и дайджесты, которым сборка требует соответствия от этих Recipes, закрепляются отдельно, в lockfile каждой сущности Release. - Сущность Release определяет место назначения (например, физическую выходную папку для генерации артефактов GitOps). Это маршрутизатор развёртывания — описание для каждого окружения того, куда попадают скомпилированные артефакты.
Схема сущности Release не содержит поля provider ни на одном уровне вложенности; диспетчеризация провайдеров принадлежит исключительно сущности Manifest.
Путь компиляции. Когда пользователь запускает aggrega build --release release.yaml, компилятор определяет физические артефакты, объединяя оба источника:
- Чтение места назначения. Компилятор просматривает границы сущности Release — например, граница
ovh-cluster-3содержит компонентuser-db(тип:core/postgres:1.0.0). - Просмотр Manifest. Компилятор открывает Manifest, на который указывает Release через своё поле
manifest:. - Двухуровневый поиск. Сначала проверяется уровень
nameна наличие"user-db". Если запись не найдена, проверяется уровеньtypeна наличие"core/postgres:1.0.0"(с версией), затем"core/postgres"(без версии). - Разрешение Recipe. Значение найденной записи — это URI сущности Recipe; названный им Recipe объявляет в
spec.capability, какой провайдер его отрисовывает. - Генерация вывода. Теперь компилятору известны целевая папка (
dist/boundaries/ovh-cluster-3/), провайдер (отрисовка Helm через Wasm) и артефакт (исходный код сущности Recipe). Границы GitOps, заданные заранее (ahead-of-time), соблюдаются от начала до конца.
Плоское сопоставление URI
Блок mappings: сущности Manifest — это плоское отображение из URI типа компонента в URI Recipe (и из URI типа функции в URI FeatureRecipe). На уровне Manifest сопоставление не зависит от возможностей: возможность определяется полем spec.capability каждого разрешённого Recipe во время рендеринга, а не структурой Manifest. Блок организует сопоставления под двумя ключами верхнего уровня:
components.typeсопоставляет URI типа компонента с URI Recipe. Каждый экземпляр компонента объявленного типа разрешается в указанный Recipe. Сопоставление взаимно однозначно для каждого типа компонента. Ключ, который не называет точный тип экземпляра, всё равно достигает его по базе типа, если ни один ключ не называет этот точный тип и для той же базы не написан другой ключ, — поэтому ключ, написанный без версии (core/postgres), или ключ, называющий другую версию (core/postgres:1.0.0), может достичь экземпляраcore/postgres:2.0.0, — но названный им Recipe должен реализовывать собственную версию каждого такого экземпляра: экземплярcore/postgres:2.0.0, достигнутый таким образом и сопоставленный с Recipe, объявляющимimplements: core/postgres:1.0.0, останавливает сборку. Сопоставьте такой экземпляр ключом, называющим его версию (core/postgres:2.0.0), с Recipe, который её реализует.features.typeсопоставляет URI типа функции с URI FeatureRecipe. Каждое присоединение Feature объявленного типа разрешается в указанный FeatureRecipe. Учётные Features (с меткойfeature.aggrega.ai/kind: secret) находятся в той же картеfeatures.type, что и операционные Features, — это единая модель сущности Feature.
Каждый блок наряду с type принимает также уровень name, сопоставляющий конкретное имя экземпляра с URI Recipe (или FeatureRecipe). Уровень имени имеет приоритет над уровнем типа: экземпляр, названный в components.name, разрешается в этот Recipe, а все остальные экземпляры того же типа разрешаются через components.type. Так выражается переопределение для отдельного экземпляра: два экземпляра одного типа компонента могут развёртываться через два разных Recipes (например, большинство экземпляров базы данных используют массово сопоставленный Recipe, а один экземпляр закреплён за другой физической реализацией), без ответвления типа компонента и без дублирования Manifest. Переопределение применяется единообразно: названный экземпляр и рендерится через переопределяющий Recipe, и закрепляет из него свой исходный код. features.name — симметричный уровень для присоединений Feature, ключом которого служит собственное имя присоединения — ключ, под которым оно записано в features: компонента, — и никогда не имя компонента, к которому оно присоединено. Пример переопределения recipe для экземпляра разбирает минимальный случай с двумя экземплярами от начала до конца.
Ключом присоединения, которое несёт соединение, служит имя, которое оно получает в потребляющем компоненте: <alias>.<slot> — псевдоним, под которым записано соединение, точка и слот, заполняемый присоединением (см. запись соединения в сущности Aggregate). Поэтому учётные данные одного соединения можно реализовать иначе, чем все прочие присоединения того же типа:
spec: mappings: features: type: core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0 name: # The credential the "gpt" connection carries in its "credential" slot. gpt.credential: helm/k8s-external-secret:1.0.0Запись закрепляется и проверяется, как любая другая запись уровня имени, что описано в следующем абзаце. Сущность Feature, которую называет присоединение, тоже закрепляется и проверяется — точно так же, как Feature присоединения, записанного на самом компоненте, — под записью соединения, которую написал её автор; см. Файл блокировки.
Ключ name должен называть то, что есть в сборке. Уровень сопоставляется по точному имени, поэтому ключ components.name, который не является экземпляром компонента в сборке, или ключ features.name, который не является присоединением в ней, — чаще всего это имя компонента, на котором находится присоединение, написанное там, где должно быть собственное имя присоединения, — ни к чему бы не применялся, а экземпляры, для которых он предназначался, молча разрешались бы через уровень type. Вместо этого сборка останавливается на таком ключе ещё до какого-либо рендеринга, называя Manifest, ключ, имена этого вида, которые в сборке есть, и имя, которое вы, вероятно, имели в виду, — см. A Manifest name mapping names nothing in the build (сопоставление Manifest не называет ничего в сборке).
Реализация, привязанная по имени, закрепляется и проверяется так же, как привязанная по типу. aggrega pull получает каждый Recipe и FeatureRecipe, привязанный любым из уровней, — из каталога, кэша или реестра — и записывает каждый в файл блокировки сущности Release с разрешённой версией и дайджестом содержимого под записью сопоставления, которая его привязывает: manifest.spec.mappings.components.name.<instance> для записи уровня имени, рядом с manifest.spec.mappings.components.type.<type> для записи уровня типа. aggrega build проверяет каждую из них на соответствие закреплению. Файл блокировки, в котором нет строки для реализации, привязанной в Manifest, останавливает сборку как устаревший, называя реализацию и привязывающую её запись; реализация, содержимое которой изменилось после pull, останавливает сборку так же, называя оба дайджеста. В обоих случаях aggrega pull --release <release> записывает реализацию в её текущем состоянии. Как и запись type, запись name закрепляется независимо от того, объявляет ли Release экземпляр с таким именем, поэтому запись name, называющая Recipe, которого нет ни в одном каталоге или реестре, останавливает pull; запись name, не называющая ни одного экземпляра в сборке, тоже закрепляется и останавливает сборку, как описано в предыдущем абзаце.
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: production-manifest version: 1.0.0spec: mappings: components: type: # Component-type → Recipe URI. A Recipe URI is at most two segments: an # optional leading capability, then the recipe name. The bare one-segment # form (last line) is the common case. core/datastore/postgres: helm/postgres:1.2.0 core/api-server: helm/api-helm:0.5.0 core/python-worker: standard-python-worker:2.0.0
features: type: # Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones. core/data-masking: helm/data-masking-litellm:1.0.0 core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0Определение возможности во время рендеринга. Запись Manifest привязывает тип компонента к URI Recipe. URI Recipe содержит не более двух сегментов — необязательную начальную возможность, затем имя recipe — плюс необязательный :version; резолвер разделяет только по первому /, поэтому ссылка с третьим сегментом не называет никакой recipe и останавливает разрешение. Во время рендеринга резолвер загружает Recipe прямым поиском URI по файлу блокировки и каталогу, а поле spec.capability каждого Recipe определяет группировку диспетчеризации по паре (путь, возможность). Структура Manifest остаётся плоской независимо от того, сколько провайдеров поддерживает каталог в целом.
Прямой поиск URI
Значение сопоставления в Manifest — это URI Recipe. Компилятор разрешает URI напрямую по файлу блокировки и каталогу и возвращает соответствующий Recipe. Он не перебирает объявления spec.implements в поисках Recipe, который «реализует» тип компонента. Каждая запись Manifest привязывает написанный разработчиком тип компонента к конкретному URI Recipe; выбор явен и однозначен в содержимом Manifest.
spec.implements — это проверка согласованности таблицы сопоставлений. Значение spec.implements разрешённого Recipe ДОЛЖНО совпадать с ключом типа компонента в Manifest для этой записи сопоставления — или с базой, которую этот ключ extends, на любой глубине цепочки, поскольку Recipe, написанный для базы, реализует всё, что её расширяет. Значение, не совпадающее ни с тем, ни с другим, порождает OPS_ERROR с понятной диагностикой, называющей запись Manifest, разрешённый Recipe и конфликтующее значение spec.implements. Проверка срабатывает один раз для каждой записи сопоставления Manifest, над составленным Manifest и до разрешения любого Recipe, — статически, детерминированно и не обходя ничего, кроме собственной цепочки extends сопоставленного типа. Ключ components.type, который достигает экземпляра компонента в версии, не названной в ключе, оценивается ещё раз для этого экземпляра тем же способом: на месте ключа при этом стоит собственный тип экземпляра в той версии, в которой сборка его компилирует, как описано в разделе Плоское сопоставление URI. См. ../vocabulary/inheritance-and-interface.md, чтобы узнать, от чего Recipe базы избавляет специализацию, а от чего нет.
Её выполняет каждая команда, читающая зависимости сущности Release, и каждая сама решает, что означает находка: aggrega build и aggrega pull останавливаются, поскольку обе производят то, что вы затем будете использовать, а aggrega validate и aggrega lint сообщают о ней вместе с остальными находками и завершаются с ненулевым кодом; редактор публикует её как одну из диагностик. Для оценки экземпляра исключением является aggrega lint: он оценивает записи сопоставления, а не экземпляры, которых они достигают, поэтому не сообщает о ней, тогда как aggrega build, aggrega pull и aggrega validate --release сообщают. См. ../errors/fatal-halts.md о диагностике и способе исправления.
Проверка согласованности — единственное место сопоставления, читающее цепочку extends. Выбор Recipe остаётся точным по ключу сопоставления: тип компонента, расширяющий сопоставленную базу, всё равно нуждается здесь в собственной записи и не получает её по наследованию.
spec.implements также предлагает кандидатов. Экземпляр, тип которого не имеет сопоставления в Manifest, останавливает сборку с OPS_ERROR, перечисляющей в качестве кандидатов на закрепление recipes, чей spec.implements способен реализовать этот тип; автодополнение в редакторе для значения сопоставления ставит те же подходящие recipes на первые места. Оба механизма сравнивают spec.implements с самим запрошенным типом, поэтому recipe, реализующий одну из баз этого типа, не предлагается кандидатом, хотя сопоставление было бы признано согласованным. Таким образом, spec.implements объявляет, что recipe может реализовать, и помогает человеку сделать выбор — в проверке согласованности, в диагностике отсутствующего сопоставления и в автодополнении, — но никогда не разрешает сборку. Сопоставление в Manifest — явный выбор развёртывания пользователем, закреплённый в файле блокировки для воспроизводимости; каталог никогда не выбирает развёртывание за пользователя.
Три формы сегмента версии в URI
URI сущности Recipe в сущности Manifest может содержать версию в одной из трёх форм:
- Точная —
helm/postgres:1.2.0. Lockfile должен закреплять именно эту версию; при первом разрешении lockfile резолвер закрепляет эту версию; если каталог или реестр не содержит этой версии в момент разрешения, загрузка рабочего пространства останавливается с ошибкой. - Диапазон —
helm/postgres:^1.2.0. Диапазон semver со стандартным правилом MVS; при первом разрешении lockfile резолвер закрепляет наивысшую доступную версию, удовлетворяющую диапазону. - Без версии —
helm/postgres. Суффикса:versionнет; при первом разрешении lockfile резолвер закрепляет последнюю доступную версию.
Последующие сборки используют версию, закреплённую в lockfile, независимо от формы, введённой пользователем. Повторное разрешение к более новой версии требует явного действия пользователя — aggrega pull --upgrade --release <release> <uri> повторно разрешает одну зависимость, сохраняя все остальные закрепления, а aggrega pull --upgrade --release <release> повторно разрешает все; lockfile — источник истины для сборок, а форма, введённая пользователем, — способ выразить ограничение версии во время написания.
Ссылки с указанием возможности
Идентичность сущности Recipe в каталоге ограничена возможностью: два рецепта могут иметь одинаковые metadata.name и версию, объявляя при этом разные значения spec.capability. Идентичность в реестре — recipe/{capability}/{name}:{version}; она выводится из вида рецепта, его spec.capability без какого-либо закрепления версии, которое оно может содержать, и его имени; дерево каталога стандартной библиотеки по соглашению отражает эту координату в recipe/{capability}/{name}/. Значение сопоставления в Manifest называет рецепт с любой из двух степеней точности:
- Голая —
mariadb:1.0.0. Разрешается, когда это имя носит ровно один рецепт в каталоге; на практике это преобладающая форма. - С указанием возможности —
compose/mariadb:1.0.0. Сегмент перед первым/называетspec.capabilityрецепта без закрепления версии: закрепление, записанное в ссылку, отклоняется (E0095). Обязательна, когда одно и то же имя поставляют несколько рецептов: голая ссылка, совпадающая с двумя рецептами, неоднозначна и при разрешении явно останавливает работу, а не выбирает один из них молча.
Других позиций в URI сущности Recipe нет. Резолвер разделяет только по первому /, поэтому compose/mariadb называет возможность compose и рецепт mariadb, а ссылка из трёх сегментов не совпадает ни с одним рецептом ни при какой степени точности.
Приведённые выше формы сегмента версии применимы к обеим формам ссылки.
Сущности, опубликованные в реестре, в сопоставлениях
На сущность, получаемую из реестра, а не из локального каталога, ссылаются ровно той же идентичностью, что и на локальную: ссылка не содержит ни хоста реестра, ни сегмента вида сущности. Резолвер подставляет оба — хост из настроенного в рабочем пространстве реестра по умолчанию, сегмент вида — по месту ссылки в схеме — по правилам Context-Aware Shorthand URIs ниже. Если копии нет ни в локальном каталоге, ни в кэше, aggrega pull — или сборка, запущенная с --auto-pull, — загружает сущность из выведенного расположения, кэширует её и закрепляет разрешённую версию и дайджест содержимого в lockfile; последующие сборки используют кэш без доступа к сети.
# Aggregate fragment — a registry-published Component as the type:components: db: type: core/datastore/mariadb:1.0.0Поскольку хост и сегмент вида сущности выводятся, а не
пишутся автором, указание любого из них в ссылке не адресует
опубликованную сущность — получается идентичность, которой нет ни у одной записи каталога.
Ссылка на сущность Component или Feature — это её metadata.name дословно плюс
необязательный :version, независимо от того, разрешается ли сущность из локального каталога,
из кэша или из реестра. Рабочее пространство, использующее частный
реестр, указывает этот хост в собственной конфигурации, а не в каждой
ссылке.
Проверка полноты
После разрешения всех сопоставлений компилятор проверяет, что у каждого экземпляра компонента и прикрепления (учётная сущность Feature — такое же прикрепление, как любое другое) в сущности Aggregate разработчика есть разрешённая сущность Recipe или FeatureRecipe. Несопоставленные сущности вызывают фатальную остановку с явной диагностикой, перечисляющей все отсутствующие сущности и предлагающей, какой ключ components.type или features.type добавить, чтобы закрыть пробел.
Якоря YAML для манифестов без повторов (DRY)
Чтобы избежать разрастания YAML в больших наборах сопоставлений, Manifest поддерживает необязательный блок defs: для стандартных якорей YAML (& и *):
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: global-base-manifest version: 1.0.0defs: - &python_worker_recipe "helm/standard-python-worker:2.0.0"spec: mappings: components: type: core/python-worker: *python_worker_recipe core/postgres: helm/postgres:1.2.0Согласование сущностей Feature
Согласование возможностей использует то же плоское сопоставление URI:
- Разработчик прикрепляет
core/data-maskingк компоненту в сущности Aggregate под собственным именем в картеfeatures:этого компонента. - Компилятор ищет
core/data-maskingв картеfeatures.typeсущности Manifest. - Если поиск разрешается в URI сущности FeatureRecipe (например,
helm/data-masking-litellm:1.0.0), возможность существует, и конвейер сущности FeatureRecipe выполняется в заданном порядке. - Если
features.typeне содержит подходящей записи, компилятор останавливает сборку и выводит несопоставленную сущность Feature.
Manifest также принимает блок features.annotations — параллельную поверхность написания, позволяющую сущности Release или подсистеме Aggregate прикреплять Features по ключу аннотации, а не через объявление в каждом компоненте. Форма привязки, разделение «сторона/опора», определяющее, какая поверхность написания использует какие пути маршрутизации, принцип приоритета явного прикрепления и правило значений схемы по умолчанию описаны в отдельном разделе Annotation-Driven Feature Bindings ниже.
Композиция через extends
Manifest может объявить одну ссылку extends:, указывающую на базовый Manifest, чьи mappings он наследует. Эта ссылка не является URI и никогда не разрешается через каталог: Manifest относится к стороне развёртывания и пишется рядом с Release, а не публикуется, поэтому значение — это либо относительный путь к файлу Manifest — ./base-manifest.yaml, — либо просто metadata.name сущности Manifest, находящейся в собственном каталоге Release. Относительный путь должен вести к Manifest внутри рабочего пространства — или, если Release указан вне рабочего пространства (в командной строке или в конфигурации рабочего пространства), внутри каталога, содержащего этот Release, а для Manifest, который вы указываете отдельно в командной строке вне рабочего пространства, — внутри каталога, содержащего этот Manifest: путь, который выходит за его пределы или выводится за них символической ссылкой, отклоняется до чтения указанного им файла (см. errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Ссылка на другой файл ведёт за пределы каталога, внутри которого она должна оставаться)”). При совпадении ключей сопоставления дочернего манифеста перезаписывают базовые, что поддерживает шаблоны наложения окружений (паритет staging/prod с точечными различиями для каждого окружения) и шаблоны локальной разработки без полного копирования.
Семантика слияния. Когда локальный Manifest расширяет базовый Manifest, компилятор выполняет поверхностную замену ключей на каждом уровне — словари type и name сливаются независимо, без глубокого слияния, — что гарантирует поиск по словарю за O(1) и сохраняет предсказуемость наследования. В пределах каждого уровня дочерние ключи перезаписывают родительские.
Шаблон моста для локальной разработки. Типичное применение extends — замена FeatureRecipe для учётных данных при локальном прототипировании без изменения Aggregate. В продакшене базовый Manifest сопоставляет Feature учётных данных core/aws-secrets-manager с продакшен-сущностью FeatureRecipe на уровне features.type. Для локального прототипирования команда платформы предоставляет local-manifest, который расширяет базовый и точечно переопределяет сопоставление Feature учётных данных на host-env-injector — локальный FeatureRecipe, который передаёт учётные данные в файл Compose в виде ссылки на переменную, например ${SECRET_NAME}, которую Docker Compose подставляет из окружения оболочки или из файла .env при запуске стека. Разработчик получает стандартный локальный рабочий процесс, а Aggregate остаётся независимым от возможностей в продакшене.
Контекстно-зависимые сокращённые URI
При разрешении OCI URI в сущностях Manifests компилятор Aggrega использует контекстно-зависимый вывод. Если инженер опускает полное доменное имя (FQDN) и тип архитектурной сущности, компилятор автоматически использует реестр по умолчанию (настраивается в .aggrega-config.yaml) и выводит тип сущности исходя из того, где строка расположена в схеме.
Правила вывода:
- Домен по умолчанию: к любому URI без домена (например,
python-worker-helm:1.0) добавляется префикс из настроенногоdefault_registry(по умолчанию:hub.aggrega.ai/). - Контекстное расширение сущности: компилятор добавляет правильный путь сущности на основе строгого словаря схемы:
- Строки в
Aggregate.spec.components[].typeрасширяются до/component/. - Строки в
Aggregate.spec.aggregates[].typeрасширяются до/aggregate/. - Строки в
Manifest.spec.mappings.components.typeилиManifest.spec.mappings.components.nameрасширяются до/recipe/. - Строки в
Manifest.spec.mappings.features.typeилиManifest.spec.mappings.features.nameрасширяются до/featurerecipe/. Это относится и к сущностям Features для учётных данных (с меткойfeature.aggrega.ai/kind: secret): они используют тот же путь FeatureRecipe. - Строки, присвоенные
pipeline[].plugin, расширяются до/plugin/.
- Строки в
- Трёхуровневый приоритет: перед применением вывода OCI компилятор просматривает каталоги каталога рабочего пространства и кэш артефактов (уровень рабочего пространства и кэша), как определено в трёхуровневой модели разрешения сущностей. Вывод OCI применяется, только когда сущность доходит до уровня реестра. Ключ или значение сопоставления никогда не читается как путь к файлу: локально написанный Recipe или FeatureRecipe находится в каталоге каталога —
catalog/в корне рабочего пространства или в одном из каталогов, перечисленных вworkspace.catalog_dirs, — и называется по своей ссылке.
Сокращения в действии:
# Capability-qualified — required when two recipes share the name "postgres":"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:"core/postgres": "postgres:2.0"# Found in a local catalog directory or the cache; failing both, `aggrega pull`# (or a build run with --auto-pull) fetches it from the registry location derived# from the configured default registry and the Recipe kind.# A private registry is named in workspace configuration, not in the reference.Без префикса ops/. Имена сущностей Recipe не содержат префикса ops/: каталог типа сущности recipe/ в таксономии OCI уже определяет домен, и сущности Recipes публикуются как recipe/{capability}/{name} без дополнительных префиксов. Сущности Manifests ссылаются на Recipes по {capability}/{name} или по голому имени для контекстно-зависимого вывода. Полное описание таксономии OCI см. в architecture/13-catalog-and-registry.md §6.
Привязки Feature на основе аннотаций
Блок features.annotations в Manifest объявляет привязки между ключами аннотаций и типами Feature, а также пути маршрутизации, по которым каждая привязка передаёт значение аннотации. Привязка — это поверхность авторинга для сжатия повторяющихся подключений Feature к отдельным компонентам (ситуации, когда десятки компонентов внутри одной границы несут одинаковый блок features:) в единичные объявления аннотаций на границах Release или подсистемах Aggregate.
Форма схемы:
spec: mappings: features: type: core/rewrite-host: helm/rewrite-host-helm:1.0.0 core/db-pool: helm/db-pool-helm:1.0.0
annotations: feature.aggrega.ai/rewrite-host: feature: core/rewrite-host maps: infra: - upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool: feature: core/db-pool maps: values: - pool # Aggregate-side: routes annotation value into values.poolПривязка содержит поле feature, указывающее целевой тип Feature, и блок maps, группирующий маршруты подключей с путями через точку по целевому столпу. Поле feature ссылается на тип Feature, который также должен присутствовать в соседнем разделе features.type (именно там находится привязка версии FeatureRecipe). Блок maps объявляет два списка с ключами по столпам — maps.infra и maps.values, — каждый из которых содержит строки путей через точку, указывающие на свойства spec.schema.<pillar>.<path> целевой сущности Feature. Привязка должна объявлять хотя бы один путь в двух списках (JSON Schema требует minProperties: 1 для maps).
Provider-полиморфизм для одного и того же ключа аннотации — например, feature.aggrega.ai/rewrite-host привязывается к core/k8s-dns-resolver в развёртывании Kubernetes, но к core/compose-bridge в локальном развёртывании Compose — выражается выбором разных типов Feature в разных сущностях Manifests; каждая сущность Manifest привязывает аннотацию к одной сущности Feature, а FeatureRecipe выбранной сущности Feature содержит реализацию, специфичную для провайдера.
Разделение сторон и столпов. Инвариант «Aggregate как поверхность авторинга» ограничивает каждую сторону авторинга путями маршрутизации одного столпа. Аннотации на стороне Aggregate маршрутизируются только через пути maps.values; аннотации на стороне Release — только через пути maps.infra. Привязка, объявляющая пути в обоих столпах, поддерживает композицию между сторонами: аннотация на стороне Aggregate активирует подмножество столпа values; аннотация на стороне Release с тем же ключом активирует подмножество столпа infra; оба вклада объединяются в одно подключение Feature на пару (Component, Feature) с заполненными обоими столпами. Несоответствие стороны и столпа — например, аннотация на стороне Aggregate для привязки, объявляющей только maps.infra, — останавливает сборку с понятной диагностикой, в которой указаны ключ аннотации, столп маршрутизации, сторона авторинга и место в исходнике; диагностика относится к домену документа, в котором было написано значение аннотации.
Проверка целевых путей. При загрузке каталога компилятор проверяет, что каждый путь через точку, объявленный в maps.infra и maps.values, соответствует свойству, которое действительно объявлено в spec.schema.<pillar> целевой сущности Feature. Привязка, маршрутизирующая в путь, которого нет в схеме Feature, останавливает загрузку каталога с понятной ошибкой OPS_ERROR, в которой указаны привязка, целевая Feature, а также столп и путь маршрутизации. Формы схемы, выходящие за рамки простого обхода свойств ($ref, patternProperties, композиция oneOf / anyOf / allOf), завершают статическую проверку на этой ветви, и любое несоответствие выявляет последующая валидация схемы.
Формы значений аннотаций. Привязка принимает значения аннотаций в трёх формах. Скаляр — одно значение YAML (строка, число, логическое значение). Скаляр в паре с привязкой, объявляющей ровно один путь в обоих столпах, маршрутизирует значение в этот единственный путь; скаляр в паре с привязкой, объявляющей более одного пути, означает неоднозначную маршрутизацию и останавливает сборку с понятной диагностикой, относящейся к домену документа, в котором было написано значение аннотации. Структурированное значение — YAML-словарь, каждый подключ верхнего уровня которого соответствует записи пути через точку в maps.infra или maps.values; каждый подключ маршрутизируется в свой объявленный столп независимо, и разделение сторон и столпов применяется к каждому подключу. Явный YAML null — отказ от унаследованной привязки на уровне каскада (при этом null для отдельного подключа внутри структурированного значения отключает только этот подключ, а соседние остаются в силе). Основное руководство по авторингу структурированных значений — каскадное слияние по подключам, композиция между сторонами, проверка типов по подключам, ослабленная дисциплина значений по умолчанию для полей схемы без объявленного type — см. в providers/well-known-annotations.md, §«Structured annotation values».
При коллизии ключей побеждает явное подключение. Если компонент Release или компонент Aggregate содержит одновременно явную запись features: и аннотацию, которая раскрывается в тот же ключ Feature, явная запись сохраняется, а раскрытие аннотации для этого ключа на этом компоненте не выполняет никаких действий. Синтетическое подключение никогда не перезаписывает экземпляр Feature, объявленный автором. Поэтому авторы могут использовать раскрытие аннотаций для большинства компонентов и точечно переопределять отдельные компоненты, записывая явную запись features: с тем же ключом: явная запись несёт настройку конкретного компонента, а аннотация каскадно применяется ко всем остальным компонентам без изменений.
Приоритет явного значения на уровне листа при композиции между сторонами. Если явное подключение и вклад аннотации заполняют один и тот же экземпляр Feature, но записывают в разные листья, оба вклада сохраняются, и итоговая Feature содержит оба листа с происхождением на уровне листа, фиксирующим источник каждого листа. Если явное подключение и вклад аннотации нацелены на один и тот же лист в одном столпе, побеждает явный вклад, а IR записывает подавленное происхождение аннотации как маркер переопределения на этом листе. Загрузка каталога сообщает об этом переопределении во время сборки рекомендательным предупреждением линтера с указанием подавленного ключа аннотации и источника.
Значения схемы по умолчанию при раскрытии. Синтетическое подключение Feature, созданное раскрытием аннотации, содержит только те листья, которые значение аннотации заполняет через объявленные пути привязки. Значения по умолчанию, объявленные в spec.schema целевой Feature, не сливаются в синтетическое подключение при раскрытии. Материализация значений по умолчанию — ответственность слоя рендеринга FeatureRecipe, она единообразно применяется к явным и синтетическим подключениям, так что оба пути дают одинаковый результат для одной и той же фактической конфигурации.
Разделение пространств имён аннотаций:
| Префикс | Владелец | Назначение |
|---|---|---|
aggrega.ai/ | Только платформа Aggrega | Нативные аннотации платформы, которые провайдер читает напрямую (например, aggrega.ai/namespace). |
feature.aggrega.ai/ | Официальная стандартная библиотека | Сокращения аннотаций Feature, привязанные в Manifest. |
{any-other-domain}/ | Предприятие / сообщество | Пользовательские сокращения аннотаций Feature. |
Резервирование префикса aggrega.ai/
Привязки features.annotations в Manifest не могут использовать голый префикс aggrega.ai/: он зарезервирован для платформенных аннотаций, которые генерирует компилятор (метки OTel и происхождения и т. п.). Ограниченные подпрефиксы (component.aggrega.ai/*, compliance.aggrega.ai/*, корпоративный acme.aggrega.ai/*) остаются доступными для пользовательского авторинга. Набор аннотаций, зарезервированных платформой, см. в providers/well-known-annotations.