Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Поверхность публикации

Каждый YAML каталога Aggrega содержит единый набор полей метаданных, описывающих сущность для распространения через каталог: кто её сопровождает, под какой лицензией она поставляется, где находится её исходный код, по каким ключевым словам её можно найти. Вместе эти поля составляют поверхность публикации — словарь метаданных, на который опираются издатели каталогов и потребители-инструменты; он отличается от механизма metadata.labels / metadata.annotations на стороне содержимого, описанного в labels-and-annotations.md.

На этой странице описаны поля поверхности публикации, перечень полей описания по всему корпусу (описания конверта, экземпляра и уровня поля), предполагаемое использование поля сопровождающих и его подтверждённый потребитель, а также асимметрии обязательных полей для каждой сущности (какие поля требует каждая сущность сегодня и где эти асимметрии намеренны).

Поля публикационной поверхности

Следующие поля присутствуют у каждой сущности домена 2 (Component, Feature) и домена 3 (Recipe, FeatureRecipe, Plugin), а также у сущности Aggregate как повторно используемого модуля. Они есть и у сущностей Manifest и Release, но с урезанной семантикой (атрибуция рабочего пространства, а не публикация в каталоге).

ПолеТипНазначениеПотребитель
descriptionstringПонятное человеку краткое описание сущностиВсплывающие карточки в редакторе (aggrega serve); инструмент describe, который вызывает ассистент (aggrega mcp); аннотация для поиска в опубликованном артефакте (aggrega push); aggrega inspect
maintainersмассив объектовКто владеет сущностью (name, email, url)Узловой блок catalog_metadata в IR, на узлах Component
licensestringСоответствие лицензионным требованиям (обычно идентификатор SPDX)Узловой блок catalog_metadata в IR, на узлах Component
repositorystring (URL)Git-репозиторий с исходным кодомУзловой блок catalog_metadata в IR, на узлах Component — больше его ничто не читает
homestring (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, которые одинаково обязательны для каждой сущности):

СущностьДополнительные обязательные поляОбоснование
Componentmetadata.labels.component.aggrega.ai/typeТребование метки несёт нагрузку при сопоставлении селекторов: аннотации usesSchema x-aggrega-selector: фильтруют целевые Components по этой метке; без неё сущность Component отклоняется при загрузке
Feature—Требования зарезервированной метки нет; Features идентифицируются по имени и издателю
Recipespec.capability, spec.implementsCapability управляет диспетчеризацией провайдеров; implements управляет привязкой к сущности Component
FeatureRecipespec.capability, spec.implementsКак у Recipe
Pluginmetadata.pluginType, spec.abiVersionТип сокета, который реализует плагин (часть блока адресации, задающая сегмент <pluginType> производной координаты plugin/<pluginType>/<name>), и целевая версия ABI; расположение .wasm выводится из этой идентичности, а не записывается автором; плагин рендеринга провайдера (pluginType: provider) дополнительно содержит свой контракт трансляции в spec.provider
Aggregate—Aggregate, в котором не объявлено ни components, ни subsystems, ни aggregates, загружается и собирается, но ничего не рендерит
Manifestspec.mappingsУровни сопоставлений — единственное назначение сущности Manifest
Releasespec.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.