Перейти до вмісту
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масив об’єктівХто володіє сутністю (ім’я, 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.implementsМожливість керує диспетчеризацією провайдера; 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 §«Lockfile pinning and artifact immutability» + §«Catalog entity name-shape enforcement» — що правило незмінності відхиляє під час публікації і де перевіряються форми імен для кожного виду сутностей: плагін дисципліни публікації повідомляє про них у рекомендаційному порядку, коли автор запускає aggrega lint, а ні збирання, ні публікація їх не перевіряють.
  • architecture/11-governance-and-compliance.md §«Inheritance and publishing discipline» — які правила керування належать плагіну дисципліни публікації, а які натомість вирішує за побудовою успадкування в розширювальній сутності Component.