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

Дисциплина трансляции ошибок

Конвейер компиляции Aggrega выдаёт ошибки из множества источников: валидаторов схем, резолвера, построителя IR, провайдеров, движка шаблонов Go и нижележащих библиотек YAML / Helm / docker-compose, которые оборачивают провайдеры. Ошибки, доходящие до CLI, начинаются с заголовка в квадратных скобках, называющего до двух вещей: категорию, которая указывает, на какую область следует обратить внимание (для большинства значений — на виновную поверхность авторинга), и короткий код условия, остановившего сборку. За заголовком следуют указатель на источник и сообщение. Если условие вызвал плагин, код уточняется плагином, который его вызвал, поскольку о том же самом условии может сообщить более чем один плагин. На этой странице описана форма такого вывода, чтобы авторы могли интерпретировать сообщения об ошибках напрямую.

Каталог ошибок по отдельности (каждая фатальная остановка с указаниями по исправлению) см. в fatal-halts.md. Четыре уровня валидации схем и взаимодействие форм их ошибок описаны в vocabulary/validation-surface.md.

Категории ошибок

Тег категории указывает, какой аспект следует проверить. Большинство тегов называют поверхность авторинга, где находится исправление; остальные называют аспект, который не является ничьей ошибкой авторинга, — получение артефакта, вердикт управления или доверие и подпись, — и в каждом случае конкретное условие определяет короткий код в заголовке рядом с категорией:

  • [DEVELOPER_ERROR] — сбой относится к авторингу сущности Aggregate. Исправление находится в YAML сущности Aggregate или в части каталога, написанной разработчиком (значения Component, сокеты uses, подключения Feature). Примеры поверхностей: остановки резолвера из-за проблем на стороне Aggregate; нарушения селекторов и appliesTo в том, что написал Aggregate.
  • [OPS_ERROR] — сбой относится к собственным документам оператора, Release и Manifest. Исправление находится в YAML сущности Release (топология границ, значения параметров, подключения Feature на уровне Release) или в YAML сущности Manifest (через какой Recipe развёртывается тип и привязки аннотаций, записанные рядом). Примеры поверхностей: валидация схемы Release; вычисление шаблонов путей границ; коллизии subDirectory между провайдерами; отказы сопоставления и привязки аннотаций в Manifest; правило, отклоняющее соединение, которое связывает Release, или подключение, которое он заполняет на соединении, — селектор сокета, селектор слота, слот, объявленный сокетом обязательным; правило, отклоняющее Feature, который подключает только Release, к компоненту или к границе, — appliesTo сущности Feature, селектор слота, его объявленная схема.
  • [CATALOG_ERROR] — сбой относится к сущности каталога (Recipe, FeatureRecipe, Component, Feature, Plugin). Исправление находится в содержимом каталога. Примеры поверхностей: правила формы Recipe; перекрёстные проверки featuresSchema сущности Workload; ошибки разбора шаблонов в шаблонах, написанных в каталоге.
  • [TRANSLATION_ERROR] — сбой относится к синтезу на стороне провайдера (плагин провайдера пытается преобразовать Workload, вывод valuesMapping или подключённый оверлей в нативные артефакты провайдера). Исправление обычно находится в форме services / containers / volumes сущности Workload, в выводе шаблона valuesMapping сущности Recipe или в структуре оверлея в режиме источника.
  • [FETCH_ERROR] — сбой относится к получению закреплённой зависимости из реестра или удалённого источника, а не к какой-либо поверхности авторинга. Исправление обычно эксплуатационное: аутентифицироваться в реестре (docker login <registry>), восстановить связь или заново закрепить изменившийся или подменённый артефакт (aggrega pull --upgrade --release <release>). Примеры поверхностей: сущность каталога или чарт не найдены в реестре; требуется аутентификация или она не удалась; сеть недоступна; дайджест кэшированного артефакта не совпадает с lock-файлом. Ошибки получения содержат в сообщении конкретное указание на способ исправления.
  • [POLICY_ERROR] — сборку отклонил плагин политики, подключённый в роли вердикта управления. Это не ошибка поверхности авторинга: входные данные корректны, но не проходят правило управления (соответствие требованиям, FinOps или безопасность), которое применяет плагин. Исправление — привести написанное вами в соответствие с применяемой политикой или пересмотреть подключение политики. Сообщение называет отклонивший плагин и содержит переданное им сообщение правила.
  • [TRUST_ERROR] — слой доверия и подписи отклонил операцию. Эта категория называет аспект, а не поверхность авторинга, и охватывает два способа исправления, которые можно различить по короткому коду рядом с ней. Неверна ваша конфигурация доверия: политика доверия, которую невозможно прочитать, закреплённый корень доверия, который невозможно загрузить, политика keyless, не объявляющая ни одной доверенной идентичности, политика подписи, требующая подпись для публикуемого вами вида артефакта, или плагин, записанный как доверенный для подключения вердикта, которое ваша конфигурация больше не подключает. Этот артефакт не прошёл проверку: подпись, которая не проверяется по якорю доверия, артефакт без подписи там, где она обязательна, подпись реального, но недоверенного подписанта, или плагин, записанная доверенная идентичность которого больше не совпадает с разрешаемой. В первом случае исправление находится в вашей конфигурации или в зафиксированной записи доверия; во втором это решение об артефакте — восстановить проверенный или проверить и заново записать то, что изменилось.

