Схема lockfile Aggrega для отдельного Release
Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.
Идентификатор схемы: https://aggrega.ai/schemas/lockfile-v1beta1.schema.json
Машинно сгенерированный lockfile, фиксирующий каждый URI, разрешённый из сущности Release, для детерминированных будущих сборок. Располагается в <release-stem>.lock рядом с <release-stem>.yaml; создаётся командой aggrega pull --release <release>; используется командой aggrega build --release <release>. Две формы происхождения записывают два различных отношения в графе зависимостей: referenced_from (список строк) присутствует в entities в виде путей мест авторинга через точку и фиксирует, откуда в Release / Aggregate / Manifest / .aggrega-config.yaml был подтянут каждый URI, а также в plugins — в виде ссылки на каждую сущность Plugin, через которую был достигнут артефакт; consumers (список записей {consumer_uri, fragments}) присутствует в schema_libraries, mapping_libraries, workload_libraries и artifact_libraries и фиксирует, какая сущность каталога ссылается на какие фрагменты <entry-name> библиотеки — структурированная форма позволяет отслеживать различия, показывающие, каких потребителей затрагивает повышение версии библиотеки, без повторного разрешения Release. Порядок эволюции схемы: добавление нового раздела верхнего уровня — изменение SemVer-MINOR (аддитивное); добавление нового поля в существующий раздел — SemVer-MINOR; удаление ключа или ужесточение ограничения — SemVer-MAJOR.
Тип верхнего уровня: object
Свойства
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
entities | object[] | нет | Сущности каталога, достижимые из этой сущности Release: Component, Feature, Recipe, FeatureRecipe, Plugin, Aggregate, собственные Aggregate и Manifest этой сущности Release, а также сущность Manifest, которую расширяет эта сущность Manifest. Каждая запись идентифицируется своим kind вместе со своим каноническим URI, поэтому две сущности разных видов с общим именем — скажем, сущности Aggregate и Manifest, обе с именем imported/flow, — это две записи, каждая из которых сверяется со своим дайджестом. Каждая фиксирует разрешённую версию, дайджест того, что несёт сущность, и места авторского описания (referenced_from), из-за которых URI попал в замыкание зависимостей Release. Lock-файл, записи которого не содержат kind, устарел: aggrega pull --release <release> записывает его заново. По умолчанию: [] |
external_inputs | ExternalInput[] | нет | Удалённые входные данные, закреплённые в адресуемом по содержимому хранилище входных данных в момент получения, — содержимое из-за пределов рабочего пространства, которое потребляет рендеринг плагина провайдера, например удалённые документы схем или невендоренные зависимости чартов. Каждая запись закрепляет один URL за дайджестом, которым его байты названы в хранилище. Сборка выдаёт закреплённые входные данные из хранилища и читает этот раздел без доступа к сети. По умолчанию: [] |
generated_at | string | да | Метка времени RFC 3339 операции pull, создавшей этот lock-файл; шаблон ограничивает значение этим форматом при загрузке lock-файла. Диагностическое происхождение — фиксирует момент разрешения по настенным часам. Намеренно меняется между операциями pull; не входит в гарантию побайтовой идентичности lock-файла. Шаблон: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$. |
mapping_libraries | LibraryEntry[] | нет | Записи MappingLibrary, которых замыкание зависимостей Release достигает через места valuesMapping: { $import: ... } в Recipe / FeatureRecipe. Список consumers каждой записи фиксирует, какая сущность каталога ссылается на какие фрагменты <entry-name> библиотеки, — структурированная запись, которая позволяет отследить влияние повышения версии библиотеки по диффам без повторного разрешения Release. По умолчанию: [] |
mutators | object[] | нет | Разрешённые подключения управления в роли transform, в порядке авторского описания. Плагин в роли transform (label-transform, переписывающий метки узлов, или annotation-transform, внедряющий аннотации до развёртывания) формирует байты результата рендеринга, поэтому набор подключений — упорядоченный список, а также для каждого подключения роль, координата плагина и экспортируемая функция — является входными данными, определяющими байты, и закрепляется здесь. Сборка читает этот раздел — и никогда .aggrega-config.yaml — чтобы восстановить набор, порядок, роль и экспортируемую функцию, поэтому результат сборки не зависит от изменения plugins.governance, сделанного после pull (оно принимается только при следующем pull). Порядок СЕМАНТИЧЕН: каждый исполнитель transform применяет подключения своей роли в порядке списка, поэтому, в отличие от отсортированных по URI разделов plugins / providers, этот список никогда не переупорядочивается. Дайджест содержимого плагина здесь НЕ дублируется: его единственный источник — разделы plugins и entities, на которые эта запись указывает по идентичности. По умолчанию: [] |
plugins | object[] | нет | Wasm-плагины, чьи байты формируют отрисованный вывод, каждый закреплён дайджестом содержимого своего .wasm: плагин governance, подключённый в роли преобразования (label-transform, annotation-transform) в .aggrega-config.yaml plugins.governance, а также любые встроенные URI плагинов из используемых Recipes / FeatureRecipes / Providers. Плагин governance, подключённый в роли вердикта (ir-verdict, render-verdict), и подключение plugins.linter возвращают вердикт и не формируют выходных байтов, поэтому ни один из них не закрепляется: ни один не появляется ни здесь, ни в entities, а файлы правил, которые читает подключение вердикта, записываются в verdict_inputs. По умолчанию: [] |
providers | object[] | нет | Разрешённый выбор провайдера для каждой возможности. Каждая запись закрепляет одну возможность (например, helm) за OCI-идентичностью без дайджеста плагина, выполняющего рендеринг провайдера, который её рендерит; она разрешается при pull из списка plugins.providers в .aggrega-config.yaml (когда возможность обслуживается неоднозначно) или из единственного обслуживающего плагина (когда однозначно). Сборка читает этот раздел — и никогда .aggrega-config.yaml — чтобы выбрать провайдера, поэтому результат сборки не зависит от изменений конфигурации рабочего пространства, сделанных после pull. Дайджест содержимого плагина здесь НЕ дублируется: его единственный источник — разделы plugins и entities, на которые эта запись указывает по идентичности. Сосуществование версий сохраняется: эта запись выбирает репозиторий плагина для каждой возможности; конкретные версии находятся в entities (одна запись на каждую разрешённую версию плагина), а закрепление версии spec.capability каждой сущности Recipe выбирает среди них при рендеринге. По умолчанию: [] |
release | string | да | Путь к сущности Release, которой соответствует этот lock-файл, разрешаемый относительно собственного каталога lock-файла (например, ./release-prod.yaml). Соглашение об именовании для каждой сущности Release помещает <release-stem>.lock рядом с <release-stem>.yaml; относительный путь делает lock-файл самоописывающим без машинно-зависимых абсолютных путей. Это поле называет сущность Release; то, что содержала Release на момент разрешения, фиксируется в release_documents. |
release_documents | object[] | нет | Файлы Release, прочитанные при разрешении, каждый из которых зафиксирован дайджестом содержимого его байтов: сначала Release, которой принадлежит этот lock-файл, затем каждая Release, которую она расширяет, в порядке обхода цепочки extends. Всё, что запрашивает Release, разрешается из того, что она содержит, поэтому Release, отредактированная после pull, больше не совпадает со своим зафиксированным дайджестом, и сборка — или aggrega pull --verify — останавливается с указанием файла и рекомендацией aggrega pull --release <release> до того, как что-либо будет отрендерено. Дайджест охватывает байты как есть, без какой-либо нормализации, — то же правило, которому следуют закрепления Aggregate и Manifest: изменение комментария или пробелов считается изменением. Lock-файл без этого раздела не фиксирует ни одного файла Release, и сборка с таким файлом сообщает, что Release не зафиксирована. Файл, который Release импортирует через parameters, здесь не фиксируется. |
schema_libraries | LibraryEntry[] | нет | Записи SchemaLibrary, которых замыкание зависимостей Release достигает через места $ref и $import: в содержимом schema: / usesSchema: / featuresSchema: сущностей. Список consumers каждой записи фиксирует, какая сущность каталога ссылается на какие фрагменты <entry-name> библиотеки, — структурированная запись, которая позволяет отследить влияние повышения версии библиотеки по диффам без повторного разрешения Release. По умолчанию: [] |
source_artifacts | SourceArtifactEntry[] | нет | Исходные артефакты, полученные из полей spec.source в Recipe / FeatureRecipe во время pull. Каждая запись определяет уникальную идентичность {kind, url, chart, pinned_version} с дайджестом содержимого, типом носителя и структурированными обратными указателями referenced_by:, называющими каждую сущность каталога, которая разрешилась в этот артефакт. url — авторский идентифицирующий URL; разрешённое расположение артефакта для источника helm в корне репозитория фиксируется отдельно в resolved_url: как сведения о происхождении. Несколько Recipes, закрепляющих один и тот же чарт в одной и той же версии, дедуплицируются в одну запись с несколькими записями referenced_by:. Перечисление kind охватывает четыре вида источников, которые разрешаются, и terraform-module-oci, который не обслуживает ни один адаптер источника: Recipe или FeatureRecipe, указывающий его, отклоняется при чтении, поэтому ни один pull не записывает запись этого вида. По умолчанию: [] |
toolchain | object | нет | Версии инструментария, создавшего этот lock-файл: собственная версия компилятора и версия каждого базового плагина, который несёт компилятор. Фиксируются, чтобы lock-файл постфактум отвечал, какой компилятор и какие базовые плагины разрешили и отрендерили сборку, — на этот вопрос закреплённые разделы ответить могут не всегда, потому что базовый плагин провайдера, обслуживаемый изнутри бинарного файла компилятора, остаётся незакреплённым и потому не несёт собственной зафиксированной версии. Только версии: отметка никогда не фиксирует, откуда взялись байты плагина, поэтому две машины, закрепившие одно и то же замыкание зависимостей одним и тем же компилятором, записывают одинаковую отметку. Ничто не сравнивает этот раздел, не предупреждает о нём и не отклоняет сборку из-за него, а его отсутствие в lock-файле проходит молча: инструментарий не входит в замыкание зависимостей, которое закрепляет lock-файл. По той же причине раздел исключается из побайтового сравнения двух операций pull с одинаковыми входными данными наравне с generated_at. |
verdict_inputs | object[] | нет | Внешние входные данные правил, которые подключение governance в роли вердикта (ir-verdict / render-verdict) читает во время компиляции, — файл правил Kyverno / Rego, переданный через with.sources подключения. Записываются как дайджест содержимого для каждого источника — для аудита и видимости расхождений между pull: дайджест, определивший вердикт, можно сравнивать между pull, поэтому изменённый файл правил проявляется как diff lockfile. Этот раздел — ПРОИСХОЖДЕНИЕ, а не входные данные сборки: в отличие от mutators.sources, он не содержит content, и сборка его НЕ читает — плагин вердикта кэшируется, а не закрепляется, и читает свои входные данные правил напрямую (вердикт не формирует выходных байтов, поэтому ничто из того, что lockfile закрепляет ради детерминированного вывода, его не включает). Поскольку плагин вердикта не закрепляется, он отсутствует в разделах entities / plugins; поэтому эта запись идентифицирует подключение по указанному автором URI — самостоятельно, а не через ссылку на эти разделы. Запись дайджеста делает входные данные, определившие решение о принятии или отклонении, проверяемыми и воспроизводимыми без их закрепления в сборке. По умолчанию: [] |
version | const 1 | да | Версия схемы lockfile: 1. Изменение схемы уровня SemVer-MAJOR увеличивает её. Константа: 1 |
workload_libraries | LibraryEntry[] | нет | Записи WorkloadLibrary, которых замыкание зависимостей Release достигает через места workload: { $import: ... } в Recipe. Список consumers каждой записи фиксирует, какая сущность каталога ссылается на какие фрагменты <entry-name> библиотеки, — структурированная запись, позволяющая отследить влияние повышения версии библиотеки без повторного разрешения Release. По умолчанию: [] |
artifact_libraries | LibraryEntry[] | нет | Записи ArtifactLibrary, которых замыкание зависимостей Release достигает через места artifacts.<name>: { $import: ... } в Recipe / FeatureRecipe. Список consumers каждой записи фиксирует, какая сущность каталога ссылается на какие наборы <entry-name> библиотеки, — структурированная запись, позволяющая отследить влияние повышения версии библиотеки без повторного разрешения Release. По умолчанию: [] |
Дополнительные свойства не допускаются.
lockfile.entities[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
kind | string (enum) | да | Вид сущности каталога, считываемый из того места, где сущность Release, её Aggregate или её Manifest называет её: component и feature для типа Component или Feature, который называет Aggregate, Release или сопоставление в Manifest, recipe и feature_recipe для реализации, которую привязывает сопоставление в Manifest, plugin для сущности Plugin, aggregate для собственной сущности Aggregate сущности Release и каждой сущности Aggregate, которую она включает, и manifest для собственной сущности Manifest сущности Release и сущности Manifest, которую она расширяет. Вместе с uri он идентифицирует запись: сборка сравнивает каждую запись с сущностью того же вида и URI, поэтому правка любой из двух одноимённых сущностей разных видов будет замечена. Допустимые значения: "aggregate", "component", "feature", "feature_recipe", "manifest", "plugin", "recipe" |
uri | string | да | Канонический URI сущности каталога (например, hub.aggrega.ai/component/core/compute/api-server). |
resolved_version | string | да | Конкретная версия, выбранная резолвером во время pull, — собственная версия сущности каталога (например, 1.2.3) или пустое значение для сущности верхнего уровня, разрешённой по пути, а не по версии. Записывается как один сегмент пути, поскольку именует один сегмент, поэтому не содержит /, \ и ..: из значения строится слот кэша, из которого сборка читает эту сущность, и значение, выходящее за пределы каталога кэша, указывало бы на расположение вне его. Шаблон: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | да | Дайджест того, что содержит публикация сущности, в виде sha256: и 64 шестнадцатеричных символов в нижнем регистре: SHA-256 по документу сущности и каждому файлу, объявленному рядом с ним, отсортированным по пути, причём каждый вносит свой путь и SHA-256 своих байтов. Сущность, не объявляющая файлов, считается своим единственным документом. Больше ничего не учитывается — ни способ сжатия архива, ни метка времени, ни какие-либо биты прав доступа, включая бит исполнения, — поэтому сущность записывает один и тот же дайджест, прочитана ли она из каталога или получена из реестра, и при любом checkout тех же файлов в любой системе. Шаблон: ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | нет | Дайджест манифеста OCI разрешённого артефакта в виде sha256: и 64 шестнадцатеричных символов в нижнем регистре. Подпись фиксирует этот дайджест, а манифест именует дайджест опубликованных байтов, с которым сверяются загрузка и чтение из кэша, прежде чем сущность проверяется по своему digest выше. Присутствует только для сущности, разрешённой из реестра. Шаблон: ^sha256:[a-f0-9]{64}$. |
referenced_from | string[] | нет | Места происхождения при написании — пути через точку в YAML Release / Aggregate / Manifest (например, aggregate.spec.components.api.type), фиксирующие, почему этот URI входит в замыкание зависимостей Release. По умолчанию: [] |
signature | VerifiedSignature | нет | Факт проверенной подписи, записываемый, когда подпись этой сущности была проверена во время pull по политике доверия разрешающего реестра. |
deprecation | DeprecationRecord | нет | Проверенный ретроактивный маркер устаревания, записываемый, когда во время pull на этом артефакте обнаружен подписанный доверенный маркер устаревания. Маркер — это подписанный OCI referrer артефакта, который он объявляет устаревшим, прикреплённый после публикации без повторной публикации артефакта. Записывает серьёзность и сообщение маркера, а также проверенного подписанта, создавшего его. Сборка читает этот факт и применяет политику устаревания только на основе lockfile; она никогда не обнаруживает и не проверяет маркер повторно. |
Дополнительные свойства не допускаются.
lockfile.mutators[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
plugin | string | да | Разрешённая координата плагина в роли преобразования — идентичность <pluginType>/<name> сущности Plugin (например, governance/tag-injector). Соединяется по идентичности с разделами plugins и entities для закреплённого дайджеста и набора версий. |
role | string (enum) | да | Роль преобразования, к которой привязано это подключение, записанная дословно из указанной автором записи plugins.governance, поэтому сборка запускает подключение именно в этой роли, а не выводит её: label-transform переписывает метки узлов при построении топологии; annotation-transform внедряет аннотации перед развёртыванием, во время разрешения. Допустимые значения: "label-transform", "annotation-transform" |
function | string | нет | Переопределение экспорта, которое называет подключение. При отсутствии выбирается экспорт роли по умолчанию (mutate для label-transform, transform_annotations для annotation-transform). |
settings | object | нет | Объект настроек свободной формы, объявленный подключением, закреплённый в авторском виде и передаваемый плагину дословно. Сборка читает настройки отсюда — никогда не из текущей конфигурации, — поэтому изменение настроек после pull не меняет результат сборки. Отсутствует, если подключение их не объявляет. |
sources | object[] | нет | Адресуемые по содержимому закрепления объявленных подключением исходных файлов в порядке базовых имён. Сборка восстанавливает исходные данные, которые читает плагин, из записанного содержимого каждого закрепления, а не читая файл на хосте, поэтому результат сборки не зависит от изменения исходного файла после pull. Отсутствует, если подключение их не объявляет. |
Дополнительные свойства не допускаются.
lockfile.mutators[].sources[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
content | string | да | Содержимое исходного файла, хранимое дословно, чтобы сборка восстанавливала исходные входные данные плагина из lockfile. |
digest | string | да | Адрес содержимого записанного содержимого в виде sha256: и 64 шестнадцатеричных символов в нижнем регистре. Повторный pull сравнивает исходный файл с этим дайджестом, чтобы обнаружить расхождение. Шаблон: ^sha256:[a-f0-9]{64}$. |
path | string | да | Базовое имя исходного файла — никогда не абсолютный путь на хосте, поэтому закрепление переносимо и детерминировано. |
Дополнительные свойства не допускаются.
lockfile.plugins[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
uri | string | да | Голая идентичность артефакта .wasm плагина Wasm — путь <pluginType>/<name> (например, governance/aggrega-security-baseline). Первый сегмент — тип плагина (provider, linter, pipeline-step, governance, cli, parser, importer); следующий за ним сегмент — имя плагина. Тип и имя вместе образуют идентичность плагина: одно и то же имя под двумя типами означает два плагина. Физическое место загрузки выводится из этой идентичности и настроенного реестра и никогда не хранится в lockfile. |
resolved_version | string | да | Дайджест содержимого, в который разрешился артефакт Wasm, в виде sha256: и 64 шестнадцатеричных символов в нижнем регистре. Артефакт плагина адресуется по содержимому, а не именуется по версии — .wasm встраивается в манифест своего плагина и закрепляется дайджестом своих байтов, — поэтому это поле записывает этот дайджест, который также является digest ниже. Из него строится слот кэша, из которого сборка считывает артефакт, поэтому он не содержит ни /, ни \, ни .., что форма sha256: и так исключает. Шаблон: ^sha256:[a-f0-9]{64}$. |
digest | string | да | Дайджест содержимого разрешённого артефакта Wasm в виде sha256: и 64 шестнадцатеричных символов в нижнем регистре — в той форме, в которой адрес содержимого записывается везде, где он сравнивается. Шаблон: ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | нет | Дайджест манифеста OCI разрешённого артефакта Wasm в виде sha256: и 64 шестнадцатеричных символов в нижнем регистре. Подпись фиксирует этот дайджест; digest содержимого выше — переносимая идентичность, используемая для закрепления в кэше и проверки целостности. Присутствует только для артефакта, разрешённого из реестра. Шаблон: ^sha256:[a-f0-9]{64}$. |
referenced_from | string[] | нет | Почему этот артефакт входит в замыкание зависимостей Release: ссылка на каждую сущность Plugin, через которую он был достигнут, в том виде, в каком раздел entities записывает эту сущность (например, governance/label-injector:1.0.0). По умолчанию: [] |
signature | VerifiedSignature | нет | Факт проверенной подписи, записываемый, когда подпись этого плагина была проверена во время pull по той же политике доверия каждого реестра, что и для сущностей каталога. |
deprecation | DeprecationRecord | нет | Проверенный ретроактивный маркер устаревания, записываемый, когда во время pull на этом артефакте обнаружен подписанный доверенный маркер устаревания. Маркер — это подписанный OCI referrer артефакта, который он объявляет устаревшим, прикреплённый после публикации без повторной публикации артефакта. Записывает серьёзность и сообщение маркера, а также проверенного подписанта, создавшего его. Сборка читает этот факт и применяет политику устаревания только на основе lockfile; она никогда не обнаруживает и не проверяет маркер повторно. |
Дополнительные свойства не допускаются.
lockfile.providers[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
capability | string | да | Возможность, для которой эта привязка выбирает провайдера, — голое имя возможности, к которому Recipe привязывается через spec.capability (например, helm, compose). |
plugin | string | да | Голая идентичность разрешённого плагина рендеринга провайдера (идентичность сущности Plugin — её metadata.pluginType и metadata.name, соединённые косой чертой, например provider/helm). Соединяется по идентичности с разделами plugins и entities, где хранятся закреплённый дайджест и набор версий. |
Дополнительные свойства не допускаются.
lockfile.release_documents[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
digest | string | да | Дайджест содержимого байтов файла Release в момент их чтения при разрешении, в виде sha256: и 64 шестнадцатеричных символов в нижнем регистре. Шаблон: ^sha256:[a-f0-9]{64}$. |
path | string | да | Путь к файлу Release относительно каталога, содержащего Release, которому принадлежит этот lockfile, с прямыми косыми чертами (например, release-prod.yaml, ../shared/base-release.yaml) — никогда не абсолютный путь на хосте, поэтому запись переносима и детерминирована. |
Дополнительные свойства не допускаются.
lockfile.toolchain
Версии инструментария, создавшего этот lock-файл: собственная версия компилятора и версия каждого базового плагина, который несёт компилятор. Фиксируются, чтобы lock-файл постфактум отвечал, какой компилятор и какие базовые плагины разрешили и отрендерили сборку, — на этот вопрос закреплённые разделы ответить могут не всегда, потому что базовый плагин провайдера, обслуживаемый изнутри бинарного файла компилятора, остаётся незакреплённым и потому не несёт собственной зафиксированной версии. Только версии: отметка никогда не фиксирует, откуда взялись байты плагина, поэтому две машины, закрепившие одно и то же замыкание зависимостей одним и тем же компилятором, записывают одинаковую отметку. Ничто не сравнивает этот раздел, не предупреждает о нём и не отклоняет сборку из-за него, а его отсутствие в lock-файле проходит молча: инструментарий не входит в замыкание зависимостей, которое закрепляет lock-файл. По той же причине раздел исключается из побайтового сравнения двух операций pull с одинаковыми входными данными наравне с generated_at.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
compiler_version | string | да | Версия компилятора, записавшего этот lockfile, в форме без «v», которую сообщает каждый интерфейс Aggrega (1.2.0, а не v1.2.0). Сборка с отметкой версии записывает эту версию — сборка тегированного релиза записывает свой тег, — а сборка без отметки версии записывает маркер (devel), чтобы lockfile, созданный компилятором без отметки, не был принят за результат релиза. Записывается как один сегмент пути, поэтому не содержит ни /, ни \, ни ... Шаблон: ^([^/\\.]|\.[^/\\.])*\.?$. |
core_plugins | object[] | да | Версия каждого основного плагина, который несёт компилятор, по одной записи на плагин, упорядоченные по координате плагина. Основной плагин публикуется под собственным тегом компилятора с той же версией, поэтому эти версии одинаковы независимо от того, предоставил ли компилятор плагин изнутри себя или загрузил его из реестра, — именно это избавляет отметку от машинно-зависимых деталей. Пусто для сборки, не несущей основных плагинов. По умолчанию: [] |
Дополнительные свойства не допускаются.
lockfile.toolchain.core_plugins[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
plugin | string | да | Координата основного плагина — идентичность <pluginType>/<name> сущности Plugin (например, provider/helm), та же идентичность, по которой разделы providers и mutators называют плагин. |
version | string | да | Версия этого основного плагина в форме без «v», которую сообщает каждый интерфейс Aggrega. Записывается как один сегмент пути, поэтому не содержит ни /, ни \, ни ... Шаблон: ^([^/\\.]|\.[^/\\.])*\.?$. |
Дополнительные свойства не допускаются.
lockfile.verdict_inputs[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
plugin | string | да | URI плагина вердикта, как он записан в .aggrega-config.yaml plugins.governance (например, governance/aggrega-security-baseline:1.0.0). Определяет, к какому подключению относятся записанные входные данные правил; плагин вердикта кэшируется, а не закрепляется, поэтому не имеет записи в разделах plugins / entities, с которой можно было бы соединиться. |
role | string (enum) | да | Роль вердикта, к которой привязано это подключение, — ir-verdict (при статическом анализе, по графу IR) или render-verdict (при рендеринге, по отрендеренным артефактам). Различает один и тот же плагин, подключённый на обоих этапах вердикта, каждый, возможно, со своими входными данными правил. Допустимые значения: "ir-verdict", "render-verdict" |
sources | object[] | нет | Дайджесты содержимого объявленных подключением файлов входных данных правил в порядке базовых имён. Отсутствует, если подключение не объявляет источников. |
Дополнительные свойства не допускаются.
lockfile.verdict_inputs[].sources[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
digest | string | да | Адрес содержимого байтов файла входных данных правил на момент pull, в виде sha256: и 64 шестнадцатеричных символов в нижнем регистре. Повторный pull пересчитывает его, поэтому изменённый файл правил проявляется как diff lockfile. Шаблон: ^sha256:[a-f0-9]{64}$. |
path | string | да | Базовое имя файла входных данных правил — никогда не абсолютный путь на хосте, поэтому запись переносима и детерминирована. |
Дополнительные свойства не допускаются.
Определения
DeprecationRecord
Проверенный ретроактивный маркер устаревания, записываемый, когда во время pull на этом артефакте обнаружен подписанный доверенный маркер устаревания. Маркер — это подписанный OCI referrer артефакта, который он объявляет устаревшим, прикреплённый после публикации без повторной публикации артефакта. Записывает серьёзность и сообщение маркера, а также проверенного подписанта, создавшего его. Сборка читает этот факт и применяет политику устаревания только на основе lockfile; она никогда не обнаруживает и не проверяет маркер повторно.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
message | string | да | Понятное человеку сообщение об устаревании, которое несёт маркер, — обычно указание на способ миграции. |
severity | string (enum) | да | Серьёзность маркера в порядке warning < error < retracted. Сборка останавливается, когда эта серьёзность достигает настроенного порога остановки или превышает его, а в противном случае выдаёт предупреждение. Допустимые значения: "warning", "error", "retracted" |
signer | VerifiedSignature | нет | Проверенный подписант маркера, записанный так же, как подписант подписи артефакта: субъект/издатель сертификата для бесключевой подписи или отпечаток закреплённого ключа для подписи ключом. Маркер сам по себе является подписанным артефактом, поэтому его подписант имеет ту же структуру, что и подпись артефакта, — а bundle_digest здесь обозначает собственный пакет подписи маркера, а не пакет устаревшего артефакта. |
Дополнительные свойства не допускаются.
ExternalInput
Один закреплённый внешний вход: URL, запрошенный рендерингом, закрепление SHA-256, именующее его байты в адресуемом по содержимому хранилище входов (sha256/<digest>), размер полезной нагрузки и происхождение потребителей, которым он потребовался. Закрепление является определяющим: закреплённый URL всегда обслуживается из хранилища, а повторное заполнение хранилища проверяется по этому дайджесту, прежде чем байты попадут в рендеринг.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
required_by | string[] | да | Происхождение — места рендеринга, запросившие этот вход. Сортируется и очищается от дубликатов при записи lockfile. |
sha256 | string | да | Закрепление SHA-256 в виде шестнадцатеричной строки в нижнем регистре. Для входа https — дайджест байтов полезной нагрузки; для входа oci — дайджест манифеста, в который разрешилась ссылка. Именует blob хранилища по пути sha256/<digest>. Шаблон: ^[0-9a-f]{64}$. |
size | integer | да | Размер закреплённой полезной нагрузки в байтах. Количество байтов никогда не бывает отрицательным. Минимум: 0. |
url | string | да | URL входа в том виде, в каком он написан в месте рендеринга, — ключ поиска, сопоставляющий запрос во время рендеринга с его закреплением. |
Дополнительные свойства не допускаются.
LibraryEntry
Общая структура записей schema_libraries, mapping_libraries, workload_libraries и artifact_libraries. Список consumers фиксирует связи в графе каталога — какая сущность каталога ссылается на какие фрагменты <entry-name> этой библиотеки, — что позволяет получать структурированные различия по влиянию при изменении дайджеста библиотеки. Библиотека — такой же OCI-артефакт, как и любой другой, поэтому для неё записываются те же проверенные факты, что и для сущности каталога: дайджест манифеста, к которому привязана её подпись, сама проверенная подпись и любой проверенный ретроактивный маркер устаревания, обнаруженный во время pull.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
uri | string | да | Канонический URI сущности библиотеки. |
resolved_version | string | да | Конкретная версия, разрешённая во время pull (выбор минимальной версии по графу зависимостей библиотек), — собственная версия библиотеки. Записывается как один сегмент пути, поскольку из неё строится слот кэша, из которого сборка считывает библиотеку, поэтому она не содержит /, \ и ..: значение, выходящее за пределы каталога кэша, указывало бы на место вне его. Шаблон: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | да | Дайджест содержимого разрешённого артефакта библиотеки в формате sha256:, за которым следуют 64 шестнадцатеричных символа в нижнем регистре, — в той форме, в которой адрес содержимого записывается везде, где он сравнивается. Шаблон: ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | нет | Дайджест OCI-манифеста разрешённого артефакта библиотеки в формате sha256:, за которым следуют 64 шестнадцатеричных символа в нижнем регистре. Подпись привязана к этому дайджесту; дайджест содержимого digest выше — переносимый идентификатор, используемый для закрепления в кэше и проверки целостности. Присутствует только для библиотеки, разрешённой из реестра. Шаблон: ^sha256:[a-f0-9]{64}$. |
signature | VerifiedSignature | нет | Факт проверенной подписи, записываемый, когда подпись этой библиотеки была проверена во время pull по той же политике доверия для каждого реестра, что и для сущностей каталога. |
deprecation | DeprecationRecord | нет | Проверенный ретроактивный маркер устаревания, обнаруженный для этой библиотеки во время pull. Сборка сообщает о нём и, если в рабочем пространстве настроен порог остановки, которого достигает записанная серьёзность, останавливается — так библиотека, отозванная после закрепления версии, объявляется при каждой сборке, а не только при выборе версии, который явно закреплённая версия обходит. |
consumers | object[] | нет | Записи о том, какая сущность каталога ссылается на эту библиотеку и на какие фрагменты <entry-name>. Отражают входящие связи: много потребителей на одну библиотеку, каждый из которых может ссылаться на много фрагментов. Каждая запись содержит URI потребителя и набор фрагментов, которые этот потребитель подключает. По умолчанию: [] |
Дополнительные свойства не допускаются.
LibraryEntry.consumers[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
consumer_uri | string | да | Канонический URI сущности каталога, ссылающейся на эту библиотеку: Component или Feature для библиотеки схем, Recipe или FeatureRecipe для библиотеки сопоставлений, рабочих нагрузок или артефактов либо другая библиотека того же вида, записи которой ссылаются на эту. |
fragments | string[] | да | Набор фрагментов <entry-name>, на которые этот потребитель ссылается в библиотеке (например, ["#/schemas/PortSpec", "#/schemas/EndpointSpec"]). Порядок канонизируется лексикографически при записи. |
Дополнительные свойства не допускаются.
SourceArtifactEntry
Одна фиксация исходного артефакта: идентичность {kind, url, chart, module_subdir, pinned_version}, дайджест содержимого, проверяющий загрузку, канонический mediatype и структурированные обратные ссылки на каждую сущность каталога, которая разрешилась в этот артефакт. chart и module_subdir — два термина-селектора: каждый указывает то, чего не указывает один URL, для тех видов, которым это нужно.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
kind | enum | да | Вид источника. Определяет, какой адаптер разрешил артефакт и какой mediatype ожидается. terraform-module-oci входит в этот набор, но ни один адаптер источника его не обслуживает: Recipe или FeatureRecipe, указывающий его, отклоняется при чтении. Допустимые значения: "helm-oci-chart", "helm-https-chart", "compose-https-fragment", "git-repository", "terraform-module-oci" |
url | string | да | URL в авторской записи — идентифицирующий URL так, как он записан в spec.source.url сущности Recipe. Для helm-https-chart это корень репозитория (форма repo-root) или прямой .tgz (прямая форма) ровно так, как записано автором; сборка восстанавливает этот же URL офлайн, поэтому он служит стабильной идентичностью, по которой индексируется фиксация. Для git-repository — URL репозитория, пригодный для клонирования. Для helm-oci-chart — ссылка на реестр. Для compose-https-fragment — HTTPS URL фрагмента. Разрешённое расположение артефакта для helm-источника в форме repo-root записывается отдельно в resolved_url: как сведения о происхождении. |
chart | string | нет | Имя чарта для helm-источника в форме repo-root (spec.source.chart сущности Recipe), часть идентичности {kind, url, chart, module_subdir, pinned_version}, благодаря чему два чарта, отдаваемые из одного корня репозитория в одной версии, фиксируются в разных записях. Отсутствует для прямого .tgz, а также для источников OCI, compose и git: ни один из них не выбирает чарт внутри URL. |
module_subdir | string | нет | Каталог внутри git-репозитория, который является артефактом (spec.source.module_subdir сущности Recipe), часть идентичности {kind, url, chart, module_subdir, pinned_version}, благодаря чему два каталога одного репозитория на одном коммите фиксируются в разных записях. Отсутствует, когда артефактом является весь репозиторий, а также для каждого вида, который получает свой артефакт по URL, а не спуском внутрь клона. |
pinned_version | string | да | Конкретная версия, зафиксированная при загрузке. Для видов helm-* — версия чарта. Для git-repository — коммит, в который разрешилась авторская ссылка (НЕ исходная ссылка на тег или ветку — она записывается в requested_ref: в каждой записи referenced_by:, если Recipe задаёт spec.source.ref:). Сборка находит эту запись по тому, что записано в Recipe: по авторскому ref:, если он есть, сопоставляя его с записанным requested_ref:, а иначе — по этому зафиксированному значению. Поэтому Recipe, указывающий тег, разрешается в коммит, на котором этот тег был зафиксирован, хотя сам коммит в Recipe не появляется. Записывается как один сегмент пути, поскольку из него строится слот кэша, из которого сборка читает артефакт, поэтому не содержит /, \ и ... Шаблон: ^([^/\\.]|\.[^/\\.])*\.?$. |
resolved_url | string | нет | Только сведения о происхождении: конкретное расположение артефакта, в которое авторский URL разрешился при загрузке. Для helm-источника в форме repo-root это URL прямого .tgz, в который индекс репозитория разрешил пару чарт+версия; он записывается для диагностики и НЕ входит в идентичность артефакта. Отсутствует, когда разрешённое расположение совпадает с авторским URL (прямой .tgz, источник OCI, compose или git). |
digest | string | да | Дайджест содержимого разрешённого архива .tar.gz в виде sha256: и 64 шестнадцатеричных символов в нижнем регистре. Проверка во время сборки читает байты слота кэша, заново вычисляет дайджест и сравнивает его с этим полем; при несовпадении сборка останавливается с сообщением о несовпадении дайджеста содержимого. Шаблон: ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | нет | Дайджест манифеста OCI разрешённого артефакта в виде sha256: и 64 шестнадцатеричных символов в нижнем регистре. Манифест — независимый корень доверия, по которому проверяется кэшированный архив; дайджест содержимого digest выше — переносимая идентичность, используемая для фиксации в кэше и проверки целостности. Присутствует только для источника, распространяемого через OCI (helm-oci-chart). Шаблон: ^sha256:[a-f0-9]{64}$. |
mediatype | string | да | Канонический тип медиа, объявленный реестром (или значение по умолчанию для вида, если у вида нет метаданных реестра). Записывается как диагностические сведения о происхождении. |
referenced_by | SourceArtifactReference[] | да | Сущности каталога, которые разрешились в этот артефакт, отсортированные по (uri, field) для детерминированного вывода. Запись существует только потому, что её загрузил Recipe или FeatureRecipe, поэтому список никогда не бывает пустым. Не менее 1 записи. |
Дополнительные свойства не допускаются.
SourceArtifactReference
Одна обратная ссылка «сущность каталога → исходный артефакт». entity и uri вместе идентифицируют сущность каталога; field указывает путь на стороне источника внутри spec сущности, где был объявлен артефакт. Необязательный requested_ref: сохраняет авторский spec.source.ref: сущности Recipe и записывается всякий раз, когда Recipe его задаёт (теги/ветки git-repository → SHA коммита).
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
entity | enum | да | Вид сущности каталога, которой принадлежит эта обратная ссылка. Допустимые значения: "recipe", "feature_recipe" |
uri | string | да | Канонический URI сущности Recipe или FeatureRecipe (например, hub.aggrega.ai/recipe/helm/mariadb-bitnami:1.0.0). |
field | string | да | Путь на стороне источника внутри spec сущности, где был объявлен артефакт. Значение — spec.source. |
requested_ref | string | нет | Необязательно — авторский spec.source.ref: сущности Recipe, записываемый всякий раз, когда Recipe его задаёт. Для Recipe вида git-repository с ref: v1.0.0 здесь сохраняется "v1.0.0", а pinned_version: содержит коммит, в который разрешилась эта ссылка. Отсутствует, когда Recipe не задаёт ref:, — это все виды, чей резолвер фиксирует авторскую версию дословно (helm-, compose-). Поле выполняет сразу две задачи, и именно безусловная запись не даёт им исключать друг друга. Сборка соединяет по нему, чтобы найти эту запись по Recipe, указывающему ссылку, а не коммит. А pull, не являющийся обновлением, удерживает каждую записанную ссылку на её зафиксированной версии: если ссылка в удалённом репозитории сдвинулась, выполнение останавливается, а не принимает новое значение. |
Дополнительные свойства не допускаются.
VerifiedSignature
Факт проверенной подписи, записываемый, когда подпись артефакта была проверена во время pull по политике доверия реестра, через который он разрешён. Каждый подписываемый артефакт записывает его одинаково — сущность каталога, библиотека, Wasm-плагин, — потому что все они проверяются по одному пути, а не по отдельному для каждого вида. Записывает режим проверки, совпавшие keyless-идентичность и издателя (для keyless) и адресуемый по содержимому дайджест пакета подписи в кэше содержимого. Сборка не выполняет проверку повторно. Прежде чем что-либо отрисовать, она читает этот факт в каждой записи, из которой строит, во всех разделах: заново хэширует закэшированный пакет и сравнивает результат с bundle_digest, останавливаясь, если блоб отсутствует или отличается; а для записи, выданной кэшем содержимого, читает из этого пакета, для какого артефакта была сделана подпись, и останавливается, если она сделана для другого артефакта, чем тот, который сборка прочитала для записи, — так что signature, скопированная из одной записи в другую, отклоняется, что бы ни говорило требование подписи. Сборка не проверяет подписи, поэтому пакет, записанный в кэш вручную и выписанный на собственный артефакт записи, неотличим от пакета, проверенного при pull. А если конфигурация доверия рабочего пространства требует подпись для записи, выданной кэшем содержимого, — это требование pull применяет при загрузке артефакта, поэтому пропуски и реестр advisory, позволяющие pull принять артефакт без подписи, позволяют и сборке принять его запись, — то запись без факта останавливает сборку. Запись, прочитанная из каталога, из копии внутри бинарного файла компилятора или из файлов рядом с сущностью Release, никогда не подчиняется этому требованию.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
bundle_digest | string | да | Дайджест SHA-256 блоба закэшированного пакета подписи в виде sha256: и 64 шестнадцатеричных символов в нижнем регистре. Он именует блоб кэша, поэтому образует путь и не содержит /, \ и .. — что форма sha256: уже исключает, — и в записи любого раздела именно с ним сборка сверяет повторный хэш этого блоба. Шаблон: ^sha256:[a-f0-9]{64}$. |
identity | string | нет | Проверенный подписант подписи: субъект подписывающего сертификата для keyless-подписи или keyed:sha256: и SHA-256 PEM-текста закреплённого открытого ключа для подписи с ключом. |
issuer | string | нет | Проверенный издатель OIDC для keyless-подписи. Пусто для подписи с ключом. |
mode | string (enum) | да | Режим проверки, по которому подпись была принята. Допустимые значения: "keyless", "keyed" |
Дополнительные свойства не допускаются.