Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Конвеєр компіляції (загальний огляд)

У цьому розділі детально описано внутрішню фізику компілятора Go: як абстрактний YAML перетворюється на фізичні конфігурації в конвеєрі компіляції, графі проміжного представлення (Intermediate Representation, IR) та сокетах виконання WebAssembly (Wasm).

Конвеєр компіляції та потік виконання

Aggrega виконує суворий конвеєр компілятора Ahead-of-Time (AOT) із фіксованим порядком замість жорстко закодованої логіки оркестрування. Запущений командою aggrega build, компілятор передає плаский граф між ізольованими сокетами WebAssembly (Wasm), щоб оцінити архітектуру перед рендерингом фізичних артефактів.

Сокети Wasm працюють на вбудованому хості — інструментарії Extism поверх рушія Wazero — за брандмауером AOT-чистоти, який забороняє плагіну будь-яку можливість доступу під час виконання (мережа, файлова система, системний годинник, середовище, стандартний ввід-вивід), тож плагін не може порушити детерміновану гарантію ahead-of-time. Хост запускає publishing-linter позасмугово, через aggrega lint. Описані нижче внутрішньосмугові шлюзи — роль label-transform сокета управління під час побудови топології та його роль IR-verdict під час статичного аналізу, а також конвеєр плагінів, що завершує рендеринг, — виконуються в кожній збірці: роль управління — скрізь, де робочий простір приєднує до неї плагін, а конвеєр плагінів — для кожної сутності Recipe, яка оголошує кроки. Статус мови відстежує статус кожної фази конвеєра.

Конвеєр виконується повністю в пам’яті у суворому фіксованому порядку:

Розв’язання — резолвер і валідатор синтаксису

  • Механізм: Злиття успадкування, інтерполяція шаблонів Go та валідація JSON Schema 2020-12.
  • Дія: CLI отримує всі запитані сутності (Components, Features, Releases). Спершу він перевіряє ці визначення на наявність ключового слова extends. Для сутностей каталогу він глибоко зливає метадані YAML, і на стовпах даних два види розходяться: schema: сутності Feature компонується зі схемою її бази за правилами композиції JSON Schema 2020-12, тоді як Component, що розширює базу, компонує лише структуру — свої слоти приєднання, сокети топології, allowlist самоін’єкції та іменовані твердження — і отримує блок schema: своєї бази точно в тому вигляді, в якому його написав автор бази. Release, що розширює інший, згортається за тим самим правилом: значення нащадка перемагає ключ за ключем, аж до першого неподільного значення — скаляра, списку, шаблону, — яке замінюється цілком, а ключ, який нащадок записує як null, видаляється. Отже, переноситься вся його авторська поверхня — дерево меж із покомпонентними infra та приєднаннями Feature, блок parameters, анотації та вказівник на Manifest, — тоді як жодне поле metadata не переноситься, оскільки ідентичність і походження визначаються для кожного Release окремо. Далі він виконує інтерполяцію в пам’яті у три підкроки: валідацію контракту параметрів щодо типізованих декларацій parameters: сутності Aggregate; інтерполяцію розв’язаних значень у навколишні рядки values:; вилучення мапи .parameters з кожного контексту шаблону значень, після чого вона лишається доступною для читання лише шаблонам шляхів, написаним оператором. Нарешті, він вставляє розв’язані блоки infra у корисні навантаження цільових компонентів. Щойно креслення стає повністю конкретним, компілятор використовує уніфіковану декларацію schema: з каталогу (компактна форма або повна JSON Schema 2020-12), щоб суворо локально провалідувати конфігурації values та infra розробника.
    • Валідація схем Feature у Release: Features, приєднані через Release (як на рівні всієї межі, так і для конкретних компонентів), на цьому кроці розв’язуються щодо відповідних сутностей каталогу. Компілятор валідує надані Release блоки infra щодо декларації schema: кожної Feature одразу після розв’язання каталогу, забезпечуючи типобезпеку ще до побудови топології.
    • Підфаза розгортання Feature на основі анотацій: Після розв’язання Manifest, прив’язування Recipe/Provider і валідації цілей прив’язування Manifest (шляхи, оголошені в mappings.features.annotations.<key>.maps, існують у spec.schema зазначеної Feature) компілятор запускає підфазу розгортання анотацій перед побудовником топології. Підфаза обходить межі Release ззовні всередину та підсистеми Aggregate ззовні всередину, обчислюючи ефективний набір анотацій для кожного компонента через злиття каскаду + перевизначення + відмови через null; розбирає кожне значення анотації як YAML у скаляр, структуроване значення або null; спрямовує кожне значення (скалярне або структуроване за підключами) через декларацію maps прив’язки Manifest до стовпа схеми цільової Feature із перевіркою відповідності сторони й стовпа (сторона Aggregate спрацьовує в maps.values; сторона Release — у maps.infra); валідує типи кожного листка щодо spec.schema цієї Feature; і вставляє синтетичні приєднання Feature, які граф IR позначає як origin: annotation. Схеми компілюються один раз на збірку й повторно використовуються під час обходів каскаду. Розгортання виконується після валідації цілей прив’язування та до побудови топології, тож подальші етапи обробляють синтетичні приєднання структурно так само, як і явні (за винятком інспектування походження). Див. 13-catalog-and-registry.md §«Розгортання Feature на основі анотацій» та language-reference/providers/well-known-annotations.md щодо форми прив’язки, семантики каскаду та правил композиції між сторонами.