Замечание о подключении Feature следует за документом, который его записал

Feature можно подключить в любом из документов — Aggregate подключает его на компоненте или на подсистеме, Release — в своей записи для компонента или на границе, — поэтому категория замечания о подключении определяется по месту, где подключение записано, а не по компоненту, которого оно достигает. Замечание размещается у записи features:, которая записала подключение, в этом документе, и относится к автору этого документа: подключение, которое делает только Release, сообщается по собственному пути Release как [OPS_ERROR], а подключение, которое делает Aggregate, — по пути Aggregate как [DEVELOPER_ERROR].

[OPS_ERROR E0007] release.yaml at .spec.boundaries.main.components.app.features.metrics
selector violation ("component.aggrega.ai/type in (server, worker)", declared by Feature "core/prometheus-exporter", not satisfied by the labels of "app"). Add the labels the Feature's appliesTo requires to this component's type, or attach a Feature whose applicability the component already satisfies.

Если одно подключение записывают оба документа — Aggregate называет свой Feature, Release задаёт его размер, — замечание о подключении в целом размещается там, где назван его Feature, то есть в Aggregate. Замечание об одной части его конфигурации размещается там, где эта часть записана: его values принадлежат разработчику, в Aggregate, а его infra — оператору, в Release. Подключение, созданное расширением на основе аннотаций, не записано ни одной записью features:, поэтому замечание о нём размещается у компонента, в документе, объявляющем компонент, как [DEVELOPER_ERROR].

Обязательный слот, оставленный пустым, — единственный случай, который не записал ни один документ. Указывать не на что, поэтому замечание остаётся у компонента в Aggregate и относится к [DEVELOPER_ERROR], а его способ исправления называет оба документа, поскольку заполнить слот может любой из них: «Подключите Feature с этим именем в Aggregate или в Release, на компоненте или в области выше него».

Редактор использует то же размещение: замечание, размещённое в Release, отображается в документе Release, на ключе, который его записал, и вовсе не отображается в документе Aggregate; замечание, размещённое в документе модуля, который импортирует Aggregate, таким же образом отображается в документе этого модуля.

Формат вывода

Выводимая диагностика начинается с заголовка в квадратных скобках и указателя на источник, а сообщение помещается на отдельную строку с отступом:

[CATEGORY SHORTCODE] <source>
<message>

Заголовок содержит два токена, и они отвечают на разные вопросы. Категория — одна из перечисленных выше; она указывает, какую область следует проверить. Короткий код состоит из буквы E и четырёх цифр и называет точное условие, остановившее сборку: укажите его в отчёте, введите в поиск или найдите в таблице всех условий в sentinels.md. Ни один из них не выводится из другого, поэтому выводятся оба — а там, где категория охватывает несколько способов исправления, как [TRUST_ERROR], именно короткий код говорит, с каким из них вы столкнулись.

Код, выданный плагином, уточняется идентификатором этого плагина

Каждый короткий код называет условие, которое объявляет Aggrega, и никакие два условия не делят один код: условие, объявленное под номером, который уже занят другим условием, отклоняется до того, как компилятор прочитает какие-либо входные данные. Плагин не выделяет собственных кодов. Сообщая о сбое, он называет одно из условий, объявленных Aggrega, — одно из нескольких общих условий, описывающих, как плагин дал сбой, или более конкретное, если оно подходит, — и передаёт предложение, говорящее, что на самом деле произошло. Поэтому два плагина могут сообщить один и тот же короткий код, и в этом случае они сообщают об одном и том же условии.

Чего код сказать не может — так это какой плагин столкнулся с условием, и заголовок, сообщающий об условии, выданном плагином, содержит идентификатор плагина непосредственно перед кодом:

[CATEGORY PLUGIN/SHORTCODE] <source>
<message>

Короткий код — всегда последний сегмент: буква E и четыре цифры после последнего /. Идентификатор плагина содержит собственные разделители и может содержать версию, поэтому код можно извлечь из любого заголовка, только если читать с конца, а не от первого /. Всё, что стоит перед последним сегментом, — это плагин.

