Поверхность публикации
Каждый YAML каталога Aggrega содержит единый набор полей метаданных, описывающих сущность для распространения через каталог: кто её сопровождает, под какой лицензией она поставляется, где находится её исходный код, по каким ключевым словам её можно найти. Вместе эти поля составляют поверхность публикации — словарь метаданных, на который опираются издатели каталогов и потребители-инструменты; он отличается от механизма metadata.labels / metadata.annotations на стороне содержимого, описанного в labels-and-annotations.md.
На этой странице описаны поля поверхности публикации, перечень полей описания по всему корпусу (описания конверта, экземпляра и уровня поля), предполагаемое использование поля сопровождающих и его подтверждённый потребитель, а также асимметрии обязательных полей для каждой сущности (какие поля требует каждая сущность сегодня и где эти асимметрии намеренны).
Поля публикационной поверхности
Следующие поля присутствуют у каждой сущности домена 2 (Component, Feature) и домена 3 (Recipe, FeatureRecipe, Plugin), а также у сущности Aggregate как повторно используемого модуля. Они есть и у сущностей Manifest и Release, но с урезанной семантикой (атрибуция рабочего пространства, а не публикация в каталоге).
| Поле | Тип | Назначение | Потребитель |
|---|---|---|---|
description | string | Понятное человеку краткое описание сущности | Всплывающие карточки в редакторе (aggrega serve); инструмент describe, который вызывает ассистент (aggrega mcp); аннотация для поиска в опубликованном артефакте (aggrega push); aggrega inspect |
maintainers | массив объектов | Кто владеет сущностью (name, email, url) | Узловой блок catalog_metadata в IR, на узлах Component |
license | string | Соответствие лицензионным требованиям (обычно идентификатор SPDX) | Узловой блок catalog_metadata в IR, на узлах Component |
repository | string (URL) | Git-репозиторий с исходным кодом | Узловой блок catalog_metadata в IR, на узлах Component — больше его ничто не читает |
home | string (URL) | URL документации или вики | Узловой блок catalog_metadata в IR, на узлах Component — больше его ничто не читает |
keywords | массив строк | Теги для поиска | Узловой блок catalog_metadata в IR, на узлах Component — ни один поисковый индекс их не использует |
Все шесть полей необязательны у каждой сущности, которая их содержит. Автор каталога, опустивший весь набор, получает корректный YAML: публикационная поверхность предназначена для сущностей, распространяемых через каталог, а сущности для внутреннего использования могут обходиться без неё без каких-либо последствий.
Столбец «Потребитель» исчерпывающе описывает то, что поставляется сегодня, и два следствия из него стоит сформулировать прямо, поскольку они определяют, что имеет смысл заполнять:
description— единственное поле, у которого больше одного читателя.aggrega serveвыводит его во всплывающую карточку для Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest и четырёх видов библиотек (SchemaLibrary,MappingLibrary,WorkloadLibrary,ArtifactLibrary), но не для Plugin и не для Release. Инструментdescribe, который предоставляетaggrega mcp, возвращает его для сущности любого вида.aggrega pushзаписывает его в опубликованный артефакт как аннотацию для поиска.aggrega inspectвыводит его под заголовком сущности для всех видов и не выводит никаких других полей публикационной поверхности.repository,homeиkeywordsпроверяются и переносятся, но за пределами IR их ничто не читает. Их не использует ни одна витрина, сайт каталога или поисковый индекс. Заполняя их, вы фиксируете происхождение, которое путешествует вместе с сущностью и доступно для чтения из вывода IR и из политики управления; находимой где-либо сущность от этого не становится.
Устаревание не является полем публикационной поверхности. Сущность помечается как устаревшая записью маркера в реестре после публикации — подписанного маркера с уровнем серьёзности (warning, error или retracted), причиной и заменой, который проверяется при загрузке. После этого о нём сообщает каждая поверхность, читающая lock-файл; build.halt_on_deprecated_severity определяет лишь то, останавливает ли он ещё и сборку. Маркер никогда не записывается в собственный YAML сущности, и причина этого структурная: опубликованный артефакт неизменяем, поэтому флаг, зафиксированный в нём при публикации, не смог бы выразить решение, принятое позже. Уведомление об устаревании, которое aggrega inspect выводит для сущности каталога, берётся из маркера — для каждого вида, который команда разрешает по имени.
Потребление в IR — узловой блок catalog_metadata
Компилятор переносит поля публикационной поверхности каждой сущности Component в блок catalog_metadata соответствующего узла, видимый в графе IR, который возвращает запуск (aggrega inspect <release> --ir-graph). Блок содержит maintainers, license, repository, home и keywords — пять полей, которые переносит IR; description среди них нет. Инструменты, построенные на контракте графа IR, читают метаданные оттуда, а не перечитывают YAML каталога.
Только узлы Component. Блок заполняется поиском типа компонента узла в каталоге как сущности Component, поэтому публикационная поверхность сущностей Feature, Recipe, FeatureRecipe или Plugin никогда не попадает в IR: эти сущности содержат поля, и поля проходят проверку, но узлов IR из них не возникает.
catalog_metadata полностью исчезает из JSON IR, если все поля публикационной поверхности исходной сущности Component пусты или нулевые: блок опускается, а не выводится с пустыми значениями. Поэтому одни и те же входные данные дают один и тот же компактный вывод, что сохраняет diff IR стабильным между запусками.
Блок может читать политика управления. Плагин, подключённый в plugins.governance в роли ir-verdict, получает весь граф IR узел за узлом, включая catalog_metadata каждого узла Component, поэтому политика может принять или отклонить сборку по license, repository, home, keywords или maintainers узла. Такой доступ есть только у сокета управления: плагин рендеринга провайдера получает ограниченную проекцию каждого узла, которая не включает catalog_metadata, поэтому плагины рендеринга не могут читать эти поля.
Три типа описаний
Поле description единообразно присутствует в конверте, но корпус также содержит строки-описания внутри объявлений схем (описания отдельных полей) и внутри тел столпов (описания отдельных экземпляров). Сосуществуют три различных типа описаний; таблица ниже разграничивает их.
| Тип | Где находится | Автор | Назначение |
|---|---|---|---|
| Описание конверта | metadata.description в каждой сущности | Издатель каталога | Краткое описание сущности в целом, показываемое во всплывающих карточках редактора и записываемое в опубликованный артефакт |
| Описание экземпляра | Поле description рядом с объявлением отдельного экземпляра (например, featuresSchema.<slot>.description, usesSchema.<socket>.description) | Автор схемы | Описание слота / сокета / порта для авторов потребляющих сущностей, читающих объявление |
| Описание поля | Аннотация JSON Schema 2020-12 description: внутри содержимого schema: / featuresSchema: / usesSchema: (в компактной форме или в полном YAML JSON Schema) | Автор схемы | Документация отдельных полей, которая передаётся вместе со схемой |
Три типа объединяет слово «description», но они находятся на структурно разных уровнях. Описание конверта относится к сущности в целом; описание экземпляра — к объявлению внутри слота схемы; описание поля — к конкретному значению внутри типизированной схемы. Авторы, пишущие сущность Component:
- Задают
metadata.descriptionодин раз для самой сущности Component. - Задают
featuresSchema.admin_password.descriptionодин раз для каждого слота учётных данных, который объявляет Component. - Задают аннотации
description:для отдельных полей внутри блокаschema:— в компактной форме (port: { type: integer, description: "..." }) или в полном YAML JSON Schema, — чтобы документировать каждое поле для тех, кто читает схему Component.
Три типа не наследуются каскадно и не конфликтуют, и каждый попадает в свою поверхность — или ни в какую:
- Описание конверта — всплывающие карточки редактора, аннотации опубликованного артефакта, доступные для поиска, и
aggrega inspect, согласно столбцу «Потребитель» выше. - Описание поля — дословно появляется в фрагменте схемы, который отображает всплывающая карточка Component или Feature. Фрагмент охватывает только
spec.schemaи обрезается до первых строк, поэтому описание, расположенное глубже в блоке, — или описание внутриfeaturesSchema:илиusesSchema:— там не появляется. - Описание экземпляра — объявляется и передаётся вместе с сущностью; ни одна поставляемая поверхность не отображает его отдельно.
aggrega inspectперечисляет сокеты и слоты функций Component без их описаний.
Назначение поля maintainers
Поле maintainers содержит массив объектов, каждый из которых имеет name, email и url. Назначение и подтверждённый потребитель:
Назначение (информационное + происхождение в IR). Поле носит информационный характер для публикации каталога: архитектурный замысел — «кто отвечает за эту сущность каталога», то есть сигнал о владении, который передаётся вместе с сущностью. Ни одна поверхность не представляет его как список контактов, и ни одна встроенная проверка ни с чем его не сравнивает.
Подтверждённый потребитель (catalog_metadata на уровне узла). Компилятор переносит metadata.maintainers каждой сущности Component в catalog_metadata.maintainers соответствующего узла в IR; это видно в графе, который возвращает aggrega inspect <release> --ir-graph, если исходная сущность Component его объявила. Это единственный читатель поля. Политика управления, подключённая в plugins.governance в роли ir-verdict, видит его там, поэтому правило владения — каждая сущность называет хотя бы одного сопровождающего, домен сопровождающего входит в утверждённый набор — можно выразить по отношению к IR, а не к YAML каталога. Такое правило не поставляется; сокет — это место, куда его следует подключить.
Компилятор не проверяет и не валидирует содержимое сопровождающих сверх структурной формы JSON Schema (name обязательно; email и url необязательны, оба — строки). Действительно ли перечисленные сопровождающие владеют сущностью, доступен ли их адрес электронной почты, подписан ли коммит в репозитории одним из них — всё это вопросы управления каталогом, и ни одна поставляемая проверка ничего из этого не оценивает. Они относятся к политике управления, которую подключает оператор, а не к компилятору.
Асимметрии обязательных полей
Виды сущностей Aggrega имеют в своих JSON Schema несколько разные наборы обязательных полей. Большинство асимметрий намеренны и отражают роль сущности.
Обязательные поля по сущностям (без учёта apiVersion / kind / metadata.name / metadata.version, которые одинаково обязательны для каждой сущности):
| Сущность | Дополнительные обязательные поля | Обоснование |
|---|---|---|
| Component | metadata.labels.component.aggrega.ai/type | Требование метки несёт нагрузку при сопоставлении селекторов: аннотации usesSchema x-aggrega-selector: фильтруют целевые Components по этой метке; без неё сущность Component отклоняется при загрузке |
| Feature | — | Требования зарезервированной метки нет; Features идентифицируются по имени и издателю |
| Recipe | spec.capability, spec.implements | Capability управляет диспетчеризацией провайдеров; implements управляет привязкой к сущности Component |
| FeatureRecipe | spec.capability, spec.implements | Как у Recipe |
| Plugin | metadata.pluginType, spec.abiVersion | Тип сокета, который реализует плагин (часть блока адресации, задающая сегмент <pluginType> производной координаты plugin/<pluginType>/<name>), и целевая версия ABI; расположение .wasm выводится из этой идентичности, а не записывается автором; плагин рендеринга провайдера (pluginType: provider) дополнительно содержит свой контракт трансляции в spec.provider |
| Aggregate | — | Aggregate, в котором не объявлено ни components, ни subsystems, ни aggregates, загружается и собирается, но ничего не рендерит |
| Manifest | spec.mappings | Уровни сопоставлений — единственное назначение сущности Manifest |
| Release | spec.aggregate, spec.manifest (Release, объявляющий extends, не записывает aggregate и может опустить manifest); metadata.environment | Первые два привязывают сборку к конкретным Aggregate и Manifest; environment проставляется в отрендеренный вывод как метка aggrega.ai/environment |
Требование метки Component несёт нагрузку
Метка component.aggrega.ai/type — единственная метка, которую Aggrega требует от какой-либо сущности. Это требование существует потому, что механизм usesSchema стандартной библиотеки фильтрует целевых кандидатов с помощью аннотаций x-aggrega-selector:, содержащих строки селекторов вроде "component.aggrega.ai/type=database": селектор обращается к меткам цели, чтобы определить, соответствует ли тип типам, принимаемым сокетом. Схема Component обеспечивает это: Component без этой метки отклоняется при загрузке (E0215) с указанием отсутствующего ключа.
Таким образом, это требование относится не к поверхности публикации (метка не служит для обнаружения в каталоге), а к топологии: её несёт каждый Component, включая Components для внутреннего использования, не предназначенные для распространения через каталог.
Поле metadata.environment сущности Release обязательно
Схема Release требует metadata.environment — строку, которую сборка проставляет в отрендеренный вывод как метку aggrega.ai/environment.
Другие асимметрии
Остальные асимметрии (обязательные поля Recipe и Component, требование mappings для Manifest) отражают роль каждой сущности. Авторы, которым нужен единый контракт обязательных полей для всех видов сущностей, его не найдут: асимметрии намеренны в соответствии с ролевым дизайном.
Перекрёстные ссылки
labels-and-annotations.md— механизм метаданных на стороне содержимого, дополняющий поверхность публикации.entities/component.md— требованиеmetadata.labels.component.aggrega.ai/typeдля сущности Component и объявленияschema/usesSchema/featuresSchema.entities/release.md— полеmetadata.environmentсущности Release и требование к нему.10-status.md— статус конверта метаданных.architecture/02-ecosystem-philosophy.md— строгое разделение API и концепция набора корпоративных метаданных (Enterprise Metadata Suite).architecture/13-catalog-and-registry.md§«Закрепление в lock-файле и неизменяемость артефактов» + §«Контроль формы имён сущностей каталога» — что правило неизменяемости отклоняет во время публикации и где проверяются формы имён для каждого вида сущностей: плагин дисциплины публикации сообщает о них в рекомендательном порядке, когда автор запускаетaggrega lint, а ни сборка, ни публикация их не проверяют.architecture/11-governance-and-compliance.md§«Наследование и дисциплина публикации» — какие правила управления относятся к плагину дисциплины публикации, а какие вместо этого решаются по построению через наследование расширяющей сущности Component.