Контракт плагинов Wasm
Конвейер компиляции Aggrega содержит выделенные точки подключения (сокеты), в которых плагины WebAssembly (Wasm) расширяют поведение компилятора: четыре роли сокета управления, среди них Mutation Gate при построении топологии и Validation Gate при статическом анализе; конвейер плагинов после рендеринга для шагов FeatureRecipe и Recipe; сокет рендеринга провайдеров; сокет парсеров; сокет импортёров; и внеполосный сокет линтинга. На этой странице описан публичный контракт плагинов Wasm: какие сокеты существуют, что каждый сокет принимает и выдаёт, где каждый сокет находится в конвейере компиляции, а также песочница, в которой выполняется каждый плагин.
Эта страница посвящена сокетам — точкам конвейера и форме их входных и выходных данных. О плагине — сущности Plugin, заявках на возможности для каждого экспорта, ограничениях среды выполнения и жизненном цикле publish→pull→build — см. руководство разработчика плагинов Wasm.
Aggrega встраивает среду выполнения Wasm-хоста — Extism поверх движка Wazero, — которая загружает и выполняет плагины за брандмауэром AOT-чистоты: хост не предоставляет гостю никаких фоновых возможностей — ни сети, ни файловой системы, ни окружения, stdio отбрасывается, а наблюдаемые настенные часы заморожены на моменте, инвариантном для сборки, — поэтому плагин не может нарушить гарантии компиляции заранее (ahead-of-time), которые даёт компилятор. Полная поверхность возможностей — правило модулей импорта при загрузке, запреты на этапе инстанцирования и курируемые функции хоста — описана в разделе контракт песочницы ниже. Авторы Plugin обращаются к хосту через PDK на трёх языках (Go, Rust, TypeScript). aggrega lint вызывает через хост сокет линтера — стандартный линтер публикации. aggrega build вызывает роли сокета управления на этапе сборки, если они настроены в рабочем пространстве: роль преобразования аннотаций во время разрешения и роль преобразования меток при построении топологии (обе формируют вывод), а также вердикт по IR при статическом анализе и вердикт рендеринга по отрендеренным артефактам. Каждая из них ничего не делает, если к этой роли не подключён плагин, поэтому сборка без конфигурации управления не меняется. aggrega build также выполняет pipeline: для FeatureRecipe и Recipe в конвейере плагинов, завершающем рендеринг: каждый объявленный шаг выполняется через хост над набором отрендеренных документов, применяя патчи RFC 6902 этого шага и порождая его побочные эффекты. См. Состояние языка → Фазы конвейера компиляции.
Контракт песочницы
Каждый сокет вызывает свой плагин через одну и ту же песочницу хоста. Песочница состоит из двух независимых уровней — структурной проверки при загрузке и запрета возможностей при инстанцировании, — и вместе они определяют, к чему плагин имеет доступ, к чему не имеет и за что отвечает сам.
Правило модулей импорта (при загрузке). Загрузчик обходит секцию импорта бинарного файла плагина и допускает импорт функций только из трёх пространств имён модулей: wasi_snapshot_preview1 (среда выполнения WASI preview-1, с которой компонуется среда выполнения гостевого языка), extism:host/env (ABI среды выполнения Extism — собственные встроенные функции PDK для памяти и ввода-вывода) и extism:host/user (отобранные функции хоста Aggrega). Гость может импортировать любое имя функции из разрешённого модуля; импорт из любого другого модуля указывает на поверхность, которую хост не предоставляет, и плагин отклоняется при загрузке с диагностикой, называющей модуль и импорт. Правило намеренно не проверяет отдельные имена функций WASI: статически скомпонованная среда выполнения языка импортирует функции файловой системы и сокетов, которые её рабочие пути кода никогда не вызывают, — они подтягиваются транзитивно через зависимости, — а само объявление импорта ничего не предоставляет. Отсутствие ввода-вывода гарантирует запрет возможностей при инстанцировании, а не цензура импортов.
Нулевые фоновые возможности (инстанцирование). Хост инстанцирует гостя с реальным поведением WASI и нулевыми фоновыми полномочиями:
- нет файловой системы — нет заранее открытых каталогов, поэтому вызов файловой системы завершается ошибкой на границе вызова;
- нет сетевых сокетов;
- пустое окружение;
- отбрасываемый stdio — ничто из того, что гость пишет в stdout или stderr, не попадает в потоки хоста;
- замороженные наблюдаемые часы реального времени, зафиксированные на неизменном для сборки моменте, поэтому гость, читающий время, не может допустить утечку времени сборки в свой вывод;
- реальные идущие монотонные часы — они нужны среде выполнения гостевого языка для запуска, а монотонное время измеряет прошедшую длительность, а не момент по часам реального времени;
- реальная энтропия хоста — зафиксированная энтропия стабилизировала бы внутреннее начальное значение хеша среды выполнения языка и маскировала бы недетерминированность гостя, вместо того чтобы позволить ей проявиться в виде различающегося вывода;
- единственное синтетическое имя программы в качестве argv.
Вызов ввода-вывода, который гость действительно выполняет, — открытие файла, подключение к сокету — завершается ошибкой на границе вызова. Это собственная модель безопасности WASI, основанная на возможностях: песочница запрещает возможность, а не надзирает за кодом.
Входные данные поступают только через полезную нагрузку и отобранные функции хоста. Всё, что плагин рендерит или вычисляет, он получает в полезной нагрузке своего сокета — проекции графа и узлов, значения и контекст рендеринга. Кодировка полезной нагрузки фиксирована для каждого сокета и указана в разделе этого сокета ниже; каждый опубликованный тип полезной нагрузки поставляется с точками входа кодирования и декодирования для кодировки своего сокета, поэтому гость вызывает одну функцию, а не выбирает парсер. Для рендеринга провайдера из исходников полезная нагрузка содержит список исходников, а не байты исходников: отсортированный набор записей {path, is_dir} под корнем исходников узла, без какой-либо интерпретации структуры провайдера со стороны хоста. Гость применяет собственную логику структуры — выбирает единственный compose-файл, спускается к корню чарта, требует наличия Chart.yaml, рекурсивно включает модуль — и считывает ровно выбранный фрагмент через обратный вызов хоста. Помимо полезной нагрузки, хост связывает отобранный набор функций хоста с минимальными привилегиями и предоставляет плагину ровно те из них, которые импортирует его бинарный файл:
aggrega_log— строка журнала в журнал хоста.aggrega_emit_warning— структурированное предупреждение, которое хост выводит после вызова.aggrega_fetch_external_input— канал получения внешних входных данных (см. ниже).aggrega_pack_source— обратный вызов выбора исходников: гость указывает выборку{file | dir | tree, path}под корнем исходников, а хост считывает и упаковывает ровно её в песочнице, которая разрешает пути относительно корня и отклоняет...aggrega_read_source_file— чтение содержимого одного файла в той же песочнице, для выбора исходников в зависимости от содержимого.aggrega_parse_source— обратный вызов потребления продюсера: гость указывает синтаксический формат и передаёт байты исходника, а хост находит парсер для этого формата, запускает его и возвращает созданное им каноническое дерево. Так потребитель получает вывод продюсера через хост, а не вызывает гостя-продюсера сам, и хост ограничивает это одним уровнем — продюсеру, вызванному таким образом, повторный вызов запрещён, — поэтому потребитель вызывает его один раз на исходник и может последовательно потреблять много исходников.
Хост определяет набор импортов плагина по его бинарному файлу .wasm, проверяет его по отобранному списку разрешённых и сверяет с функциями хоста, которые объявляет describe() гостя. aggrega plugin sync записывает этот набор в spec.runtime.hostFunctions сущности, а публикация отклоняет сущность, запись которой расходится с бинарным файлом, поэтому поверхность хоста каждого плагина видна в каталоге и не может расходиться с бинарным файлом.
Ошибки обратных вызовов несут машинно сопоставляемый код в hostfunc_error_code. Обратные вызовы хоста, возвращающие ответ, — aggrega_fetch_external_input, aggrega_pack_source, aggrega_read_source_file и обратный вызов потребления продюсера aggrega_parse_source — передают ошибку внутри ответа: конверт ответа содержит понятное человеку сообщение и рядом с ним необязательный машинно сопоставляемый код в hostfunc_error_code из закрытого словаря. Сообщение — произвольный текст для человека; код — стабильный идентификатор, по которому гость ветвится без разбора сообщения. При успехе код отсутствует; при ошибке хост задаёт и то, и другое. PDK представляет эту пару как типизированную ошибку, текст которой — сообщение, а поле кода гость сопоставляет с реэкспортированными константами кодов языка. Гость допускает отсутствие кода и код, который он не распознаёт, возвращаясь к сообщению, — поэтому сопоставление по коду является уточнением по мере возможности поверх всегда присутствующего сообщения и никогда не заменяет его. Закрытый набор значений задан в схеме кодов ошибок функций хоста.
🔴 Ошибку на этой границе называют два разных словаря, и ключ, который вы читаете, говорит, с каким из них вы имеете дело. Их путаница — единственная ошибка, о которой стоит здесь предупредить, потому что значение из любого из них — обычная строка, и ни хост, ни гость не проверяют, из какого набора оно взято.
hostfunc_error_code— в ответе, который хост отправляет гостю. Его значение входит в закрытый каталог, ссылка на который дана выше, — фиксированный, медленно меняющийся список способов, которыми может завершиться ошибкой обратный вызов хоста. Поскольку набор закрыт, гость может сопоставить значение с именованной константой, которую реэкспортирует его набор, и ветвиться по результату.condition_codeрядом сcondition_short_code— в выводе сокета, который гость возвращает хосту. Это два идентификатора останавливающего условия, которое поднял сам гость, и они берутся из открытого, растущего набора условий, регистрируемых компилятором, а не из каталога.condition_code— описательный код, под которым зарегистрировано условие;condition_short_code— компактная форма (букваEи четыре цифры), которую читатель цитирует, ищет и вставляет в отчёт. Хост выводит короткий код в заголовке в квадратных скобках формируемой им диагностики, поэтому условие, поднятое гостем, можно процитировать так же, как условие, поднятое компилятором. Хост не вычисляет ни одно из значений, но проверяет их: короткий код, не соответствующий ни одному условию, объявленному этим компилятором, или соответствующий условию, номер которого выведен из употребления, останавливает сборку, вместо того чтобы дойти до читателя как идентификатор, ни на что не указывающий.
Два идентификатора на стороне гостя сообщаются вместе: гость, который задаёт один и не задаёт другой, назвал условие, которое хост не может разрешить, и тогда хост сообщает вместо него собственное общее условие сбоя плагина, а сообщение по-прежнему несёт полное описание сбоя. Кроме того, condition_code никогда не входит в каталог функций хоста, поэтому сравнение его с реэкспортированной константой никогда не даёт совпадения — именно поэтому каждый ключ называет свой собственный словарь, а не сбой вообще.
Слоты каждого обратного вызова имеют заявленную кодировку, и каждый слот, содержащий документ полезной нагрузки, содержит его в двоичном виде. Каждый аргумент обратного вызова хоста — это указатель в память гостя, кроме числового уровня aggrega_log; обратный вызов, возвращающий ответ, тоже отвечает указателем. Что содержит каждый из этих слотов, зафиксировано для каждого обратного вызова:
| Обратный вызов | Слоты аргументов | Слот ответа |
|---|---|---|
aggrega_log, aggrega_emit_warning | текст UTF-8 — без документа полезной нагрузки | без ответа |
aggrega_fetch_external_input | голый URL в UTF-8 — без документа полезной нагрузки | канонический CBOR |
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_source | канонический CBOR (RFC 8949 §4.2.1) | канонический CBOR |
Таблица разделяет случаи по тому, что содержит каждый слот, а не по идентичности обратного вызова: слот с документом полезной нагрузки несёт канонический CBOR, а слот с голой строкой — строкой журнала, полем диагностики, URL — несёт текст UTF-8. aggrega_fetch_external_input — единственный, у которого два слота различаются: его аргумент — голый URL, читаемый как текст UTF-8, а ответ — документ полезной нагрузки в каноническом CBOR.
Что гость делает в слоте с полезной нагрузкой и чего делать не должен. 🔴 Слот с документом полезной нагрузки содержит непрозрачную последовательность байтов, а не текст UTF-8 — так что это форма, которую объявляет гость, а не только байты, которые он туда кладёт. Гость, который выделяет такой запрос как строку или читает такой ответ как строку, несовместим: текстовое преобразование в любом направлении портит двоичные байты. Сбой громкий, а не частичный — запрос, который хост не может декодировать, возвращается в виде конверта ответа с кодом request_undecodable, в той же внутриполосной форме, что и любой другой сбой обратного вызова, поэтому гость сообщает о нём, а не продолжает работу с наполовину прочитанной полезной нагрузкой. Типы полезной нагрузки: SourcePackRequest и SourcePackResponse для aggrega_pack_source, SourceFileRequest и SourceFileResponse для aggrega_read_source_file, ParseInput и ParseSourceResponse для aggrega_parse_source и только тип ответа FetchExternalInputResponse для aggrega_fetch_external_input, URL которого выделяется как текст. Конкретно для каждого набора:
- Go — постройте запрос с помощью
EncodeCBOR()типа запроса, выделите его черезpdk.AllocateBytes(а неpdk.AllocateString) и прочитайте ответ с помощьюReadBytes()из памяти, на которую указывает указатель ответа, передав вDecodeCBORтипа ответа. URL для загрузки — исключение на стороне запроса, он выделяется черезpdk.AllocateString; его ответ читается как любой другой. Объявление//go:wasmimportв любом случае — указатель, поэтому сигнатура никак не показывает форму: она заключена в выделении и чтении. - Rust — объявление
#[host_fn]прямо указывает форму: каждый из трёх обратных вызовов с полезной нагрузкой имеет видfn <callback>(request: Vec<u8>) -> Vec<u8>;, а обратный вызов загрузки —fn aggrega_fetch_external_input(url: String) -> Vec<u8>;. Постройте запрос с помощьюencode_cbor()типа запроса и прочитайте ответ с помощьюdecode_cbor(&raw)типа ответа. - TypeScript — постройте запрос функцией
encodeCBOR…типа запроса, выделите его черезMemory.fromBuffer(а неMemory.fromString) и прочитайте ответ с помощьюreadBytes(), передав в функциюdecodeCBOR…типа ответа. URL для загрузки выделяется черезMemory.fromString; его ответ читается с помощьюreadBytes(), как и остальные. Как и в Go, записьdeclare moduleв любом случае — указатель.
Гостю, который вызывает обёртку PDK, ничего из этого не нужно. Обёртки — FetchExternalInput, PackSource, ReadSourceFile и ParseSource, в написании каждого языка — выполняют выделение и кодирование, и ни одна из их сигнатур не называет тип передачи, поэтому гость, который обращается к этим обратным вызовам через свой набор, сам ничего не выделяет и не декодирует; гость, который сам объявляет и вызывает функции хоста, выделяет и читает свою память, как описано выше. Запрос, выделенный как текст, получает отказ, а не обслуживается наполовину, а ответ, прочитанный как текст, невозможно декодировать, поэтому расхождение между сторонами проявляется явно, а не остаётся незамеченным.
Два свойства, на которые можно опираться. Ответ несёт одну и ту же кодировку и при успехе, и при сбое: гость читает один слот и до декодирования не может знать, что из двух он содержит, поэтому одна точка входа декодирования читает оба, и описанные выше код ошибки и сообщение приходят через неё. И гость заполняет поле с байтовым значением в типе поля своего набора — срезом байтов в Go, строкой base64 в Rust и TypeScript, — потому что преобразование в сырую последовательность байтов, которую несёт двоичная кодировка, — задача сгенерированного кодировщика, выполняемая на выходе и обращаемая на входе. Это касается исходных байтов ParseInput, содержимого файла, которое возвращает aggrega_read_source_file, содержимого, загруженного aggrega_fetch_external_input, и содержимого каждого упакованного файла в ответе pack-source: эти байты пересекают границу один раз, а не в двойном кодировании, и ни один гость не кодирует в base64 то, что кодировщик вот-вот раскодирует. Поле content в ответах read-source-file и fetch опускается, когда оно пустое, поэтому ответ для пустого файла или загруженной полезной нагрузки нулевой длины вообще не несёт содержимого; такой ответ всё равно считается успехом, потому что сбой всегда несёт своё сообщение и код, и обёртка каждого набора возвращает для него пустые байты. Дерево, которое возвращает aggrega_parse_source, передаётся как последовательность байтов, содержащая собственный JSON-документ дословно; хост не читает и не перестраивает его. Парсер читает тот же ParseInput, в той же кодировке, в своём собственном экспорте parse — см. сокет парсера.
Каноничность означает, что одинаковый ввод даёт одинаковые байты на каждой стороне; именно это позволяет сравнивать полезную нагрузку между тремя наборами для плагинов, а не только передавать её туда и обратно, и именно поэтому вывод сборки остаётся побайтово идентичным. В госте не нужна библиотека CBOR, и ничто не разбирает байты вручную: каждый опубликованный тип полезной нагрузки поставляется с точками входа кодирования и декодирования, которые нужны для кодировки его слота.
За детерминированность отвечает автор плагина. Хост использует выходные байты гостя дословно и не прогоняет их через сериализатор, поэтому контракт, который должен соблюдать каждый плагин, таков: одинаковый ввод даёт одинаковые выходные байты. Песочница устраняет внешние источники недетерминированности — время по настенным часам, окружение, состояние файловой системы, — но намеренно не маскирует остальные: гость, который кодирует в свой вывод энтропию или прошедшее монотонное время, выдаёт заметно различающиеся между запусками байты, а не стабильно скрытый дефект.
Канал загрузки внешних входных данных. aggrega_fetch_external_input — единственный санкционированный канал для удалённого содержимого, и он опосредован хостом, а не является сетевым доступом гостя: гость называет URL, а хост выдаёт байты по дисциплине закрепления внешних входных данных. URL, закреплённый в lock-файле сущности Release, выдаётся из локального хранилища с адресацией по содержимому и проверяется по записанному дайджесту; незакреплённый URL отклоняется с диагностикой, называющей URL и шаг, который его закрепляет, потому что рендеринг использует замыкание, записанное в его lock-файле, и никогда его не расширяет. Закрепления записываются при разрешении зависимостей сущности Release — это единственный момент, когда что-либо закрепляется. Руководство разработчика содержит полное описание авторской работы и дисциплины закрепления.
Отображения, сохраняющие порядок
Некоторые отображения в полезной нагрузке помечены в схеме их сокета как сохраняющие порядок, потому что порядок их записей — часть того, что они передают: узлы сборки, метки узла, вложения узла, входы и выходы шага конвейера, пространства ключей, которые объявляет провайдер. Опубликованные типы полезной нагрузки хранят каждое такое отображение в контейнере, который сохраняет записи в том порядке, в каком они были заданы:
| Набор | Контейнер |
|---|---|
| Go | aggrega.OrderedMap[V] — имя, под которым набор предоставляет abi.OrderedMap[V] из пакета ABI |
| Rust | OrderedMap<V> из крейта aggrega-abi, реэкспортируемый набором |
| TypeScript | собственный тип языка Map<string, V> |
Контейнеры Go и Rust поддерживают операции отображения: поиск ключа, его установка, удаление, чтение ключей, обход записей по порядку, подсчёт. Установка ключа, который уже есть в контейнере, заменяет его значение и сохраняет его место; новый ключ добавляется после всех существующих.
Порядок сохраняется в обеих кодировках. В двоичной кодировке помеченное отображение записывается как упорядоченный список записей — каждая запись представляет собой список из двух элементов, сначала ключ, затем значение, — в порядке контейнера, тогда как каноническая кодировка иначе записала бы отображение с отсортированными ключами. В текстовой кодировке это объект JSON, члены которого записаны в порядке контейнера. Декодер в любой из кодировок отклоняет отображение с повторяющимся ключом и называет этот ключ. Отображение, не помеченное в схеме, сохраняет форму отсортированного отображения в двоичной кодировке и обычный тип отображения языка в опубликованных типах.
Три следствия для гостевого модуля:
- Порядок — это часть вывода. Поскольку помеченное отображение записывается в том порядке, в каком оно было заполнено, гостевой модуль, заполняющий его из источника без фиксированного порядка (например, перебирая встроенное отображение Go), записывает байты, различающиеся между запусками на одинаковых входных данных. Заполняйте его в фиксированном порядке.
- Порядок сохраняется, только пока отображение остаётся в своём контейнере. Гостевой модуль, преобразующий полезную нагрузку в обобщённый тип значения своего языка, получает порядок этого типа: у
map[string]anyв Go порядка нет, аserde_json::Valueв Rust хранит ключи объекта отсортированными, если крейт не собран с функциейpreserve_order. - В TypeScript читайте и записывайте через сгенерированные функции. Тип, содержащий помеченное отображение, декодирует свой JSON член за членом, поэтому ключ, читаемый как индекс массива, например
"8080", сохраняет своё место, тогда какJSON.parseпереместил бы его в начало объекта; а его кодировщик записывает каждыйMapкак объект, тогда какJSON.stringifyзаписываетMapкак{}.Object.keysдляMapтоже пуст: читайте ключиMapего собственным методомkeys().
Значения, которые входные данные помечают как конфиденциальные
Плагин никогда не цитирует в возвращаемом отказе или предупреждении значение, которое его входные данные помечают как конфиденциальное, — по его ключу или как часть полезной нагрузки, помеченной целиком. Отказ — это error, который несёт вывод; предупреждение — это Diagnostic, который несёт вывод, независимо от его серьёзности, или предупреждение, выданное через aggrega_emit_warning. Хост передаёт этот текст без изменений везде, где он о нём сообщает, — в командной строке, в языковом сервере и списке проблем редактора, в инструментах ассистента — и не извлекает из него никаких значений, поэтому только плагин может не допустить попадания значения в текст. Вместо этого назовите ключ, параметр или позицию: по ним читатель найдёт значение.
Правило распространяется на текст, который за плагин пишет библиотека, так же, как на текст, который плагин пишет сам. Шаблонизатор сообщает данные, которые он вычислял, валидатор схемы цитирует значение, не прошедшее pattern, парсер цитирует токен, который не смог прочитать. Если такой сбой произошёл на значении, помеченном во входных данных, сообщите о нём без значения — например, выполните тот же шаг повторно, заменив каждое помеченное значение заполнителем, сообщите о сбое этого запуска, если он произойдёт в том же месте, а иначе укажите, что текст сбоя скрыт. В полезной нагрузке, помеченной целиком, каждое значение является помеченным, а её ключи — структура документа — остаются читаемыми.
Где входные данные помечают ключ или полезную нагрузку как конфиденциальные, в написании, принятом в формате передачи:
| Сокет и экспорт | Где читается пометка |
|---|---|
provider: render_node и validate_node_input (RenderNodeInput) | node.sensitive_rendered_keys: каждый ключ называет запись node.values, когда эти значения принадлежат самой сущности Component и индексированы объявленными ею листьями, — valuesMapping сущности Recipe записывает ключи, которых не называет ни одно объявление, поэтому ни один из них здесь не помечается, — или запись карты attachments контейнера workload, которая читает слот, объявленный конфиденциальным. node.sensitive_values помечает node.values целиком: значение равно true, когда эти значения создал valuesMapping — сущности Recipe или сущности FeatureRecipe вложения — и он читает значение, которое автор объявил конфиденциальным. workload_projection.sensitive_workload так же помечает каждое значение workload, когда шаблон workload читает такое значение, а каждая запись artifacts_projection.entries несёт sensitive_content для собственного содержимого, включая сообщение парсера об этом содержимом. Каждая запись omits несёт sensitive, когда шаблон, создающий любое из её полей kind, name или namespace, читает такое значение, и тогда каждое поле этой записи является помеченным значением. Каждая запись node.features несёт пометку своего вложения: sensitive_payload_leaves (листья values.<path> и infra.<path>, которые её сущность Feature объявляет конфиденциальными), sensitive_inject (ключи доставки inject, которые читают ключ provides, объявленный её сущностью Feature конфиденциальным) и sensitive (обрабатывает ли вложение вообще материал, объявленный конфиденциальным). |
governance: ir-verdict (PolicyInput) | graph: sensitive_payload_leaves каждого узла, а также sensitive_payload_leaves, sensitive_inject и sensitive каждого вложения. Каждое значение, названное этими пометками, уже поступает в виде маркера сокрытия {"aggrega_withheld": "declared"}, поэтому само значение никогда не доходит до плагина. |
Никакие другие входные данные сокетов и никакие входные данные других экспортов provider не несут пометок. Пометка ключа называет только то, что она точно сопоставляет с объявлением, поэтому отсутствие ключа никогда не означает, что значение безопасно цитировать: оно означает, что с этим ключом не удалось сопоставить ни одно объявление. Пометка полезной нагрузки читается из ссылок шаблона, создавшего полезную нагрузку, — ссылки, достигающей объявленного значения, передачи шаблоном всех своих данных или шаблона, который не разбирается, — и никогда из значения, поэтому её отсутствие означает, что шаблон не читал объявленных значений, насколько показывают его ссылки, или что полезную нагрузку не создавал ни один шаблон; это не утверждение, что полезная нагрузка не несёт ничего конфиденциального.
Размещение сокетов Wasm в конвейере
Конвейер компиляции резервирует следующие точки сокетов. Метки формы следуют таксономии из четырёх меток со страницы «Статус».
| Сокет | Место в конвейере | Статус сегодня |
|---|---|---|
Сокет управления, роль annotation-transform | Разрешение (до раскрытия аннотаций) | доступен — вызывается, когда рабочее пространство подключает плагин annotation-transform; внедряет аннотации, которые раскрытие превращает в подключения Feature |
Сокет управления, роль label-transform | Построение топологии (Topology Builder) | доступен — вызывается, когда рабочее пространство подключает плагин label-transform; автоматически проставляет метки узлов через JSON Patch |
Сокет управления, роль ir-verdict | Статический анализ (Static Analyzer, по графу IR) | доступен — вызывается, когда рабочее пространство подключает плагин ir-verdict; вердикт halt останавливает сборку |
Сокет управления, роль render-verdict | Рендеринг (по отрендеренным артефактам) | доступен — вызывается, когда рабочее пространство подключает плагин render-verdict; вердикт halt останавливает сборку |
Плагины pipeline: сущностей FeatureRecipe и Recipe | Конвейер плагинов (изменение после рендеринга) | доступен — каждый объявленный шаг выполняется над набором отрендеренных документов, применяя патчи RFC 6902 и порождая побочные эффекты |
| Плагины рендеринга Provider (helm, helm-chart, compose, terraform, cloudformation) | Базовый рендеринг (провайдеры) | доступен — каждый провайдер рендерит через свой гостевой модуль Wasm; рендеринг выполняется только в Wasm, без резервного рендерера на стороне хоста |
Плагины парсеров (parse:<format>) | Рендеринг — для политики render-verdict; и вне основного потока — для импорта | доступно — вызывается для артефакта в формате, который политика render-verdict не читает нативно, для импортёра через aggrega_parse_source и для распознавания формата импорта, который его не называет |
Плагины импортёров (import:<format>) | Вне основного потока (aggrega import) | доступно — вызывается командой aggrega import, сеансом редактора и инструментом для ассистента |
Плагины линтеров (linter/publishing) | Вне основного потока (aggrega lint) | доступен — publishing-linter поставляется и выполняется через хост с помощью aggrega lint |
Подфаза раскрытия Feature по аннотациям, входящая в разрешение, — это нативный проход конвейера на Go, а не сокет Wasm. Она проверяет значения аннотаций по spec.schema целевой сущности Feature и внедряет синтетические подключения Feature во время построения IR. Шесть поверхностей, несущих аннотации и метки, описаны в vocabulary/labels-and-annotations.md, а форма привязки и руководство по написанию — в providers/well-known-annotations.md.
Контракт формы вывода — что существует сегодня
Сокет управления предоставляет типизированную контрактную поверхность для каждой из своих четырёх ролей, и роль определяет, какую именно. Авторы Plugin реализуют гостевой код, который формирует документированные структуры; хост считывает их во время сборки, по одному разу для каждого настроенного плагина, когда рабочее пространство подключает плагин в этой роли. Подразделы ниже следуют в том порядке, в котором конвейер их вызывает.
Роль annotation-transform — вывод внедрения аннотаций
Место в конвейере. Разрешение, после разрешения компонентов и до запуска расширения Feature на основе аннотаций.
Форма ввода (хост → гость). Документ AnnotationTransformInput, содержащий:
targets— цели внедрения: разрешённые компоненты, которые гость может аннотировать, — те, которые граница называет напрямую, и каждый компонент, который маршрутизирует внутрь запись маршрутизации вaggregates:границы, независимо от того, называет ли его эта запись, — каждый со своимиboundary_path,component_name(для маршрутизированного компонента — его идентификатор с точками в графе сборки, напримерmetrics.query) иannotations, которые записывает на нём Release, чтобы гость мог решить, что добавить, не вытесняя заданное автором значение. Каждое значение аннотации приходит в записанном виде — строка, объект подключей илиnull, если компонент отказывается от аннотации, которую иначе унаследовал бы, — и каждый ключ, который несёт компонент, присутствует независимо от его значения. Хост упорядочивает их детерминированно.binding_keys— ключи аннотаций, для которых сущность Manifest регистрирует привязку, в авторском порядке. Внедрение под зарегистрированным ключом затем расширяется в подключение Feature, поэтому гость читает этот список, чтобы внедрять ключи, которые возымеют действие. Хост не требует, чтобы внедрение называло зарегистрированный ключ: незарегистрированная внедрённая аннотация ведёт себя точно так же, как заданная автором непривязанная аннотация.sources— файлы определений, объявленные подключением вwith.sources, каждый со своим путём по базовому имени и содержимым, отсортированные по пути.settings— объект настроек произвольной формы, объявленный подключением вwith.settingsи передаваемый гостю дословно.
settings и sources — это тот же независимый от движка канал with, который читают все остальные роли, и оба отсутствуют, если подключение их не объявляет. Поскольку вывод этой роли влияет на сборку, настройки и содержимое источников подключения фиксируются в lockfile релиза при pull и восстанавливаются из него при сборке.
Форма вывода (гость → хост). Документ AnnotationTransformOutput, содержащий:
injections— добавляемые аннотации по порядку. Каждая называет существующую координату цели (boundary_pathиcomponent_name), а такжеannotation_keyи егоannotation_value: строку или объект подключей, который питает привязку, маршрутизирующую сразу несколько подключей.
Хост применяет только добавления аннотаций, только к предоставленным им координатам и только со значением, которое автор мог бы записать в этой аннотации. Внедрённое значение он читает точно так же, как то же значение, записанное в Release, — подключи объекта в том порядке, в котором их записал гость, — поэтому развёртывание встречает его так же, как написанное автором. Внедрение, называющее координату, которой нет в полезной нагрузке, или несущее null, список, число, логическое значение или объект без подключей, останавливает сборку с сообщением, называющим координату и аннотацию, а не отбрасывается или применяется молча; весь вывод проверяется до того, как применяется любая его часть. Именно это ограничение задаёт рамки роли: оператор, подключающий здесь плагин, объявил внедрение аннотаций и ничего сверх того. Если сборка позже отклоняет внедрённую аннотацию из-за того, как она маршрутизируется, из-за значения подключа, которое не допускает схема привязанной Feature, или из-за опоры, которую аннотация на стороне Release использовать не может, её сообщение называет плагин, внедривший её, и роль, к которой он подключён.
Кодирование при передаче. Полезная нагрузка и результат этой роли передаются как канонический CBOR (RFC 8949 §4.2.1) в обоих направлениях. Гость читает и записывает его через точки входа, которые есть у типов полезной нагрузки, — DecodeCBOR и EncodeCBOR в Go, decode_cbor и encode_cbor в Rust, decodeCBORAnnotationTransformInput и encodeCBORAnnotationTransformOutput в TypeScript, — поэтому библиотека CBOR не нужна и ничто не разбирает байты вручную. В Rust экспорт принимает и возвращает Vec<u8>; в TypeScript он читает Host.inputBytes() и записывает Host.outputBytes(...). Поле annotations каждой цели — это карта, которую схема помечает как сохраняющую порядок, поэтому она передаётся как упорядоченный список записей в том порядке, в котором её хранит цель, и гость читает её через сохраняющий порядок контейнер своего набора; каждое значение передаётся как байты своего JSON, так же как annotation_value внедрения в обратном направлении. settings передаётся как байты своего JSON-документа, который гость разбирает как JSON, чтобы заглянуть внутрь. Ответ, не являющийся AnnotationTransformOutput в этом кодировании, — записанный как JSON или содержащий поле верхнего уровня, которое форма не объявляет, — останавливает сборку с указанием плагина и его экспорта, а не читается как пустой список внедрений. При прямом вызове через aggrega plugin run-local --export transform_annotations гость получает заданную автором полезную нагрузку JSON, преобразованную в это кодирование, а его ответ читается как выходная форма экспорта и выводится как JSON — ответ, не имеющий этой формы, отклоняется с указанием экспорта, так же как его отклоняет сборка.
Определения типов. Типы передачи annotation-transform — AnnotationTransformInput, AnnotationTransformOutput, AnnotationTarget, AnnotationInjection, AnnotationSource — опубликованы во всех трёх пакетах ABI и сгенерированы из одного кодека, поэтому все три остаются синхронными.
Роль label-transform — вывод JSONPatch
Место в конвейере. Построение топологии, после того как граф сглажен, и до построения графа IR, поэтому селекторы сокетов и Feature, которые вычисляет анализатор, читают оставленные этой ролью метки.
Форма входных данных (хост → гость). Документ MutatorInput, содержащий:
compilation_context— идентификация релиза (release_name,environment).graph— проекцияMutatorGraphузлов топологии: Component каждого узла, разрешённая версия, метки иvalues, которые объявляет его экземпляр.settings— объект настроек произвольной формы, объявленный подключением вwith.settingsи передаваемый гостю дословно.sources— файлы определений, объявленные подключением вwith.sources, каждый с путём в виде базового имени и содержимым, так что мутатором может управлять хранящийся в репозитории файл правил или сопоставлений, а не встроенные настройки.
Граф — это проекция, а не граф IR: каждый узел несёт свой разрешённый набор меток и значения, которые его экземпляр объявляет в Aggregate, а рёбра и полезные нагрузки feature остаются внутри компилятора. Значения принадлежат самому Aggregate, и его шаблоны уже вычислены по его параметрам, поэтому значение, вынесенное в параметр, приходит в виде значения, которое предоставил Release; значение по умолчанию, объявленное схемой Component, и всё, что вносит Recipe или Feature, к ним не относятся, а узел, не объявляющий значений, не несёт ключа values. Значение, которое Component узла объявляет чувствительным, скрывается точно так же, как его скрывает вердикт по графу, — оно читается как {"aggrega_withheld": "declared"}, — а каждое соседнее значение, которого не касается ни одно объявление, приходит в записанном виде. Именно это позволяет конфигурации, объявленной разработчиком, определять метку — например, база данных, значения которой включают векторное расширение, получает метку datastore.aggrega.ai/engine: vector. settings и sources — тот же агностичный по отношению к движку канал with, который читают роли вердиктов; хост передаёт их дальше и никогда не интерпретирует их содержимое. Поскольку вывод мутатора определяет сборку, настройки и содержимое источников подключения фиксируются в lock-файле релиза при pull и восстанавливаются из него при сборке, поэтому входные данные мутатора не зависят от изменения любого из них после pull вплоть до следующего pull.
Форма выходных данных (гость → хост). Документ MutatorOutput, содержащий:
patches— массив непрозрачных документов JSONPatch (RFC 6902), которые хост применяет только к меткам узлов; значения, которые нёс вход, доступны только для чтения.
Каждый патч адресует метки конкретного узла через JSON Pointer (RFC 6901); хост применяет патчи в порядке массива и повторно загружает изменённый набор меток в граф IR. Задача роли label-transform — автоматическая разметка на уровне предприятия: добавление меток соответствия требованиям, наблюдаемости и распределения затрат, объявленных корпоративной политикой, без изменения содержимого каталога. Поверхность меток — единственная разрешённая цель этой роли: патч, который затрагивает поле узла помимо его меток, добавляет или удаляет узел либо задаёт нестроковое значение метки, останавливает сборку, а не поглощается молча. RFC 6901 — базовая грамматика путей для каждой поверхности путей документа в Aggrega: здесь это контракт плагинов Wasm, а также экспорты .locals *_path и поля схем *Path в других частях документации. Каноническое объявление базы и дисциплину суффиксов *Path / *_path, различающую две стороны авторинга, см. в 02-naming-conventions.md, раздел «Document-path naming-suffix discipline».
Кодирование при передаче. Полезная нагрузка и результат этой роли передаются в обоих направлениях как канонический CBOR (RFC 8949 §4.2.1). Каноничность означает, что одинаковые входные данные дают одинаковые байты на любой стороне: именно это позволяет сравнивать полезную нагрузку между тремя наборами для плагинов, а не только передавать её туда и обратно, и именно поэтому вывод сборки остаётся побайтово идентичным. Гость читает и записывает её через точки входа, которые уже есть у типа полезной нагрузки его набора, — DecodeCBOR и EncodeCBOR в Go, decode_cbor и encode_cbor в Rust, decodeCBORMutatorInput и encodeCBORMutatorOutput в TypeScript, — поэтому библиотека CBOR не нужна и ничто не разбирает байты вручную. В Rust экспорт принимает и возвращает Vec<u8>; в TypeScript он читает Host.inputBytes() и записывает Host.outputBytes(...). nodes графа, labels каждого узла и values каждого узла — это словари, которые схема помечает как сохраняющие порядок, поэтому они передаются как упорядоченные списки записей: узлы — в порядке, в котором их хранит сборка, то есть в авторском порядке, метки каждого узла — в порядке, в котором их несёт узел, а значения каждого узла — в порядке, в котором их записывает Aggregate; гость читает все три через сохраняющий порядок контейнер своего набора. Каждое значение передаётся как байты своего JSON-документа: наборы для Go и Rust передают его гостю как этот JSON, который разбирается настолько, насколько нужно правилу, а набор для TypeScript — как уже разобранное значение.
Две вещи это не меняет. Массив patches остаётся JSON: сокет передаёт каждый документ патча дословно как непрозрачное содержимое, и ни одна сторона не заглядывает внутрь, поэтому собственная форма документа патча не зависит от кодирования, которое использует его сокет. Кроме того, settings и sources по-прежнему передаются дословно: settings поступает в виде байтов, написанных автором подключения, и гость разбирает их как JSON, если ему нужно заглянуть внутрь.
Все остальные роли управления используют то же кодирование — роль annotation-transform и две роли вердиктов указывают это в своих разделах, — поэтому гость, обслуживающий несколько ролей, говорит на каноническом CBOR в каждой обслуживаемой роли, читая каждую полезную нагрузку через точку входа декодирования её собственного типа.
Определения типов. Типы передачи мутатора — MutatorInput, MutatorOutput, CompilationContext, MutatorGraph, MutatorNode — опубликованы во всех трёх пакетах ABI (github.com/aggrega-ai/aggrega-abi/go, крейт aggrega-abi и @aggrega-ai/aggrega-abi) и генерируются из одного кодека, поэтому все три остаются синхронными. Хост собирает входные данные и применяет патчи, возвращённые гостем.
Роли вердиктов — вывод в виде массива вердиктов
Гостевой модуль политики проверяет сборку и возвращает список вердиктов; хост действует в соответствии с уровнем серьёзности каждого вердикта и никогда не интерпретирует саму политику. Полное описание — четыре роли, уровни серьёзности, канал входных данных, предоставляемых оператором, написание политики для любого из двух движков, поставляемых внутри компилятора, обёртывание стороннего движка политик, эталонные гостевые модули и то, как оператор подключает политику, — приведено на странице сокета управления. В этом разделе описаны размещение в конвейере и типизированные формы передаваемых данных.
Размещение в конвейере. Политика подключается ровно к одной роли вердикта, которая определяет, где она вычисляется:
ir-verdict— вычисляется на этапе статического анализа, до базового рендеринга. Анализатор собирает полезную нагрузку при каждой сборке.render-verdict— вычисляется после рендеринга, над сгенерированными артефактами.
Когда рабочее пространство подключает плагин роли вердикта, конвейер передаёт плагину полезную нагрузку этой роли и считывает обратно его вердикты.
Форма входных данных (хост → гость). Полезную нагрузку выбирает роль:
PolicyInputролиir-verdictсодержитgraph— полный граф IR, агностичный по отношению к возможностям (той же формы, что выдаёт Topology Builder), со всеми узлами, рёбрами и сведениями о подключениях, которыми располагает компилятор, за исключением того, что значение, объявленное автором чувствительным, приходит скрытым (см. Значения, которые вход помечает как чувствительные), — иprecalculated_paths, пути маршрутизации, которые анализатор перечисляет попутно, чтобы политика могла рассуждать о достижимости, не обходя граф заново. Граф — это версионированный граф IR с единственным источником в схемеir-v1beta1; форма IR не является секретной (это тот же граф, что выдаётaggrega inspect), а секреты в ней представлены указателями, а не открытым текстом.RenderPolicyInputролиrender-verdictсодержитartifacts— отрендеренные выходные файлы, отсортированные по пути, так что передаваемые данные побайтово идентичны между запусками с одинаковыми входными данными. Каждая запись содержит выходной путь артефактаpathи его отрендеренное содержимоеcontent; она также содержитformat, в котором он был отрендерен, если создавший его провайдер его объявил, иtree— разобранное каноническое представление формата, который гость не читает нативно; хост разбирает его с помощью разрешённого парсера и передаёт непрозрачно. Оба поля отсутствуют, когда неприменимы: формат, который гость читает нативно (JSON, YAML), остаётся неразобранным, и гость читает его изcontent.
Обе роли дополнительно передают sources подключения (файлы определений политики, которые хост читает во время сборки и передаёт гостю дословно, пути — в виде базовых имён, содержимое непрозрачно) и settings (объект произвольной формы, передаваемый без изменений). Оба отсутствуют, если подключение их не объявляет.
Форма выходных данных (гость → хост). Документ PolicyOutput, содержащий:
results— массив записейDiagnostic, каждая с полемseverity(halt,warnилиinfo) и строкойmessage. Вердикт может также задать в той же записиcode,rule_id,classification,source_ref,locationиsuggest; хост добавляет те из них, что содержал вердикт, к отрендеренному вердикту на любом маршруте уровня серьёзности.
Присутствуют только сработавшие вердикты; разрешающее вычисление возвращает пустой массив. Хост обходит вердикты и сопоставляет каждому уровню серьёзности действие: halt останавливает сборку (выводя каждое сообщение halt), warn помечает вердикт и позволяет сборке продолжиться, info записывает его, не влияя на результат. halt останавливает сборку через тот же шлюз, что и нарушение селектора или appliesTo.
Кодирование при передаче. Полезные нагрузки обеих ролей и PolicyOutput, который гость возвращает в любой из них, передаются как канонический CBOR (RFC 8949 §4.2.1). Гость читает и записывает их через точки входа, которые есть у типов полезной нагрузки, — DecodeCBOR и EncodeCBOR в Go, decode_cbor и encode_cbor в Rust, decodeCBORPolicyInput, decodeCBORRenderPolicyInput и encodeCBORPolicyOutput в TypeScript, — поэтому библиотека CBOR не нужна и ничто не разбирает байты вручную. В Rust каждый экспорт принимает и возвращает Vec<u8>; в TypeScript он читает Host.inputBytes() и записывает Host.outputBytes(...). Сохраняющие порядок отображения графа, среди них его nodes и labels каждого узла, передаются как упорядоченные списки записей в том порядке, в котором их хранит сборка, и гость читает их через сохраняющий порядок контейнер своего набора; в каком порядке политика встречает их в каждом движке политик, описано на странице сокета управления. settings и разобранное tree артефакта передаются как байты их JSON-документов, которые гость разбирает как JSON, чтобы заглянуть внутрь. Ответ, который не является PolicyOutput в этой кодировке, — записанный как JSON или содержащий поле верхнего уровня, не объявленное формой, — останавливает сборку с указанием плагина и его экспорта, а не читается как пустой список вердиктов. При прямом вызове через aggrega plugin run-local --export verdict_ir или --export verdict_render гость получает написанную автором полезную нагрузку JSON, преобразованную в эту кодировку, а его ответ читается как выходная форма экспорта и выводится как JSON — ответ, не имеющий этой формы, отклоняется с указанием экспорта, так же как его отклоняет сборка.
Определения типов. Типы передачи данных политики публикуются в тех же трёх пакетах ABI: PolicyInput (роль ir-verdict), RenderPolicyInput (роль render-verdict), общий PolicySource и PolicyOutput, записи results которого являются значениями Diagnostic. Уровень серьёзности диагностики — одно из трёх значений, общих для всех сокетов, — halt, warn или info, — и эти три значения публикуются как константы рядом с типами передачи данных в каждом из трёх пакетов, так что гость сообщает из того же замкнутого набора, по которому маршрутизирует хост. Гость, вернувший любое другое значение, останавливает сборку с сообщением, указывающим плагин и возвращённое им значение: немаршрутизируемый уровень серьёзности — это дефект плагина, о котором хост сообщает, а не диагностика, которую он отбрасывает.
Контракт формы вывода — конвейер FeatureRecipe и сокеты провайдеров
Перечисленные ниже сокеты несут типизированные поверхности контракта, которые компилятор вызывает при сборке. Шаги pipeline: сущностей FeatureRecipe и Recipe выполняются в конвейере плагинов над набором отрендеренных документов; сокет рендеринга провайдера выполняется на этапе базового рендеринга; линтер публикации выполняется вне основного процесса.
Патчи RFC 6902 (конвейер плагинов)
Шаги pipeline: сущностей FeatureRecipe и Recipe, выполняемые в конвейере плагинов, выдают операции JSON Patch по RFC 6902 над набором отрендеренных документов. Хост передаёт каждому шагу весь набор документов с ключами; шаг выбирает целевые документы по содержимому и возвращает патчи с адресацией по ключу, которые механизм применения применяет к адресованным документам — как правило, добавляя sidecar-контейнер, монтируя том с секретом или переписывая переменную окружения. Шаг также возвращает side_effects (см. ниже), diagnostics — каждая запись имеет ту же общую форму Diagnostic, в которой о проблемах сообщает любой сокет, — и outputs (см. ниже). Описано в examples/04-secrets.md.
Текущий статус: доступно. Каждый объявленный шаг выполняется во время aggrega build.
Кодирование при передаче. Вход шага (FRPStepInput) и его ответ (FRPStepOutput) передаются как канонический CBOR (RFC 8949 §4.2.1) в обоих направлениях. Гость декодирует свой вход и кодирует ответ через точки входа, которые есть у типов полезной нагрузки, — DecodeCBOR и EncodeCBOR в Go, decode_cbor и encode_cbor в Rust (на типах, которые публикует крейт aggrega-abi), decodeCBORFRPStepInput и encodeCBORFRPStepOutput в TypeScript, — читая и записывая байты (Vec<u8> в Rust, Host.inputBytes() и Host.outputBytes(...) в TypeScript). Библиотека CBOR не нужна, и разбирать байты вручную не приходится. Вход шага with (step_input), возвращаемые им outputs, а также наборы документов own и host — это словари, которые схема помечает как сохраняющие порядок, поэтому они передаются как упорядоченные списки записей в том порядке, в котором их хранит конвейер, а гость читает и записывает их через сохраняющий порядок контейнер своего набора инструментов — именно это позволяет выходам шага попасть в .steps.<id>.outputs в том порядке, в котором шаг их вернул. tree каждого блока, каждое значение step_input и outputs, value патча, crd побочного эффекта и context рендеринга передаются как байты своих JSON-документов, которые гость разбирает как JSON, чтобы заглянуть внутрь; bytes блока передаются как сырая последовательность байтов, которую сгенерированный декодер помещает в собственный тип поля набора инструментов — срез байтов в Go, строку base64 в Rust и TypeScript. Каждая диагностика передаётся в общей форме Diagnostic. Ответ, не являющийся FRPStepOutput в этой кодировке, — записанный как JSON или содержащий поле верхнего уровня, которое форма не объявляет, — приводит к сбою шага с указанием выполняемой им функции, что останавливает сборку, если шаг не помечен optional. При прямом вызове через aggrega plugin run-local --export step шаг получает написанную автором JSON-нагрузку, преобразованную в эту кодировку, а его ответ читается как выходная форма экспорта и выводится как JSON — ответ, не имеющий этой формы, отклоняется с указанием экспорта, так же как его отклоняет сборка.
Побочные эффекты — выдача ресурсов (плагины учётных данных в конвейере плагинов)
Конвейеры FeatureRecipe для учётных данных (Two-Part Plugin Principle: Fetcher + Injector) выдают полные ресурсы вместе с патчем через side_effects шага, каждый из которых объявляет один из двух видов, определённых контрактом: emit_crd — документ пользовательского ресурса, например CRD ExternalSecret или VaultSecret, который кластер получает во время выполнения, или emit_file — записанный файл. Шаг, возвращающий любой другой вид, останавливает сборку с указанием узла, индекса побочного эффекта и объявленного им вида. Шаг Fetcher выдаёт полный ресурс; шаг Injector возвращает патч, который монтирует получившийся Kubernetes Secret. Описано в examples/04-secrets.md.
Текущий статус: доступно.
Выход шага (словарь outputs шага pipeline:)
Шаг конвейера плагинов публикует именованные выходы, которые последующие шаги используют через {{ .steps.<id>.outputs.<key> }}. Форма выхода определяется провайдером для каждого плагина; выходы шагов ограничены тем же конвейером и видны только последующим шагам в порядке объявления. Описано в templates/expansion-matrix.md, строка 10.
Текущий статус: доступно.
Provider-рендеринг — сокет, управляемый гостем
Провайдер — это гость Wasm. Рендеринг выполняется только через Wasm: имя capability: сущности Recipe разрешается в плагин рендеринга провайдера (pluginType: provider), который указывает это имя в своих spec.provider.capabilities и объявляет экспорт render_node, и гость этого плагина рендерит узел. Встроенного в хост рендерера, к которому можно было бы откатиться, нет; имя провайдера, которое не разрешается ни в один обслуживающий его Plugin, останавливает сборку на этапе маршрутизации. Добавить стандартный провайдер — значит поставить гостя .wasm и сущность каталога Plugin: хост не содержит кода для отдельных провайдеров.
Возможность, которую обслуживает провайдер, не содержит двоеточия, как и возможность, с которой шаг конвейера объявляет себя совместимым. capability: сущности Recipe читается как возможность до последнего двоеточия и закрепление версии после него — helm:1.0.0 запрашивает helm версии 1.0.0, — поэтому имя, содержащее двоеточие, не может запросить ни один Recipe. Хост отклоняет такое имя в capabilities из describe() для гостя provider или pipeline-step при загрузке гостя и при генерации его сущности для публикации, указывая гостя и имя. parse:<format> парсера и import:<format> импортера сохраняют своё двоеточие: их ищут по формату, а не через capability: сущности Recipe.
Хост — универсальный маршрутизатор. Он читает самоописание гостя из describe(), включая его контракт поведения рендеринга, и вызывает экспорты гостя, не понимая ни одного формата провайдера. Этот контракт управляет диспетчеризацией как данные:
input_kinds(sourced,synthesized,artifacts_standalone) — какие виды входа Recipe рендерит гость; хост проверяет вид входа узла по этому набору.boundary_assembly(none|merge|nest) — как гость объединяет выход группы диспетчеризации:mergeклассифицирует выход каждого узла как фрагменты, которые сборщик сливает в один артефакт,nestвкладывает файлы каждого узла в собранную обёртку,noneзаписывает выход каждого узла напрямую.nest_segment(необязательно) — для сборкиnestкаталог, в который помещается собственный подкаталог каждого участника, записанный как одно имя каталога; если он отсутствует, подкаталог каждого участника находится непосредственно в позиции диспетчеризации.assembly_name_annotation(необязательно) — аннотация границы, разрешённое значение которой задаёт имя артефакта, собираемого гостем из группы диспетчеризации; если она отсутствует, гость именует свою сборку только по пути диспетчеризации.cross_boundary_linking(необязательно) — связывает ли гость межграничное реброusesчерез свои экспортыlink_publishиlink_resolve; гость объявляет его истинным ровно тогда, когда экспортирует оба, а загрузка отклоняет гостя, у которого флаг и экспорты расходятся.artifact_delimiters(необязательно) — пара разделителей Go-шаблонов, которую гость применяет к телам артефактов.reusable_instance(необязательно) — может ли один загруженный экземпляр обслуживать все обращения в рамках сборки (см. Детерминизм и повторное использование экземпляров ниже).omits(необязательно) — учитывает ли гость записи исключения, которые несёт рендеринг источника (см. Исключение отрендеренных блоков ниже).boundary_artifacts(необязательно) — принимает ли цель гостя файлы, которые Recipe вносит в общий выход своей границы (см. Приём файлов, которые Recipe вносит в границу ниже).source_ignore(необязательно) — файлы, которые экосистема гостя никогда не поставляет рядом с рендеримым источником (см. Объявление того, что экосистема источника никогда не поставляет ниже).
Сокет — это фиксированный набор экспортов: один обязательный, остальные необязательные и объявляются в describe():
render_node(обязательно) — рендерит один узел IR в нативные для провайдера файлы.assemble_boundary(необязательно) — сливает выход отдельных узлов группы диспетчеризации в один артефакт на каждый путь (присутствует, когдаboundary_assemblyравноmergeилиnest).validate_node_input(необязательно) — структурная проверка входа узла перед рендерингом; диагностикаhaltостанавливает сборку,warnвыводится в результат сборки.carve/reassemble(необязательно, парные) — собственный побайтово точный кодек патчей гостя для шагов конвейера после рендеринга; используется только когда объявлены оба.name_bound(необязательный) — гость оценивает, даёт ли имя, которое хост предлагает в качестве идентичности компонента, имена, допустимые для его целевой платформы, и отвечает ограничением, а не собственным именем.rendered_name(необязательный) — гость сообщает имя, которое его целевая платформа присваивает ресурсам, отрисованным им для узла.link_publish/link_resolve(необязательные, парные) — гость связывает межграничное реброuses: потребляемая конечная точка публикует дескриптор, а потребляющая конечная точка разрешает его в собственный собранный вывод.
artifacts: сущности Recipe сводятся в render_node через проекцию артефактов во входных данных: хост выполняет чтение $import, вычисление Go-шаблонов и вычисление ключей и значений происхождения и передаёт гостю каждую запись уже прочитанной и вычисленной; гость отвечает за размещение и вывод в формате, который известен только ему. Описано в architecture/13-catalog-and-registry.md.
Входные данные отрисовки источника несут значения узла в node.values, а node.values_mapped указывает, откуда они взялись: оно равно true, когда значения являются выводом valuesMapping сущности Recipe — или, для собственной отрисовки вложения, его сущности FeatureRecipe, — и отсутствует, когда это собственные значения компонента, переданные в том виде, в каком они написаны. Читает ли его гость — дело собственного контракта этого гостя. Провайдер cloudformation привязывает Parameters шаблона-источника только из значений, созданных отображением, поскольку собственные значения компонента могли быть написаны для других входов сущности Recipe; провайдер terraform записывает аргументы модуля-источника из значений, которые получает его сборка, и не читает этот флаг. Эти значения передаются в каждом отрисованном узле входных данных assemble_boundary для узла, отрисованного из источника, — значения компонента независимо от того, создало ли их отображение, значения присоединённой сущности Feature только там, где их создало valuesMapping её сущности FeatureRecipe, — и тот же флаг передаётся рядом с ними и только там, где передаются они, поэтому сборщик читает тот же ответ, что и собственная отрисовка узла; провайдер cloudformation читает его там, чтобы узнать, какие параметры заполнила привязка узла, и отклоняет ссылку на такой параметр из любого другого места стека, включая хост присоединённой сущности Feature. Флаг фиксирует, как были получены значения, и никогда не выводится из ключа или значения.
Кодирование при передаче. Каждый экспорт этого сокета принимает входные данные и возвращает выходные в виде канонического CBOR (RFC 8949 §4.2.1) в обоих направлениях. Гость декодирует входные данные и кодирует выходные через точки входа, которые уже есть у типов полезной нагрузки, — DecodeCBOR и EncodeCBOR в Go, decode_cbor и encode_cbor в Rust, а в TypeScript функции decodeCBOR и encodeCBOR каждого типа, например decodeCBORRenderNodeInput и encodeCBORRenderNodeOutput, — читая и записывая байты (Vec<u8> в Rust, Host.inputBytes() и Host.outputBytes(...) в TypeScript). Библиотека CBOR не нужна, и ничто не разбирает байты вручную. Поле content отрисованного файла, как и любое другое байтовое поле, передаётся как необработанная последовательность байтов, которую сгенерированный декодер помещает в собственный тип поля набора: срез байтов в Go, строку base64 в Rust и TypeScript. Отображения, которые схема помечает как сохраняющие порядок, — среди них values, features и uses узла, derived_keys ответа и values участника сборки, — передаются как упорядоченные списки записей в том порядке, в котором их хранит сборка, и гость читает их через сохраняющий порядок контейнер своего набора. Каждое значение values узла передаётся как байты собственного JSON-документа, поэтому ключи внутри значения сохраняют порядок, в котором были написаны; так же передаются каждая запись вложения в features, контекст отрисовки, разобранная рабочая нагрузка, каждое обогащённое ребро, каждая вырезанная единица и каждая операция патча, и гость разбирает их как JSON, чтобы заглянуть внутрь. Каждая диагностика передаётся в общей форме Diagnostic. Ответ, который не соответствует форме вывода своего экспорта в этом кодировании, — записанный как JSON или содержащий поле верхнего уровня, не объявленное формой, — останавливает сборку с указанием вызванного экспорта. Примеры полезной нагрузки на этой странице для удобства чтения записаны в JSON. При прямом вызове через aggrega plugin run-local --export render_node или через любой другой экспорт сокета гость получает написанную JSON-нагрузку, преобразованную в это кодирование, а его ответ читается как форма вывода экспорта и печатается в виде JSON — ответ, не соответствующий этой форме, отклоняется с указанием экспорта, как его отклоняет сборка.
Текущее состояние: доступно для всех пяти провайдеров. Гость helm отрисовывает чарты-источники (разрешая корень чарта), синтезированные рабочие нагрузки и автономные артефакты как плоские манифесты Kubernetes. Гость helm-chart собирает зонтичный чарт, вкладывая чарт-источник каждого узла как подчарт, и содержит побайтово точный кодек патчей и разделители артефактов в виде скобок ([[ ]]). Гость compose отрисовывает compose-файлы-источники и синтезированные рабочие нагрузки, объединяет группу диспетчеризации в один docker-compose.yaml и подключает сервис к сетям компонентов, которые называет его x-aggrega-networks-of. Гость terraform выводит конфигурацию Terraform дословно (HCL или JSON) либо включает модуль-источник и передаёт его входные данные как аргументы блока module этого компонента, структурно проверяет HCL модуля-источника перед отрисовкой и собирает границу в одну корневую конфигурацию, объявляющую каждый компонент блоком module, источником которого служит собственный подкаталог этого компонента. Гость cloudformation отрисовывает шаблоны-источники и автономные фрагменты стека, объединяет группу диспетчеризации в один шаблон стека и связывает межграничное ребро uses через link_publish и link_resolve. Каждый из них отрисовывает без сети и детерминированно.
Объявление имён, которые выводит гостевой модуль
Гостевой модуль провайдера обычно выводит имена, которые нужны его выходным данным, но которые никто не написал, — идентификатор, по которому цель обращается к одному ресурсу, имя, под которым один выход публикуется, чтобы на него мог сослаться другой, — из идентичности узла и ресурса, который он выдаёт. Два узла могут прийти к одному имени всякий раз, когда совпадают части, из которых оно выводится, а поскольку имя находится внутри байтов файла, которые хост записывает дословно, хост не видит конфликта: чтобы найти его, ему пришлось бы разбирать формат провайдера, а это именно то знание, которое остаётся в гостевом модуле.
Поэтому render_node возвращает в своих выходных данных необязательное поле derived_keys, и направление обращено: вместо того чтобы хост изучал выходные данные, гостевой модуль объявляет, а хост проверяет:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "derived_keys": { "logical-ids": ["paymentsapiQueue", "paymentsapiTopic"], "export-names": ["aggrega--prod--api--orders-db--host"] }}Каждый ключ derived_keys — это пространство ключей, которое называет гостевой модуль, и каждое пространство содержит имена, которые гостевой модуль вывел в него, в порядке вывода. И имена пространств, и имена внутри них — ваш словарь: хост читает их только как строки, сравниваемые на равенство в пределах одного пространства. Он не разбирает имя, не узнаёт, что означает пространство или имя, и никогда не выводит имя сам, — поэтому одна проверка охватывает все виды имён, которые выводит любой провайдер, и новому провайдеру не нужен новый код хоста. В опубликованных типах derived_keys — это словарь, сохраняющий порядок, поэтому пространства передаются в том порядке, в котором их задаёт ваш гостевой модуль.
Что хост делает с ними, сводится к одному вопросу: в пределах одного пространства различается ли каждое объявленное имя у всех участников, чьи выходные данные сливаются в одну сборку? Два участника, объявившие одно имя в одном пространстве, останавливают сборку, и сообщение об остановке называет пространство, имя и обоих участников, чтобы автор мог действовать, не читая код провайдера. Различные имена, а также имена, которые случайно совпадают в двух разных пространствах, проходят проверку.
Решая, что объявлять, полезно знать три свойства:
- Область действия — один собранный результат, то есть множество участников, чьи файлы сливаются вместе. Гостевой модуль, которому нужна уникальность в более узкой или более широкой области, выражает эту область в имени объявляемого пространства, и выбор при этом остаётся за вами, а не за хостом.
- Один участник может свободно повторять имя. Узел может рендериться в нескольких пересечениях — рендер источника, синтез рабочей нагрузки, размещение артефактов, — и объявления сливаются. Одно и то же имя, дважды объявленное одним участником, означает, что этот участник дважды описывает один ресурс, а не конфликт.
- Объявление не меняет ни одного байта. Поле — это утверждение о том, что вывел гостевой модуль, и никогда не изменение того, что он выдал, поэтому отрендеренный результат гостевого модуля одинаков независимо от того, объявляет он что-либо или нет. Опустить
derived_keysдопустимо, и тогда проверка для этого гостевого модуля бездействует.
Сообщение фактов о том, что выдал гостевой модуль
Некоторые сведения о рендере узла видны только провайдеру, который его выполнил, — что содержат записанные им документы, какие имена они определяют, сколько чего-либо он выдал, — потому что извлечь их из байтов файла значит понимать формат провайдера. render_node может сам сообщать такие сведения в необязательном списке render_facts рядом со своими файлами:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "render_facts": [ { "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] }, { "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] } ]}Каждый факт — это name и value, и оба принадлежат вашему провайдеру: какие факты он сообщает, что означает каждое имя и что содержит каждая запись, — часть собственного документированного контракта вашего провайдера, поэтому задокументируйте их для авторов, которые будут их читать.
Сообщайте значение каждого факта как список — массив JSON, — даже если в нём одна запись. Одно имя может сообщаться более чем одним рендером компонента: его собственный рендер может состоять из нескольких вызовов — скажем, рендера чарта и размещения артефактов, — а каждая сущность Feature, прикреплённая к компоненту, рендерится через собственный вызов провайдера. Ни один провайдер не может знать во время рендера, будет ли его сообщение единственным под данным именем, поэтому каждое сообщение — список, и компилятор объединяет списки, полученные одним именем, в один список. Факт, значение которого является чем-либо иным — объектом, строкой, числом, логическим значением, null, — отклоняется, когда ваш гостевой модуль его возвращает: сборка останавливается с кратким кодом E0325, называя факт, узел и ваш гостевой модуль и указывая, каким было значение. Записи внутри списка — любые значения JSON в той форме, которую вы документируете.
То, что значение является списком, — единственное, что компилятор о нём узнаёт. Он индексирует факты по имени и передаёт каждый список шаблонам, которые его читают, — факты компонента-хоста каждой прикреплённой к нему сущности Feature, факты каждого вызывающего — сущности Feature, которая объявляет, что читает факты рендера своих вызывающих, и факты каждой цели — сущности Feature, которая объявляет, что читает факты рендера компонентов, с которыми связан её хост, как описывает контекст шаблонов, — декодируя каждый список в значение, по которому шаблон может выполнить range. Он никогда не узнаёт, что означает имя или запись, и никогда не выводит факт сам, поэтому новый провайдер может сообщать новые факты без каких-либо изменений на стороне компилятора. Факты, которые прикреплённая к узлу сущность Feature сообщает из собственного рендера, хранятся отдельно от фактов, сообщённых собственным рендером узла.
Решая, что сообщать, полезно знать четыре свойства:
- Порядок определяете вы. Факты сохраняют порядок, в котором их перечисляет ваш гостевой модуль, а каждое значение сохраняет собственные байты — порядок записей списка и ключей каждого объекта таков, каким его записал ваш гостевой модуль. Перечисляйте факты в фиксированном порядке и записывайте каждую запись с фиксированным порядком ключей, чтобы одинаковые входные данные давали одинаковые байты; список фактов, а не словарь, используется именно для того, чтобы порядок сохранялся в собственном типе последовательности каждого набора разработки без какой-либо пометки, тогда как словарь сохраняет порядок, записанный гостевым модулем, только если его схема помечает его как сохраняющий порядок и гостевой модуль заполняет контейнер набора, сохраняющий порядок.
- Сообщение фактов не меняет ни одного байта. Файлы, которые записывает компилятор, — это файлы, которые вернул ваш гостевой модуль, независимо от того, сопровождают их факты или нет.
- Узел может сообщать факты в нескольких пересечениях. Узел может рендериться как рендер источника, синтез рабочей нагрузки и размещение артефактов; факты, сообщённые каждым из них, хранятся в порядке выполнения пересечений, а имя, сообщённое более чем одним из них, читается как один список, объединяющий их в этом порядке.
- Не сообщать ничего — полный ответ. Опустить
render_factsдопустимо, и провайдер, который ничего не сообщает, рендерит точно так же, как без этого поля.
Тип RenderFact опубликован в трёх пакетах ABI и реэкспортируется набором разработки плагинов каждого языка, а примеры рендера в наборах сообщают два факта рядом со своими файлами. В Go значение — это JSON, который пишет ваш гостевой модуль; именно сериализация среза структур, а не словарей, сохраняет ключи каждой записи в том порядке, в котором вы их объявили:
type stackFact struct { Name string `json:"name"` Resources int `json:"resources"`}
stacks, err := json.Marshal([]stackFact{{Name: "payments-api", Resources: 2}})if err != nil { pdk.SetError(err) return 1}out := aggrega.RenderNodeOutput{ Files: files, RenderFacts: []aggrega.RenderFact{{Name: "stacks", Value: stacks}},}Исключение отрисованных единиц
Отрисовка источника может называть единицы, которые провайдер должен исключить из результата отрисовки, — например, Secret, который загруженный чарт заново генерирует при каждой отрисовке. Какую именно отрисованную единицу называет запись, знает только ваш провайдер, поэтому записи передаются вашему гостю, и исключение выполняет он. Они поступают во входные данные render_node как необязательный список omits рядом с source_listing:
{ "node": { "id": "payments-api" }, "context": { }, "source_listing": { "root": "/acquired/payments-chart", "root_is_dir": true, "entries": [] }, "omits": [ { "kind": "Secret", "name": "payments-api-token", "namespace": "payments" }, { "kind": "ConfigMap", "name": "payments-api-dashboards" } ]}Каждая запись состоит из kind, name и необязательного namespace, уже разрешённых в простые строки и перечисленных в порядке, в котором их объявил автор; запись, не относящаяся к сборке, не передаётся. Что выбирают эти три поля, определяет собственный контракт вашего провайдера — вид, имя и пространство имён ресурса в формате вашей цели, — поэтому задокументируйте его для авторов, которые пишут записи.
Автор может построить поля записи из значения, которое он объявил чувствительным, — например, ресурс, названный по чувствительной настройке. Такая запись поступает с "sensitive": true, и ваш гость обращается с ней так же, как с любым другим помеченным значением во входных данных отрисовки (см. Значения, которые входные данные помечают как чувствительные): он по-прежнему сопоставляет и подсчитывает запись по её полям, для чего запись и существует, и не включает ни одно из её полей в отказ, предупреждение или строку журнала. Пометка охватывает всю запись, потому что компилятор не сообщает, какое поле получено из этого значения. Она отсутствует, если ни одно поле не построено из такого значения.
Гость, соблюдающий записи, делает три вещи:
- Сопоставляет каждую запись с тем, что он отрисовал, в терминах вашего формата.
- Исключает каждую сопоставленную единицу из всего, что возвращает, — из своих
files, имён, которые он объявляет вderived_keys, и фактов, которые он сообщает вrender_facts, — чтобы ничто из полученного компилятором её больше не описывало. - Сообщает по одному счётчику на запись в необязательном списке
omittedв своих выходных данных, в порядке поступления записей; каждый счётчик — число единиц, сопоставленных записи, причём они учитываются независимо от того, сопоставила ли их также другая запись:
{ "files": [ { "path": "templates/deployment.yaml", "content": "..." } ], "omitted": [1, 0]}Ноль — полноценный ответ: эта запись не сопоставила ничего из отрисованного вашим гостем. Счётчики — единственное, что возвращается об исключённом; сами единицы просто отсутствуют в том, что вернул ваш гость.
Провайдер, выполняющий все три действия, объявляет это через omits: true в своём контракте. Сущность Plugin фиксирует то же заявление как spec.provider.contract.omits; если сущность содержит контракт поведения отрисовки, загрузка отклоняет гостя, чей describe() сообщает другое значение. Записи сопровождают только листинг источника: отрисовка синтезированной рабочей нагрузки или набора артефактов их никогда не содержит.
Отрисовка без записей не затрагивается этими полями. Оба поля необязательны и отсутствуют, если пусты, поэтому отрисовка без записей проходит через сокет байт в байт так же, как если бы этих полей не существовало, а гость, который их никогда не читает, ими не затрагивается. Тип OmitEntry опубликован в трёх пакетах ABI и реэкспортируется комплектом разработки плагинов для каждого языка.
Что компилятор делает с вашим ответом. Записи берутся из ключа omits:, который автор пишет в Recipe или FeatureRecipe (Recipe → Поле omits:); компилятор вычисляет шаблоны каждой записи и передаёт вашему гостю применимые. Затем он читает ваши счётчики, и только их, — он никогда не заглядывает в возвращённый файл, чтобы их проверить:
- Список счётчиков, не содержащий ровно по одному неотрицательному счётчику на каждую переданную запись, останавливает сборку — если он отсутствует, слишком короткий, слишком длинный или содержит счётчик меньше нуля; при этом называются узел, ваш провайдер, сколько записей было передано и сколько счётчиков вернулось. Несовпадающий отчёт не позволяет определить, какая запись что исключила. См. A provider’s omitted counts do not match the omits entries it was handed (Счётчики исключений провайдера не соответствуют переданным ему записям omits).
- Ноль останавливает сборку; при этом называется первая в авторском порядке запись с нулевым счётчиком: узел, ваш провайдер, позиция записи в списке, который объявляет её документ, а также вид, имя и пространство имён, в которые она разрешилась. Ноль сообщает ваш гость; остановка — дело компилятора. См. An omits entry left out nothing the source rendered (Запись omits не исключила ничего из отрисованного источником).
- Документ, объявляющий
omits:, провайдер которого не заявляетomits: true, отклоняется до начала какой-либо отрисовки, чтобы автор сразу узнал, что ключ не подействует, а не обнаружил документ в выходных данных. Компилятор читает ваше заявление из вашегоdescribe(), как только привязаны все Recipe и FeatureRecipe сборки, и отклоняет до отрисовки первого компонента, — поэтому гость, не заявляющий ключ, никогда не получает записей. Отказ называет провайдера и компонент, для которого отрисовывается документ, а для FeatureRecipe, генерирующего один раз для границы, — границу и подключение. См. The provider does not support omits (Провайдер не поддерживает omits).
Текущий статус: доступно. Гости helm, compose и cloudformation, распространяемые с компилятором, объявляют это заявление и соблюдают записи. Гость helm не записывает ни одного поля какой-либо записи в возвращаемый текст. Гости compose и cloudformation называют вид, имя и пространство имён записи, когда отклоняют её, а также исключённые записью единицы, когда отклоняют файл или шаблон, который всё ещё их называет, и показывают там каждое поле помеченной записи как <redacted>. Гости helm-chart и terraform этого заявления не объявляют, поэтому документ, объявляющий omits:, который отрисовывает один из них, отклоняется.
Приём файлов, которые Recipe добавляет в границу
Некоторые файлы принадлежат границе в целом, а не одному из её компонентов, — например, конфигурация провайдера, которую цель читает один раз для всего, что развёртывает граница. Recipe записывает их в spec.boundary.artifacts, и работу выполняет компилятор, а не ваш гость: он вычисляет каждый файл в том же контексте, в котором вычисляется запись artifacts:, объединяет по имени файлы, объявленные всеми участниками группы диспетчеризации, и записывает каждый один раз в каталог с собранными выходными данными группы, рядом с тем, что возвращает ваш assemble_boundary. Ваш гость не получает ни одного из этих файлов ни в одном экспорте, и о них его никогда не спрашивают, поэтому реализовывать ничего не нужно — нужно лишь сделать заявление о вашей цели:
"contract": { "input_kinds": { "sourced": true, "artifacts_standalone": true }, "boundary_assembly": "nest", "boundary_artifacts": true}Объявляйте boundary_artifacts: true, только если ваша цель читает файл, помещённый в этот каталог, как часть выходных данных границы. Сущность Plugin фиксирует то же заявление как spec.provider.contract.boundaryArtifacts; если сущность содержит контракт поведения отрисовки, загрузка отклоняет гостя, чей describe() сообщает другое значение. Recipe, объявляющий этот блок, провайдер которого его не заявляет, отклоняется до начала какой-либо отрисовки с указанием провайдера и компонента; см. The provider does not support boundary artifacts (Провайдер не поддерживает артефакты границы). Файл, который одно из этих объединений помещает под именем, которое записывает и ваша сборка, останавливает сборку как два участника, записывающих один выходной путь, поэтому имена, которые записывает ваша сборка, входят в то, что вы документируете для авторов.
Текущий статус: доступно. Гость terraform, распространяемый с компилятором, объявляет это заявление, и Terraform читает каждый файл рядом с корневой конфигурацией границы; гости helm, compose, helm-chart и cloudformation его не объявляют.
Объявление того, что экосистема источника никогда не поставляет
Локальный каталог источника Recipe — расположенный рядом чарт, модуль — публикуется вместе с Recipe, и не каждый файл в нём к нему относится. Гостевой модуль провайдера сообщает, что его собственная экосистема никогда не поставляет, через source_ignore в своём контракте, в виде правил игнорирования в синтаксисе, который использует .gitignore:
"contract": { "input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false }, "boundary_assembly": "none", "source_ignore": { "patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"], "files": [".helmignore"] }}patterns— правила, читаемые от корня каталога источника и применяемые по порядку; более позднее совпадение переопределяет более раннее.filesназывает файлы игнорирования, которые ваша экосистема учитывает внутри источника. Где бы обход источника ни встретил такой файл, его строки читаются как дополнительные правила для содержащего его каталога, после ваших шаблонов.
Объявление читается при закреплении сущности, а не при её рендеринге. Шаг закрепления у автора находит плагин, обслуживающий возможность сущности в его рабочем пространстве, объединяет ваши правила с его собственным .aggregaignore — строки которого идут последними и поэтому побеждают для любого пути, который они называют, — и записывает имя вашего плагина, без версии, вместе с точными объединёнными правилами в entity.lock сущности. Каждая последующая публикация, сравнение и рендеринг этой сущности применяют записанные правила; хост сопоставляет их и не имеет собственного мнения ни о какой экосистеме. Поэтому файлы, которые получает ваш гостевой модуль при рендеринге, — листинг и каждый файл, который он просит хост упаковать или прочитать, — это ровно те файлы, которые несёт публикация сущности, а на запрос файла, исключённого правилами, хост отвечает, что его нет, называя его. Символическая ссылка внутри источника отклоняется до вызова вашего гостевого модуля.
Совместимость следует из записанного. Гостевой модуль может отрендерить Recipe, опубликованный для его возможности, если он использует ту же версию ABI, его контракт соответствует заявлению его сущности и ему не нужен файл вне опубликованного набора. Гостевой модуль, которому нужен файл, исключённый из набора, должен явно завершить сборку с ошибкой и назвать файл — отказ хоста в упаковке или чтении называет его, и гостевой модуль передаёт это в свою ошибку. Если плагин, который рабочее пространство потребителя привязывает к возможности, объявляет правила, отличные от записанных в lock-файле сущности, команда pull потребителя выводит предупреждение с названием обоих плагинов и разницей; она никогда не останавливается из-за этого.
Отсутствие source_ignore означает отсутствие правил, и тогда отображаемый вами источник сохраняет каждый файл, который сохраняют собственные правила автора. Поле необязательно и не требует собственной версии ABI: гостевой модуль без него загружается как не объявляющий ничего. Сущность Plugin записывает то же объявление как spec.provider.contract.sourceIgnore; если она это делает, загрузка отклоняет гостевой модуль, чей describe() сообщает что-то иное.
Детерминизм и повторное использование экземпляра
Хост использует выходные байты гостевого модуля дословно, поэтому гостевой модуль должен выдавать идентичный вывод на идентичный ввод. По умолчанию гостевой модуль загружается заново для каждого узла — по построению между узлами не переносится никакого состояния. Гостевой модуль, который сам объявляет reusable_instance, вместо этого загружается один раз на сборку, и его единственный экземпляр обслуживает каждый переход, что устраняет основные затраты на создание экземпляра для каждого узла. Поскольку повторное использование безопасно только для гостевого модуля без состояния, aggrega build --verify-determinism рендерит каждый узел дважды через один и тот же экземпляр и останавливает сборку, если два рендеринга какого-либо узла различаются; сборка по умолчанию рендерит один раз и доверяет объявлению. Кеш компиляции Wasm хранится на диске и общий для процесса, поэтому гостевой модуль компилируется один раз, а повторные сборки пропускают перекомпиляцию.
Сокет линтера — линтер публикации
Сокет линтера поставляется как стандартный publishing-linter — внеполосная проверка, которая запускается через aggrega lint, а не во время компиляции. Он принимает сущность каталога (а в режиме --pre-publish — ещё и текущую опубликованную версию сущности) и возвращает список замечаний, каждое с уровнем серьёзности и сообщением; в режиме --pre-publish он также возвращает классификацию повышения версии. Хост вызывает его через встроенную среду выполнения Wasm, за тем же барьером AOT-чистоты, что и любой другой сокет. Полный набор правил, уровни серьёзности и отключение отдельных правил описаны в cli/aggrega-lint.md.
Линтер — добровольная дисциплина каталога: компилятор не запускает его во время aggrega build (за единственным исключением рекомендации, не одобряющей x-aggrega-*, которая выводится с уровнем warn во время сборки и с уровнем halt при aggrega lint --pre-publish). Поскольку правила находятся в плагине, предприятие может направить aggrega lint на другой плагин-линтер, чтобы применять собственную дисциплину.
Никакое значение параметра не попадает в плагин-линтер ни в одной области, в которой запускается aggrega lint. Прежде чем передать какой-либо документ, хост скрывает значения параметров по умолчанию сущности Aggregate, значения, которые она передаёт каждому импортируемому модулю, и параметры сущности Release, сохраняя контракт каждого объявления параметра — только ключи, которыми записано объявление, на каждом уровне вложенности, — и любой текст шаблона, читающий параметр: значение параметра само может быть учётными данными, а подключённый здесь плагин может быть кодом, написанным не в этом рабочем пространстве. Что несёт каждый документ, изложено в разделе Что получает плагин-линтер.
Кодирование при передаче. Ввод и вывод передаются как канонический CBOR (RFC 8949 §4.2.1). Гостевой модуль декодирует ввод и кодирует вывод через точки входа, которые уже есть у LinterInput и LinterOutput его набора, — DecodeCBOR и EncodeCBOR в Go, decode_cbor и encode_cbor в Rust, decodeCBORLinterInput и encodeCBORLinterOutput в TypeScript, — читая и записывая байты (Vec<u8> в Rust, Host.inputBytes() и Host.outputBytes(...) в TypeScript). Библиотека CBOR не нужна, и никто не разбирает байты вручную. Документы сущностей — proposed, previous, implemented_component и release — и каждое значение components передаются как байты своих JSON-документов, поэтому гостевой модуль разбирает их как JSON, чтобы заглянуть внутрь. components — отображение, которое схема помечает как сохраняющее порядок, поэтому на вводе правила, читающего сущность Release целиком, оно передаётся как упорядоченный список записей в порядке, в котором Aggregate объявляет свои экземпляры компонентов, и гостевой модуль читает его через сохраняющий порядок контейнер своего набора. policies передаётся как отображение, содержащее только установленные флаги, поэтому флаг, которого в нём нет, читается как false, а каждое замечание передаётся в общей форме Diagnostic. Ответ, который не является LinterOutput в этой кодировке — записанный как JSON или содержащий поле верхнего уровня, не объявленное формой, — проваливает проверку с указанием вызванного экспорта, а не читается как запуск без замечаний. При прямом вызове через aggrega plugin run-local --export lint_rules линтер получает написанную автором JSON-нагрузку, преобразованную в эту кодировку, а его ответ читается как форма вывода экспорта и печатается в виде JSON — ответ, не соответствующий этой форме, отклоняется с указанием экспорта, как его отклоняет сборка.
Текущий статус: доступно. publishing-linter поставляется и запускается через хост с помощью aggrega lint.
Сокет парсера — вывод канонического дерева
Парсер превращает исходный текст в формате, который компилятор не читает нативно, в каноническое структурированное дерево, так что потребитель читает дерево, а не несёт собственный парсер. Хост находит парсер, объявляющий запрошенный формат как parse:<format>, и вызывает его экспорт parse в трёх случаях: когда политике render-verdict передаётся отрендеренный артефакт в формате, который она не читает нативно, когда импортёр запрашивает у хоста дерево через aggrega_parse_source, и когда распознаётся импорт, в котором формат не указан (см. сокет импортёра ниже). Гость никогда не вызывает парсер сам.
Форма входных данных (хост → гость). Документ ParseInput, содержащий:
format— запрошенный формат, одна из возможностейparse:<format>парсера без префикса.bytes— байты исходного текста.options— документ параметров, который потребитель передаёт для специфичного для парсера поведения; передаётся без изменений. Отсутствует, если потребитель его не передаёт.
Форма выходных данных (гость → хост). Документ ParseOutput, содержащий tree — разобранный исходный текст в виде JSON-документа, верхним уровнем которого может быть объект, массив или скаляр, — диагностические сообщения в общей форме Diagnostic, необязательные диапазоны исходного текста, указывающие положение узлов дерева в исходных байтах, и ошибку error, если разбор не удалось завершить. Все поля и их ограничения приведены в сгенерированном справочнике по схеме сокета парсера.
Кодирование при передаче. Входные и выходные данные передаются в каноническом CBOR (RFC 8949 §4.2.1) — в том же кодировании, в котором передаётся тот же ParseInput, когда гость передаёт его в aggrega_parse_source. Гость декодирует входные данные и кодирует выходные через точки входа, которые уже есть у ParseInput и ParseOutput его набора, — DecodeCBOR и EncodeCBOR в Go, decode_cbor и encode_cbor в Rust, decodeCBORParseInput и encodeCBORParseOutput в TypeScript, — читая и записывая байты (Vec<u8> в Rust, Host.inputBytes() и Host.outputBytes(...) в TypeScript). Библиотека CBOR не нужна, и ничто не разбирает байты вручную. Байты исходного текста передаются как необработанная последовательность байтов, и сгенерированный декодер помещает их в собственный тип поля набора: срез байтов в Go, строку base64 в Rust и TypeScript. options и tree передаются как байты их JSON-документов, так что дерево, записанное парсером, доходит до потребителя без изменений. Парсер, который не может завершить работу, сообщает причину в поле error выходных данных, и разбор завершается ошибкой с указанием парсера и этого сообщения; ответ, не являющийся ParseOutput в этом кодировании, — записанный как JSON или содержащий поле верхнего уровня, которое форма не объявляет, — тоже приводит к ошибке разбора с указанием парсера и его экспорта parse. Неудачный разбор останавливает сборку на роли render-verdict и доходит до импортёра как ошибка, которой отвечает aggrega_parse_source. То же происходит с исходным текстом, который парсер отвергает, — отвечая на него диагностикой halt рядом с деревом: вызов импортёра завершается ошибкой с сообщением каждой такой диагностики в порядке парсера, и дерево ему не передаётся. При прямом вызове через aggrega plugin run-local --export parse парсеру передаётся написанная вручную полезная нагрузка JSON, преобразованная в это кодирование, — исходный текст в ней записан в base64, как JSON записывает любое байтовое поле, — а его ответ читается как форма вывода экспорта и печатается в виде JSON — ответ, не соответствующий этой форме, отклоняется с указанием экспорта, как его отклоняет сборка.
Определения типов. Типы передачи парсера — ParseInput, ParseOutput, NodeSpan и SourceSpan — опубликованы во всех трёх пакетах ABI и реэкспортируются набором для разработки плагинов каждого языка; они сгенерированы из одного кодека, поэтому все три остаются согласованными. Пример parse каждого набора читает входные данные и записывает выходные именно так, как и встроенные в бинарный файл парсеры для HCL, TOML, YAML, JSON и JSON с комментариями.
Текущий статус: доступно — вызывается на роли render-verdict для артефакта в формате, который политика не читает нативно, через aggrega_parse_source для импортёра и для распознавания формата импорта, в котором формат не указан.
Сокет импортёра — черновые файлы описания
Импортёр превращает исходник, написанный для другого инструмента (например, поток, экспортированный из конструктора агентов), в черновые файлы описания Aggrega. Он работает вне сборки: aggrega import, метод aggrega/import сеанса редактора и инструмент import для ассистента находят импортёр, объявляющий запрошенный формат как import:<format>, и вызывают его экспорт import один раз за импорт. Сборка никогда его не вызывает. Какой импортёр запускается и что ему передаёт оператор, описано в разделе Какой импортёр превращает исходник в черновики. Собственные импортёры компилятора, по одному на каждый читаемый им формат, описаны на странице Базовые импортёры: какие это форматы, что читает каждый, что он создаёт в черновике, какие настройки принимает, как они публикуются с каждым выпуском компилятора и как импорт загружает и проверяет импортёр, которого ещё нет на машине.
Форма входа (хост → гость). Документ ImportInput, содержащий:
format— формат, запрошенный импортом, одна из возможностей импортёраimport:<format>без префикса.bytes— байты исходника: весь файл при импорте файла и пусто при импорте каталога, файлы которого приходят вsources.name— имя источника без каталога перед ним, чтобы импортёр мог назвать источник в том, что он сообщает, и в том, что он создаёт как черновик: при импорте файла — базовое имя файла, из которого прочитаныbytes; при импорте каталога — собственное базовое имя каталога, прочитанное из его полного пути, так чтоaggrega import .передаёт имя каталога, в котором выполняется, тогда как файлы каталога по-прежнему приходят каждый под своим именем. Отсутствует, если у источника нет имени, которое можно передать.sources— именованные исходники, каждый со своим именем и байтами, в одном списке, отсортированном по имени: при импорте каталога — каждый его файл, выбранный объявленными шаблонами файлов импортёра, за исключением каталога результатов сборки рабочей области, с именем в виде пути внутри каталога через косую черту; а также файлы, которые записьplugins.importer, подключающая этот импортёр, объявляет вwith.sources, каждый под своим базовым именем. Файл каталога и файл изwith.sourcesс одинаковым именем приводят к отказу в импорте, а не к сокрытию одного другим. Отсутствует, если исходников нет.settings— объект настроек, который эта запись объявляет вwith.settings, в виде JSON-документа с отсортированными ключами, передаваемый без изменений. Отсутствует, если ни одна запись не подключает импортёр или запись не объявляет настроек.catalog— представление сущностей Components, которые содержит собственный каталог рабочей области: того каталога, из которого был выбран сам импортёр, — папок каталога рабочей области или, если рабочая область их не называет, снимка каталога, который публикует её реестр по умолчанию и который хранится на этой машине, — без какой-либо загрузки для самого представления. Его списокcomponentsсодержит по одной записи на каждое имя сущности Component, отсортированные по имени; если каталог содержит несколько версий сущности Component, запись описывает версию, в которую разрешается ссылка на неё без версии. Каждая запись содержитnameиversionсущности Component, еёlabels, имена ключей верхнего уровня, объявленных в её values и provides (valuesиprovides, каждый отсортирован), и еёsockets— для каждого сокетаnameи меткуselector, которой должна удовлетворять подключённая через него зависимость, — в порядке объявления в сущности Component. Сущность Component, расширяющая другую, содержит и унаследованное, и объявленное ею, причём унаследованные сокеты идут первыми. Представление содержит только имена, версии, метки и селекторы — никогда не значение, значение по умолчанию или секрет, — а его порядок фиксирован, так что один каталог даёт одну последовательность байтов. Отсутствует, если каталог не содержит ни одной сущности Component.
Форма выхода (гость → хост). Документ ImportOutput, содержащий сущности, созданные импортом (каждая — ссылка на существующую сущность каталога или черновое тело), решения сопоставления, стоящие за ними, диагностику в общей форме Diagnostic, файлы заготовки для записи и error с описанием сбоя, если импорт не удалось завершить. Все поля и их ограничения приведены в сгенерированном справочнике схемы сокета импортёра.
Кодирование при передаче. И вход, и выход передаются как канонический CBOR (RFC 8949 §4.2.1). Гость декодирует вход и кодирует выход через точки входа, которые уже есть у ImportInput и ImportOutput его набора, — DecodeCBOR и EncodeCBOR в Go, decode_cbor и encode_cbor в Rust, decodeCBORImportInput и encodeCBORImportOutput в TypeScript, — читая и записывая байты (Vec<u8> в Rust, Host.inputBytes() и Host.outputBytes(...) в TypeScript). Библиотека CBOR не нужна, и ничто не разбирает байты вручную. settings передаётся внутри двоичного документа как байты своего JSON-документа, поэтому, чтобы заглянуть внутрь, гость разбирает его как JSON, как и на любом другом сокете. Импортёр, который не может завершить работу, сообщает причину в поле error выхода, и импорт останавливается с указанием импортёра и этого сообщения; ответ, не являющийся ImportOutput в этом кодировании (записанный как JSON или содержащий поле верхнего уровня, не объявленное формой), тоже останавливает импорт с указанием импортёра и его экспорта import. При прямом вызове через aggrega plugin run-local --export import импортёр получает написанную полезную нагрузку JSON, преобразованную в это кодирование, а его ответ читается как форма вывода экспорта и печатается в виде JSON — ответ, не соответствующий этой форме, отклоняется с указанием экспорта, как его отклоняет сборка.
Как распознаётся исходник вашего формата. Импорт может не указывать формат, и тогда хост распознаёт его по тому, что объявляют импортёры, сам не зная ни одного формата. Импортёр объявляет в своём самоотчёте describe(), в разделе importer (ImporterContract), список detect сигнатур, по которым распознаётся исходник его форматов. Каждая DetectSignature указывает:
syntax— синтаксический формат, в котором разбирается исходник, — формат, который плагин-парсер объявляет какparse:<syntax>, напримерjsonилиyaml;files— необязательные шаблоны имён файлов, сопоставляемые с концом имени исходника: один сегмент — с собственным именем файла, несколько сегментов через косую черту — с таким же числом последних сегментов его пути;*,?и[...]совпадают в пределах сегмента. Сигнатура без шаблонов применяется к исходнику-файлу с любым именем и ни к одному файлу каталога;match— предикаты, которым должно удовлетворять разобранное дерево, все сразу; каждый —PathMatchсpathиз ключей, соединённых точками от вершины дерева (целочисленный сегмент выбирает позицию в массиве),isсо значениемpresent,absent,object,array,string,numberилиbooleanи, необязательно, строкойequalsили строкойprefix— не более чем одной из двух.
Если импорт не указывает формат, хост сопоставляет сигнатуры всех импортёров, из которых выбирает импорт, — из каталога рабочей области и базовых импортёров компилятора — в порядке их идентификатора и версии: он разбирает исходник парсером, который каталог предоставляет для синтаксиса (а для синтаксиса, парсера которого в каталоге нет, — парсером, встроенным в сам компилятор), не более одного раза на синтаксис, вычисляет предикаты над деревом и читает исходник как формат единственного импортёра, чья сигнатура совпала. Через этот же парсер обслуживается и вызов aggrega_parse_source импортёра, поэтому импортёр читает исходник тем же парсером, через который он был распознан. Исходник, не разбираемый в некотором синтаксисе, не совпадает ни с одной сигнатурой, указывающей этот синтаксис; синтаксис, для которого парсера нет ни в каталоге, ни в компиляторе, останавливает распознавание с указанием отсутствия парсера. Исходник, не совпавший ни с одной сигнатурой, отклоняется с просьбой указать формат, а распознанный как несколько форматов отклоняется с их перечислением. Сигнатура распознаёт исходник как каждый формат, объявленный её импортёром, поэтому импортёр, исходники которого должны распознаваться, обслуживает один формат, а импортёр без сигнатур доступен только при явном указании его формата.
Сущность Plugin импортёра записывает тот же список как spec.importer.detect, выведенный из describe(), когда сущность генерируется из гостевого модуля; распознавание читает эту запись, поэтому гостевой модуль не загружается, пока не определён его формат. Загрузка и публикация гостевого модуля отклоняют модуль, отчёт которого отличается от записи его сущности, с указанием importer.detect, а сущность, не записывающая ни одной сигнатуры, ничего не заявляет. Дескриптор отклоняется при загрузке, если контракт объявлен у плагина, который не является импортёром, если сигнатура не называет синтаксис или содержит некорректный шаблон файла, и если предикат не называет путь, указывает is вне семи значений или одновременно equals и prefix.
Базовые импортёры компилятора и пример import из Go-кита объявляют свои сигнатуры именно так. Импортёр Langflow читает источник как JSON и требует массив в data.nodes; импортёр Flowise требует массивы в nodes и edges и отсутствие чего-либо в data.nodes; импортёр n8n требует массив в nodes, объект в connections и отсутствие чего-либо в edges и data.nodes; импортёр MCP объявляет по одной сигнатуре на каждую клиентскую конфигурацию с указанием её файла — .mcp.json, claude_desktop_config.json и .cursor/mcp.json, читаемые как JSON с объектом в mcpServers, и .vscode/mcp.json, читаемый как JSON с комментариями, как его читает Visual Studio Code, с объектом в servers, — и одну без указания файла, требующую строку $schema, начинающуюся с https://static.modelcontextprotocol.io/schemas/; импортёр Compose читает источник как YAML, называет файлы, которые Compose читает по умолчанию, — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml и четыре соответствующих файла переопределений — и требует объект в services; импортёр Dify читает источник как YAML, не называет файлов и требует строку app в kind и наличие чего-либо в app.mode и в version; импортёр CrewAI называет config/agents.yaml и config/tasks.yaml, читаемые как YAML без требований к дереву, crew.jsonc и crew.json, читаемые как JSON с комментариями со списком в agents, и agents/*.jsonc и agents/*.json, читаемые как JSON с комментариями с наличием чего-либо в role, так что никакие две из них не совпадают с одним источником, а файл, импортируемый отдельно без указания формата, читается и как YAML, и как JSON; импортёр LangGraph называет langgraph.json, читаемый как JSON с объектом в graphs, объявляет одну сигнатуру без указания файла, требующую объект в graphs и строку https://langgra.ph/schema.json в $schema, и не называет файл окружения, поскольку распознавание читает каждый файл, выбранный шаблонами любого импортёра, и шаблон, называющий такой файл, открывал бы файлы окружения каждого каталога, импортируемого без указания формата; импортёр Google ADK называет root_agent.yaml, читаемый как YAML с наличием чего-либо в name и в instruction либо строки в agent_class и чего-либо в name, и не называет других файлов, поскольку конфигурация субагента может называться как угодно, а шаблон, называющий каждый YAML-файл, открывал бы каждый такой файл в каждом каталоге, импортируемом без указания формата; импортёр Agent Framework читает источник как YAML, не называет файлов и требует строку Prompt в kind и объект в model; пример import из Go-кита читает источник как YAML и требует строку DemoSource в kind. На Go:
Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{ Syntax: "json", Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},}}},Что читает импорт каталога. Источником может быть каталог, и то, что из него читается, определяют объявленные шаблоны файлов импортёра: хост читает ровно те файлы каталога на любой глубине, которые выбирает один из шаблонов files сигнатур импортёра, — каждый сопоставляется с концом пути файла внутри каталога, разделённого косыми чертами, — и передаёт их как sources в порядке имён, при пустом bytes и с собственным именем каталога в качестве name. Никакие другие файлы каталога не открываются. Папка, в которую сборка рабочего пространства записывает свои отрендеренные файлы, — dist/ под корнем рабочего пространства — не читается как часть содержащего её каталога: ни один из её файлов не передаётся и не распознаётся, а ссылка, ведущая к ней, пропускается, поэтому собранный каталог читается как содержащийся в нём проект, тогда как каталог, который является этой папкой или находится внутри неё, читается так, как он указан. Сигнатура без шаблонов files не выбирает ни одного файла каталога, поэтому импортёр, не объявивший шаблонов, читает один файл и отклоняет каталог; каталог, не содержащий ни одного файла, выбираемого шаблонами, тоже отклоняется. Каталог ограничен самим собой: ссылка среди читаемых файлов или на каталог, ведущая за пределы каталога, отклоняется до какого-либо чтения, в ссылку на каталог вход никогда не выполняется, а ссылка на файл, не выбранный ни одним шаблоном, пропускается без чтения. Распознавание формата каталога следует тому же правилу: каждая сигнатура проверяется на файлах, выбранных её шаблонами, в порядке имён, каждый файл читается и разбирается не более одного раза на синтаксис, а сигнатура без шаблонов не применяется ни к одному из них. Хост ничего не ограничивает: слишком большой для импортёра каталог отклоняется собственными ограничениями среды выполнения импортёра. Ни один из импортёров компилятора Langflow, Flowise, n8n, Dify и Agent Framework не объявляет шаблонов files, поэтому каждый читает один файл; его импортёр MCP объявляет имена четырёх клиентских конфигураций, поэтому читает каждую из них, имеющуюся в каталоге; его импортёр Compose объявляет восемь имён файлов Compose, поэтому получает каждый файл Compose из каталога и объединяет те, которые прочитал бы Compose; его импортёр CrewAI объявляет шесть имён, под которыми записываются декларации проекта CrewAI, поэтому получает декларации проекта и ничего из его программы; его импортёр LangGraph объявляет langgraph.json, поэтому получает конфигурацию приложения и ничего из его кода или файлов окружения, а файл окружения попадает к нему только через with.sources его подключения; и его импортёр Google ADK объявляет root_agent.yaml, поэтому получает конфигурацию корневого агента приложения и ничего из его кода или файла окружения, а конфигурации, называемые его субагентами, попадают к нему только через with.sources его подключения.
Определения типов. Типы передачи импортёра — ImportInput, ImportSource, CatalogProjection, CatalogComponent, CatalogSocket, ImportOutput и переносимые им формы сущностей, решений и заготовок — публикуются во всех трёх пакетах ABI и реэкспортируются комплектом разработки плагинов для каждого языка; они генерируются из одного кодека, чтобы все три оставались синхронными, — как и типы распознавания ImporterContract, DetectSignature и PathMatch, которые переносит самоотчёт describe. Пакет импортёра Go-кита, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer, содержит всё, что делает импортёр независимо от формата, и базовые импортёры компилятора, каждый из которых построен на нём, читают ввод и пишут вывод именно так.
С чем сопоставляет импортёр, построенный на Go-ките. Оценщик кита взвешивает каждый узел источника по отношению к сущностям Components представления catalog и ни к чему другому: кандидатами служит собственный каталог рабочего пространства — сущности Components корпоративного каталога точно так же, как стандартной библиотеки, — и у кита нет собственных кандидатов. У каждой сущности Component он читает имя, категорию из её метки component.aggrega.ai/category, её метки и имена ключей, объявленных её values; её ключи provides и сокеты не взвешиваются. Сущность Component, добавленная в каталог, становится кандидатом при следующем импорте без пересборки импортёра. Если представление отсутствует, поскольку каталог не содержит ни одной сущности Component, ни у одного узла нет кандидата: ни один не связывается ссылкой и не получает подсказки, а каждый узел, которому черновик даёт собственную сущность Component, создаётся черновиком. Так оценивает каждый импортёр, использующий кит, — в том числе импортёры компилятора Langflow, Flowise, n8n и Compose, тогда как его импортёр MCP не взвешивает кандидатов; импортёр, не использующий кит, читает представление как угодно.
Для чего импортёр, построенный на наборе для Go, читает сокеты платформы. Сокеты ничего не весят в оценке, но набор читает их, чтобы скомпоновать черновик. Формат, потоки которого платформа выполняет в том виде, в каком они написаны, — как это происходит с потоками Langflow, Flowise и n8n, — по умолчанию оформляется в черновике как один экземпляр сущности Component этой платформы, несущий поток, и каждая часть потока подключается к первому сокету — в порядке, в котором запись catalog платформы перечисляет свои sockets, — чьему selector удовлетворяют метки сущности Component этой части в том виде, в каком их несёт представление. Читаются только селектор и метки, а селектор сопоставляется функцией, которую предоставляет импортёр, поскольку набор не несёт собственной грамматики селекторов; если в представлении нет сущности Component с именем платформы, ни одна часть не подключается. В разделе Основные импортёры описан черновик, который таким образом создают импортёры Langflow, Flowise и n8n компилятора, а также параметр layout, который вместо этого оформляет каждый узел как отдельную сущность Component.
Текущий статус: доступно — вызывается командой aggrega import, а также той же операцией в сеансе редактора и в инструменте для ассистента.
Критерий размещения: сокет линтера и роли вердиктов управления
Два из документированных сокетов имеют схожую поверхность — оба выдают результаты по каждому правилу, — но различаются размещением в конвейере и семантикой блокировки. Критерий выбора сокета для конкретной проверки:
- Роли вердиктов управления (внутриполосные, останавливающие сборку). Предназначены для политик, останавливающих сборку: вердикт
haltостанавливает конвейер компиляции, и сборка не создаёт артефактов. Сценарии использования — политики, нарушение которых делает применение результата небезопасным: контрольные точки соответствия (размещение границ PCI / SOC2), инварианты топологии (входящий трафик по принципу нулевого доверия, аутентификация через границы), форма потоков учётных данных (никаких секретов в открытом виде в IR) и т. д. Политика анализирует граф IR (ir-verdict, до рендеринга) или отрендеренные артефакты (render-verdict, после рендеринга). - Сокет линтера (внеполосный, CI / IDE, рекомендательный). Предназначен для проверок лучших практик и обнаруживаемости: правил, нарушение которых подозрительно, но не небезопасно, — осиротевшие секреты, неиспользуемые параметры, устаревший словарь меток, полнота тегов для учёта затрат, отклонение от соглашений об именовании. Сбой даёт рекомендательный вывод; сборка по-прежнему создаёт артефакты.
Критерий размещения в виде одного правила: если проверка должна останавливать сборку, её место — в роли вердикта управления; если проверка должна предупреждать автора или рецензента, не блокируя конвейер, её место — в сокете линтера.
Оба уже доступны. Сокет линтера запускает линтер публикации через aggrega lint; роли вердиктов управления вызываются внутри полосы во время aggrega build, когда рабочее пространство подключает плагин с ролью вердикта. Обратите внимание, что у роли вердикта есть собственные уровни серьёзности — политика сама может выдавать вердикты warn и info, которые дают рекомендации без остановки, — поэтому приведённая выше граница «остановить или порекомендовать» — это указание по размещению проверок целиком, а не утверждение, что политика может только останавливать. Модель уровней серьёзности описана на странице сокета управления.
Перекрёстные ссылки
policy-socket.md— исчерпывающее описание сокета управления: четыре роли, уровни серьёзности вердиктов, входной канал оператора, написание политики для любого из двух движков, поставляемых в составе компилятора, обёртывание стороннего движка политик и эталонные гостевые модули.core-importers.md— собственные импортеры компилятора, по одному на каждый формат, который он читает: что читает каждый из них, их настройки и их публикация с каждым выпуском компилятора.10-status.md#compilation-pipeline-phases— классификация конвейера плагинов на странице статуса (готовность среды выполнения конвейера плагинов Wasm).architecture/04-entity-taxonomy.md§«Domain 3: Infrastructure Base» — принцип Two-Part Plugin для сущностей FeatureRecipes, работающих с учётными данными (шаблон Fetcher + Injector).architecture/13-catalog-and-registry.md— таксономия OCI, начинающаяся с сегмента провайдера.entities/featurerecipe.md— поверхность описанияpipeline:в сущности FeatureRecipe.when-to-use-a-pipeline-step.md— руководство по выбору: шаг конвейера или шаблонная сущность FeatureRecipe.templates/expansion-matrix.md— правила вычисления шаблонов в блокеpipeline:with:конвейера плагинов и семантика доступа к.steps.examples/04-secrets.md— вид конвейера Fetcher + Injector, который может принимать сущность FeatureRecipe для учётных данных.errors/error-translation.md— дисциплина трансляции ошибок, в которой участвуют гостевые модули плагинов.