Побудова топології — побудовник топології та шлюз мутацій

  • Механізм: Розгортання AST + роль label-transform сокета управління.
  • Дія: Компілятор нативно читає явно оголошені блоки uses з провалідованих компонентів, щоб детерміновано накреслити топологічні ребра між вузлами графа, залишаючи блок values повністю непрозорим. Потім він обчислює шлюз мутацій, передаючи проєкцію графа — мітки кожного вузла та values, оголошені його екземпляром, які компілятор передає, не читаючи, — разом з іменем і середовищем сутності Release плагіну управління, приєднаному в ролі label-transform. Плагін оцінює контекст і повертає JSONPatches, щоб динамічно автоматично позначити граф (наприклад, вставляючи мітку compliance.aggrega.ai/data-class: restricted на основі середовища сутності Release або datastore.aggrega.ai/engine: vector на основі оголошених розширень бази даних); патчі стосуються лише міток.

Фіналізація графа

  • Механізм: Нормалізація.
  • Дія: Компілятор фіналізує плаский граф проміжного представлення (IR), зберігаючи явні топологічні ребра, які накреслив побудовник топології. Потім він нормалізує приєднані Features та їхні корисні навантаження values у плаский словник, упорядкований за ID вузла, готуючи агностичний щодо можливостей граф до валідації.
    • Нормалізація корисного навантаження IR: Структурна форма IR забезпечує єдине джерело істини для конфігурації: рівень топології несе лише структуру графа (ідентичність вузлів, ребра, мітки метаданих), а нормалізований стан конфігурації зберігається в окремому словнику в пам’яті, який компілятор передає подальшим плагінам. Мутатори, що змінюють конфігурацію, змінюють її в одному місці; провайдер читає нормалізований стан без ризику розбіжностей через надлишкове зберігання.

Статичний аналіз — статичний аналізатор і шлюз валідації

  • Механізм: Перевірки топологічної чистоти + роль ir-verdict сокета управління.
  • Дія: Компілятор виконує абстрактний статичний аналіз графа IR. По-перше, він витягує рядки selector з визначень usesSchema та обчислює їх за допомогою нативного рушія зіставлення міток Go (з підтримкою семантики AND, OR через in() і NOT через != у стилі Kubernetes) по явно визначених ребрах графа, щоб гарантувати типобезпеку між вузлами для оголошених сокетів. Ребро на ad-hoc сокеті — такому, який назвав автор Aggregate і не оголосив каталог, — не має запису в каталозі, а отже й селектора, тож цій перевірці немає чого обчислювати і нічого не бракує; кожне ребро фіксує, до якого з двох видів воно належить, а те, що може нести ad-hoc ребро, натомість обмежується оголошеними provides цілі. Він також обчислює селектори appliesTo та appliesToAnyOf сутностей Feature, щоб перевірити, що приєднані функції сумісні з мітками цільового компонента, а також власний selector кожного заповненого слота приєднання щодо міток Feature, яка його заповнює. По-друге, він обчислює кожен мандат присутності, який оголошує Component вузла, — кожну анотацію features.aggrega.ai/requiredType.<label> — щодо фінального набору приєднань цього вузла. Ця перевірка належить аналізатору, бо це перший етап, який має обидві половини правила: анотації розв’язаної сутності Component і набір приєднань, створений 5-рівневим каскадом, з однаковим урахуванням приєднань до Aggregate, до підсистем, до Release і розгорнутих з анотацій. Мандат, який не задовольняє жодне приєднання, зупиняє збірку; мандат із неправильно сформованою декларацією зупиняє збірку з окремою діагностикою, тож зламана декларація ніколи не сприймається як задоволена вимога. По-третє, він виконує шлюз валідації, передаючи повну структуру графа (включно з усіма вузлами, ребрами, приєднаними функціями та попередньо обчисленими шляхами DFS) плагіну управління, приєднаному в ролі ir-verdict. Власна Wasm-політика підприємства оцінює топологію. Якщо Wasm-плагін повертає масив помилок (наприклад, виявивши безперервний шлях від вузла public до вузла restricted без певної функції проксі), збірка зупиняється.

