Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Каталог і реєстр

У цьому розділі визначено, як платформа масштабується на рівні підприємства завдяки каталогу OCI (Open Container Initiative): як улаштовано каталог, як розв’язується посилання, як сутність публікується і закріплюється та яким формам імен відповідають сутності каталогу.

Каталог Aggrega: таксономія та розв’язання реєстру

Компілятор Aggrega спирається на суворо типізований реєстр, натхненний OAM, щоб розв’язувати абстрактний намір розробника (Домен 1) у конкретну реальність Ops (Домен 3). Щоб підтримувати відкриту розподілену екосистему й водночас зберігати безшовний досвід розробника, усі схеми, прив’язки інфраструктури, програмовані політики та плагіни-адаптери дотримуються стандартизованої таксономії URI Open Container Initiative (OCI). Оскільки кожна сутність каталогу адресується через URI, aggrega pull завантажує до кешу ті з них, які потрібні сутності Release, і закріплює їх у її lock-файлі, а збирання читає їх звідти. Локальний робочий простір розробника містить лише його файли Aggregate і Release, а не копію каталогу.

1. Основна структура каталогів (каталог)

Тека aggrega-catalog стандартної бібліотеки (і будь-який сумісний сторонній каталог) організована так, щоб фізично забезпечувати розділення відповідальностей. Структура явно відокремлює абстрактні інтерфейси від їхніх конкретних реалізацій інфраструктури.

Для сутностей Components і Features сегменти URI відповідають 1:1 сегментам шляху у файловій системі. Сутності Components використовують URI з трьох сегментів ({publisher}/{category}/{name}), де сегмент категорії містить одну із закритого набору когнітивних категорій — те саме слово, що й мітка component.aggrega.ai/category компонента (дзеркало каталогу 1:1, яке перевіряє правило category-matches-directory лінтера публікації). Сутності Features залишаються пласкими ({publisher}/{name}) — невеликий набір, що росте повільно. Операційна онтологічна класифікація (stateful-server, server тощо) міститься в мітці component.aggrega.ai/type, ніколи не в структурі каталогів; мітки когнітивних можливостей (datastore.aggrega.ai/engine, agent.aggrega.ai/autonomy, …) накладають поверх поведінкові підмножини. Вебінтерфейс хабу використовує мітки для фільтрування та пошуку; категорії слугують і для навігації файловою системою, і для осі перегляду каталогу.

Наведене нижче дерево ілюстративне за вмістом і точне за формою. Там, де сутність намальовано повністю, вона сягає аж до свого листового файлу, тож із діаграми можна прочитати цілий реальний шлях: який рівень каталогу несе який сегмент URI, де розташований обов’язковий сегмент версії та яке ім’я файлу використовує кожен вид сутності в листі. Воно показує кілька записів на рівень, а не повний вміст каталогу — ... позначає пропуск, а імена, написані поруч, — це інші записи того самого рівня.

aggrega-catalog/
│
├── schemalibrary/ # TIER 3: Reusable JSON Schema 2020-12 definitions
│ │ # Shared shapes (BaseComponentParameter,
│ │ # BaseDatastoreParameter) consumed from a Component or
│ │ # Feature schema via $ref: <Library>#/schemas/<name>
│ │ # Path: {name}/{version}/library.yaml
│ │
│ ├── ai-datastores/
│ │ └── 1.0.0/
│ │ └── library.yaml
│ └── base-components/
│ └── 1.0.0/
│ └── library.yaml
│
├── workloadlibrary/ # TIER 3: Reusable Workload template fragments
│ │ # Shared bodies (StatelessService) consumed from a
│ │ # Recipe via workload: { $import: <Library>#/workloads/<name> }
│ │ # Path: {name}/{version}/library.yaml
│ │
│ └── base-workloads/
│ └── 1.0.0/
│ └── library.yaml
│
├── component/ # DOMAIN 2: Abstract Interfaces
│ │ # URI: {publisher}/{category}/{name}
│ │ # Path: {publisher}/{category}/{name}/{version}/component.yaml
│ │ # type: core/datastore/mariadb:1.0.0
│ │ # → component/core/datastore/mariadb/1.0.0/component.yaml
│ │
│ ├── core/ # "core" = official Aggrega standard library
│ │ ├── ai-agent/ # AI agent frameworks, platforms, patterns
│ │ │ └── ... # anthropic, crewai, langflow, pydantic-ai, …
│ │ ├── ai-model/ # model providers and inference runtimes
│ │ │ └── ... # ai21, anthropic, azure-openai, openai, …
│ │ ├── ai-tool/ # tools agents invoke
│ │ │ └── ... # browser, mcp, search, …
│ │ ├── ai-pipeline/ # AI data/processing pipelines
│ │ │ └── ... # argo-workflows, temporal
│ │ ├── datastore/ # persistent datastores
│ │ │ ├── mariadb/
│ │ │ │ └── 1.0.0/
│ │ │ │ └── component.yaml
│ │ │ ├── postgres/
│ │ │ │ └── 1.0.0/
│ │ │ │ └── component.yaml
│ │ │ └── ... # etcd, ferretdb, qdrant, redis, valkey, …
│ │ ├── gateway/ # API and AI gateways
│ │ │ └── ... # apisix, contour, kong, nginx, …
│ │ ├── compute/ # generic compute primitives
│ │ │ └── ... # function, keda, server, task, worker, …
│ │ ├── messaging/ # event buses, queues
│ │ │ └── ... # kafka, nats, rabbitmq, …
│ │ ├── observability/ # metrics, logs, traces
│ │ │ └── ... # grafana, loki, otel-collector, prometheus, tempo, …
│ │ ├── security/ # identity, secrets, certificates
│ │ │ └── ... # cert-manager, external-secrets, keycloak, …
│ │ ├── devtool/ # developer-facing tooling
│ │ │ └── ... # adminer, promptlayer, …
│ │ └── storage/ # object/file storage, and the backup controllers
│ │ │ # that copy a cluster's resources, or its
│ │ │ # volumes' files, into a bucket
│ │ ├── s3-object-store/
│ │ │ └── 1.0.0/
│ │ │ └── component.yaml
│ │ └── ... # barman-cloud-plugin, gcs, k8up, velero, …
│ └── example/ # a second publisher, same three-segment shape
│ └── compute/
│ └── greeter/
│ └── 1.0.0/
│ └── component.yaml
│
├── feature/ # DOMAIN 2: Abstract Interfaces
│ │ # Flat: {publisher}/{name} (no category segment)
│ │ # Path: {publisher}/{name}/{version}/feature.yaml
│ │ # type: core/data-masking:1.0.0
│ │ # → feature/core/data-masking/1.0.0/feature.yaml
│ │
│ ├── core/
│ │ ├── data-masking/
│ │ │ └── 1.0.0/
│ │ │ └── feature.yaml
│ │ ├── secret-value/ # feature.aggrega.ai/kind: secret
│ │ │ └── 1.0.0/
│ │ │ └── feature.yaml
│ │ └── ... # k8s-dns-resolver, public-ingress, retry-policy, …
│ └── ... # other publishers, same flat shape
│
├── aggregate/ # DOMAIN 1: Reusable Aggregate Modules
│ │ # Path: {publisher}/{name}/{version}/aggregate.yaml
│ └── core/
│ ├── keycloak/
│ │ └── 1.0.0/
│ │ └── aggregate.yaml
│ └── ... # agenta, apisix, dify, harbor, kong, thanos, …
│
├── recipe/ # DOMAIN 3: Concrete Implementations
│ │ # Organized by CAPABILITY (the one a Recipe declares
│ │ # in spec.capability).
│ │ # Path: {capability}/{name}/{version}/recipe.yaml
│ │ # The version directory may bundle the Recipe's own
│ │ # source charts or modules beside recipe.yaml.
│ │ # OCI: hub.aggrega.ai/recipe/helm/mariadb:1.0.0
│ │
│ ├── helm/
│ │ ├── mariadb/
│ │ │ └── 1.0.0/
│ │ │ └── recipe.yaml
│ │ └── postgres/
│ │ └── 1.0.0/
│ │ └── recipe.yaml
│ ├── compose/
│ │ └── mariadb/
│ │ └── 1.0.0/
│ │ └── recipe.yaml
│ ├── terraform/
│ │ └── mariadb-rds-module/
│ │ └── 1.0.0/
│ │ ├── recipe.yaml
│ │ └── module/ # bundled Terraform source
│ │ ├── main.tf
│ │ └── variables.tf
│ └── cloudformation/
│ └── postgres-rds/
│ └── 1.0.0/
│ └── recipe.yaml
│
├── feature-recipe/ # DOMAIN 3: Concrete Implementations
│ │ # Capability leads the path, same as recipes.
│ │ # Path: {capability}/{name}/{version}/recipe.yaml
│ │
│ ├── helm/
│ │ ├── k8s-secret-from-parameter/
│ │ │ └── 1.0.0/
│ │ │ └── recipe.yaml
│ │ └── public-ingress/
│ │ └── 1.0.0/
│ │ ├── recipe.yaml
│ │ └── chart/ # bundled Helm source
│ │ ├── Chart.yaml
│ │ └── templates/
│ │ └── ingress.yaml
│ ├── compose/
│ │ └── dotenv-secret/
│ │ └── 1.0.0/
│ │ └── recipe.yaml
│ └── ... # terraform, cloudformation
│
└── plugin/ # ARTIFACTS: Plugin entities, each a content-addressed
│ # reference to a Wasm artifact. The compiled artifact
│ # is published separately and is not stored here.
│ # Path: {pluginType}/{name}/{version}/plugin.yaml
│
├── linter/
│ └── publishing/
│ └── 0.5.0/
│ └── plugin.yaml
└── provider/ # the directory mirrors metadata.pluginType
├── helm/
│ └── 0.5.0/
│ └── plugin.yaml
└── ... # cloudformation, compose, helm-chart, terraform

Категорії компонентів — це закритий набір, і саме цей набір — а не файлова система — є авторитетним джерелом щодо категорій. Значення категорії, яке ще не має жодної сутності, є зарезервованою лексикою: вісь перегляду залишається стабільною, і автор знає, куди потрапить майбутній компонент, тому порожня полиця — це правильно, а не вакансія, що чекає мешканця. Оскільки каталог не містить файлів-заповнювачів, каталог для такого значення створюється, коли з’являється його перша сутність.

