Архітектурні інваріанти
Ці вісім інваріантів — засадничі правила Aggrega. Вони діють в усіх випусках, у ядрі компілятора, на рівні схем, у каталозі та на поверхні плагінів Wasm. Кожне проєктне рішення, кожна функція та кожна створена сутність їх дотримуються.
Інші розділи архітектури посилаються на інваріанти за номером. Коли пізніший розділ каже «згідно з інваріантом 2» або «за правилом String Pipe (інваріант 3)», він посилається сюди.
1. Компілятор нейтральний щодо вмісту, без власної позиції та агностичний щодо намірів користувача
Компілятор Aggrega — це текстовий маршрутизатор Ahead-Of-Time (AOT). Він розбирає YAML, обходить графи, обчислює перетини міток і передає рядки від джерел до приймачів. Він не контролює, що автори вкладають у values, parameters, infra, provides чи locals. Він не нав’язує домовленостей щодо іменування, домовленостей щодо портів чи семантичних міток, які вигадує Architect.
Багато правил, що звучать як правила компілятора, — контракт Zero-Port, стиль каталогу Naked-Base / Flavored-Edges, вибір операційного примітиву, що пасує певному компоненту, — є суспільними договорами: найкращими практиками із запасними виходами, яких дотримуються архітектори платформи, що створюють каталог стандартної бібліотеки. Компілятор їх не інтерпретує.
Цей інваріант стосується того, що компілятор виводить із вмісту, який ви створюєте, і ця сфера — усе, що він охоплює. Невелика кількість ключів належить самій Aggrega — вони зарезервовані, а значення, які вони приймають, записано в опублікованій схемі, — і схема перевіряє їх так само, як будь-яке інше оголошене поле. component.aggrega.ai/type — один із них: його множина значень закрита, і документ зі значенням поза нею відхиляється під час завантаження. Це платформа визначає, що означає її власний ключ, а не компілятор вчитує зміст у рядок, який ви написали, і кожен ваш власний ключ залишається рівно настільки неконтрольованим, як каже цей інваріант. Каталог, що класифікує компоненти за віссю, якої Aggrega не визначає, створює власний ключ мітки, який схема приймає з будь-яким рядковим значенням і який кожна поверхня селекторів читає однаково.
Те, що компілятор справді забезпечує, обмежене: валідація схем, розбір YAML, побудова графа, обчислення шаблонів і проста текстова маршрутизація контракту ін’єкції. Усе інше — домовленість, яка забезпечується під час створення каталогу або в необов’язковому сокеті управління Wasm.
Підприємства, що створюють власні внутрішні каталоги, явно вільні порушувати домовленості стандартної бібліотеки. Компілятор приймає все, що вони напишуть, за умови що воно проходить валідацію схеми. Архітектура заохочує найкращі практики; вона не будує в’язниць.
2. Чистота AOT: компілятор не має доступу до інформації часу виконання
Aggrega — це компілятор Ahead-Of-Time. Під час компіляції:
- Він не автентифікується в хмарних API.
- Він не отримує живих IP-адрес, DNS-імен чи URL-адрес, згенерованих хмарою.
- Він не розкриває секрети у відкритий текст — секрети залишаються вказівниками на метадані в усьому проміжному поданні (Intermediate Representation).
- Він не знає стану цільових кластерів чи сервісів під час виконання.
- Він не може отримати дані, яких ще не існує (кінцеві точки після підготовки ресурсів, динамічно призначені порти, автоматично згенеровані імена ресурсів).
Усе, що залежить від стану під час виконання, виражається як детермінований рядок-вказівник — стабільне DNS-ім’я, рядок інтерполяції Terraform, посилання на ресурс CloudFormation, — який надає сутність Ops Recipe. Компілятор передає вказівник далі, не розкриваючи його. Кінцеві фізичні дані розкриває середовище виконання (кластер, менеджер стану IaC).
Це справжня інверсія керування (True Control Inversion): розробники визначають Injection Contract у сутності Aggregate, компілятор заздалегідь з’єднує детерміновані вказівники, а середовище виконання розкриває кінцеві фізичні дані. Вимоги, яким справді потрібне розкриття під час виконання, належать до конвеєра Wasm сутності Ops Recipe, а не до ядра компілятора.
3. String Pipe: компілятор не може виводити зміст
Компілятор не інтерпретує значення переданих значень. Коли сутність Component A використовує сутність Component B, компілятор бере скаляр, який Recipe сутності Component B створює через provides, — рядок, число чи булеве значення — і передає його в контекст Recipe сутності Component A, детерміновано перетворений на рядок на межі ін’єкції. Чи є це значення FQDN, локальним ім’ям хоста, літералом IP, номером порту чи DSN, відформатованим Wasm, не має значення: компілятор не перевіряє маршрутизованість, коректність протоколу чи семантичну доречність.
З цього випливають два наслідки:
- Компілятор не вгадує призначення компонента з його імені. Компонент з іменем
database-productionне розпізнається як база даних. Семантичні мітки типу, як-отcomponent.aggrega.ai/type(якщо вони є), — це непрозорі метадані, що використовуються для зіставлення міток, а не логіка розгалуження компілятора. - Компілятор не відрізняє ім’я хоста від імені бази даних, номера порту чи довільного непрозорого значення. Усі вони — скалярні записи в контексті впровадження, що доставляються як рядки.
Тріада топології — provides у сутності Recipe, що виробляє, uses у сутності Aggregate, що споживає, inject на ребрі — це Injection Contract. Компілятор обчислює мітки й передає рядки; тлумачення — це авторський договір між сутностями Recipe і Component.
4. Жодної примарної інфраструктури: компілятор ніколи не вигадує обчислювальних ресурсів чи функцій
Компілятор ніколи мовчки не впроваджує обчислювальних ресурсів, сутностей Features, анотацій, маршрутизувальних проксі чи будь-яких інших ресурсів, яких автор явно не оголосив. Порушення політик породжують гучні запобіжники (Loud Guardrails) — збірка зупиняється з конкретною помилкою, яка повідомляє авторові, що виправити в написаному ним документі, — а не мовчазні зміни, що створюють інфраструктурні загадки під час налагодження.
Ресурси потрапляють до графа через явні оголошення під час створення:
- Сутність Aggregate розробника (компоненти, ребра
uses, приєднання сутностей Feature). - Приєднання сутностей Feature у сутності Release (додавання на рівні оператора).
- Розгортання на основі анотацій (сутність Manifest оголошує прив’язки анотація → Feature; анотація на сутності Component або межі є явним оголошенням).
- Створення ресурсів на рівні сутності Recipe: рендеринг
sourceсутності Recipe створює основний артефакт; синтезworkloadвидає специфічну для провайдера форму розгортання (специфікація Pod, сервіс Compose тощо); записиartifacts:(вбудовані або завантажені через$import:) видають допоміжні маніфести, властиві сутності Recipe; генерація ресурсів сутності FeatureRecipe видає допоміжні ресурси для кожної сутності Feature, що запускаються явним приєднанням сутності Feature.
Шляхи на рівні сутності Recipe — це оголошення часу створення, віддалені на один крок: автор сутності Recipe пише source / workload / artifacts / valuesMapping відповідно до контракту сутності Component, а сутність Aggregate розробника вибирає, які сутності Components беруть участь. Ресурс, що з’являється у відрендереному результаті, простежується або до оголошення в сутності Aggregate, у сутності Release чи в прив’язці анотації, або до вмісту сутності Recipe, який вибрали типи компонентів сутності Aggregate.
Синтез перетворює оголошені автором форми на специфічні для провайдера формати виводу. Специфікація сутності Workload, написана як мапа контейнерів, може бути відрендерена як специфікація Pod Kubernetes, блок сервісу Compose або модуль Terraform — перетворення кероване провайдером, але ресурси простежуються до оголошення сутності Workload автора.
Сокет керування несе роль для кожного приєднання, і саме роль — а не вид плагіна — визначає, що приєднання може робити зі збіркою. Плагін керування, приєднаний у ролі вердикту, — який перевіряє граф IR (ir-verdict) або відрендерені артефакти (render-verdict), — може відхилити збірку, але не може її змінити. Якщо такий вердикт хоче, щоб було додано ресурс, він провалює збірку з підказкою щодо виправлення, щоб автор сам додав ресурс; хост читає вивід вердикту лише як прийняття або відхилення і ніколи не застосовує його як зміну, тож незапрошене переписування графа до стану відповідності — саме та примарна інфраструктура, яку забороняє цей інваріант, — не може походити з ролі вердикту. Плагін керування, приєднаний у ролі перетворення (label-transform або annotation-transform), — вузький, явний виняток: оператор, який його приєднує, — за власним вибором, через конфігурацію plugins.governance робочого простору, — оголосив це перетворення, тож зміни, які воно вносить, є явним оголошенням із тим самим статусом, що й розгортання на основі анотацій, а не мовчазним впровадженням. Різниця — у запрошенні: незапитаний вердикт не може переписати збірку, а явно приєднане перетворення може, бо оператор його попросив. Оскільки перетворення формує відрендерений вивід, воно закріплюється у файлі блокування, як і кожен плагін, що формує вивід, — застосовуване перетворення фіксується під час pull, тож його зміна означає повторний pull, а не мовчазний зсув між збірками; вердикт не формує жодного виводу й не закріплюється.
5. Сутність Aggregate — це поверхня створення; сутність Release не може оголошувати values:
Схема сутності Release механічно забороняє блок values:. Оператори не можуть із сутності Release записувати values у сутність Component чи сутність Feature. Це забезпечення на рівні схеми JSON Schema — не суспільний договір і не домовленість, — і воно гучне: кожен документ сутності під час завантаження перевіряється за схемою свого виду, тож сутність Release, що містить values:, зупиняє збірку з діагностикою, яка називає файл і проблемний ключ, а не ігнорується мовчки.
Це не означає, що значення однакові в усіх середовищах. Підтримуваний шлях для варіювання за середовищами — підйом параметрів (Parameter Hoisting):
- Розробник відкриває в сутності Aggregate типізоване поле
parameters.*. - Шаблон
valuesсутності Component посилається на нього:storage_size: "{{ .parameters.db_size }}". - Сутність Release заповнює параметр:
parameters: { db_size: "100Gi" }. - Відрендерений вивід відображає значення, специфічне для середовища.
Сутність Aggregate залишається єдиним джерелом істини щодо того, які значення відкриті для варіювання за середовищами (оголошення parameters) і як вони потрапляють у значення компонента (посилання в шаблоні). Сутність Release заповнює; вона не перевизначає.
Той самий інваріант захищають ще два обмеження:
- Коли сутність Release використовує
extends, оголошення вказівникаaggregate:заборонене схемою. Дочірня сутність Release має розгортати той самий намір розробника (Developer Intent), що й її батьківська. - Сутність Release не може додавати обчислювальних ресурсів, яких не оголосила сутність Aggregate, і не може перенаправляти ребро, оголошене розробником. У межах сокетів, які оголосив Architect, сутність Release може з’єднувати й налаштовувати ребра між наявними компонентами: вона задає
infraдля ребра на ребрі, яке з’єднав розробник, або з’єднує з наявним компонентом ребро до оголошеного, але не прив’язаного сокета. Вона не може оголошуватиvaluesдля ребра (вони залишаються в сутності Aggregate), прив’язувати сокет, якого не оголошуєusesSchemaсутності Component, чи спрямовувати ребро на компонент, якого не існує, — кожен із цих випадків зупиняє збірку. Зверніть увагу, яке оголошення має на увазі середня частина речення: сокет має з’являтися вusesSchemaкаталогової сутності Component. Автор сутності Aggregate може назвати сокет, якого не оголошує його тип компонента, а поверхню сутності Release свідомо не відкрито так само — оператор з’єднує й налаштовує в межах архітектури, а не вигадує її.
Конфігурація з’єднання для ребра обмежена споживачем: values та infra, що їх несе ребро, з’являються лише в контексті рендерингу вузла, який створив ребро, і ніколи — у контексті цілі. Тож власний відрендерений вивід компонента інваріантний щодо з’єднань, які встановлюють із ним інші компоненти, — з’єднання чи налаштування ребра до цілі ніколи не збурює того, що рендерить сутність Recipe цілі. Єдине місце, де ці з’єднання видно, — сутність Feature, приєднана до цілі: її сутність FeatureRecipe може прочитати, які компоненти використовують ціль, тож ресурси, які вона видає, — скажімо, політика, що допускає саме оголошених викликачів, — слідують за з’єднаннями, тоді як власний вивід цілі — ні. Навіть там values та infra для ребра залишаються при споживачеві.
6. Межа ABI WebAssembly: предметно-специфічний інтелект живе у Wasm
Хостовий бінарний файл Go не містить жодної логіки, специфічної для хмари чи інфраструктури. Увесь предметно-специфічний інтелект, рендеринг шаблонів і форматування живуть суворо всередині плагінів WebAssembly, які виконує вбудоване середовище виконання Wazero. Хост Go оркеструє конвеєр і передає корисні навантаження через ABI гостям Wasm як вказівники на пам’ять, у кодуванні, яке несе кожен сокет.
З цього випливають два наслідки:
- Логіка, специфічна для сутності Provider (рендеринг, специфічний для Helm, форматування, специфічне для Terraform, злиття, специфічне для Compose), ніколи не живе в ядрі компілятора Go. Компілятор розв’язує ім’я провайдера, яке сутність Recipe оголошує в
spec.capability, до сутності Plugin рендерингу провайдера, що його обслуговує, і передає вузол цьому плагіну; сам переклад повністю виконується в гості Wasm. Хост не містить коду Go для окремих провайдерів для стандартного провайдера, тож у процесі немає нічого, до чого можна відступити, — ім’я провайдера, яке не розв’язується до жодної обслуговувальної сутності Plugin, зупиняє збірку замість рендерингу якогось вбудованого значення за замовчуванням. - Логіка політик (правила безпеки, перевірки відповідності, обчислення FinOps) ніколи не живе в ядрі компілятора Go. Політики належать до сокета керування Wasm, який підприємства вмикають за власним вибором, — плагіна, приєднаного в ролі вердикту (
ir-verdict/render-verdict), щоб прийняти або відхилити збірку, або в ролі перетворення (label-transform/annotation-transform), щоб формувати мітки чи анотації.
Межа ABI зберігає ядро Go компактним, придатним до аудиту й незалежним від хмари. Заміна логіки рендерингу провайдера — це заміна артефакту Wasm, а не перекомпіляція самої Aggrega.
7. Розділення відповідальності (поділ на чотири домени) — орієнтир, а не в’язниця
Проєктні настанови Aggrega розділяють створення на чотири домени:
- Developer Intent — Aggregate.
- Platform Architect — каталогові сутності Component і Feature.
- Platform Ops — Recipe, FeatureRecipe, Plugin (зокрема сутність Plugin рендерингу провайдера).
- Platform Operator — Manifest, Release.
Типове розгортання, що добре працює, дотримується цього поділу: розробники пишуть намір застосунку, а не фізичну інфраструктуру; команда Ops пише фізичну інфраструктуру, а не логіку застосунку. Aggrega спроєктовано для використання саме так, а офіційна документація, приклади й каталог стандартної бібліотеки написані відповідно до цього поділу.
Поділ на чотири домени — це орієнтир і проєктна рамка, а не забезпечення компілятором. Компілятор (згідно з інваріантом 1) без власної позиції. Користувачі вільні:
- Об’єднувати ролі (одна людина пише і сутності Aggregates, і сутності Recipes).
- Змішувати відповідальність (Architects жорстко прописують мітки відповідності безпосередньо в сутностях Components
core/*, коли цього вимагають корпоративні каталоги). - Перетинати межі доменів (розробники використовують підйом параметрів, щоб впроваджувати інфраструктурні аспекти в сутність Aggregate, коли цього вимагає застарілий код).
Компілятор приймає будь-який шаблон створення, що проходить валідацію схеми. Архітектура заохочує найкращі практики; обмеження на рівні схеми (як-от заборона values: у сутності Release з інваріанту 5) — єдині перетини доменів, які компілятор справді відхиляє. Будь-яке інше розділення — це суспільний договір, якого дотримуються автори каталогів, а там, де підприємства його вмикають, — сокет керування Wasm.
8. Детермінований вивід
За ідентичного вводу компілятор створює побайтово ідентичний вивід. Дві компіляції тих самих сутностей Aggregate + Release + Manifest з тим самим каталогом дають відрендерені артефакти, що збігаються побайтово.
Це контракт, на який покладаються інструменти GitOps і процеси рецензування на основі diff. Pull request, який не змінив вводу, не повинен створювати жодного diff у відрендереному виводі. Pull request, який змінив ввід, повинен показувати лише diff, що випливає з цієї зміни, — без хибних перевпорядкувань, без коливань позначок часу, без артефактів ітерації мап.
Детермінований вивід забезпечують три принципи:
- Мапи, впорядковані автором: кожна мапа, порядок ітерації якої може вплинути на відрендерений вивід, використовує контейнер упорядкованої мапи, тож ітерація слідує порядку оголошення автора, а не порядку хешів.
- Жодного вмісту, залежного від годинника чи випадкового, у відрендерених артефактах, якщо автор явно не впровадив його через ввід шаблону.
- Рендеринг чистий: той самий виклик гостя Wasm з тим самим вводом дає той самий вивід.
Прапорець компілятора --trace (див. language-reference/cli/aggrega-build.md) дає авторам і операторам поверхню перевірки цього інваріанту. Дві компіляції того самого вводу з увімкненим --trace створюють побайтово ідентичні дампи трасування; будь-який diff на окремому проході локалізує регресію. Детермінованість — не лише властивість на момент випуску: її можна спостерігати в кожному проміжному стані компілятора через розкладку трасування для кожного вузла.
Детермінований вивід — це контракт, завдяки якому Aggrega безпечно використовувати як джерело істини в циклі GitOps.
Обсяг інваріантності за рівнями розв’язання
Гарантія побайтово ідентичного виводу поширюється на артефакти, закріплені у файлі блокування, — сутності, розв’язані через артефакти реєстру, дайджести яких записує файл блокування (рівень реєстру в трирівневій моделі розв’язання сутностей). Коли збірка читає файли, які сутність Release вказує за шляхом (локальні шляхи, що починаються з ./ або ../), або сутності в каталогових директоріях робочого простору (catalog_dirs:, на рівні робочого простору та кешу), інваріантність залежить від того, чи залишаться ці файли незмінними між збірками. Файл блокування записує сутність із каталогової директорії робочого простору за дайджестом її документа й оголошених нею файлів, тож збірка зупиняється на сутності, яка змінилася після pull, замість рендерити її, — з одним винятком: сутність Recipe або FeatureRecipe, яку сутність Manifest називає посиланням, що водночас є іменем сутності Component або Feature, записується під цим посиланням як Component або Feature, тож її вводи утримуються лише закріпленнями поруч із нею у файлі блокування, а редагування її власного документа не виявляється. Зберігати файли такими, як були, — відповідальність системи керування версіями (зазвичай Git).
Посилання на локальний шлях, базовий файл якого змінюється між двома компіляціями, створює легітимний diff у відрендереному виводі, хоча форма вводу компілятора не змінилася, — гарантія детермінованого виводу зберігається (той самий байтовий ввід → той самий байтовий вивід), але вводи різняться, бо змінився локальний файл. Каталоги, яким потрібна інваріантність між збірками для кожного джерела, отримують артефакти з реєстру в закріплений файлом блокування кеш, а не читають їх за локальним шляхом чи з директорії робочого простору; файл блокування — якір побайтової ідентичності.