Последний сегмент распознаётся как любой другой короткий код, какой бы плагин его ни выдал: его перечисляет таблица всех условий в sentinels.md, и aggrega explain его распознаёт. Цитируйте только последний сегмент — уточнение говорит, какой плагин столкнулся с условием, а не какое это условие. Если плагин называет код, который Aggrega не объявляет, — номер, не занятый ни одним условием, или выведенный из употребления, — этот код не печатается: сборка останавливается на E0293, уточнённом этим плагином, а её сообщение цитирует код, предложенный плагином, называет те общие условия и сохраняет собственное предложение плагина.

Заголовок с коротким кодом без уточнения сообщает об условии, выданном самой Aggrega, в том числе в случае, когда плагин завершился ошибкой, не назвав собственного условия. Тогда сборку остановило общее условие компилятора об ошибке плагина, а подробности содержатся в сообщении плагина.

Любой из токенов может отсутствовать, и отсутствующий опускается

Токен, которого у диагностики нет, ничем не заменяется — ни заполнителем, ни пустыми скобками. Заголовок может быть сокращён тремя способами, и каждый из них что-то сообщает:

  • Нет короткого кода. Ошибка не называет ни одного собственного условия Aggrega — чаще всего это сбой, о котором сообщила библиотека, обёрнутая компилятором. Заголовок выводит только категорию, так что вы всё равно знаете, какую область проверить.
  • Нет категории. У ошибки нет области, к которой можно вас направить, поэтому она не угадывается. Заголовок выводит только короткий код, и именно его следует искать. Такое возникает в двух ситуациях, и выглядят они одинаково, потому что для ваших целей они одинаковы: ни одна не говорит, где искать, а код говорит, что произошло. Первая — сбой в самом компиляторе: сообщение говорит об этом и просит сообщить о нём; на практике это случай, когда собственные представления компилятора о каталоге расходятся друг с другом. Вторая — ошибка, которая называет условие, но не прошла через уровень, относящий её к какой-либо области; это обычный вид отказа, выданного на границе команды. Категория никогда не придумывается, чтобы заполнить пробел, и в этом смысл её отсутствия, а не его недостаток: категория отвечает на вопрос «какую область проверить», а ответ там, где у вопроса ответа нет, — не осторожный, а неверный, и действовать по нему начнут в первую очередь. Стоит также сказать, что обратный вывод неверен: заголовок, который содержит категорию, не всегда указывает на то, что написали вы, потому что [FETCH_ERROR], [POLICY_ERROR] и [TRUST_ERROR] называют область, а не уровень авторинга.
  • Нет ни того, ни другого. Скобки опускаются полностью, и диагностика — это само сообщение. Это ошибка, которая не называет ни одного собственного условия Aggrega и не имеет области, к которой можно вас направить: команда, отклоняющая свои аргументы, файл, который она не может прочитать, отмена или сбой, о котором сообщила библиотека, обёрнутая компилятором, без какого-либо нашего условия под ним. Искать в sentinels.md нечего, и сообщение — это всё, что ошибка может сказать.

Та же ошибка, сведённая к одной строке, — форма, предназначенная для журналов, а не для терминала, — содержит категорию и опускает короткий код:

[CATEGORY] <source>: <message>

Категория, отсутствующая в заголовке, отсутствует и здесь вместе со скобками, поэтому эта строка никогда не имеет вид [] <source>: <message>. Однострочная форма по мере подъёма ошибки заново оборачивается во внешние фреймы, так что пустой тег перешёл бы в каждый из них.

Источник — это структурированный указатель: обычно <file>:<line>:<column>, когда известна позиция в YAML, или логический идентификатор (имя сущности каталога, имя Release, путь границы), когда позиция в файле неприменима. Третий вид, <file> at <key>, появляется, когда указатель знает и документ, и ключ авторинга в нём, но не позицию в байтах: файл — это то, что нужно открыть, а ключ — то, на что смотреть после открытия. Сообщение — это диагностика конкретного уровня.

Сбой, касающийся одного экземпляра вашей сборки — компонента, компонента, который вносит модуль, или самого модуля, — называет этот экземпляр после позиции в виде (instance <name>), так что aggregate.yaml (instance shop) — это Aggregate, объявляющий модуль shop. Если у сбоя нет документа, на который можно указать, экземпляр стоит отдельно как instance <name>: провайдер, давший сбой при рендеринге компонента adminer, выводит [TRANSLATION_ERROR E0082] instance adminer, а строки под ним содержат остальную часть сбоя, включая любой документ, который он называет. Имя — то, под которым Aggregate объявляет компонент; компонент, который вносит модуль, называется своим путём через модуль, например shop.cart. Экземпляр никогда не выводится там, где должен быть файл, поэтому то, с чего начинается указатель источника, — всегда документ, который можно открыть, или один из перечисленных выше логических идентификаторов.