Авторитетний перелік — кожна категорія, що вона містить, операційні значення type, які зазвичай мають її сутності, і які каталоги існують — це розділ Категорії сутностей Component посібника з домовленостей каталогу, що публікується разом із каталогом стандартної бібліотеки, яким він керує.

Вісь type несе лише операційні примітиви — когнітивна лексика на ній ніколи не з’являється, а опублікована схема сутності Component перелічує значення, які приймає зарезервований ключ, тож когнітивне слово, записане там, відхиляється під час завантаження документа. Поділ на три осі: операційний type (як інфраструктура поводиться з компонентом), когнітивна category (чим він є, віддзеркалена каталогом) і мітки можливостей для кожної ролі (поведінкові підмножини — сутність є category: datastore плюс те значення datastore.aggrega.ai/engine, яке несе її власна продуктова ідентичність, тож core/datastore/qdrant несе vector, а core/datastore/redis — kv, і обидві осі можна запитувати). Можливість, істинність якої залежить від того, що налаштує автор, у каталозі взагалі не зберігається: її впроваджує під час компіляції роль label-transform сокета управління, яка читає оголошені розробником values. Суто AI-категорії мають префікс ai-; категорії подвійного призначення з’являються без префікса, а їхній AI-характер виражають мітки можливостей. Категорії обирають за тим, як користувачі орієнтуються й переглядають, а не за тим, як класифікує компілятор — лексика категорій і мітки можливостей є термінами, з якими компілятор зіставляє селектори і яким не надає жодного значення. Ім’я компонента не повторює його категорію: модель OpenAI у стандартній бібліотеці — це core/ai-model/openai, а не core/ai-model/openai-model.

2. Розділена схема і конвеєр синтезу мосту

Щоб позбутися шаблонного коду для кожної сутності Component навколо оголошень сокетів топології, Aggrega розділяє валідацію на дві частини й перевіряє кожну там, де розташований її предмет:

  1. usesSchema (декларативний YAML). Оголошує сокети топології, які пропонує сутність каталогу, і надає кожному з них контракт. CLI на Go нативно читає його, щоб видобути рядки selector: для зіставлення міток під час статичного аналізу та щоб перевірити дозволені механізми inject. Кожен запис сокета підтримує необов’язкове поле required: true (за замовчуванням false) — якщо його встановлено, компілятор видає помилку валідації, коли в цьому сокеті не оголошено жодної залежності. Це відповідник семантики required: true у записах featuresSchema для сокетів: обидва зупиняють збирання. Оголошення сокета тут — це те, що робить каталог стандартної бібліотеки, і воно залишається кращим шляхом — але це не єдиний спосіб, у який розробник може провести ребро. Автор сутності Aggregate може назвати на власному компоненті сокет, якого цей usesSchema не оголошує, зокрема на сутності, що взагалі не оголошує usesSchema; такий ad hoc сокет не має ні селектора, ні списку дозволених inject, ні схеми для окремого ребра — саме тому, що тут немає запису, який би їх містив. uses прикріплення сутності Feature і uses для окремого ребра в сутності Release не відкриті в такий спосіб — обидва можуть називати лише оголошений сокет. Повний контракт і те, від чого відмовляється ad hoc сокет, описано в dependency-resolution §«Домен 2: розділена схема».
  2. Розцукровування. Якщо розробники використовують скорочену форму масиву YAML (uses: databases: ["db1"]), CLI нормалізує її в мапу ({"db1": {"target": "db1"}}).
  3. Синтез мосту. Компілятор проєктує таблицю слотів featuresSchema: у фрагмент JSON Schema 2020-12 — одна властивість на кожен слот прикріплення, що описує форму заповнення, яке може його зв’язати, з ключовим словом розширення x-aggrega-inject: на слоті, що оголошує список дозволених inject. Валідація JSON Schema ігнорує ключові слова розширень під час структурної валідації, і ніщо не зчитує жодного з них назад із фрагмента: перевірка, якій потрібен список дозволених слота, читає сам слот. Таблиця сокетів usesSchema: не проєктується в жоден фрагмент. selector: та inject: сокета залишаються в типізованому YAML, який написав архітектор, і читаються звідти, а valueSchema: / infraSchema: для окремого ребра сокета обгортається й компілюється окремо, без жодного вигаданого навколо нього обмеження.
  4. Композиція. Архітектор платформи пише сувору декларацію schema: (компактна форма або повна JSON Schema 2020-12), що визначає values, infra і provides. Ця декларація є власним контрактом сутності й компілюється окремо: ні фрагмент слотів, ні таблиця сокетів до неї не включаються. Кожна поверхня перевіряється там, де розташований її предмет, тож помилка сокета повідомляється для запису сокета, який написав архітектор, а не для шляху всередині блоку schema: — і архітектор, як і раніше, не пише жодного шаблонного коду uses.

Приклад — оголошення сокета і те, що з ним робить компілятор: YAML архітектора платформи

spec:
usesSchema:
databases:
selector: "component.aggrega.ai/type=stateful-server"
inject: ["env", "file", "ssm_param"] # env and file are core mechanisms; ssm_param is a user-provided mechanism
schema:
values:
ha_mode: { type: boolean, default: false }
infra:
replicas: { type: integer, min: 1 }
provides:
host: { type: string, required: true }
assertions:
# The Architect can write cross-pillar invariants against the unified instance content.
ha-mode-needs-two-databases: |
{{- if eq .values.ha_mode true -}}
{{- if lt (len .uses.databases) 2 -}}
{{- fail "ha_mode=true requires at least two database attachments" -}}
{{- end -}}
{{- end -}}

Що з ним робить компілятор Таблиця сокетів читається як типізований YAML, яким вона і є: рядок selector: потрапляє до нативного рушія зіставлення міток, а список inject: обмежує, які механізми доставлення може називати ребро, що проходить через цей сокет. Блок schema: компілюється окремо, як власний контракт values / infra / provides сутності. Статичний аналізатор читає рядок selector: із запису сокета, який написав архітектор, — разом з appliesTo / appliesToAnyOf із сутностей Feature — і оцінює зіставлення міток щодо metadata.labels кожної цілі, щоб перевірити безпеку типів між вузлами.

Селектори в стилі Kubernetes в usesSchema

Нативний рушій зіставлення міток компілятора Go оцінює рядки селекторів за стандартною семантикою вибору в стилі Kubernetes (AND через кому, OR через in(), NOT через !=/notin()). Цей самий рушій — і та сама граматика рядків селекторів — оцінює також селектори прикріплення сутностей Feature (appliesTo і кожен елемент appliesToAnyOf). Шар селекторів — це виключно шлюз топології — декларації schema: для кожної опори незалежно перевіряють вміст values, infra і provides. Після того як компілятор Go проводить топологічні ребра під час побудови топології, статичний аналізатор читає рядки selector із записів сокетів, які написав архітектор, і оцінює їх щодо каталожних labels цільового вузла, щоб перевірити безпеку типів між вузлами.

usesSchema:
# 1. The AND Operator (Comma)
databases:
selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
# 2. The OR Operator (Set-based 'in')
datastores:
selector: "datastore.aggrega.ai/engine in (relational, vector)"
# 3. The NOT Operator
internal_systems:
selector: "compliance.aggrega.ai/data-class!=public"

Селектор, який рушій не може прочитати як одну з шести своїх форм вимоги, — порожня вимога, ключ, що містить пробіл або один із символів =, !, (, ) і кому, незакрита множина, — зупиняє збірку на кожному ребрі, яке він охороняє, замість того щоб бути прочитаним як якийсь інший селектор. Граматика селекторів перелічує форми та кожну відмову.

3. Формати схем і композиція

Щоб забезпечити і сувору валідацію, і стандартні метадані каталогу (автор, версія, опис), визначення Домену 2 (Інтерфейси) і Домену 3 (Реалізації) пишуться як YAML-конверти. Домен 2 використовує вбудовані декларації schema:, виражені в компактній формі (за замовчуванням; ~15 ключових слів, механічно перетворених на JSON Schema 2020-12) або в повному YAML JSON Schema.

Чому кожен YAML каталогу повторює конверт. Конверт (блок apiVersion, kind, metadata) з’являється на початку кожного файлу каталогу — Component, Feature, Recipe, FeatureRecipe, Aggregate, Manifest, Release, Plugin — незалежно від того, наскільки коротке тіло. Повторення навмисне: кожен файл розроблено так, щоб його можна було розбирати, валідувати, перевіряти лінтером і інспектувати як самостійний артефакт. Окремий файл, завантажений з реєстру OCI, поміщений у пісочницю CI або відкритий у сторонньому редакторі, мусить містити достатньо самоопису, щоб подальші інструменти могли визначити, який вид сутності він представляє і яка версія схеми застосовується. Розташування директорії ніколи не замінює конверт: кожен парсер, валідатор і лінтер читає вид сутності та версію схеми з конверта. Ціна — механічний шаблонний код у кожному файлі; вигода — гарантія самостійних інструментів діє на поверхні розповсюдження OCI, у локальній файловій системі та на поверхнях IDE / CI / inspect. Автори копіюють конверт з наявних файлів, створюючи новий вміст каталогу, або починають з aggrega scaffold <kind>, який виводить початковий документ для цього виду із заповненими apiVersion і kind.

