Контракт плагінів 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 диспетчеризує ролі сокета керування (governance), що діють під час збірки, якщо робочий простір їх налаштовує: роль перетворення анотацій під час розв’язання та роль перетворення міток під час побудови топології (обидві формують вихідні дані), а також вердикт щодо 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, а для aggrega_fetch_external_input, URL якого виділяється як текст, — лише тип відповіді FetchExternalInputResponse. Конкретно для кожного набору:
- 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, парсер цитує токен, який не зміг прочитати. Якщо така помилка стосувалася значення, яке позначають вхідні дані, повідомляйте про неї без значення — наприклад, запустіть той самий крок ще раз, замінивши кожне позначене значення заповнювачем, повідомте про помилку цього запуску, якщо він завершується помилкою в тому самому місці, а інакше вкажіть, що текст помилки приховано. У корисному навантаженні, позначеному цілком, кожне значення є позначеним, тоді як його ключі — структура документа — залишаються читабельними.
Де вхідні дані позначають ключ або корисне навантаження як чутливі (назви наведено так, як їх записує протокол):
| Сокет і експорт | Де зчитується позначка |
|---|---|
провайдер: render_node і validate_node_input (RenderNodeInput) | node.sensitive_rendered_keys: кожен ключ називає запис node.values, коли ці значення належать самій сутності Component і мають ключами листки, які вона оголошує, — valuesMapping сутності Recipe записує ключі, яких не називає жодне оголошення, тож жоден із них тут не позначено, — або запис мапи attachments контейнера робочого навантаження, що читає слот, оголошений чутливим. node.sensitive_values позначає node.values цілком: він має значення true, коли ці значення створив valuesMapping — сутності Recipe або сутності FeatureRecipe приєднання — і він читає значення, яке автор оголосив чутливим. workload_projection.sensitive_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"}, тож саме значення ніколи не потрапляє до плагіна. |
Жодні інші вхідні дані сокетів і жодні вхідні дані інших експортів провайдера не несуть позначок. Позначка ключа називає лише те, що вона точно зіставляє з оголошенням, тож відсутність ключа ніколи не означає, що значення безпечно цитувати: вона означає, що з цим ключем не вдалося зіставити жодне оголошення. Позначка корисного навантаження зчитується з посилань шаблону, який створив це навантаження, — посилання, що досягає оголошеного значення, шаблону, що передає далі всі свої дані, або шаблону, який не вдається розібрати, — і ніколи зі значення, тож її відсутність означає, що шаблон не читав оголошеного значення, наскільки показують його посилання, або що навантаження не створив жоден шаблон; це не твердження, що навантаження не містить нічого чутливого.
Розміщення сокетів Wasm у конвеєрі
Конвеєр компіляції резервує такі точки сокетів. Мітки форми відповідають таксономії з чотирьох міток зі сторінки статусу.
| Сокет | Розміщення в конвеєрі | Статус на сьогодні |
|---|---|---|
Сокет governance, роль annotation-transform | Розв’язання (перед розгортанням анотацій) | доступно — викликається, коли робочий простір підключає плагін annotation-transform; додає анотації, які розгортання перетворює на підключення Feature |
Сокет governance, роль label-transform | Побудова топології (Topology Builder) | доступно — викликається, коли робочий простір підключає плагін label-transform; автоматично додає мітки вузлів через JSON Patch |
Сокет governance, роль ir-verdict | Статичний аналіз (Static Analyzer, над графом IR) | доступно — викликається, коли робочий простір підключає плагін ir-verdict; вердикт halt зупиняє збірку |
Сокет governance, роль 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, який читає кожна інша роль, і обидва відсутні, коли підключення їх не оголошує. Оскільки вивід цієї ролі формує збирання, налаштування й вміст джерел підключення фіксуються в lock-файлі релізу під час 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, crate 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 виконуються в конвеєрі плагінів над набором відрендерених документів; сокет рендерингу провайдера виконується на етапі базового рендерингу; publishing-linter виконується поза основним процесом.
Патчі 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 — це мапа, що зберігає порядок, тож простори передаються в тому порядку, в якому їх задає ваш гість.
Те, що хост із ними робить, зводиться до одного питання: чи в межах одного простору кожне оголошене ім’я різне серед учасників, чий вивід зливається в одну збірку? Два учасники, що оголошують одне ім’я в одному просторі, зупиняють збірку, і зупинка називає простір, ім’я та обох учасників, тож автор може діяти, не читаючи провайдера. Різні імена, а також імена, що випадково збігаються у двох різних просторах, проходять.
Вирішуючи, що оголошувати, варто знати три властивості:
- Область — один зібраний вивід, тобто набір учасників, чиї файли зливаються разом. Гість, якому потрібна унікальність у вужчій чи ширшій області, виражає цю область у назві простору, яку оголошує, тож вибір залишається за вами, а не за хостом.
- Один учасник може вільно повторювати ім’я. Вузол може рендеритися через кілька перетинів — рендер джерела, синтез workload, розміщення артефактів, — і оголошення зливаються. Одне й те саме ім’я, оголошене одним учасником двічі, означає, що цей учасник двічі описує один ресурс, а не конфлікт.
- Оголошення не змінює жодного байта. Поле є твердженням про те, що вивів гість, і ніколи не змінює того, що він згенерував, тож відрендерений вивід гостя однаковий незалежно від того, оголошує він чи ні. Пропуск
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, яка оголошує, що читає факти рендеру компонентів, з якими пов’язаний її хост, як описує контекст шаблонів, — декодуючи кожен список у значення, яке шаблон може перебирати. Він ніколи не дізнається, що означає ім’я чи запис, і ніколи не виводить факт сам, тож новий провайдер може повідомляти нові факти без жодних змін на боці компілятора. Факти, які Feature, приєднана до вузла, повідомляє зі свого рендеру, зберігаються окремо від тих, що повідомив власний рендер вузла.
Вирішуючи, що повідомляти, варто знати чотири властивості:
- Порядок належить вам. Факти зберігають порядок, у якому їх перелічує ваш гість, а кожне значення зберігає власні байти — порядок записів списку та ключів кожного об’єкта такий, як записав ваш гість. Перелічуйте факти у фіксованому порядку й записуйте кожен запис із фіксованим порядком ключів, щоб ідентичний вхід давав ідентичні байти; список фактів замість мапи існує саме для того, щоб порядок зберігався у власному типі послідовності кожного kit без жодних позначок, тоді як мапа зберігає записаний гостем порядок лише тоді, коли її схема позначає її як таку, що зберігає порядок, і гість заповнює контейнер свого kit, що зберігає порядок.
- Повідомлення не змінює жодного байта. Файли, які записує компілятор, — це файли, які повернув ваш гість, незалежно від того, чи супроводжують їх факти.
- Вузол може повідомляти через кілька перетинів. Вузол може рендеритися як рендер джерела, синтез workload і розміщення артефактів; факти, які повідомляє кожен із них, зберігаються в порядку виконання перетинів, а ім’я, повідомлене більш ніж одним із них, читається як один список, що об’єднує їх у цьому порядку.
- Не повідомити нічого — повна відповідь. Пропуск
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() повідомляє інше значення. Записи супроводжують лише перелік джерела: рендер синтезованого workload або набору артефактів ніколи їх не містить.
Рендер без записів ці поля не змінюють. Обидва поля необов’язкові й відсутні, коли порожні, тож рендер без записів проходить через сокет байт у байт так, ніби цих полів не існувало, а гість, який їх ніколи не читає, від них не залежить. Тип OmitEntry опубліковано у трьох пакетах ABI і реекспортовано в наборі розробки плагінів для кожної мови.
Що компілятор робить із вашою відповіддю. Записи походять із ключа omits:, який автор пише в сутності Recipe або FeatureRecipe (Recipe → Поле omits:); компілятор обчислює шаблони кожного запису й передає вашому гостю ті, що застосовні. Потім він читає ваші кількості, і лише їх, — він ніколи не заглядає в повернутий файл, щоб їх перевірити:
- Список кількостей, що не містить рівно однієї невід’ємної кількості на кожен переданий запис, зупиняє збірку — якщо він відсутній, закороткий, задовгий або містить кількість, меншу за нуль, — із зазначенням вузла, вашого провайдера, кількості переданих записів і кількості повернутих значень. Звіт, що не збігається, не дає змоги визначити, який запис що вилучив. Див. A provider’s omitted counts do not match the omits entries it was handed (Кількості вилучень провайдера не відповідають переданим йому записам).
- Нуль зупиняє збірку із зазначенням першого в авторському порядку запису з нульовою кількістю: вузла, вашого провайдера, позиції запису в списку, який оголошує його документ, а також типу, імені та простору імен, у які він обчислився. Нуль повідомляє ваш гість; зупинка — справа компілятора. Див. An omits entry left out nothing the source rendered (Запис вилучення не вилучив нічого з відрендереного джерелом).
- Документ, що оголошує
omits:, провайдер якого не заявляєomits: true, відхиляється ще до будь-якого рендеру, тож автор одразу дізнається, що ключ не мав би ефекту, а не виявляє документ у виводі. Компілятор читає ваше твердження з вашогоdescribe(), щойно всі Recipe і FeatureRecipe у збірці прив’язано, і відхиляє до рендеру першого компонента, — тож гостю, який не заявляє ключ, ніколи не передається жоден запис. Відмова називає провайдера й компонент, для якого рендериться документ, або, для FeatureRecipe, що генерується один раз для межі, — межу та приєднання. Див. The provider does not support 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 (Провайдер не підтримує артефакти межі). Файл, який одне з цих об’єднань розміщує під іменем, що його також записує ваше складання, зупиняє збірку як two contributors writing one output path (два учасники записують один шлях виводу), тож імена, які записує ваше складання, входять до того, що ви документуєте для авторів.
Поточний стан: доступно. Гість terraform, що постачається з компілятором, заявляє це твердження, і Terraform читає кожен файл поруч із кореневою конфігурацією межі; гості helm, compose, helm-chart і cloudformation його не заявляють.
Оголошення того, що екосистема джерела ніколи не постачає
Локальний каталог джерела Recipe — розміщений поруч chart, модуль — публікується разом із 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 корпоративного каталогу мають ту саму вагу, що й Components стандартної бібліотеки, а набір не містить жодного власного кандидата. Для кожної сутності Component він читає назву, категорію з її мітки component.aggrega.ai/category, її мітки та назви ключів, які оголошують її значення; її ключі provides і сокети не зважуються. Component, додана до каталогу, стає кандидатом під час наступного імпорту без перезбирання імпортера. Якщо подання відсутнє, бо каталог не містить жодної сутності Component, жоден вузол не має кандидата: жоден не отримує посилання чи підказки, а кожен вузол, якому чернетка дає власну Component, створюється в чернетці. Так оцінює кожен імпортер, що оцінює через набір, — зокрема імпортери Langflow, Flowise, n8n і Compose компілятора, тоді як його імпортер MCP не зважує жодного кандидата; імпортер, який не використовує набір, читає подання так, як сам вирішить.
Для чого імпортер, побудований на Go kit, читає сокети платформи. Сокети нічого не важать в оцінці, але kit читає їх, щоб скомпонувати чернетку. Формат, потоки якого платформа виконує так, як їх написано, — як це роблять потоки Langflow, Flowise і n8n, — за замовчуванням оформлюється в чернетці як один екземпляр сутності Component цієї платформи, що несе потік, і кожна частина потоку під’єднується до першого сокета в порядку, у якому запис catalog платформи перелічує свої sockets, чий selector задовольняють мітки сутності Component цієї частини, як їх несе подання. Читаються лише селектор і мітки, а селектор зіставляється функцією, яку надає імпортер, оскільки kit не має власної граматики селекторів; якщо подання не містить сутності Component з назвою платформи, жодна частина не під’єднується. Основні імпортери описує чернетку, яку так створюють імпортери Langflow, Flowise і n8n компілятора, а також параметр layout, який натомість оформлює кожен вузол як окрему сутність Component.
Поточний стан: доступно — викликається через aggrega import, а також тією самою операцією в сеансі редактора та в інструменті для асистента.
Критерій розміщення: сокет лінтера чи ролі вердикту governance
Два з задокументованих сокетів мають подібну поверхню — обидва видають результати для кожного правила, — але відрізняються розміщенням у конвеєрі та семантикою блокування. Критерій, за яким вирішують, який сокет виконує певну перевірку:
- Ролі вердикту governance (у межах збірки, зупиняють збірку). Призначені для політик, що зупиняють збірку: вердикт
haltзупиняє конвеєр компіляції, і збірка не створює артефактів. Сценарії використання — політики, порушення яких робить результат небезпечним для застосування: контрольні точки відповідності (розміщення меж PCI / SOC2), інваріанти топології (вхідний трафік zero-trust, автентифікація між межами), форма потоку облікових даних (жодних секретів у відкритому вигляді в IR) тощо. Політика аналізує граф IR (ir-verdict, до рендерингу) або відрендерені артефакти (render-verdict, після рендерингу). - Сокет лінтера (поза збіркою, CI / IDE, рекомендаційний). Призначений для перевірок найкращих практик і виявлення проблем: правил, порушення яких підозріле, але не небезпечне, — осиротілі секрети, невикористані параметри, застарілий словник міток, повнота тегів для розподілу витрат, відхилення від домовленостей щодо іменування. Невдача дає рекомендаційний вивід; збірка все одно створює артефакти.
Критерій розміщення, сформульований як одне правило: якщо перевірка має зупиняти збірку, її місце — у ролі вердикту governance; якщо перевірка має попереджати автора чи рецензента, не блокуючи конвеєр, її місце — у сокеті лінтера.
Обидва доступні вже сьогодні. Сокет лінтера запускає лінтер публікації через aggrega lint; ролі вердикту governance викликаються в межах збірки під час aggrega build, коли робочий простір підключає плагін ролі вердикту. Зауважте, що роль вердикту має власні рівні серйозності — політика може й сама видавати вердикти warn та info, які лише радять, не зупиняючи збірку, — тож наведена вище межа між зупинкою та порадою є настановою щодо розміщення цілих перевірок, а не твердженням, що політика може лише зупиняти. Модель рівнів серйозності описано на сторінці сокета governance.
Перехресні посилання
policy-socket.md— вичерпний опис сокета governance: чотири ролі, рівні серйозності вердиктів, канал введення оператора, написання політики для будь-якого з двох рушіїв, що постачаються в складі компілятора, обгортання стороннього рушія політик і еталонні гостьові модулі.core-importers.md— власні імпортери компілятора, по одному для кожного формату, який він читає: що читає кожен із них, їхні налаштування та їхня публікація з кожним випуском компілятора.10-status.md#compilation-pipeline-phases— класифікація конвеєра плагінів на сторінці статусу (готовність середовища виконання конвеєра плагінів Wasm).architecture/04-entity-taxonomy.md§«Domain 3: Infrastructure Base» — принцип двочастинного 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— дисципліна трансляції помилок, у якій беруть участь гостьові модулі плагінів.