Правило, вычисляемое по готовому графу, сообщает в третьем виде, и ключ различает две находки, когда одного сообщения недостаточно. Такое правило называет объявляющий тип компонента, а не экземпляр, поэтому два компонента одного типа, нарушающие одно правило, несут одинаковое сообщение об одном и том же файле:

[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.checkout
missing required feature: attach a Feature of the required type to the component ("core/observability/monitoring", required by component type "core/compute/api-server", under the requirement label "monitoring")
---
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.inventory
missing required feature: attach a Feature of the required type to the component ("core/observability/monitoring", required by component type "core/compute/api-server", under the requirement label "monitoring")

Различается только ключ, и именно он указывает, какой из двух компонентов править. Обе находки несут один и тот же короткий код, потому что это одно и то же условие, встреченное дважды: короткий код называет правило, а ключ — конкретный случай.

К формату относятся ещё две строки — для ошибки, у которой есть контекст для их заполнения: шаблонное выражение, вызвавшее сбой, и снимок столпов, доступных в месте сбоя:

[CATEGORY SHORTCODE] <source>
<message>
expression: <the template excerpt that triggered the failure>
active pillars:
<one line per top-level pillar key in scope at the point of failure>

Строка expression: содержит фрагмент шаблона, вызвавший ошибку. Блок active pillars: перечисляет ключи столпов верхнего уровня, доступные в точке сбоя, чтобы авторы видели, что можно было запросить. Обе опускаются, если ошибка не несёт ни того, ни другого.

Вложенные фреймы контекста

По пути к CLI ошибка часто проходит через несколько поверхностей: фаза загрузки оборачивает конкретный сбой сущности, который, в свою очередь, оборачивает сигнальную ошибку, объясняющую правило. Каждый категоризированный фрейм такой цепочки выводится: самый внешний — как заголовок в описанной выше форме, а каждый вложенный — как продолжение caused by: с отступом, со своим тегом категории, указателем на источник и сообщением. Самый внутренний фрейм с указанием файла всегда виден:

[CATALOG_ERROR E0094] aggrega-catalog
catalog load
caused by: [CATALOG_ERROR] aggrega-catalog/recipe/compose/mariadb-copy/1.0.0/recipe.yaml
duplicate entity identity within a single catalog directory (recipe identity "compose/mariadb:1.0.0")

Короткий код есть только в заголовке, а продолжения несут лишь свою категорию. Условие называется один раз — там, где читатель встречает сбой; фреймы под маркером caused by: — это тот же сбой, увиденный глубже, поэтому повторение его идентификатора в каждом добавило бы строки, не добавив фактов. Блок note: не является продолжением и этому правилу не следует: он сообщает об условиях других документов, а не о том же условии, увиденном глубже; он описан в разделе ниже. Код, который выводит заголовок, — это код, названный цепочкой (здесь — правило в самом низу), поэтому фрейм контекста фазы наверху всё равно идентифицирует условие под ним.

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

Цепочка становится глубже всякий раз, когда сбой на пути наружу проходит через большее число поверхностей, и правило соблюдается на любой глубине. Шаблон, отклонённый внутри синтезированного Workload сущности Recipe, проходит через три — отрисовываемый узел, поверхность шаблонов Recipe и сам шаблон:

[CATALOG_ERROR E0060] instance db
rendering node "db"
caused by: [CATALOG_ERROR]
recipe "mariadb" workload template
caused by: [CATALOG_ERROR] workload[mariadb]
template references a root the render context does not define (template "workload[mariadb]" references ".nosuchroot.database", the render context defines .context, .values, .infra, .locals, .provides, .features, .metadata, .attachment_name, .inject, .inject_raw, .steps, .source, .workload, .boundary)

Читайте её сверху вниз, как и раньше, и обратите внимание на три вещи, которые становятся видны благодаря дополнительной глубине. Короткий код появляется один раз, в заголовке, сколько бы продолжений за ним ни следовало. Самый внутренний фрейм — это место, где находится собственная формулировка условия, поэтому самая глубокая строка — одновременно та, по которой следует сопоставлять, и та, что говорит, что изменить. И фрейм без указателя на источник выводит только свою категорию: средний фрейм выше называет поверхность, на которой произошёл сбой, внутри своего сообщения, потому что эта поверхность — шаблон, а не файл, и указывать в ней не на что.

Когда сбой разветвляется под фреймом — фаза собрала несколько независимых нарушений перед остановкой, — продолжение содержит их число, и под ним выводится каждый собранный сбой, разделённые той же чертой ---, что используется в цепочках из нескольких ошибок ниже:

[OPS_ERROR E0099]
recipe resolution
caused by (2):
[OPS_ERROR] .spec.components.edge
no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.edge, "edge", of type "example/gateway/nginx-reviewed"). no recipe in the catalog implements this type; write one, then map the type to it
---
[OPS_ERROR] .spec.components.internal
no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.internal, "internal", of type "example/gateway/nginx-reviewed"). no recipe in the catalog implements this type; write one, then map the type to it