Щоб дотримуватися принципу DRY (Don’t Repeat Yourself, «не повторюйся»), каталог використовує два різні механізми композиції:

  • Спільні записи SchemaLibrary (міждокументний $ref:): Багаторазові визначення JSON Schema зберігаються в сутностях каталогу SchemaLibrary (Tier 3). На них посилаються за ідентичністю через міждокументний $ref: (<library>#/schemas/<entry>, без хоста — версія береться з lock-файлу) з будь-якої схеми сутності Component або Feature, що їх споживає. Ланцюжок обходиться під час компіляції. Форму створення сутності бібліотеки описано в entities/schemalibrary, а семантику розв’язання — у vocabulary/cross-document-ref.
  • Одиночне успадкування (extends): Для повних базових компонентів сутності можуть використовувати властивість extends: "URI". Компілятор Go рекурсивно читає ланцюжок батьківських сутностей і глибоко зливає метадані YAML (перезаписуючи мітки в разі конфлікту й дописуючи масиви). Далі два види каталогу розходяться щодо опор даних. schema: сутності Feature компонується зі схемою її бази за правилами композиції JSON Schema 2020-12. Сутність Component, що розширює, взагалі не пише вмісту опор: вона записує буквальний маркер schema: inherited і отримує блок schema: своєї бази точно таким, яким його написала база, на будь-якій глибині ланцюжка. Натомість така сутність Component компонує структуру — її слоти прикріплення (featuresSchema), сокети топології (usesSchema), список дозволених самоінʼєкцій (inject) та іменовані assertions зливаються вздовж ланцюжка. Приклади розширення базових і дочірніх компонентів див. у entities/component + те, що успадкування вирішує за побудовою, а що залишається правилом дисципліни публікації, див. у governance-and-compliance §«Успадкування і дисципліна публікації».

Приклади розширення базових і дочірніх компонентів див. у entities/component, а створення сутностей Recipe з покажчиками й маперами з повними прикладами — у entities/recipe.

4. Конфігурація робочого простору (.aggrega-config.yaml)

Файл .aggrega-config.yaml у корені робочого простору — це конфігурація робочого простору проєкту — власна декларація робочого простору, придатна для системи контролю версій так само, як go.mod чи package.json. Директорію .aggrega/ за домовленістю не додають до системи контролю версій — внесіть її до .gitignore, як ви зробили б із node_modules/ чи .terraform/.

Розділ workspace — це маркер кореня: його наявність позначає корінь робочого простору, і він містить лише директорії каталогу, що визначають корінь, — catalog_dirs і мапу releases, яка надає сутності Release власні директорії каталогу. Усі інші налаштування розташовані на верхньому рівні. Багато з них — окремі значення; інші — розділи, що збирають налаштування одного аспекту під одним ключем. Кожне поле необов’язкове й має задокументовані значення за замовчуванням. Повний актуальний набір ключів верхнього рівня, кожен із типом, значенням за замовчуванням і значенням, генерується зі схеми в schema/other/aggrega-config; наведений нижче приклад показує маркер кореня поряд із кількома налаштуваннями з одним значенням:

.aggrega-config.yaml
workspace: # Root marker; presence marks the workspace root
catalog_dirs: # Ordered list of local catalog directories (checked before cache)
- ./aggrega-catalog
default_registry: hub.aggrega.ai # Default registry for unqualified URIs
offline: false # Set true for air-gapped environments
auto_pull: true # Opt in to the implicit pull; the default is false, keeping build read-only
artifact_cache_dir: .aggrega/cache # On-disk artifact cache root

Блок signing: містить типові налаштування підписування артефактів, які використовують aggrega push --sign і aggrega sign, як на верхньому рівні (глобально), так і для окремого реєстру:

.aggrega-config.yaml
signing: # Global signing defaults
fulcio_url: https://fulcio.sigstore.dev # Keyless certificate authority (defaults to public-good)
rekor_url: https://rekor.sigstore.dev # Keyless transparency log (defaults to public-good)
timestamp_url: https://tsa.example.com/api/v1/timestamp # Optional RFC3161 timestamp authority (no default; opt-in)
key_path: ./keys/signing.pem # Optional: path to a held keyed-key PEM (a pointer, never inline material)
registries:
- host: hub.example.com
signing: # Per-registry override of the global signing block
key_path: ./keys/hub.pem

Пріоритет для кожного поля: прапорець CLI > signing для реєстру > глобальний signing > загальнодоступне значення за замовчуванням. Fulcio і Rekor за замовчуванням використовують загальнодоступні екземпляри Sigstore, тому вони необов’язкові; timestamp_url не має значення за замовчуванням — довірена позначка часу без ключів походить із включення до журналу прозорості Rekor, а орган позначок часу RFC3161 вмикається за бажанням (щоб увімкнути його, задайте timestamp_url або --timestamp-url з повною кінцевою точкою). Безпека: блок signing: не містить секретних матеріалів — токен ідентичності OIDC ніколи не є полем конфігурації (це короткоживучий секрет, що передається під час підписування: його отримують через браузерний потік в інтерактивному терміналі або з робочого процесу в GitHub Actions, а в інших випадках передають через --identity-token або експортують як AGGREGA_IDENTITY_TOKEN чи SIGSTORE_ID_TOKEN), а приватний ключ ніколи не вказується inline; key_path — це шлях до файлу ключа. Це навмисна асиметрія щодо сторони перевірки, яка закріплює відкритий ключ inline, тоді як на стороні підписування завжди лише шлях до ключа.

Корінь без вендорених каталогів позначте, записавши workspace: {}. Список catalog_dirs підтримує конфігурації монорепозиторію, де спільний каталог розташований у сусідній директорії. Компілятор перевіряє кожну директорію по черзі. Прапорець offline: true забороняє будь-який доступ до мережі — компілятор використовує лише локальні шляхи та кеш і зупиняється, якщо сутність не знайдено локально. Налаштування, згруповані в розділи, кожне збирають один аспект. Серед них: регулятори суворості під час збирання та підказки для авторів; сокети прикріплення Wasm на рівні робочого простору (governance, linter, importer, providers, cli), кожен із яких приймає список посилань на плагіни; суворість лінтингу для кожного правила, зокрема перемикачі політик дисципліни публікації; налаштування кешу розбору демона і розмір його пулу воркерів для диспетчеризації запитів; та обмеження розміру сховища скомпільованих модулів, спільного для всієї машини. Ще інші містять типові налаштування підписування й довіри до підписів, а також власну поведінку демона. Кожен ключ верхнього рівня повністю задокументовано в schema/other/aggrega-config.

Налаштовуються три різні кеші, і варто на мить зупинитися, щоб їх розрізнити, бо їхні назви схожі, а області дії — ні. artifact_cache_dir вказує описаний нижче дисковий кеш вмісту для робочого простору. parse_cache обмежує кеш розбору демона в пам’яті, який існує лише доти, доки існує демон. compiled_module_cache обмежує дискове сховище скомпільованого машинного коду плагінів — один із кешів, спільних для всіх робочих просторів на машині, бо скомпільована форма плагіна залежить від плагіна, а не від проєкту, що його використовує:

# .aggrega-config.yaml — most at home in the global config file, since the store is machine-wide
compiled_module_cache:
max_bytes: 53687091200 # Default 50 GiB; 0 disables the cap

Серед кешів, спільних для всіх проєктів на машині, саме він може почати домінувати у використанні дискового кешу, оскільки кожен плагін, який запускає машина, компілюється в нього один раз і зберігається, тож він єдиний має постійне обмеження розміру. Кожен виклик, що відкриває сховище, застосовує обмеження ще до того, як щось компілювати, видаляючи цілі записи, починаючи з найраніше скомпільованих, доки решта не вміститься. (Збирання, запущене з --disable-plugin-cache, натомість компілює в пам’ять, тож воно ані не збільшує сховище, ані не обрізає його.) Видалення запису коштує пізнішої перекомпіляції і нічого більше — саме тому безпечно знижувати обмеження й застосовувати його, поки на тій самій машині виконуються інші збирання. Встановлюйте його вище за те, що компілює одне збирання: оскільки обмеження застосовується перед компіляцією, обмеження, нижче за робочий набір одного збирання, змушує кожне збирання відкидати й перекомпільовувати ті самі модулі, і з тієї ж причини сховище між збираннями може перевищувати обмеження й знову обрізається на початку наступного. aggrega cache status повідомляє розмір сховища, а aggrega cache evict --max-size обрізає його на вимогу до обмеження, заданого в командному рядку.

Корінь artifact_cache_dir містить три паралельні піддерева, які один виклик aggrega pull заповнює однаково, по одному на кожен клас закріплених залежностей: <artifact_cache_dir>/entities/<encoded-kind>/<encoded-reference>/<encoded-version>/ для сутностей каталогу (Components, Features, Recipes, FeatureRecipes, Aggregates, бібліотеки та Plugins разом із виконуваними файлами, які вони публікують), де вид — це той, під яким сутність публікується, тож дві сутності різних видів, що мають спільні посилання й версію, — сутність Component і сутність Recipe з однаковою назвою — займають два слоти; <artifact_cache_dir>/source-artifacts/<kind>/<host>/<path>/<version>/<digest-prefix>/ для вихідних артефактів, завантажених із полів spec.source сутностей Recipe / FeatureRecipe (чарти Helm, фрагменти compose); і <artifact_cache_dir>/inputs/sha256/<hex-digest> для зовнішніх вхідних даних — віддалених документів, які provider запитує в хоста під час рендерингу, як-от $ref у values.schema.json чарту, що вказує на URL. Кожен слот кешу вихідного артефакту містить авторитетний архів .tgz, похідну директорію extracted/, що відтворюється під час кожного читання збиранням, і файл metadata.yaml, який фіксує ідентичність артефакту {kind, url, version, digest, mediatype, pulled_at}. Кожен слот кешу сутності містить опублікований артефакт у тому вигляді, в якому його отримано, і маніфест OCI, щодо якого його перевіряють. Слот кожного виду, документ якого може називати файл поруч із собою, — Recipe, FeatureRecipe, Component, Feature — також містить похідну директорію extracted/ з файлами, які несе цей артефакт, у директорії, названій за дайджестом вмісту артефакту: документ і файли, оголошені сутністю, якщо її опубліковано як архів, і лише документ, якщо її опубліковано як її документ (§6). Директорія сутності розгортається там із перевіреного артефакту під час кожного читання так само, як файли вихідного артефакту: кожен файл перевіряється щодо артефакту, файл, змінений або доданий у цій директорії вручну, відкидається, а не читається, ніщо інше під extracted/ не читається, а артефакт, що не пройшов перевірки, відхиляється ще до того, як щось буде розгорнуто. Читання перезаписує лише те, що відрізняється від артефакту, тож збирання, які одночасно читають один кеш, — запити, що їх aggrega serve обробляє паралельно, або дві команди над одним робочим простором, — кожне знаходять передані їм файли цілими. 12-символьний сегмент <digest-prefix> розносить у різні слоти той самий {kind, url, version}, повторно позначений тегом з різними upstream-дайджестами. Зовнішнім вхідним даним такий слот не потрібен: вони зберігаються як один файл, названий за дайджестом вмісту, до якого їх закріплює lock-файл, тож те, що читає пізніше збирання, адресується закріпленням, а не URL, з якого надійшли байти, — і саме це дає змогу цьому збиранню видавати вхідні дані, коли мережу заборонено.

Поруч із цими трьома можуть з’явитися ще три директорії, і жодна з них не містить вмісту закріплених залежностей: index/ містить знімки для пошуку по кожному реєстру, які записує aggrega registry update (§8), signatures/ кешує кожен перевірений пакет підпису під його власним дайджестом, тож пізніше читання повторно перевіряє кешований blob щодо дайджесту, під яким його зафіксовано, замість того щоб знову завантажувати пакет, а catalog-snapshots/ зберігає кожен опублікований знімок каталогу, який прочитав імпорт (§8), — архів і його маніфест у слоті, названому за дайджестом маніфесту, причому дерево каталогу розгортається з архіву під час кожного читання, а також файл current, що вказує знімок, який читає робочий простір, коли ніщо не вказує інший.

Пакета документації серед них немає. Його байти залежать лише від реєстру, у якому його опубліковано, і від версії, під якою його опубліковано, тому він зберігається один раз на машину, поруч зі сховищем скомпільованих модулів під тим самим коренем кешу користувача, у docs-bundles/<encoded-reference>/<encoded-version>/ під цим коренем: пакет, маніфест, щодо якого його перевіряють, і підписи, перевірені під час його завантажень. artifact_cache_dir до нього не сягає. Перш ніж з нього буде прочитано сторінку, ці підписи перевіряються знову за власною перевіркою підписів робочого простору, що читає, для реєстру пакета, тож копія, яку впустили м’якші налаштування одного робочого простору, не видається робочому простору, перевірка якого її відхиляє, — див. aggrega-explain і aggrega-cache.

artifact_cache_dir записується відносно кореня робочого простору й означає ту саму директорію незалежно від того, з якої директорії викликано команду чи які директорії каталогу скануються. Абсолютне значення відхиляється під час завантаження конфігурації з діагностикою, що називає поле: кожен читач цього налаштування розв’язує його відносно кореня робочого простору, тож абсолютний шлях називав би місце, до якого жоден із них не сягає, а збій інакше був би непомітним — кеш, який записує pull, непомітно перестав би бути кешем, який читає збирання. Кеш може розташовуватися всередині директорії каталогу, і в типовому розміщенні так і є, оскільки директорією каталогу зазвичай є сам корінь робочого простору. Чого він не повинен — це бути директорією каталогу: сканування каталогу оминає кеш, тож директорія кешу, яка водночас є директорією каталогу, вилучає весь вміст цієї директорії з кожного сканування. artifact_cache_dir: . називає корінь робочого простору, що в типовому розміщенні є саме цим випадком, і відхиляється під час завантаження конфігурації з діагностикою, що називає поле, — як і будь-яке інше написання, що зводиться до кореня робочого простору. Ці дві форми разом з абсолютним шляхом, згаданим вище, — це ті, які перевірка конфігурації здатна розпізнати самостійно. Значення, що називає якусь іншу директорію каталогу, — sub у робочому просторі, чий catalog_dirs містить sub, — завантажується без заперечень, і єдиний симптом — сутності в ній перестають знаходитися. Тому тримати кеш поза кожною директорією, переліченою в workspace.catalog_dirs, — це частина написання конфігурації, а не те, що вона перевіряє за вас.

Оминання кешу — це те, що не дає прочитати артефакт розв’язання так, ніби його написав автор. Слот кешу містить байти, які туди помістило завантаження з реєстру, збережені під координатою, з якої їх завантажено, і засвідчені дайджестом lock-файлу; сканування, яке підхопило б один із них як написаний автором вміст каталогу, брало б байти, яких ніщо не перевірило, зі шляху, який автор не може редагувати. Один наслідок варто сказати прямо: якщо кеш містить сутність, яку не закріплює жоден lock-файл, — залишену перерваним pull, скопійовану вручну або покинуту, коли сутність Release перестала на неї посилатися, — ця сутність невидима для сканування каталогу, і збирання чи валідація, що від неї залежить, зупиняється з повідомленням, що сутність не знайдено. Рішення — знову виконати pull для сутності Release, щоб сутність було розв’язано через lock-файл і зафіксовано її дайджест; зупинка називає сутність, щоб можна було визначити відсутнє закріплення. Альтернатива — все одно її розв’язати — це саме те неперевірене читання, якому покликане запобігати оминання кешу.

Lockfile існує окремо для кожної сутності Release: розв’язання release.yaml записує поруч із ним release.lock (основа імені файлу сутності Release плюс .lock). aggrega pull розв’язує залежності й записує lockfile; aggrega build читає його і використовує закріплені версії незалежно від стану реєстру на момент збирання. Робочі простори комітять lockfile, коли важлива відтворюваність збирання на різних машинах; після того як у робочому просторі змінюється сутність, бібліотека, плагін або сама сутність Release, aggrega pull --release <release> оновлює його, повторно розв’язуючи те, що змінилося, і зберігаючи всі інші закріплення, а aggrega pull --upgrade --release <release> — це спосіб прийняти новішу версію, яку тепер пропонує реєстр. Lockfile записує кожну розв’язану сутність з її видом, її URI у тому вигляді, як його написано, розв’язаною версією, дайджестом вмісту та місцями, що на неї посилаються. Вид і URI разом ідентифікують запис, тож сутність Release, чиї сутності Aggregate і Manifest мають спільну назву, записує по одному запису для кожної з них, а редагування будь-якої з них зупиняє наступне збирання, доки pull його не запише:

# release.lock
entities:
- kind: component
uri: core/datastore/mariadb:1.0.0
resolved_version: 1.0.0
digest: sha256:5deeedb9acc1be00d4e0f98e55e01d301a0bcc01d702c015a9d9628ff573650a
referenced_from:
- aggregate.spec.components.db.type
- kind: recipe
uri: mariadb-bitnami:1.0.0
resolved_version: 1.0.0
digest: sha256:215b54e2da1ce512fcdccff87f6f71daac707bc77e4214b60b946b27a24e483a
referenced_from:
- manifest.spec.mappings.components.type.core/datastore/mariadb:1.0.0
generated_at: "2026-06-11T16:48:15Z"
mapping_libraries: []
plugins: []
release: release.yaml
schema_libraries: []
source_artifacts: []
version: 1

Кожен закріплений запис містить вид + URI + розв’язану версію + дайджест, адресований за вмістом. Дайджест перевіряється під час кожного отримання; байти, що не відповідають закріпленому дайджесту, зупиняють збирання з помилкою цілісності. Дайджест сутності обчислюється з того, що несе її публікація, — її документа та кожного файлу, який вона оголошує поруч із ним, кожного за шляхом і байтами, — а не з байтів, у яких вона передається, тож та сама сутність записує той самий дайджест, чи її прочитано з каталогу каталогу, чи отримано з реєстру, хоч би як було стиснуто її архів і хоч би які біти дозволів, зокрема біт виконання, checkout надав її файлам. Отримання спершу перевіряється щодо дайджесту, який сам реєстр обчислює з опублікованих байтів, через маніфест, дайджест якого запис, розв’язаний через реєстр, записує поруч із власним.

5. Трирівнева модель розв’язання сутностей

Компілятор розв’язує кожне посилання на сутність, яке трапляється під час компіляції, за допомогою суворого каскадного пошуку. Три рівні — локальний шлях, робочий простір і кеш, реєстр — відповідають трьом робочим процесам створення, що співіснують у здоровому проєкті Aggrega: сутності Release, яка вказує на файли поруч із собою, команді, що використовує закомічений каталог плюс раніше отриманий кеш, і pull, який звертається до реєстру по ще не отриманий артефакт. Рівень робочого простору й кешу та рівень реєстру того самого каскаду обчислюють поля type у сутностях Aggregates, значення URI у зіставленнях сутності Manifest, оголошення implements у сутностях Recipes і FeatureRecipes та посилання plugin у конвеєрах сутностей Recipe і FeatureRecipe; рівня локального шляху досягають лише файли, на які вказують сутність Release та її Manifest.

Локальний шлях. Посилання aggregate, manifest або extends сутності Release чи extends сутності Manifest, що починається з ./ або ../ (префікс відносного шляху POSIX), читається безпосередньо з диска відносно сутності Release. Жодного пошуку в каталозі, жодного виклику реєстру. Явний префікс на синтаксичному рівні відрізняє намір використати локальний шлях від пошуку за іменем: сутність Release, яка пише aggregate: ./aggregate.yaml, вказує на файл; aggregate: checkout вказує на сутність Aggregate за її metadata.name. Резолвер ніколи не аналізує вміст рядка, щоб вирішити, який рівень застосувати, — розрізнювачем є префікс. Усі інші посилання, зокрема type сутності Component у сутності Aggregate, розв’язуються через рівень робочого простору й кешу та рівень реєстру: локально створену сутність розміщують у catalog/ у корені робочого простору або в каталозі, переліченому в workspace.catalog_dirs, а type, записаний як відносний шлях до файлу, зупиняє збирання як сутність, якої немає в жодному каталозі.

Робочий простір і кеш. Посилання без явного префікса локального шляху спершу шукається в каталогах, перелічених у workspace.catalog_dirs (локальних для проєкту деревах каталогу, написаних у репозиторії або скопійованих до нього, — форму конфігурації див. у §4), — або, для сутності Release, якій конфігурація надає власні каталоги в workspace.releases, у каталогах цієї сутності Release, — потім у каталозі catalog/ кореня робочого простору, а далі в artifact_cache_dir (ігнорованому git розташуванні .aggrega/cache/, що містить артефакти, отримані під час попередніх розв’язань через реєстр, і чиї піддерева описує §4). Влучання в кеш під час другого й наступних збирань — це те, що залишає внутрішній цикл без звернень до мережі, навіть коли проєкт залежить від віддаленого вмісту каталогу.

Реєстр. Якщо рівень робочого простору й кешу не повертає збігу, aggrega pull — або збирання, запущене з --auto-pull чи з налаштуванням робочого простору auto_pull, — виконує pull OCI на основі ORAS із default_registry (за замовчуванням hub.aggrega.ai), розпаковує артефакт у кеш для наступних збирань і продовжує з розв’язаною сутністю. Збирання без жодного з них читає лише те, що закріплює його lock-файл, і за відсутності lock-файлу зупиняється, вказуючи на aggrega pull. Форма URI OCI, яку будує виклик реєстру, відповідає таксономії типів сутностей, описаній у §6 (Пакування артефактів & таксономія OCI). Скорочені URI у сутностях Aggregates і Manifests розгортаються до повної форми OCI перед викликом реєстру; правила виведення, що керують цим розгортанням, наведено в довіднику сутності Manifest Контекстно-залежні скорочені URI та в §8 нижче.

Пріоритет і затінення. Пріоритет розв’язання суворо такий: локальний шлях > робочий простір і кеш > реєстр. Сутність у локальному каталозі каталогу з тією самою ідентичністю, що й сутність у реєстрі, затінює сутність реєстру — це навмисно й дає авторам каталогів змогу експериментувати зі змінами перед публікацією. Те саме затінення діє між catalog_dirs і кешем: сутність, присутня в каталозі каталогу робочого простору, має перевагу над кешованою копією, тож локальні зміни в скопійованому до репозиторію каталозі набувають чинності одразу.

У межах рівня робочого простору й кешу catalog_dirs — це впорядкований стек пріоритетів, у якому перемагає перший. Коли та сама ідентичність сутності трапляється в кількох перелічених каталогах каталогу, перемагає каталог, перелічений раніше, а пізніша поява затінюється — перевизначається, не завантажується і не є помилкою. Це дає проєкту змогу поставити власний каталог каталогу перед спільним або скопійованим до репозиторію і перевизначити вибрані сутності за ідентичністю, тоді як решта переходить до спільного каталогу. Перевизначення можна спостерігати: подробиці розв’язання повідомляють, який каталог переміг, а який було затінено, тож нашарування ніколи не відбувається непомітно. Затінення застосовується лише між каталогами; два файли в одному каталозі, що претендують на ту саму ідентичність, є помилкою автора і зупиняють завантаження. Каталог, названий більше одного разу, — прапорцем --catalog і в catalog_dirs або двічі у списку, — є одним записом стека, у якому пошук відбувається один раз на місці, де його названо вперше, тож затінення завжди стосується двох різних файлів і ніколи — каталогу, прочитаного проти самого себе. Оскільки пріоритет відповідає контрольованому автором порядку каталогів, розв’язана множина детермінована.

Каталог catalog/ кореня робочого простору приєднується до цього стека в його кінці, а не на початку, і лише тоді, коли каталог існує, — тож усе, що перелічує проєкт, перемагає його в разі колізії, а перелічення одного не пов’язаного каталогу ніколи непомітно не припиняє його читання. Його пропускають, коли перелічений запис уже досягає його, оскільки обхід переліченого каталогу рекурсивний, а стек, що називає корінь робочого простору, вже його прочитав. Пропустити catalog_dirs і записати його як порожній список — це різні твердження: якщо пропущено, робочий простір усе одно читає catalog/; якщо записано як [], він не читає жодного локального каталогу, і саме так робочий простір оголошує, що не має його.

Збирання без доступу до мережі. Встановлення offline: true (§4) повністю пропускає рівень реєстру. Посилання, яке не вдалося розв’язати на рівні локального шляху або на рівні робочого простору й кешу, спричиняє помилку відсутньої сутності замість непомітної спроби мережевого виклику, що дає конвеєрам CI, які за законом не можуть звертатися до мережі, детермінований контракт швидкої відмови.

Де діє каскад. Каскад завантажує сутність у пам’ять; подальші механізми розв’язання, побудовані поверх нього, — дворівневий пошук type проти name у сутності Manifest, зіставлення версій implements у трьох формах (точне / діапазон, сумісний за мажорною версією / без версії) у vocabulary/inheritance-and-interface і вибір сутності Recipe для кожної осі за провайдером та екземпляром компонента, — працюють із сутностями, які резолвер уже отримав через цей каскад.

6. Пакування артефактів & таксономія OCI (можливість як провідний сегмент)

Aggrega працює з логікою інфраструктури так само, як Docker працює з образами контейнерів, використовуючи стандарти Open Container Initiative (OCI) через ORAS (OCI Registry As Storage). Користувачі можуть розміщувати свій каталог Aggrega в будь-якому стандартному реєстрі (GHCR, AWS ECR, Aggrega Hub).

Оскільки сутності Recipes суворо відповідають 1:1 одній можливості рендерингу — сутність Recipe називає одну можливість у spec.capability і не може націлюватися на дві, — найчистіший спосіб організувати їх у реєстрі OCI — розмістити можливість у провідному сегменті репозиторію.

Таксономія OCI охоплює всі типи сутностей. Ім’я репозиторію — це сегмент виду — kind сутності в нижньому регістрі, — за яким іде ідентичність сутності, повністю в нижньому регістрі:

  • hub.aggrega.ai/component/core/datastore/mariadb:1.0.0 — Component, видавець core, категорія datastore
  • hub.aggrega.ai/component/core/compute/api-server:1.0.0 — Component, видавець core, категорія compute
  • hub.aggrega.ai/feature/core/data-masking:1.0.0 — Feature, видавець core (пласко, без категорій)
  • hub.aggrega.ai/aggregate/core/db-module:1.0.0 — Повторно використовуваний модуль Aggregate
  • hub.aggrega.ai/recipe/helm/mariadb:1.0.0 — Recipe, можливість helm
  • hub.aggrega.ai/recipe/helm-chart/mariadb:1.0.0 — Recipe, можливість helm-chart
  • hub.aggrega.ai/recipe/compose/mariadb:1.0.0 — Recipe, можливість compose
  • hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0 — FeatureRecipe, можливість helm
  • hub.aggrega.ai/schemalibrary/aidatastores:1.0.0 — SchemaLibrary, спільні визначення схем; metadata.name у PascalCase AIDatastores переводиться в нижній регістр в імені репозиторію
  • hub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0 — MappingLibrary, спільні фрагменти зіставлень на шаблонах Go
  • hub.aggrega.ai/plugin/provider/helm:0.5.0 — Plugin, тип сокета provider (сегмент metadata.pluginType)

Види, які можна публікувати, охоплюють види створення каталогу разом із сутністю Aggregate — повторно використовуваним модулем (його можна публікувати незалежно від того, чи на нього згодом посилатимуться як на spec.aggregate верхнього рівня сутності Release, чи вкладуть у блок aggregates: іншої сутності Aggregate), — і сутністю Plugin, адресованим за вмістом посиланням на артефакт WebAssembly, який компілятор маршрутизує, а середовище виконання виконує. Plugin — це структурний публікований артефакт, а не вид створення каталогу. Release і Manifest — це вхідні дані з боку розгортання, які зберігаються в системі контролю версій і ніколи не надсилаються через push — aggrega push їх відхиляє, — тому вони не мають mediatype публікації. aggrega push --list-kinds повідомляє множину, яку публікує встановлений двійковий файл, по одному виду в рядку. Кожен публікований вид має власний mediatype OCI у кожній із двох форм, яких набуває публікація:

Вид сутностіПублікується як її документПублікується з файлами, які вона оголошує
Componentapplication/vnd.aggrega.component.v1beta1+yamlapplication/vnd.aggrega.component.v1beta1+tar+gz
Featureapplication/vnd.aggrega.feature.v1beta1+yamlapplication/vnd.aggrega.feature.v1beta1+tar+gz
Recipeapplication/vnd.aggrega.recipe.v1beta1+yamlapplication/vnd.aggrega.recipe.v1beta1+tar+gz
FeatureRecipeapplication/vnd.aggrega.featurerecipe.v1beta1+yamlapplication/vnd.aggrega.featurerecipe.v1beta1+tar+gz
Aggregateapplication/vnd.aggrega.aggregate.v1beta1+yaml— не оголошує жодного файлу
SchemaLibraryapplication/vnd.aggrega.schemalibrary.v1beta1+yaml— не оголошує жодного файлу
MappingLibraryapplication/vnd.aggrega.mappinglibrary.v1beta1+yaml— не оголошує жодного файлу
WorkloadLibraryapplication/vnd.aggrega.workloadlibrary.v1beta1+yaml— не оголошує жодного файлу
ArtifactLibraryapplication/vnd.aggrega.artifactlibrary.v1beta1+yaml— не оголошує жодного файлу
Pluginapplication/vnd.aggrega.wasmplugin.v1beta1+yaml— публікується через власний маніфест

Те, що несе публікація, а отже і її форма, випливає з того, що оголошує сутність, — а не з її виду і не з того, що лежить у її каталозі. Публікація несе документ сутності та файли, які сама сутність називає поруч із ним: локальне source: сутності Recipe або FeatureRecipe — каталог подорожує з кожним файлом у ньому, який залишають правила ігнорування, записані в його entity.lock, — кожен файл, який її записи valuesMapping:, workload: і artifacts: імпортують за допомогою $import:, та entity.lock, записаний її кроком закріплення; а також кожен файл схеми, який імпортує сутність Component або Feature, зокрема кожен файл ланцюжка імпорту. Ніщо інше з каталогу не подорожує: нотатка, README або результат збирання поруч із сутністю не є частиною того, що вона публікує, хоч би як вони називалися, і не змінюють форму, у якій вона публікується. Сутність, яка нічого не називає, публікується як її написаний документ, байт у байт, під mediatype +yaml її виду; сутність, яка називає файл, публікується як стиснутий gzip архів tar документа та цих файлів, під mediatype +tar+gz її виду. Сутності Aggregate, Plugin і види бібліотек не оголошують жодного файлу поруч зі своїм документом, тому завжди публікуються як документ — зокрема й сутність Aggregate в корені робочого простору, оскільки кожен шлях, який вона оголошує, називає іншу сутність, а не файл, який вона несе; так само й сутність Recipe, увесь вміст якої вбудований. Віддалене джерело — це посилання, а не файл, тож воно нічого не несе, хоча entity.lock, що записує його закріплення, робить таку сутність Recipe архівом. Сегмент версії кожного mediatype спільний для всіх видів, які можна публікувати, а сегмент кодування вказує, яку з двох форм мають байти. Подальші інструменти виконують диспетчеризацію за повним рядком mediatype — видом, версією та кодуванням разом.

Одна написана форма не називає жодного каталогу, який могла б знати публікація: локальне джерело, записане як шаблон. Його каталог вибирається лише тоді, коли сутність Release заповнює шаблон, тому сутність несе кожен файл у власному каталозі, який залишають її записані правила ігнорування, щоб будь-який каталог, який вибере сутність Release, уже подорожував; aggrega push повідомляє про це, коли так стається. Нести лише назване має свою ціну, і вона лягає на споживача: файл, який сутність читає і ніде не називає, не подорожує, і саме збирання споживача — а не push видавця — стикається з його відсутністю, називаючи відсутній шлях у своєму слоті кешу.

Які файли вихідного каталогу належать сутності, вирішується один раз, коли сутність закріплюють, і записується. Плагін, що обслуговує можливість сутності в робочому просторі автора, оголошує те, що його екосистема ніколи не постачає, — каталоги контролю версій плагіна для чартів і врахування ним .helmignore чарту, .terraform/ плагіна для модулів, — а останнє слово має .aggregaignore автора поруч із сутністю. Крок закріплення записує цей плагін і складені правила в entity.lock, і публікація, кожне порівняння закріплень джерела, рядок сутності в lockfile та рендеринг застосовують записані правила замість того, щоб знову запитувати плагін, тож опубліковане — це те, що рендерить власне збирання автора, а змінене прив’язування чи новіший двійковий файл не змінює жодного дайджесту, доки сутність не закріплять знову. Компілятор не має думки щодо жодної екосистеми: правила походять від плагіна й автора, а компілятор лише зіставляє їх. Символьне посилання серед файлів сутності відхиляється, а не відстежується, оскільки те, на що воно вказує, подорожувало б під його іменем. aggrega pin повністю пояснює ці правила.

Ім’я сутності Recipe не містить ні префікса домену, ні можливості: каталог типу сутності та сегмент можливості вже вказують і те, і інше.

Домовленість щодо іменування: сутності Components (домен 2) використовують {publisher}/{category}/{name}, а сутності Features (домен 2) і багаторазові сутності Aggregates (домен 1) використовують {publisher}/{name}, де сегмент publisher називає постачальника/автора (core = офіційна стандартна бібліотека, acme = підприємство). Сутності домену 3 (Recipe, FeatureRecipe) використовують {capability}/{name}, де можливість — це провайдер, якого сутність оголошує в spec.capability; посилання може також називати сутність без префікса, лише листком. Імена сутностей Recipe також НЕ містять можливості, оскільки вона вже є провідним сегментом канонічного URI.

Сутності Recipes використовують ключове слово implements, щоб прив’язатися до інтерфейсу, який вони реалізують. Поле implements підтримує точне зіставлення, зіставлення за діапазоном, сумісним за мажорною версією, або без версії (зіставлення версій implements див. у vocabulary/inheritance-and-interface). Сутність Recipe у записі зіставлення сутності Manifest має реалізовувати тип, для якого її зіставлено, або базу, яку цей тип extends: ключ запису і тип кожного екземпляра компонента, якого ключ досягає у версії, яку він не називає, — у тій версії, у якій збирання компілює цей екземпляр, — тож ключ не може спрямувати екземпляр до сутності Recipe, написаної для іншої версії його типу.

Коли інженер Ops запускає aggrega push, CLI публікує сутність у цій формі, незмінно під її версією. Споживач отримує її через трирівневу модель розв’язання, локально кешує в .aggrega/cache/ і розкладає те, що вона несе, у слоті кешу сутності (§4) — файли архіву або лише документ.

Отримана сутність читає файли, які вона несе, точно так само, як читає їх поруч із собою в каталозі. Сутність читається зі свого місця в цьому розкладеному дереві, тож відносне source: або $import:, яке вона оголошує, — записане явно або створене шаблоном, — розв’язується всередині опублікованого, а шлях, що виходить за межі власного каталогу сутності, там відхиляється так само, як і в каталозі. Ніщо поза деревом не читається замість нього: ні каталог, з якого запускається збирання, ні файл, підкладений у слот кешу. Сутність Component або Feature, схема якої імпортується з файлу, несе цей файл, тож отримана копія завантажує опублікований контракт і перевіряє написані відповідно до нього значення точно так само, як копія, прочитана з каталогу.

Читання сутності назад із пакета — зворотний крок, і він ідентифікує сутність за тим, чим документ є, а не за тим, як він називається: це документ на верхньому рівні пакета, kind: якого є видом сутності, що можна публікувати. Ім’я файлу сутності — це домовленість каталогу, а не контракт, тож recipe.yaml — це те, що записує каталог стандартної бібліотеки, а не те, чого вимагає формат, і файл, що лежить поруч із сутністю, — шаблон чарту, фрагмент compose, — не плутається з нею. Правило не може бути зворотним, прив’язаним до виду, який шукає споживач: вид читається із сутності, яка лежить усередині пакета, тож у момент, коли пакет треба відкрити, немає виду, до якого можна прив’язатися. Сторона читання зупиняється, а не робить вибір, коли верхній рівень пакета містить два документи сутностей — пакет, який створює інший клієнт, пакуючи цілий каталог із двома сутностями, що потім лежав би під кожною з їхніх опублікованих координат як один артефакт. Публікація цього продукту не може його створити, оскільки кожна сутність несе лише те, що оголошує, а крім того, сторона публікації відхиляє такий каталог: кожен вид має власний каталог, окрім Aggregate, Release і Manifest, і aggrega pin та aggrega push відхиляють сутність будь-якого іншого виду, поруч із якою лежить інша сутність, тоді як завантаження каталогу, lint і збирання каталог не чіпають. Те, як називається каталог, не оцінюється на жодній стороні: структура <name>/<version>/ — це домовленість каталогу стандартної бібліотеки.

Опублікована сутність читається через той самий крок. Координата несе рівно одну копію своєї сутності у формі, яку їй надали її оголошення, і людина переглядає її за допомогою aggrega inspect oci://<registry>/<repository>:<tag>, а не через читабельну копію, опубліковану поруч, — тож немає другої копії, яка могла б розійтися з тією, яку розв’язує збирання. Команда розпаковує архів за наведеним вище правилом, читає сутність Plugin з її маніфесту, а не з опублікованого разом із нею виконуваного файлу, і відображає результат так, як відображається файл цього виду; див. Читання опублікованої сутності.

Анотації маніфесту для пошуку. Кожна публікація ставить на маніфест OCI артефакту невеликий набір анотацій для пошуку, щоб індекс реєстру або браузер каталогу могли фільтрувати артефакти за метаданими каталогу, не отримуючи й не розбираючи тіло кожної сутності. Кожна сутність несе свій зрозумілий людині опис (стандартна анотація опису OCI), а також категорію та вид у каталозі. Сутність Plugin додатково несе свій тип сокета та можливості, які вона обслуговує. Саме ці анотації aggrega registry update зчитує в локальний індекс для пошуку (§8).

Кожен опублікований файл має ім’я. Кожен файл, який несе публікація, називається в маніфесті стандартною анотацією org.opencontainers.image.title — це ім’я, під яким універсальний клієнт OCI записує цей файл, коли витягує артефакт у каталог. Ім’я вказує, що це за файл, а його розширення відповідає типу медіа файлу:

Що публікуєтьсяФайл, який записує універсальний клієнт OCI
сутність, опублікована як її документentity.yaml
сутність, опублікована з файлами, які вона оголошуєentity.tar.gz
сутність Pluginentity.yaml, сутність, поруч із entity.wasm, її виконуваним файлом
підпис, приєднаний до артефактуsignature.json
позначка застарілості, приєднана до артефактуdeprecation.json
артефакт даних, опублікований за допомогою aggrega push-artifactім’я, задане через --name

Отже, oras pull hub.aggrega.ai/component/core/compute/server:1.0.0 -o ./server залишає опубліковану сутність у ./server/entity.yaml, байт у байт такою, якою її опублікували. oras пропускає дескриптор без імені й однаково повідомляє про успіх, тому кожен дескриптор, який пакує публікація, має ім’я. Ім’я виводиться лише з типу медіа, ніколи з імені опублікованого файлу, тож ті самі байти, опубліковані з файлу з іншим іменем, дають той самий маніфест. Сутність, опублікована зі своїми файлами, надходить як її пакет: entity.tar.gz називає пакет, а сутність усередині нього знаходиться за наведеним вище правилом, а не за будь-яким іменем файлу. Власне розв’язання Aggrega ніколи не читає ці імена — воно вибирає кожен файл за типом медіа й довіряє йому за дайджестом, — тож вони існують для всіх інших клієнтів.

7. Архітектура Recipe: вказівники та маппери

Повний опис створення сутності Recipe див. у entities/recipe — source: (вказівник), valuesMapping: (маппер із трьома режимами створення: вбудований блоковий скаляр, файловий $import:, бібліотечний $import: до запису MappingLibrary), схеми джерел на основі Wasm, нативна підтримка IaC і робочі приклади.

8. Реєстр за замовчуванням і контекстно-залежні скорочені URI

Щоб уникнути роздування YAML, компілятор розв’язує скорочені URI контекстно-залежно, відносно позиції у схемі, де вони трапляються. Реєстр за замовчуванням налаштовується в .aggrega-config.yaml (за замовчуванням — hub.aggrega.ai).

Хост реєстру має одне прочитання. Кожен registries[].host записується як сам хост — ім’я хоста в нижньому регістрі, що містить крапку, localhost, одне ім’я з портом, адреса IPv4 або адреса IPv6 у квадратних дужках, кожен з необов’язковим :port, і без схеми, шляху, облікових даних чи великих літер, — бо саме за таким написанням шукається кожна політика довіри окремого реєстру, а вбудована вимога підпису офіційного хабу прив’язана до hub.aggrega.ai. default_registry називає хост так само і може продовжувати його шляхом репозиторію, як-от ghcr.io/acme: тоді все, що публікується через реєстр за замовчуванням, потрапляє під цей шлях, і кожне коротке посилання розв’язується під ним, тоді як довіра й надалі визначається лише хостом. Натомість default_registry можна записати як name: запису registries, і тоді він означає хост цього запису. Ім’я читається один раз, коли розв’язується конфігурація, відносно записів, чинних після всіх файлів конфігурації та середовища, тож кожен, хто читає значення за замовчуванням, — публікація, прив’язка розташування, перевірка підпису та кожен пошук довіри — читає хост цього одного запису, і жоден із них не звертається до хоста, написаного як це ім’я; ім’я, за яким іде шлях, відхиляється, оскільки ім’я позначає запис, а не розташування. Ім’я зіставляється раніше за написання хоста, а ім’я, яке мають два записи, відхиляється як неоднозначне. Те саме прочитання визначає три речі, які pull робить із хостом: розташування реєстру, до якого прив’язується ідентичність каталогу без хоста, чи називає отриманий артефакт реєстр, підпис якого взагалі перевіряється, і з якою політикою довіри виконується ця перевірка. Написання, яке могло б досягти реєстру, оминувши його політику, — великі літери, явний стандартний порт HTTPS, схема, облікові дані, шлях у хості запису registries, — відхиляється там, де його налаштовано, з указанням написання, яке слід використати; так само відхиляється одне ім’я без порту, що не називає жодного запису, бо це форма першого сегмента ідентичності каталогу, а не хоста. Відхилення діє на кожному рівні, що може задати значення: у файлі конфігурації, де схема задає ту саму форму як шаблон для кожного registries[].host; у змінній середовища AGGREGA_DEFAULT_REGISTRY; і в командному рядку. Тож кожен хост, який може назвати конфігурація, — це хост, чиї артефакти перевіряються за написаною для нього політикою. Хост оцінюється лише за написанням; чи розв’язується ім’я і чи відповідає там реєстр — це стан під час виконання, який компілятор ніколи не отримує. Конфігурація докладно описує допустимі форми з прикладами.

Скорочені URI розв’язуються контекстно-залежно відносно сутності Manifest; конкретні правила виведення див. у ../language-reference/entities/manifest.md, розділ «Контекстно-залежні скорочені URI».

Керування реєстрами

aggrega registry керує реєстрами, відомими робочому простору, та їхньою політикою довіри до підписів. Ідентичність реєстру — його хост; підкоманди мають спільну модель адресації:

  • aggrega registry add <host> реєструє реєстр і закріплює його політику довіри, отримуючи оголошену реєстром політику під час першого звернення, якщо прапорці довіри не задають її вручну. Необов’язковий --name <alias> додає зручний псевдонім до того самого запису, прив’язаного до хоста, — ідентичністю лишається хост, а псевдонім розв’язується в нього скрізь, де називають реєстр. Псевдонім унікальний серед усіх реєстрів.
  • aggrega registry list виводить кожен налаштований реєстр — хост, псевдонім, коротке зведення стану довіри та позначку на реєстрі за замовчуванням — у порядку зростання хостів. Команда читає розв’язану конфігурацію і не звертається до мережі.
  • aggrega registry remove <name|host> видаляє запис політики довіри реєстру, адресований за хостом або псевдонімом. Видаляється лише політика довіри: вказівник default_registry лишається незмінним, а можливість публікувати на цей хост не зачіпається, тож хост повертається до довіри за замовчуванням, а не стає недосяжним. default_registry, записаний як ім’я видаленого запису, після цього нічого не називає і відхиляється, доки його не перепишуть.
  • aggrega registry update оновлює локальний індекс для пошуку, описаний нижче.

Скрізь, де називають реєстр, — в аргументі підкоманди registry чи в прапорці --registry команд aggrega push і aggrega push-artifact, — той самий розв’язувач інтерпретує токен: налаштований псевдонім розв’язується у свій хост, а будь-який інший токен читається як хост, який він називає, з відкиданням схеми, шляху й облікових даних посилання. Там, де цей хост стає тим, щодо чого ухвалюється рішення про підпис, — місцем призначення aggrega push чи aggrega push-artifact або ключем, під яким aggrega registry add записує запис, — до нього застосовується єдине прочитання, описане вище, і його відхиляють з указанням написання, яке слід використати, якщо його записано інакше. Незареєстрований хост, записаний так, є легітимним місцем призначення і приймається.

Локальний індекс для пошуку

aggrega registry update [<name|host>] будує локальний індекс для пошуку за реєстрами, відомими робочому простору. Команда обходить репозиторії кожного налаштованого реєстру, вибирає найвищу випущену версію кожного, читає анотації маніфесту цієї версії для пошуку (§6) і записує індекс для кожного реєстру в кеш артефактів. Без аргументу індексуються всі налаштовані реєстри; з одним аргументом реєстру (хостом або псевдонімом) індексується лише він.

Індекс дотримується моделі явного оновлення, знайомої з менеджерів пакетів: registry update — це команда, що звертається до реєстрів, а подальший aggrega search читає записаний індекс офлайн. Файл записів реєстру детермінований — два оновлення за того самого стану реєстру дають побайтово ідентичний результат, а позначка часу актуальності зберігається в сусідньому файлі, щоб ніколи не змінювати записи. Репозиторій без випущеної версії або такий, що не читається, пропускається, тож один нечитабельний репозиторій ніколи не зриває побудову всього індексу.

Опублікований знімок каталогу

Кожна публікація каталогу стандартної бібліотеки також публікує каталог як ціле: один OCI-артефакт, tar-архів, стиснутий за допомогою gzip, з усіма файлами, які дерево каталогу містить на коміті, опублікованому цією публікацією, за адресою catalog/snapshot у реєстрі, до якого публікується каталог, — hub.aggrega.ai/catalog/snapshot для офіційного хабу. Його надсилають лише після того, як кожна сутність цієї публікації опиниться в реєстрі, тож він не називає жодної сутності, якої реєстр не містить. Його позначають тегом коміту, з якого його зібрано, і тегом latest, і видавець підписує його без ключа, як і кожну сутність публікації, тож ідентичність видавця дає змогу перевірити його згідно з політикою довіри реєстру; latest переходить на знімок лише після того, як його підписано. Архів записується в одному фіксованому розміщенні — записи впорядковано за зростанням їхніх назв, кожен має той самий режим, власника й час зміни, — тож один коміт завжди дає той самий tar-архів.

Його єдиний читач — імпорт, робочий простір якого не вказує жодної папки каталогу: немає ні workspace.catalog_dirs, ні AGGREGA_CATALOG_DIRS, ні директорії catalog/ у корені робочого простору. aggrega import, імпорт у сесії редактора та інструмент імпорту асистента виконують ту саму операцію, тож кожен отримує знімок однаково. Імпорт завантажує його з реєстру робочого простору за замовчуванням через той самий шлюз вихідного трафіку й той самий вхід, що й pull, перевіряє його підпис згідно з політикою довіри цього реєстру, перш ніж щось зберегти, зберігає його в кеші артефактів робочого простору й читає його там як папку каталогу, звіряючи з його дайджестом, — тож імпортерові пропонуються сутності Components каталогу, а --target створює чернетку сутності Manifest із його сутностей Recipes точно тим самим шляхом, яким іде папка каталогу. Запис, який імпорт пише поруч зі своїми чернетками, вказує знімок за дайджестом його маніфесту, тож пізніший імпорт тих самих чернеток читає той самий каталог без жодного запиту, а aggrega import --upgrade завантажує найновіший знімок і відтоді імпортує відносно нього. В офлайн-режимі імпорт, якому довелося б завантажити знімок, зупиняється із зазначенням того, що слід запустити. Робочий простір, який вказує папку каталогу, імпортує відносно неї й не завантажує жодного знімка. Жодна інша команда не читає знімок: pull, збирання та валідація розв’язують кожну сутність через рівні з §5 і закріплюють її в lock-файлі, а чернетки імпорту посилаються на сутності каталогу за назвою, тож їх збирання розв’язує ці сутності так само.

9. Закріплення версій у lockfile і незмінність артефактів

Дисципліна закріплення в lockfile прив’язує кожну залежність до конкретного артефакту з адресацією за вмістом. Під час першого розв’язання lockfile (aggrega pull) резолвер звертається до реєстру, вибирає версію відповідно до обмеження URI в одній із трьох форм (точна / діапазон / без версії) і записує закріплену версію + дайджест у <release-stem>.lock сутності Release. Подальші виклики aggrega build використовують закріплені значення незалежно від мінливості реєстру; нові версії можна публікувати, не впливаючи на наявний lockfile.

Модель закріплення має одне ключове правило: щойно name:version опубліковано в реєстрі і воно розв’язується в дайджест D, ця відповідність є постійною. Повторна публікація того самого name:version з іншим вмістом відхиляється під час push. Сама команда aggrega push забезпечує це під час кожної публікації: вона розв’язує наявний артефакт за name:version у цільовому реєстрі; якщо він існує і дайджест збігається з вмістом, який має бути надіслано, push нічого не вивантажує і додає лише те, чого цій публікації ще бракує, — дату публікації, а також підпис, якщо push підписує; якщо він існує і дайджест відрізняється, push зупиняється з помилкою порушення незмінності, у якій наведено обидва дайджести.

Незмінність важлива з огляду на два наслідки:

  1. Закріплення в lockfile є чесними. Коли lockfile фіксує mariadb:1.0.0 з дайджестом D, збірка, що завантажує за дайджестом, отримує байти D. Без незмінності зміна на боці реєстру могла б підмінити байти D під закріпленням у lockfile, підриваючи стабільність між моментом блокування і моментом збірки. Відтворювані збірки спираються на цю гарантію.
  2. Зміни метаданих після публікації мають чіткий шлях. Позначити опубліковану версію як застарілу, змінити ключі підпису чи доповнити атестації неможливо шляхом зміни опублікованого артефакту (правило це забороняє). Це слід робити, публікуючи нову патч-версію або супровідний артефакт, що окремо фіксує зміну метаданих. Обидва шляхи придатні для аудиту — нова версія чи супровідний артефакт з’являється як окремий запис у реєстрі — і жоден не змінює байтів оригінального артефакту.

Правило незмінності однаково застосовується до кожного артефакту Aggrega, опублікованого через OCI (сутності, SchemaLibrary, MappingLibrary, Wasm-плагіни, на які посилаються Recipe pipeline[].plugin: / FeatureRecipe pipeline[].plugin: / конфігурація робочого простору plugins.{governance,linter,importer}[]:). Усе, що закріплено за name:version разом із дайджестом вмісту в lockfile, підлягає незмінності.

Незмінність є безумовною, і жодна конфігурація її не послаблює. Немає ні прапорця, ні налаштування конфігурації робочого простору, яке дозволяло б перезапис, бо реєстр не надає шляху перезапису, який оператор міг би ввімкнути. Змінений вміст публікується під новою версією, а aggrega lint --pre-publish перевіряє, що підвищення версії відповідає класифікації зміни.

Повторне розв’язання до новішої версії потребує явної дії користувача: aggrega pull --upgrade --release <release> <uri> повторно розв’язує одну залежність, зберігаючи всі інші закріплення, а aggrega pull --upgrade --release <release> повторно розв’язує всі залежності відносно поточного стану реєстру. Залежності у формі діапазону та без версії повторно розв’язуються до найновішої відповідної версії; закріплення в точній формі не змінюються, доки користувач явно не оновить їх до іншої точної версії. Lockfile є джерелом істини для збірок; форма, введена користувачем, виражає обмеження версії на етапі написання.

10. Перевірка форми імен сутностей каталогу

Імена сутностей каталогу відповідають шаблонам для кожного виду сутностей — їх перелічено нижче, а докладно для кожного виду описано в огляді довідника сутностей. Це інша поверхня, ніж імена екземплярів, які розробник пише в сутності Aggregate або Release і які мають один шаблон незалежно від виду; цей шаблон описано в ../language-reference/02-naming-conventions.md «Імена екземплярів». Поле metadata.name, яке оголошує YAML каталогу, не завжди збігається з канонічним URI посилання на сутність: Component і Feature вбудовують сегменти видавця й групування безпосередньо в metadata.name; Recipe і FeatureRecipe оголошують metadata.name лише з кінцевого сегмента, а їхній канонічний двосегментний URI поєднує цей сегмент зі spec.capability, який оголошує сутність; кожен вид бібліотеки оголошує в metadata.name токен у PascalCase.

Форми для кожного виду сутностей:

  • Component — три сегменти в kebab-case {publisher}/{category}/{name}, оголошені в metadata.name. Приклад: core/datastore/postgres.
  • Feature — два сегменти в kebab-case {publisher}/{name}, оголошені в metadata.name. Приклад: core/data-masking.
  • Recipe — один кінцевий сегмент у kebab-case у metadata.name (наприклад, postgres). Канонічний URI посилання {capability}/{name} (згідно з §6 вище) поєднує оголошений у сутності spec.capability з цим сегментом; перший сегмент зіставляється зі spec.capability, а не з розташуванням сутності на диску, тому переміщення recipe.yaml не змінює способу посилання на неї. Каталог стандартної бібліотеки розміщує сутність у <catalog-root>/recipe/<capability>/<name>/<version>/recipe.yaml, щоб дерево відображало координату, але це відображення є домовленістю каталогу, а не джерелом URI. Посилання може також називати рецепт без префікса — лише кінцевим сегментом, без сегмента можливості; на практиці це найпоширеніша форма, і вона розв’язується щоразу, коли це ім’я має лише один рецепт у каталозі. У URI сутності Recipe немає сегмента видавця, а посилання з третім сегментом не відповідає жодному рецепту.
  • FeatureRecipe — один кінцевий сегмент у kebab-case у metadata.name (наприклад, k8s-secret-from-parameter), симетрично з Recipe: канонічний URI {capability}/{name} з оголошеного spec.capability і кінцевого сегмента, кінцевий сегмент без префікса приймається так само, а дерево <catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yaml відображає координату за домовленістю.
  • Види бібліотек — SchemaLibrary, MappingLibrary, WorkloadLibrary і ArtifactLibrary — один токен у PascalCase у metadata.name, що відповідає ^[A-Z][A-Za-z0-9]*$ (наприклад, BaseComponents, AIDatastores, BaseWorkloads). Форма однакова для всіх видів бібліотек, тому переміщення запису між бібліотеками ніколи не означає перейменування за іншою домовленістю. Конверт JSON Schema кожного виду бібліотеки також оголошує цей шаблон, на додачу до перевірки, описаної нижче.

Для Component, Feature, Recipe і FeatureRecipe JSON Schema для metadata.name приймає будь-який непорожній рядок, тож для цих видів форма не є структурною. Кожну задокументовану форму — зокрема для видів бібліотек, конверти яких також оголошують свій шаблон, — перевіряє плагін дисципліни публікації, який містить шаблони як регулярні вирази, єдине джерело істини, спільне з дистрибутивом компілятора. Жодному виду тут не призначено форму, яку плагін потім ігнорує.

Перевірка вмикається за бажанням: її виконує одна команда, і вона запускається лише тоді, коли автор про це просить. Дві команди, від яких її найчастіше очікують, її не виконують:

  • aggrega lint повідомляє про порушення форми імен. Плагін порівнює metadata.name кожної сутності з шаблоном для її виду. Перевірка запускається, коли автор викликає aggrega lint — для однієї сутності, для замикання залежностей сутності Release з --release або для всіх сутностей каталогу, якщо викликати без аргументу, — і той самий набір правил доступний через орієнтовану на редактор поверхню інструментів, яку надає CLI. Знахідки мають рекомендаційний характер: їх повідомляють із рівнем серйозності warn, і вони не зупиняють роботу.
warn: E0278 name-shape: metadata.name "mariadbSynth" does not match the documented pattern for Recipe entities (^[a-z][a-z0-9-]*$)

Знахідка починається з рівня серйозності та короткого коду, під яким зареєстровано її правило; розгорнутий опис дає aggrega explain E0278. Над знахідкою виводиться шлях до проблемного файлу, а запуск для всього каталогу завершується підрахунком перевірених сутностей і виявлених рекомендаційних знахідок.

  • aggrega build не перевіряє форму імен. Згенерований результат не залежить від імен сутностей Aggrega, тому збирання каталогу з невідповідними іменами не видає жодного попередження чи діагностики й завершується успішно так само, як і за інших умов.
  • aggrega push також не перевіряє форму імен. Публікацію відхиляють з інших причин — передусім через описане вище правило незмінності, за яким повторна публікація наявного name:version з іншим вмістом зупиняється. Якщо у відмові згадано aggrega lint --pre-publish, вона підказує авторові, яку команду запустити; сам push її не запускає.

Оскільки ні збирання, ні публікація не перевіряють форму, каталог, який хоче дотримуватися домовленості, свідомо запускає aggrega lint — у хуку pre-commit або як крок конвеєра. Зверніть увагу, що знахідка щодо форми імені має рекомендаційний характер: aggrega lint повідомляє про неї й усе одно завершується успішно, тому конвеєр, який хоче контролювати дотримання домовленості, зчитує повідомлені знахідки, а не покладається на код завершення.

Правило вимикає політика на рівні робочого простору:

# .aggrega-config.yaml — lint section
lint:
publishing_discipline:
allow_nonstandard_names: true # default false

Якщо політику встановлено, правило форми імен не повідомляє взагалі нічого. Її також можна встановити для одного виклику за допомогою aggrega lint --allow-nonstandard-names або знову примусово вимкнути за допомогою --no-allow-nonstandard-names. Обґрунтовані випадки використання — каталоги, які ніколи не публікуватимуться, експерименти з кількома видавцями та сутності спеціального призначення.

11. Розгортання сутностей Feature на основі анотацій

Блок mappings.features.annotations у сутності Manifest оголошує прив’язки між ключами анотацій і типами Feature, а також згруповану за стовпами таблицю маршрутизації (maps.infra, maps.values), що називає властивості схеми Feature, які може заповнювати кожна анотація. Підфаза розгортання анотацій у межах розв’язання обходить межі сутностей Release від зовнішніх до внутрішніх і підсистеми сутностей Aggregate від зовнішніх до внутрішніх, обчислює ефективні набори анотацій для кожного компонента через каскадування й перевизначення з відмовою через null як для всього значення, так і для окремого підключа, і впроваджує синтетичні приєднання Feature, що несуть origin: annotation у своєму походженні IR. Повний опис форми прив’язок і їх написання наведено в language-reference/entities/manifest.md і language-reference/providers/well-known-annotations.md; цей розділ документує механізми часу завантаження каталогу та часу інспектування, на які спирається шлях розгортання.

Кеш компіляції схем. spec.schema.{infra,values} кожної сутності Feature компілюється один раз за збірку і повторно використовується в усіх каскадних обходах. Повторна перевірка типів окремих підключів щодо тієї самої схеми Feature (одна каскадна область на компонент, для сотень компонентів) читає скомпільовану схему замість повторної компіляції. Між збірками нічого не зберігається, тож змінену схему Feature наступна збірка компілює заново.

Перевірка цілей прив’язок (завантаження каталогу). Під час завантаження каталогу компілятор обходить кожну прив’язку features.annotations у сутності Manifest і перевіряє, що кожен шлях через крапку, оголошений у maps.infra і maps.values, відповідає властивості, яку справді оголошує spec.schema.<pillar> відповідної сутності Feature. Прив’язка, що маршрутизує до шляху, якого немає в схемі Feature, зупиняє завантаження каталогу зрозумілою помилкою OPS_ERROR, що називає ключ прив’язки, відсутній шлях, URI сутності Feature і місце в джерелі.

Lint перекриття стовпів схеми (завантаження каталогу). Рекомендаційне попередження виникає, коли spec.schema сутності Feature оголошує ту саму назву властивості і в стовпі infra, і в стовпі values. Таке перекриття рідко буває навмисним: однойменні властивості в різних стовпах затьмарюють намір автора (який стовп спрацює, коли анотація спрямована на спільну назву?) і ускладнюють діагностичні повідомлення. Попередження не блокує й не вимикається: автор, який задумав перекриття, залишає і його, і попередження, а автор, який його не задумував, перейменовує властивість в одному зі стовпів.

Lint перекриття карт прив’язок (розв’язання). Рекомендаційне попередження виникає, коли шлях підключа з’являється і в maps.infra, і в maps.values у прив’язках сутності Manifest. Шлях, присутній в обох списках стовпів, є несумісним: один підключ анотації не може одночасно маршрутизуватися до обох стовпів, а детерміноване розв’язання конфлікту, яке застосовує компілятор (шлях з обох списків маршрутизується до infra; анотація, написана в Aggregate, може маршрутизуватися лише через values, тож написану там анотацію для цього шляху відхиляють), є страховкою, а не передбаченою формою написання. Попередження не блокує; автори, які ігнорують попередження, однаково отримують чисту збірку, а розв’язання конфлікту видно в походженні IR.

Відображення походження в aggrega inspect. Команда inspect відображає одну квадратну дужку на кожне приєднання Feature, записуючи джерело кожного заповненого листка:

  • [explicit] — сутність Feature приєднано явно через блок features: у сутності Aggregate або Release.
  • [annotation: <key> from <source>] — кожен заповнений листок походить з одного й того самого ключа анотації. Дужка називає ключ і місце, де оголошено анотацію: файл і шлях ключа через крапку всередині нього.
  • Дужки для окремих листків — композиція з різних боків, де кожен заповнений листок відображається з власною дужкою джерела (деякі [explicit], деякі [annotation: <key> from <source>]). Ця форма показує злиття, де явне значення перемагає для кожного поля окремо: коли явне приєднання та внесок анотації спрямовані на той самий екземпляр Feature у тій самій сутності Component, але записують різні листки, обидва внески зберігаються на своїх листках, а вивід inspect називає джерело кожного листка окремо.

Відображення inspect читає карти IR для кожного стовпа values_provenance і infra_provenance, які заповнюються під час розгортання анотацій разом із впровадженням синтетичних приєднань, і виводить ту форму дужки, що найкраще підсумовує спільне джерело листків. Механізм inspect є канонічним засобом інтроспекції, щоб зрозуміти, чому певне приєднання Feature опинилося в певній сутності Component і звідки взялися його значення.