Рендеринг

  • Механізм: Перехоплення перед рендерингом (injectMapping), пізнє зв’язування (valuesMapping) і сокети рендерингу Wasm (pipeline).
  • Дія: Фінальну фазу генерування артефактів розділено на суворі часові підфази, що виконуються у фіксованому порядку, і це зберігає детермінованість виконання:
    • Відображення ін’єкцій (перехоплення перед рендерингом): Компілятор Go розв’язує абстрактний контракт .context.inject розробника. Потім він виконує шаблони Go injectMapping з усіх приєднаних FeatureRecipes у суворому порядку виконання 5-рівневої моделі цибулини (вкладений Aggregate — спершу власні приєднання компонента модуля, потім ті, що оголошують підсистеми його модуля, ззовні всередину → компонент кореневого Aggregate → підсистема кореневого Aggregate → межа Release ззовні всередину → приєднання Release для конкретного компонента). Компілятор нативно глибоко зливає отримані словники поверх каналу пам’яті .context.inject викликача. Це безпечно переписує змінні середовища й рядки підключення для викликача ще до того, як базова Recipe їх побачить. Відображення може переписати те, що доставив власний блок inject: викликача або одне з його з’єднань; ключ, який уже доставила інша приєднана Feature — через власне відображення чи власний блок inject:, — зупиняє збірку з називанням обох приєднань, тож порядок виконання ніколи не вирішує між значеннями двох приєднань.
    • Преамбула locals: Перш ніж запуститься будь-який шаблон provides, компілятор обчислює записи .locals сутності Recipe в порядку їх написання, кожен — у самодостатньому локальному для вузла контексті: .context.instance_id, .values, .infra та вже розв’язані записи того самого блоку, але не .context.inject чи .context.uses. Отже, запис може читати сусідній запис, визначений вище, і отримує розв’язане значення цього запису; порядок автора є частиною контракту скрізь, де один запис читає інший, і блок ніколи не переупорядковується, щоб посилання розв’язалося. Саме попереднє розв’язання locals дає змогу шаблону provides читати .locals. Шаблон .source сутності Recipe обчислюється в тому самому контексті, щойно ці locals розв’язано, що зберігає .locals придатними для повторного використання як скорочення в шаблонах сутності Recipe і дає змогу авторам параметризувати .source (версію chart, шлях, реєстр) для кожної межі.
    • Базовий рендеринг (valuesMapping базової Recipe): Компілятор обчислює шаблон valuesMapping базової Recipe. Шаблон читає перехоплені рядки з каналу .context.inject (переписані під час відображення ін’єкцій), а отриманий словник значень передається провайдеру, якого називає capability сутності Recipe, — провайдери helm і helm-chart обидва рендерять через Helm, — щоб відрендерити базові інфраструктурні артефакти.
    • Розбір і валідація Workload: Для Recipe, що оголошує workload: — вбудований вміст блоку або workload: { $import: <path> }, що називає файл, — цей документ обчислюється як шаблон у контексті рендерингу вузла, потім розбирається як YAML у форму Workload і перевіряється: відрендерені байти валідуються щодо схеми Workload, декодоване значення також валідується щодо неї (байти несуть ключі, які декодування відкидає, а декодування опускає поле, задане порожнім, тож кожна перевірка відхиляє те, чого не бачить інша), кожен запис attachments перевіряється щодо слотів, які оголошує featuresSchema прив’язаного Component, а кожне посилання на ресурс перевіряється щодо розв’язаних provides слота, який воно називає. Збій на цьому етапі зупиняє збірку. Розібраний Workload розміщується в контексті шаблону як .workload, тож шаблон, обчислений пізніше на тому самому вузлі, може його прочитати.
    • Обчислення артефактів: Кожен запис, який Recipe оголошує в artifacts: — вбудований вміст або файл, названий власним $import: цього запису, — зчитується, розбирається як шаблон, обчислюється в повному контексті шаблону й несе походження збірки. Отримана проєкція передається провайдеру, який визначає вихідний формат, місце розміщення походження, вихідний шлях і фінальні байти. Кожен згенерований файл фіксує, з якої авторської форми він походить, тож колізія імен файлів може назвати кожного учасника.
    • Синтез Workload: Розібраний Workload передається провайдеру, якого називає capability сутності Recipe, і той перетворює його на нативні ресурси цього провайдера. Recipe, яка не оголошує workload:, не має тут чого синтезувати; її файли натомість надходять із рендерингу джерела.
    • Рендеринг Feature (генерування ресурсів FeatureRecipe): Кожне приєднання на вузлі, прив’язана FeatureRecipe якого несе власні source, workload, artifacts та/або valuesMapping, — патерн генерування ресурсів, що використовується для допоміжних маніфестів, як-от ServiceMonitor, NetworkPolicy, ConfigMap для sidecar або ресурсу доставлення облікових даних, — обчислюється за один прохід, у тому самому порядку 5-рівневої моделі цибулини, якого дотримується відображення ін’єкцій. Є одна послідовність над одним набором приєднань: операційна Feature і Feature облікових даних проходять тим самим шляхом, а відрізняє їх те, що генерує їхня FeatureRecipe. Для кожного приєднання .values і .infra переключаються на його власну область дії; воно успадковує обчислені .locals базової Recipe; .attachment_name називає екземпляр, що рендериться, а .provides несе власні розв’язані provides приєднання — той самий набір, який читає споживач. Отриманий словник значень передається провайдеру, якого називає власна capability сутності FeatureRecipe, а відрендерені файли додаються до виводу межі з двома координатами — компонентом, до якого приєднано Feature, і назвою, під якою її приєднано, — тож одна назва Feature, приєднана до кількох компонентів, зберігає кожне приєднання окремо. Форма цих координат випливає з власного макета провайдера-хоста: каталог <component>--<instance>/ поряд із власним каталогом компонента, де ціль дає кожному учаснику власну позицію, і префікс імені файлу <component>--<instance>--, де вона читає лише файли, що лежать безпосередньо в каталозі. FeatureRecipes лише для ін’єкцій — ті, що несуть тільки injectMapping, уже оброблений під час відображення ін’єкцій, — тут пропускаються. Як і підфази перед ним, рендеринг функцій виконується для одного компонента за раз, тож приєднання зазвичай обчислюється одразу після компонента, до якого його приєднано. Приєднання, FeatureRecipe якого оголошує readsCallerRenderFacts: true або readsTargetRenderFacts: true, натомість обчислюється, коли відрендерено кожен компонент і кожне приєднання, що не оголошує жодного з них, — тож до того часу відрендерено кожен компонент, що під’єднується до його хоста, і кожен, до якого під’єднано його хост, — і його вивід потрапляє туди, куди потрапив би в іншому разі.
    • Конвеєр плагінів (виконання кроків Wasm): Компілятор читає масив pipeline сутності Recipe і виконує його кроки в оголошеному порядку. Він запускає названий Wasm-плагін кожного кроку над відрендереними документами вузла, застосовує операції JSON Patch RFC 6902, які повертає крок, до документів, на які спрямовані ці операції, і генерує побічні ефекти кроку поряд із ними — це поверхня для хірургічних мутацій, як-от вставлення sidecar Envoy чи монтування VolumeMount із секретом. Крок, шлюз when: якого рендериться в хибне значення, пропускається як прохідний, залишаючи набір документів без змін для наступного кроку. URI plugin кожного кроку перед виконанням розв’язується у перевірені байти артефакту, які lockfile фіксує за дайджестом. Кроки pipeline сутності FeatureRecipe виконуються так само — над власними відрендереними документами приєднання, а для приєднання в області компонента — також над документами компонента-хоста.

