Перейти к содержимому
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; и в командной строке. Таким образом, любой хост, который может назвать конфигурация, — это хост, артефакты которого проверяются по написанной для него политике. Хост оценивается только по написанию; разрешается ли имя и отвечает ли по нему реестр — это состояние времени выполнения, которое компилятор никогда не запрашивает. В разделе configuration допустимые формы описаны с примерами.

Сокращённые URI разрешаются с учётом контекста относительно сущности Manifest; конкретные правила вывода см. в ../language-reference/entities/manifest.md, §Context-Aware Shorthand URIs.

Управление реестрами

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. Закрепление версий в lock-файле и неизменяемость артефактов

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

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

Неизменяемость важна из-за двух следствий:

  1. Закрепления в lock-файле честны. Когда lock-файл фиксирует mariadb:1.0.0 с дайджестом D, сборка, загружающая по дайджесту, получает байты D. Без неизменяемости изменение на стороне реестра могло бы подменить байты D под закреплением в lock-файле, нарушая стабильность между моментом фиксации и моментом сборки. Воспроизводимые сборки опираются на эту гарантию.
  2. У изменений метаданных после публикации есть ясный путь. Пометить опубликованную версию как устаревшую, сменить ключи подписи или дополнить аттестации нельзя путём изменения опубликованного артефакта (правило это запрещает). Это нужно делать, публикуя новую патч-версию или сопутствующий артефакт, который отдельно фиксирует изменение метаданных. Оба пути поддаются аудиту — новая версия или сопутствующий артефакт появляется как отдельная запись в реестре — и ни один не меняет байты исходного артефакта.

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

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

Повторное разрешение к более новой версии требует явного действия пользователя: aggrega pull --upgrade --release <release> <uri> повторно разрешает одну зависимость, сохраняя все остальные закрепления, а aggrega pull --upgrade --release <release> повторно разрешает все зависимости относительно текущего состояния реестра. Зависимости в форме диапазона и без версии разрешаются к последней подходящей версии; точные закрепления не меняются, если пользователь явно не обновит их до другой точной версии. Lock-файл — источник истины для сборок; форма, введённая пользователем, выражает ограничение версии на этапе написания.

10. Контроль формы имён сущностей каталога

Имена сущностей каталога следуют шаблонам, своим для каждого вида сущности: они перечислены ниже и подробно описаны для каждого вида в обзоре справочника сущностей. Это иная область, чем имена экземпляров, которые разработчик пишет в сущности Aggregate или Release: у них один шаблон независимо от вида, и он описан в ../language-reference/02-naming-conventions.md, раздел «Instance Names». Поле 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, это подсказка автору, какую команду запустить; сама публикация её не запускает.

Поскольку ни сборка, ни публикация форму не проверяют, каталог, которому нужно соблюдение соглашения, намеренно запускает 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 и откуда взялись его значения.