Собранные сбои под счётчиком тоже являются продолжениями, поэтому ни один из них не повторяет короткий код заголовка — именно это не даёт разветвлению из дюжины нарушений выводить один и тот же идентификатор дюжину раз.

Везде действует одна грамматика разделителей: --- между соседними сбоями, caused by: между вложенными фреймами контекста.

Отклонённый файл каталога и сбой, который он объясняет

Загрузка каталога для разрешения зависимостей сущности Release намеренно терпима к ошибкам: файл, который не удаётся прочитать, или документ Aggrega, который не удаётся разобрать или проиндексировать, отклоняется и фиксируется, а не прерывает всю загрузку. Именно поэтому повреждённая сущность, которой ваш Release никогда не касается, не приводит к сбою несвязанной сборки.

Следствие этого — отклонённый файл молча исчезает из каталога, и если ваш Release всё же до него доходит, сбоем завершается попытка разрешить ссылку на то, что этот файл объявлял. Этот сбой — следствие отклонения, а не само отклонение, поэтому отчёт выстраивает их в причинном порядке везде, где может точно назвать отклонение:

[CATALOG_ERROR E0215] catalog/recipes/helm/server.yaml
document envelope validation failed (Recipe, at catalog/recipes/helm/server.yaml); 6:1: spec.implements: missing required property: implements. correct the document to match its kind's schema
note: this file was skipped at load, so the catalog holds nothing under the identity it declares.
This Release reaches that identity, so what failed is the attempt to resolve the reference to it:
resolve entity "server-recipe:1.0.0": catalog: tier-3 pull server-recipe:1.0.0: recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI location: "server-recipe"

Первым идёт отклонение, со своей категорией и своим кратким кодом, потому что оно называет то, с чем можно что-то сделать: исправление — это недостающий implements: в сущности Recipe, а вовсе не что-либо связанное с тем, как ссылка ищется в реестре. Сбой разрешения по-прежнему сообщается, под ним, потому что именно он объясняет, зачем вообще понадобился этот документ.

Отклонение идёт первым, только когда ровно один отклонённый файл объявляет идентичность, которую называет сбойная ссылка. Сопоставление ведётся по идентичности, которую каждый документ объявляет сам для себя, — его виду, имени, версии, а для рецепта ещё и spec.capability, задающему его область, — поэтому отклонённый файл, объявляющий то, что запрашивает ссылка, и есть файл, в который эта ссылка была бы разрешена. Отсюда два следствия. Ссылка, указывающая диапазон версий, а не версию, не называет ни одного конкретного документа, поэтому ничего не выделяет. А документ, настолько некорректный, что его заголовок невозможно прочитать, не объявляет никакой идентичности, поэтому он никогда не называется причиной чего-либо.

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

[E0105]
resolve entity "server-recipe:1.0.0": catalog: tier-3 pull server-recipe:1.0.0: recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI location: "server-recipe"
note: catalog files skipped at load. A refusal outside this Release's closure is tolerated and never fails a build,
so this failure is explained only by a refusal naming something this Release reaches:
- Recipe "server-recipe" (catalog/recipes/helm/server.yaml): [CATALOG_ERROR E0215] catalog/recipes/helm/server.yaml: document envelope validation failed (Recipe, at catalog/recipes/helm/server.yaml); 6:1: spec.implements: missing required property: implements. correct the document to match its kind's schema

О второй форме стоит знать несколько вещей, потому что каждая отвечает на вопрос, который иначе возник бы при чтении блока.

Заголовок называет сбой, а не отклонение. Краткий код вверху — тот, который выдал сбой разрешения, потому что здесь первым идёт именно этот сбой: ни один отклонённый файл не был выделен, поэтому ни один из них не возглавляет строку. Рядом с кодом нет категории, потому что на этом пути ничто не отнесло сбой к какой-либо области. Собственный заголовок каждого отклонения стоит в его отдельной записи ниже — там его и следует читать.

Перечисляются все отклонения, а не только то, которое имело значение. Появление этой формы означает, что запись не смогла выделить одно из них, поэтому примечание формулирует различие, а не гадает: отклонение за пределами замыкания этого Release допускается и не может быть причиной сбоя, так что единственной записью, объясняющей сбой, остаётся отклонение, называющее то, до чего доходит Release. Сверяйте записи с тем, что ваш Release действительно использует.

Каждая запись несёт собственный заголовок в квадратных скобках — свою категорию и свой краткий код. Это единственное место, где краткий код появляется ниже заголовка диагностики, и это не исключение из приведённого выше правила продолжений, а его следствие: запись под note: — не тот же сбой, увиденный глубже, а другое условие, выданное другим документом. Название её условия позволяет найти отклонение и исправить файл, а именно ради этого действия блок и существует.