Усі три види вхідних даних Recipe доходять до компілятора: source: + valuesMapping: — через базовий рендеринг, workload: — через розбір і синтез робочого навантаження, а artifacts: — через обчислення артефактів. Які з них можна передати певному провайдеру, вирішується не на кожному підетапі окремо — це визначається один раз для вузла, перед будь-яким диспетчеризуванням рендерингу, на основі власного оголошеного контракту провайдера, тож Recipe, вид вхідних даних якої прив’язаний провайдер не приймає, відхиляється саме там, а не посеред рендерингу. Див. 16-recipe-input-composition.md щодо моделі композиції трьох видів вхідних даних, виду Workload і механізму Artifacts, та Статус мови щодо того, який провайдер приймає який вид.

Вивід, нативний для GitOps

Щоб залишатися суворо без власної позиції щодо того, як застосовується його вивід, плагіни рендерингу виводять згенеровані артефакти в чисту структуру каталогів, ізольовану за межами (наприклад, dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/). Це дає змогу зовнішнім контролерам GitOps (як-от ArgoCD чи Flux) синхронізувати й застосовувати інфраструктуру, а компілятору Aggrega ніколи не потрібні облікові дані API живого кластера.

graph TD
    subgraph CLI_Orchestrator ["The Aggrega Compiler Pipeline"]
        direction TB
        A["Resolution — The Resolver & Syntax Validator<br/>(Inheritance Merge + Parameter Interpolation + JSON Schema 2020-12 Validation)"] --> B["Topology construction — The Topology Builder<br/>(AST Expansion + governance label-transform)"]
        
        B -->|"Emits IR Graph"| C["Graph finalization<br/>(Normalization)"]
        
        C -->|"Flat IR Graph"| D["Static analysis — The Static Analyzer<br/>(Selectors + governance ir-verdict Gate)"]
        
        D -->|"Validated Topology"| E["Rendering<br/>Inject mapping: Pre-Render Interception (injectMapping)<br/>Base rendering (valuesMapping)<br/>The plugin pipeline: Wasm Mutation (pipeline)"]
    end