Отклонённый файл, заголовок которого слишком повреждён, чтобы восстановить объявленную в нём идентичность, указывается только по пути. Это честное прочтение документа, в который ничто не смогло заглянуть, и пути всё равно достаточно, чтобы открыть файл. Файл, настолько повреждённый, что не удаётся прочитать даже его вид, — например, не разбирающийся как YAML, — указывается таким образом, если он объявляет apiVersion Aggrega строкой, начинающейся без отступа с apiVersion: и значения, начинающегося с aggrega.ai/, вместе с причиной от самого парсера: строкой и тем, что парсер ожидал в ней. Файл YAML, объявляющий другую apiVersion или не объявляющий её вовсе, не является документом Aggrega — это, например, шаблон чарта или файл конфигурации, хранящийся рядом с сущностями, — поэтому он никогда не указывается, как бы сильно он ни был повреждён.

Файл, объявляющий вид, которого нет ни в одном каталоге, называется только там, где он объясняет сбой. Документ, объявляющий apiVersion Aggrega и kind, которого нет ни в одном каталоге, — например, Componnent с опечаткой, — пропускается при каждой загрузке, поэтому он не является отказом и не перечисляется среди отказов. Когда сбойная ссылка запрашивает имя, которое объявляет этот файл, и версию, если ссылка её указывает, отчёт называет этот файл в собственном примечании под сбоем, независимо от того, к какому виду была отнесена ссылка при сборе, — на каждой из перечисленных ниже поверхностей и в aggrega build, читает ли он существующий lock-файл или сначала заполняет его:

[E0114]
resolve: no entity in the catalog matches this URI: entity "<reference>" (referenced from <referring paths>)
note: a catalog file declares the name this reference asks for under a kind a catalog does not hold,
so the load skipped it:
- Componnent "<name>" (<path>): [CATALOG_ERROR E0371] <path>: catalog document declares a kind a catalog does not hold (kind "Componnent"). a catalog holds Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary, Aggregate and Plugin documents, and passes over a Workload, a Manifest or a Release; correct the kind, or move the file out of the catalog directories

Сбой по-прежнему идёт первым: вид, который объявляет файл, не задаёт никакой идентичности, поэтому файл никогда не выделяется как отказ, с которого начинается отчёт. Пояснение о том, откуда читаются локальные сущности, в этот отчёт не включается, поскольку файл уже находится там, откуда читает каталог, и его перемещение не помогло бы. Файл вида, которого нет ни в одном каталоге, объявляющий какое-то другое имя, ничего не объясняет в этом сбое и не упоминается. aggrega serve, сообщения которого занимают одну строку, помещает в эту строку то же примечание — note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it:, за которым следует отказ файла, — и никогда не перечисляет такой файл среди файлов, пропущенных при загрузке; инструмент describe из aggrega mcp, когда его спрашивают об имени в терминах сущности Release, также называет этот файл вместо того пояснения. aggrega validate и aggrega lint для всего каталога сообщают о каждом таком файле независимо от того, доходит ли до него что-либо, — см. fatal-halts.md §«A catalog document declares a kind a catalog does not hold (Документ каталога объявляет вид, которого каталог не содержит)».

Какую бы форму вы ни получили, сбой сохраняет собственную идентичность. Примечание добавляется к сбою, а не выводится вместо него, а вывод отклонения первым меняет лишь то, что вы читаете сначала, — поэтому условие, выданное сбоем, в любом случае остаётся неизменным: его краткий код по-прежнему разрешается, а инструмент, сопоставляющий по условию, по-прежнему находит совпадение.

Если отклонённый документ сам является тем, о чём сообщает команда, отклонение указывается один раз. aggrega inspect <name> загружает каталог в строгом режиме, поэтому отклонённый при загрузке документ её останавливает, и выводится отклонение этого документа в виде одной диагностики: заголовок с категорией и кратким кодом отклонения, документ в качестве источника, а под ним — что не так с документом: для нарушения схемы — нарушенные ключи с их строками и столбцами, а также совет. Загрузка, выдавшая отклонение, прошла через обходимый каталог и шаг чтения файла, но они не выводятся отдельными фреймами, потому что каждый снова назвал бы тот же документ, не добавив ни одного факта. aggrega serve на вопрос о том, на что ссылается имя, если это имя объявляет отклонённый документ, отвечает тем же отклонением теми же словами в одной строке, за которым следует примечание о том, что файл был пропущен при загрузке. Как и выше, условие отклонения в любом случае остаётся доступным для сопоставления.