graph LR
    E["Rendering"]
    E -->|"Stringified Artifacts"| F["Helm Charts"]
    E -->|"Stringified Artifacts"| G["Docker Compose"]
    E -->|"Stringified Artifacts"| H["Kubernetes Manifests"]
    E -->|"Stringified Artifacts"| I["Terraform Configuration"]
    E -->|"Stringified Artifacts"| J["CloudFormation Templates"]

Мапа джерел інфраструктури

Aggrega компілює Aggregate.yaml приблизно на 30 рядків у тисячі рядків фізичної конфігурації JSON або YAML. Без способу простежити запущений ресурс до його джерела налагодження збою на «main.tf.json, рядок 4032» змушує розробників відновлювати відповідність вручну. Плагіни рендерингу Aggrega розв’язують це, зливаючи ідентифікатори трасування з нативною поверхнею метаданих провайдера — metadata.labels і metadata.annotations для Kubernetes, коментар про походження для Terraform та еквівалентні домовленості для кожного провайдера, — тож кожен відрендерений об’єкт несе вказівник на джерело, з якого він походить. Мітка aggrega.ai/compiler-version (описана в governance-and-compliance §5) — один із ключів трасування в цьому сімействі; поряд із нею штамп несе aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri і aggrega.ai/environment, і його генерує кожен із провайдерів helm, helm-chart, compose, terraform і cloudformation — провайдер helm-chart у файлах шаблонів, які сутність Recipe додає до чарту, оскільки власні шаблони чарту він копіює без змін.

Штамп не несе жодного ключа, що вказує на походження функції чи тип каталогу.

Разом із компілятором постачаються ще два засоби налагодження. aggrega build --trace записує проміжний стан кожного вузла, прохід за проходом, у .trace/ поряд із dist/ — для автора сутності Recipe, який досліджує, що отримав і що створив кожен етап; а діагностика, що зупиняє збірку, несе категорію поверхні авторингу, до якої належить, — DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR та інші, — скрізь, де збій її має, тож вказує на потрібного автора. Помилки, що простежують збійне поле згенерованого маніфесту до рядка шаблону, який його створив, не входять до компілятора.

Конвеєр валідаторів

Фаза валідації схем під час розв’язання спирається на конвеєр валідаторів, який перетворює вміст специфікацій сутностей (компактна форма, JSON Schema у YAML або змішаний варіант) на єдиний документ JSON Schema 2020-12 із походженням для кожного листка, а потім валідує щодо нього вміст екземплярів, написаний розробниками. П’ять етапів виконуються по черзі як чисті перетворення; кожен є детермінованою функцією своїх оголошених вхідних даних.