Обе формы доходят до вас везде, где выполняется это разрешение. aggrega build, aggrega pull, aggrega validate --release и aggrega inspect --closure выводят их в терминале, как и aggrega validate для одной сущности Recipe, цель implements которой не найдена, а ИИ-ассистент, подключённый через aggrega mcp, получает тот же отчёт от инструментов build и validate, а также ведущий отказ одной строкой при чтении через catalog:// сущности, которую объявляет отклонённый файл. Поверхность, через которую вы спросили, никак не влияет на то, какой файл вам предлагают открыть, — вызывающей стороне, обращающейся к aggrega mcp по HTTP, путь сообщается относительно корня рабочего пространства, а файл за пределами рабочего пространства, которое обслуживает этот сервер, ей не сообщается, — и если первым идёт отклонение, ответ указывает на контракт написания для того вида, который объявляет отклонённый документ, а не для вида сбойной ссылки.

Класс ошибок оболочки документа

Каждый документ сущности — сущности каталога, Aggregates, Manifests, Releases — при загрузке проверяется по опубликованной JSON-схеме своего вида, до типизированного разбора. Документ, нарушающий свою оболочку (неизвестный ключ, отсутствующее обязательное поле, значение неверной формы, запрещённая конструкция, например values: в сущности Release), явно останавливает работу с диагностикой, которая сначала называет условие, затем вид сущности и файл, затем каждый ошибочный ключ или форму со строкой и столбцом, где он находится, и наконец указывает, что с этим делать:

[OPS_ERROR E0215] release.yaml
document envelope validation failed (Release, at release.yaml); 12:7: spec.boundaries.main.values: against /$defs/boundary: unexpected property: "values". correct the document to match its kind's schema

Диагностика начинается с условия, называет вид и файл и завершается указанием, что делать; каждое нарушение между ними содержит только line:column, поскольку файл уже назван в заголовке. Каждый ошибочный ключ сообщается в своей собственной позиции, а не в позиции содержащего его блока, поэтому строка и столбец указывают на ключ, который нужно изменить. Если форма в данной позиции задаётся переиспользуемым определением в схеме, диагностика называет это определение после слова against — выше это against /$defs/boundary, — чтобы было ясно, с каким контрактом сверялся ключ, и чтобы определение не читалось как ещё один шаг по написанному вами пути ключа. Документ с несколькими нарушениями перечисляет каждое в его собственной позиции в порядке ключей, а после четырёх отчёт останавливается и указывает количество оставшихся.

О том, куда указывает позиция, полезно знать две вещи, потому что обе скорее полезны, чем удивительны:

  • У отсутствующего обязательного ключа нет собственной позиции — по определению его нет в документе. Вместо этого нарушение указывает на объемлющий ключ, где и должна находиться недостающая запись. Так, spec.capability: missing required property указывает на spec:, и именно туда его нужно добавить.
  • Ключ, имя которого само содержит точку, — каждая метка component.aggrega.ai/… и аннотация features.aggrega.ai/… — сообщается в блоке, который его содержит, а не в самой записи, поскольку точки читаются как шаги вглубь документа. Нарушение в метке указывает на labels:.

Если нарушение называет ключ, которого в документе нет вовсе, — например, пропущен целый блок metadata:, — позиция опускается, а не угадывается, и нарушение содержит только путь ключа и сообщение. Позиция, которой пришлось бы не доверять, хуже, чем никакая.

Категория следует поверхности авторинга: [CATALOG_ERROR] для сущностей каталога, [DEVELOPER_ERROR] для Aggregates, [OPS_ERROR] для Releases и Manifests. Та же проверка выполняется на каждой поверхности, загружающей сущности, — aggrega build, aggrega lint, aggrega validate и диагностика редактора, которую публикует aggrega serve, — поэтому лишний или опечатанный ключ отклоняется там, где документ читается впервые, а не отбрасывается молча. Каждая из этих поверхностей определяет позицию одинаково, поэтому все они указывают на один и тот же ключ, и каждая берёт предложение условия из самого условия: строка, которую подчёркивает редактор, — это строка, которую называет терминал, а предложение, которым открывается запись редактора, — то же, которым открывается вывод терминала. Чего эти две поверхности не разделяют, так это сообщения целиком, и это сделано намеренно: терминал группирует все находки под одним заголовком и завершает советом для данного пути, а редактор выдаёт по одной записи на находку, размещённой на её собственном ключе, не повторяя ни файл, к которому запись уже привязана, ни совет, который иначе повторялся бы для каждого подчёркивания. Таким образом, совпадает именно та часть, по которой вы узнаёте условие.

Цепочки из нескольких ошибок

Когда одна компиляция обнаруживает несколько независимых нарушений (чаще всего при статическом анализе, где все нарушения селекторов и appliesTo собираются до того, как какое-либо из них остановит сборку), ошибки объединяются в одну цепочку. CLI проходит по цепочке и выводит каждую вложенную ошибку отдельно, разделяя их строкой горизонтальной черты:

[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge.uses.reviewed_upstream.internal
selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.
---
[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge2.uses.reviewed_upstream.internal
selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.

Разделитель --- выводится буквально: читатели и последующие инструменты могут разбивать вывод по нему, чтобы перечислить объединённые ошибки. Каждая вложенная ошибка — самостоятельный сбой, а не подробность соседней, поэтому у каждой есть собственный заголовок: собственная категория и собственный короткий код, каждый — там, где он есть, как описано в разделе об отсутствующих элементах. Два нарушения одного правила называют один и тот же короткий код, как в примере выше; два нарушения разных правил называют разные коды.

Чтение ошибки от начала до конца

В большинстве случаев при написании префикс категории вместе с указателем на источник определяют, что нужно исправить:

КатегорияГде находится исправлениеПримеры проявлений
[DEVELOPER_ERROR]YAML сущности AggregateНарушения селекторов / appliesTo в том, что написала сущность Aggregate; несоответствие сокета uses на стороне Aggregate; остановки резолвера из-за написанного разработчиком.
[OPS_ERROR]YAML сущности Release / YAML сущности ManifestШаблон пути границы ссылается на неподдерживаемое поле; subDirectory вызывает коллизию путей; остановки резолвера из-за написанного в Release; соединение, которое связывает Release, или вложение, которое оно заполняет в соединении, отклонено правилами сокета или слота; сущность Feature, которую прикрепляет только Release — к компоненту или к границе, — отклонена правилами Feature или слота; отклонена привязка маппинга или аннотации сущности Manifest.
[CATALOG_ERROR]Recipe / FeatureRecipe / Component / Feature / PluginПравила формы Recipe; шаблон FeatureRecipe ссылается на поле, доступное только для отдельного компонента, при executionScope: boundary; не проходит перекрёстная проверка featuresSchema сущности Workload.
[TRANSLATION_ERROR]Workload / вывод valuesMapping / оверлей источникаРазрешение порта пробы Helm; коллизия имён сервисов compose между границами; два участника compose объявляют одно имя тома или конфигурации верхнего уровня с конфликтующим содержимым; несоответствие имени чарта в зонтичном helm-chart.
[FETCH_ERROR]Получение из реестра / удалённого источника (эксплуатационная, а не авторская проблема)Артефакт не найден в реестре; требуется аутентификация; сеть недоступна; дайджест в кэше не совпадает с lock-файлом. Исправление: пройдите аутентификацию, восстановите подключение или выполните aggrega pull --upgrade --release <release>.
[POLICY_ERROR]Плагин политики (правило управления)Плагин политики, прикреплённый в роли вердикта управления, отклонил собранную сборку по правилу, которое он применяет. Исправление: выполните применяемую политику или пересмотрите прикрепление.
[TRUST_ERROR]Конфигурация доверия или собственная подпись артефакта (отдельный аспект, а не поверхность написания)Нечитаемая политика доверия или закреплённый корень доверия; политика keyless, не объявляющая ни одной доверенной идентичности; политика подписи, требующая подписи для публикуемого вида; записанный шлюз прикрепления вердикта, который конфигурация больше не прикрепляет. Либо: подпись не проходит проверку; артефакт не несёт подписи там, где она требуется; недоверенный подписант; плагин, чья записанная доверенная идентичность больше не совпадает. Исправление: исправьте конфигурацию или зафиксированную запись доверия либо примите решение об артефакте — короткий код указывает, что именно.

Префиксы контекста отдельных провайдеров (helm: node "<id>": ..., compose: node "<id>": ...) появляются в части сообщения вывода [TRANSLATION_ERROR] и [CATALOG_ERROR], чтобы указать на сбойный провайдер, когда задействовано несколько провайдеров.

Собственные ошибки библиотек

Ошибки, возникающие внутри используемой библиотеки (ошибки загрузки чартов Helm SDK, ошибки парсера YAML docker-compose, ошибки файлового ввода-вывода из-за отсутствующего исходного пути), оборачиваются контекстным префиксом соответствующего провайдера и выводятся под [TRANSLATION_ERROR] или [CATALOG_ERROR] в зависимости от того, возникли ли они при синтезе или при загрузке содержимого каталога. Обёрнутое сообщение библиотеки дословно сохраняет диагностику исходного инструмента, чтобы авторы могли сопоставить его с собственной документацией инструмента.

Перекрёстные ссылки

  • fatal-halts.md — каталог всех фатальных остановок по ошибкам, с предполагаемым сообщением и способом исправления.
  • warnings.md — нефатальные предупреждения, которые выдаёт компилятор.
  • vocabulary/validation-surface.md — четыре уровня валидации по схеме и то, как взаимодействуют формы их ошибок.