Етап 1 — Компіляція компактної форми. Компілятор обходить YAML-дерево вмісту schema:, parameters: і SchemaLibrary; виконує диспетчеризацію для кожного вузла (листок компактної форми, JSON Schema у YAML, посилання $ref: чи композиція); видає розв’язану JSON Schema 2020-12. Компактна форма та JSON Schema у YAML можуть змішуватися на будь-якій межі вузла через екранування $jsonschema:; змішаний випадок компілятор обробляє, обходячи дерево й виконуючи диспетчеризацію для кожного вузла. Перетворення є чистою функцією: той самий вхід у компактній формі завжди дає той самий вихід JSON Schema. Словник ключових слів див. у language-reference/vocabulary/compact-form-authoring.md.

Етап 2 — Розв’язання spec.templates і $instantiate:. Для записів SchemaLibrary, написаних як посилання на шаблони, компілятор обходить кожен запис бібліотеки, що викликає $instantiate: з $args:, підставляє значення параметрів як заміну літеральних скалярів і створює конкретні записи схеми. Підстановка виконується один раз на кожне завантаження бібліотеки; розв’язані записи кешуються. Форму, у якій пишеться сутність бібліотеки, див. у language-reference/entities/schemalibrary.md.

Етап 3 — Розгортання $ref: між документами. Для посилань на SchemaLibrary через $ref: (форма ідентичності <Library>#/schemas/<entry>) компілятор обходить ланцюжок посилань під час компіляції, передаючи стек розв’язання; вміст, на який посилаються, вбудовується в схему споживача. Розгортання зберігає виявлення циклів (цикли зупиняють збірку з помилкою, що називає ланцюжок), запобіжник «ідентичність, а не розташування» (посилання з хостом реєстру зупиняє збірку з підказкою використати форму ідентичності — посилання адресують бібліотеки за ідентичністю, а не за фізичним розташуванням) і композицію з одного джерела (блоки $ref: приймають лише голе посилання; перевизначення на боці споживача компонуються через allOf: з JSON Schema). Семантику розв’язання див. у language-reference/vocabulary/cross-document-ref.md.

Етап 4 — Синтез мосту для featuresSchema:. Компілятор обходить вміст featuresSchema: кожної сутності в порядку автора та видає фрагмент JSON Schema, що описує форму заповнення, яке може зв’язати кожен слот приєднання, з ключовим словом розширення x-aggrega-inject: на слоті, що оголошує список дозволених inject. Цей фрагмент компілюється й перевіряється окремо, щодо написаного блоку приєднань, а не вбудовується у вміст schema:, призначений для розробника; ключове слово розширення є метаданими, які валідація JSON Schema ігнорує, і жоден пізніший етап не зчитує його назад із фрагмента — перевірка, якій потрібен список дозволених слота, читає сам слот. Таблиця сокетів usesSchema: не проєктується в жоден фрагмент: selector: і inject: сокета читаються як типізований YAML, написаний архітектором, а valueSchema: / infraSchema: сокета для кожного ребра компілюється окремо. Синтез є чистою функцією своїх вхідних даних.

Етап 5 — Власний механізм злиття з походженням. Для сутностей, що оголошують extends:, компілятор обходить ланцюжок батьків; розв’язана JSON Schema батька стає основою; перевизначення нащадка застосовуються поверх неї. Кожен листок у розв’язаній схемі має тег походження (шлях до файлу, номер рядка, походження від батька чи нащадка). Вихід механізму злиття — це те, що споживає рушій валідатора; рушій валідатора — це незмінена стороння реалізація, сумісна з JSON Schema 2020-12, обгорнута детермінованим обхідником для впорядкованого видавання результатів.

П’ять етапів виконуються до того, як рушій валідатора побачить схему. Рушій отримує один розв’язаний документ JSON Schema 2020-12 та вміст екземпляра від розробника; він створює звіт валідації. Форматувальник помилок звертається до тегів походження, щоб видавати діагностику для користувача, яка чітко називає позиції в джерелі — зокрема вихідний файл для обмеження, яке сутність Feature успадкувала від своєї основи, а не написала сама.

Конвеєр валідатора виконується там, де кожне корисне навантаження вперше стає повним, — для values та infra компонента під час розв’язання, для компонентів вкладеного агрегату, коли побудова топології їх долучає, і для корисного навантаження приєднання під час фіналізації графа, — тож зауваження схеми зупиняє збірку до того, як статичний аналіз обчислить будь-який селектор, і до обчислення тверджень, що дає змогу шаблонам тверджень спиратися на провалідовані корисні навантаження.

Збереження детермінізму в усьому конвеєрі

Кожен етап конвеєра компіляції зберігає інваріант детермінованого виходу: за тих самих вихідних файлів, того самого lockfile і тієї самої версії компілятора збірка дає побайтово ідентичний вихід. Інваріант є фундаментальним — адресація за вмістом у lockfile потребує стабільних дайджестів артефактів; відтворювані збірки потребують, щоб реліз, написаний на ноутбуці розробника A, компілювався в той самий вихід на ноутбуці розробника B і в CI; можливість рецензувати диф потребує, щоб зміни в джерелі були єдиними змінами в скомпільованому виході.

Детермінізм зберігається завдяки невеликій кількості дисциплін, яких дотримується кожне перетворення:

  • Фіксований порядок ітерації. Кожен обхід YAML у формі мапи ітерує у фіксованому порядку, оскільки нативна ітерація мап у Go рандомізована. На більшості етапів компілятор сортує перед ітерацією (компілятор компактної форми, механізм злиття, розв’язувач spec.templates, форматувальник помилок, серіалізатор YAML); проєкція слотів приєднання натомість зберігає порядок автора, тож порядок властивостей таблиці слотів — це порядок, у якому її написано.
  • Без вбудовування часу. Компіляція не вбудовує часові позначки у вихід. Збірка о 14:00 дає той самий артефакт, що й збірка о 2:00. Метадані походження механізму злиття використовують файл:рядок, а не файл:часова позначка.
  • Шляхи відносно робочого простору. Усі шляхи в розв’язаному виході відносні щодо робочого простору; шар розв’язання шляхів нормалізує їх до того, як вони потраплять у будь-який вихід.
  • Жодних випадкових джерел, жодного зовнішнього стану. Перетворення є чистими функціями своїх оголошених вхідних даних (вміст сутності, ланцюжок батьків, lockfile). Зовнішній стан використовується лише під час розв’язання (отримання артефактів OCI), а розв’язаний вміст адресується за вмістом через дайджест.
  • Канонічна серіалізація YAML. Для одного входу вихід записується в одній фіксованій формі: однаковий порядок ключів на кожному рівні вкладеності за кожного запуску, причому масиви й масиви enum: зберігають порядок введення; відступ у 2 пробіли; закінчення рядків Unix LF; рядки без лапок там, де YAML це дозволяє; булева форма true/false; null пропускається для відсутніх полів.
  • Алфавітний порядок $defs:. Записи $defs: схеми видаються в алфавітному порядку ключів у розв’язаній JSON Schema. $defs: концептуально є словником, а не впорядкованим списком; алфавітний порядок робить дифи передбачуваними попри реорганізації джерела.
  • Паралелізм не проявляється у виході. Компілятор може розпаралелювати незалежні одиниці (різні сутності можуть компілюватися паралельно). Паралельні результати збираються в детерміновану структуру (наприклад, відсортовану за назвою сутності) перед серіалізацією.

Наскрізні тести компілятора компілюють кожну фікстуру кілька разів у межах одного тесту й перевіряють, що кожен запуск видає ті самі файли з побайтово ідентичним вмістом. Саме повторна компіляція виявляє витік порядку ітерації мап або ітерацію невідсортованою множиною, які в більшості запусків дають стабільний вихід і лише зрідка розходяться. Ці тести виконуються разом з рештою набору тестів компілятора.

Інваріант детермінованого виходу діє під час збірки: ті самі вихідні файли + той самий lockfile + та сама версія компілятора дають побайтово ідентичний вихід. Супутня властивість під час блокування (ті самі вихідні файли + той самий стан реєстру дають той самий lockfile) слабша — реєстри змінні (можна публікувати нові версії; можна додавати sidecar-файли; метадані окремих компонентів можуть змінюватися), тож два виклики блокування для тих самих вихідних файлів у різний час можуть дати різні lockfile. Саме в цьому призначення lockfile, як і в домовленостях npm, Cargo та Go. Зі свіжого lockfile збірка дає детермінований вихід. Розділення цих двох моментів і робить змінність на боці реєстру прийнятною: sidecar, опублікований у момент T2, змінює наступний виклик блокування; він не змінює збірки з lockfile, згенерованим у момент T1.