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

Стан мови

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

До цієї сторінки звертаються дві групи читачів. Автори-початківці переглядають сторінку, перш ніж писати з використанням незнайомої поверхні, щоб переконатися, що ця поверхня вже сьогодні дає відрендерений результат. Ті, хто шукає довідку, переглядають сторінку, коли поверхня, якою вони користуються, поводиться неочікувано: наприклад, коли YAML проходить валідацію, але результату немає, саме на цій сторінці насамперед варто перевірити стан поверхні. Читачі, які повертаються, також звертаються до сторінки, щоб визначити поверхні, що змінили мітку стану з часу останнього прочитання. Розділи про окремі домени та довідники сутностей описують, як поверхня має працювати; ця сторінка описує, чи вона вже працює.

Таксономія статусів

Кожна мовна поверхня на цій сторінці має одну з чотирьох позначок статусу:

  • available. Схема приймає поверхню; компілятор її обробляє; поведінка відповідає задокументованому контракту. Автори, які використовують поверхню зі статусом available, отримують задокументований контракт.

  • accepted but inert. Схема приймає поверхню — написане з її використанням проходить валідацію, — але компілятор поки що на неї не реагує. Використання поверхні зі статусом accepted but inert дає синтаксично коректну збірку без жодного відрендереного результату для цієї поверхні; компілятор може видати попередження з назвою неактивної поверхні (рекомендований підхід), а деякі поточні поверхні мовчки пропускаються без попередження. Записи в розділах нижче описують конкретну поведінку.

  • accepted but blocked. Схема приймає поверхню — написане з її використанням проходить валідацію, — але компілятор зупиняє збірку замість рендерингу. Використання поверхні зі статусом accepted but blocked завершується помилкою під час рендерингу з явним повідомленням, що слід написати натомість. Блокування може бути постійним, якщо написане є неоднозначністю, яку компілятор не розв’язуватиме за вас, бо вибір одного тлумачення замість вас міг би призвести до постачання того, про що ви не просили; або ж воно може діяти лише доти, доки не буде випущено поведінку, що стоїть за поверхнею. Те, що обіцяє позначка, однакове в обох випадках: схема її приймає, збірка її відхиляє, а помилка підказує вам, як це виправити.

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

Позначки статусу оцінюються відносно поточного компілятора. Поверхні, що активно розробляються, можуть переходити між позначками; записи в розділах описують план переходу, якщо він відомий.

Типи вхідних даних Recipe

Сутність Recipe формує свій вихід із трьох типів вхідних даних — отриманих із джерела, синтезованих і артефактів, — описаних у 16-recipe-input-composition.md. Статус за типами вхідних даних:

  • source: + valuesMapping: (з джерела) — available. Компілятор розв’язує URI source:, обчислює шаблон valuesMapping (вбудований, файловий $import: або бібліотечний $import:) і передає результат цільовому провайдеру для рендерингу. Використовується провайдерами helm, helm-chart, compose, terraform і cloudformation.

  • workload: (синтезовані) — available. Сутність Recipe оголошує workload: або вбудовано (блоковий скаляр із YAML сутності Workload), або через $import: (шлях до файлу). Компілятор розбирає шаблонізовану сутність Workload, валідує її за вбудованою схемою Workload і передає синтезатору робочих навантажень цільового провайдера. Використовується провайдерами helm і compose. Провайдер helm-chart явно перенаправляє авторів до провайдера helm для синтезованих маніфестів K8s. Сутність Recipe, що оголошує workload: для провайдера, який не реалізує синтез робочих навантажень, зупиняється під час рендерингу з помилкою CATALOG_ERROR.

  • artifacts: (артефакти) — доступно. Поле є мапою іменованих записів; кожен запис створюється inline або завантажується через $import: для окремого запису. Записи обчислюються після того, як розібрано Workload і розв’язано джерело, тож їм доступний повний контекст шаблону — зокрема .workload і .source; до документів, що містять метадані, додається інформація про походження, об’єднана в metadata.labels і metadata.annotations (ключі, небезпечні щодо набору символів, — recipe-uri, boundary-path, sync-wave — як анотації, той самий поділ, який застосовують провайдери helm), і вони виводяться як окремі файли поруч із виводом сутності Recipe, відрендереним із джерела або синтезованим із workload. Розподіл за Provider — плаский провайдер helm виводить окремі файли в каталог, названий за компонентом, який їх оголосив, усередині вихідного каталогу межі, оскільки ключ задає ім’я файлу й нічого не каже про те, який компонент його записав; провайдер compose спрямовує свій вивід через об’єднувач наприкінці Release; провайдер helm-chart обчислює кожен запис із роздільниками Aggrega [[ ]], щоб синтаксис Helm {{ }} у тому самому файлі зберігся для подальшого рендерингу, а потім розміщує кожен запис відповідно до його форми — запис, завантажений через $import:, у boundaries/<bp>/charts/<nodeID>/templates/<authored-key> (файли пакета вкладено під цим ключем), поруч із власними шаблонами джерельного чарту, а запис із вмістом inline — у boundaries/<bp>/charts/<nodeID>/<authored-key>, корені чарту, де власні шаблони чарту читають його через .Files.Get / .Files.Glob; провайдер terraform записує кожен запис дослівно у власний каталог компонента в дереві modules/ межі; провайдер cloudformation об’єднує кожен запис, що є фрагментом стека, з єдиним стеком, який збирається для цього вихідного каталогу. Колізії імен файлів між походженнями різних видів вхідних даних (вивід, відрендерений із джерела, синтезований із workload або виведений як артефакт) виявляються під час рендерингу детектором міжпоходжувальних колізій і спричиняють CATALOG_ERROR, що називає кожного учасника.

Див. entities/recipe.md щодо авторської поверхні сутності Recipe і правил композиції типів вхідних даних; errors/fatal-halts.md щодо правил форми сутності Recipe; і розділ Providers нижче щодо матриці за провайдерами.

Мови зіставлення

Recipes (і FeatureRecipes) прив’язуються до єдиного поля зіставлення, що перетворює контекст Aggrega на словник значень, який споживає базовий провайдер. Поле valuesMapping: підтримує три режими написання, вибір між якими визначається формою вмісту:

  • valuesMapping: — режими 1-3 доступні. Режим 1: вбудований шаблон Go (блоковий скаляр). Режим 2: файловий $import: (мапа, що містить лише $import: із локальним шляхом до файлу). Режим 3: бібліотечний $import: (мапа, що містить лише $import: із посиланням на ідентичність за простим іменем на запис MappingLibrary, <Library>#/mappings/<entry>, за потреби з нижньою межею версії :<version>). Компілятор обирає режим за формою вмісту: блоковий скаляр — режим 1, $import: зі шляхом до файлу — режим 2, $import: із бібліотечним посиланням за простим іменем — режим 3. Усі три режими обчислюють розв’язаний шаблон Go щодо контексту шаблону сутності Recipe під час зіставлення значень (допоміжну бібліотеку Sprig зареєстровано заздалегідь); режим 3 розв’язує запис у локальному каталозі та в усіх бібліотеках, закріплених у lock-файлі, а посилання з хостом відхиляється. Механізм вибору режиму та робочі приклади див. у entities/recipe.md, розділ «Поле valuesMapping — три режими написання».

Інтерфейс написання сутності Recipe та дизайн мови зіставлення див. у entities/recipe.md, а бібліотечну сутність, на якій ґрунтується режим 3, — у entities/mappinglibrary.md.

Синтаксис inject

Блок inject: має один синтаксис у будь-якому місці розміщення — у власному inject компонента, у з’єднанні uses і в приєднанні.

  • Список записів для кожного механізму ([{in: ..., from: ...}], [{in: ..., value: ...}]) — доступно. Кожен механізм доставки є списком; кожен запис називає свій локальний ідентифікатор (ім’я змінної середовища, шлях до файлу, прапорець аргументу) через in: і містить рівно одне з двох: from: (посилання на ключ provides) або value: (літеральний рядок). Механізм, записаний як мапа, а не як список, або запис, що містить обидва ключові слова, зупиняє збірку на оболонці документа сутності Aggregate із зазначенням шляху.

  • value: лише у власному inject компонента. Літерал належить до власного inject компонента, який його доставляє. У з’єднанні uses значення value: зупиняє збірку, як описано в An inject: entry on a connection carries a literal (Запис у з’єднанні містить літерал), а у власному inject приєднання воно так само зупиняє збірку, як описано в An inject: entry on an attached Feature carries a literal (Запис у приєднаній сутності Feature містить літерал): обидва доставляють лише ключі, які публікує інша сутність, названі через from:.

Повну специфікацію контракту ін’єкції, зокрема семантику контексту з подвійним станом, правила колізій ключів і розібрані приклади, див. у vocabulary/topology-triad.md.

Рушій шаблонів

Рушій шаблонів Go в Aggrega обчислює шаблони Recipe і FeatureRecipe відносно контексту шаблону на тій фазі для кожного місця, яку документує Матриця розгортання шаблонів. Бібліотеку допоміжних функцій Sprig попередньо зареєстровано поряд із власними допоміжними функціями Aggrega на кожній поверхні, яку обчислює рендерер, з одним винятком: розв’язання структурованої координати source: реєструє лише допоміжні функції Aggrega — там доступні optional і capitalizedWords, а функції Sprig — ні, тож виклик Sprig у полі source: або в записі locals: на сутності, що містить структуровану source:, зупиняє збірку під час розбору. Див. errors/fatal-halts.md, де цій поверхні відведено окремий розділ. Обчислення, розбір та інтеграція зі Sprig доступні вже сьогодні.

Поведінка за відсутнього ключа — допускається в шаблонах значень; суворий missingkey=error у шаблонах шляхів, у твердженнях і в координаті source:. Шаблони значень обчислюються з опцією Go missingkey=zero, тож шаблон, що посилається на незв’язаний ключ (наприклад, .values.unset_field), не викликає помилки, а зчитування нічого не виводить. Ідіоми каталогів на кшталт {{ .values.optional_field | default "fallback" }} і далі працюють за цієї політики, оскільки невстановлене значення вважається порожнім для default. Шаблони шляхів (directory: / subDirectory: на межах сутностей Release) обчислюються з missingkey=error відносно закритого списку дозволених значень — непомітні збої шляхів дають зламану структуру файлової системи, яку оператори виявляють лише після збірки, а суворість перехоплює помилку раніше. Ще дві поверхні мають ту саму сувору політику з тієї ж причини: порожній результат там дав би хибний вердикт або хибну фіксацію версії замість поля, яке автор може перечитати. Це запис assertions: у сутності Component, Feature, Recipe або FeatureRecipe та шаблонні поля структурованого блоку source: у сутності Recipe або FeatureRecipe. errors/fatal-halts.md описує політику кожної поверхні окремо й наводить форми з урахуванням наявності, які працюють за суворої політики.

Резервне значення з урахуванням наявності через optional. Коли авторові Recipe потрібно відрізнити «ключ відсутній» від «ключ присутній із нульовим / порожнім / хибним значенням» — розрізнення, якого не може зробити default зі Sprig, — рендерер надає допоміжну функцію optional: {{ optional .infra "replicas" 1 }} повертає задане автором infra.replicas (зокрема задане 0), якщо воно присутнє, і повертається до 1 лише тоді, коли ключ відсутній. Повну семантику див. у templates/sprig-functions.md.

Згортання імен через capitalizedWords. Якщо ціль приймає лише літери й цифри в іменах, за якими вона адресує ресурси, {{ capitalizedWords .context.instance_id }} читає ідентифікатор як слова, розділені будь-якими символами поза цим алфавітом, і робить першу літеру кожного слова великою, тож payments-db дає PaymentsDb. Згортання відкидає всі розділювачі, тому два ідентифікатори, що відрізняються лише пунктуацією, дають одне ім’я; збірка, яка створила б два ресурси під одним іменем, зупиняється й називає обидва ідентифікатори. Повну семантику див. у templates/sprig-functions.md.

Забезпечення контракту параметрів на рівні оголошення. Обов’язкові параметри, яких не надає сутність Release, спричиняють явні помилки на рівні контракту параметрів — першого, що перевіряє розв’язання, — із походженням file:line, яке називає параметр і контракт. Порушення типів / обмежень виявляються так само. Це і є суттєве забезпечення щодо відсутніх ключів: типізація перевіряється там, де виражено намір розробника (оголошення parameters: у сутності Aggregate), а не пізніше, під час обчислення шаблонів. Див. entities/aggregate.md §«Typed parameter contracts».

Єдина граматика оголошень для parameters: у сутності Aggregate. Кожен слот параметра задається як об’єкт типізованого контракту (key: { type: <type>, default: <value>, ... }). Скорочений скалярний запис (key: <value>) відхиляється на оболонці документа сутності Aggregate з помилкою, що називає параметр і повідомляє, що очікувався об’єкт. Словник типізованого контракту робить семантику type:, required: та обмежень явною на рівні оголошення; заповнення в сутності Release і далі використовує скалярні значення відповідно до оголошеного в контракті типу.

Матрицю обчислення для кожного місця шаблону див. у templates/expansion-matrix.md, а огляд шаблонізації — у 05-templates.md.

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

Конвеєр компіляції Aggrega задокументовано в ../architecture/10-compilation-pipeline.md. Стан за фазами:

  • Розв’язання, побудова топології, фіналізація графа, статичний аналіз і рендеринг — доступні.
  • Відображення ін’єкцій (перехоплення перед рендерингом injectMapping) і кожен підетап базового рендерингу — публікація locals, відображення values, синтез робочих навантажень, обчислення артефактів, рендеринг провайдера, рендеринг функцій і генерація ресурсів облікових даних FeatureRecipe — доступні.
  • Конвеєр плагінів (виконання Wasm у pipeline:) — доступний. Для сутності Recipe або FeatureRecipe, що оголошує непорожні кроки pipeline:, кожен крок виконується в оголошеному порядку: компілятор викликає названий у кроці плагін Wasm для відрендереного виводу, застосовує повернуті операції JSON Patch до адресованих документів і виконує побічні ефекти кроку. Крок, умова when: якого рендериться як хибна, пропускається як наскрізний, і набір документів лишається незмінним. Автори, яким потрібні мутації у стилі JSONPatch (ін’єкція sidecar Envoy, VolumeMount для секретів тощо), реалізують їх через цю поверхню.

Providers

Стандартна бібліотека Aggrega постачається з п’ятьма провайдерами рендерингу — helm, helm-chart, compose, terraform і cloudformation. Стан кожного провайдера:

  • helm — доступний. Постачаються обидва режими: режим із джерелом (рендеринг Helm-чарту через Helm SDK) і синтезований режим (сутність Workload → об’єкт контролера, вибраний за form сутності Workload, — Deployment, StatefulSet, DaemonSet, Job або CronJob — а також Services і PVC).
  • helm-chart — доступний. Постачається режим із джерелом (композиція umbrella-чарту). Синтезований тип вхідних даних до цього провайдера не застосовується; автори, яким потрібен синтез маніфестів K8s, використовують провайдер helm із workload:.
  • compose — доступний. Постачаються обидва режими: режим із джерелом (накладання фрагментів compose) і синтезований режим (сутність Workload → сервіс compose + томи + мережі). Вихідний docker-compose.yaml для кожної межі збирається композитором рівня сутності Release.
  • terraform — доступний. Постачаються і режим із джерелом, і артефакти; кожна межа отримує одну кореневу конфігурацію aggrega.modules.tf, що оголошує кожен компонент як блок module, файли якого лежать у власному каталозі компонента в modules/. Синтезований тип вхідних даних до цього провайдера не застосовується.
  • cloudformation — доступний. Постачаються і режим із джерелом, і артефакти (фрагменти стека); усі компоненти, що рендеряться в один вихідний каталог, збираються в один шаблон стека, який виводиться як чистий JSON. Синтезований тип вхідних даних до цього провайдера не застосовується.

Рендеринг сутності Provider забезпечує сутність Plugin з pluginType: provider; див. entities/plugin.md щодо інтерфейсу створення сутності Plugin для рендерингу провайдерів і 06-providers.md щодо довідкових сторінок для кожного провайдера.

Розгортання на основі анотацій

Manifests містять розділ прив’язок features.annotations:, який зіставляє ключі анотацій із типами Feature, а також згруповану за стовпами таблицю маршрутизації (maps.infra / maps.values), що визначає, які властивості схеми Feature може заповнювати кожна прив’язка. Описано в entities/manifest.md і providers/well-known-annotations.md; місце в конвеєрі — у ../architecture/10-compilation-pipeline.md; механіка під час завантаження каталогу та під час inspect — у ../architecture/13-catalog-and-registry.md §“Annotation-driven Feature expansion”.

  • Прив’язки features.annotations у сутності Manifest — доступно. Підетап розгортання анотацій у межах розв’язання постачається повністю. Він обходить межі сутності Release (від зовнішніх до внутрішніх) і підсистеми сутності Aggregate (від зовнішніх до внутрішніх), обчислює ефективний набір анотацій для кожного компонента через каскад і перевизначення з відмовою через null як для всього значення, так і для окремих підключів, розбирає кожне значення анотації як скаляр, структуровану мапу або явний null, маршрутизує кожен підключ через декларацію maps прив’язки з перевіркою відповідності сторони й стовпа (сторона Aggregate спрацьовує на maps.values; сторона Release — на maps.infra), перевіряє типи кожного листового елемента за spec.schema цільової сутності Feature і впроваджує синтетичні приєднання Feature, які граф IR позначає як origin: annotation. Композиція між сторонами об’єднує значення по стовпах і полях під час побудови IR, причому явне значення перемагає для кожного поля; aggrega inspect показує дужки походження для кожного листового елемента. Цей шлях захищають перевірка цілей прив’язок під час завантаження каталогу, лінт перекриття стовпів схеми та лінт перекриття мап прив’язок. Голий префікс aggrega.ai/ відхиляється під час завантаження сутності Manifest, якщо його використано як ключ прив’язки: цей префікс зарезервовано для власних анотацій платформи; прив’язки використовують feature.aggrega.ai/ або власний домен.

Зіставлення версій

Сутності Recipes і FeatureRecipes оголошують інтерфейс Component або Feature, який вони реалізують, за допомогою ключового слова implements:. implements: ніколи не обирає Recipe: це робить зіставлення в Manifest, а екземпляр, тип якого не охоплює жодне зіставлення, зупиняє збірку з помилкою, що перелічує як кандидатів сутності Recipes, чиє implements: може реалізувати цей тип. implements: керує перевіркою того, що сутність Recipe кожного запису зіставлення в Manifest реалізує зіставлений тип або базовий тип, який цей тип розширює через extends. Зіставлений тип — це ключ запису, а для ключа components.type також тип кожного екземпляра компонента, якого ключ досягає у версії, яку ключ не називає (для ключа, записаного без версії, — кожного екземпляра, якого він досягає), причому у версії, у якій збірка компілює цей екземпляр: у версії, яку називає екземпляр, або, для екземпляра без версії, у найвищій версії цієї сутності Component, наявній у каталозі. Стан за формами:

  • Точна (core/api-server:1.0.0) — доступна. Зіставлений тип має бути саме цієї версії.
  • Діапазон, сумісний за мажорною версією (core/api-server:^1.0.0) — доступний. Форма з кареткою є обмеженням SemVer (>=1.0.0, <2.0.0 для цього прикладу); версія зіставленого типу має йому задовольняти.
  • Без версії (core/api-server) — доступна. Їй задовольняє будь-яка версія типу.

Запис зіставлення, у сутності Recipe якого implements: не збігається ні із зіставленим типом, ні з жодним із його базових типів, зупиняє збірку з OPS_ERROR, називаючи запис, сутність Recipe та її значення implements:. Екземпляр компонента, якого ключ досягає в іншій версії і версії якого не задовольняє implements: сутності Recipe, зупиняє збірку з тим самим OPS_ERROR, називаючи екземпляр, його тип — а для екземпляра без версії ще й версію, у якій його скомпільовано, — ключ, сутність Recipe та її значення implements:. Форма з кареткою — канонічна форма написання для зіставлення, сумісного за мажорною версією.

Див. vocabulary/inheritance-and-interface.md щодо дизайну implements: і entities/manifest.md щодо структури рівня зіставлення для кожної сутності Manifest.

Оболонка метаданих

Оболонки сутностей каталогу містять metadata.labels, metadata.annotations і (у сутності Release) metadata.environment. Статус за кожною частиною:

Доступність metadata.labels і metadata.annotations — у семи видах. Ці поля містять оболонки таких сутностей: Component (мітки обов’язкові, з обов’язковим ключем component.aggrega.ai/type, анотації необов’язкові), Feature (обидва необов’язкові), чотири види бібліотек SchemaLibrary, MappingLibrary, WorkloadLibrary і ArtifactLibrary (обидва необов’язкові) та Aggregate (лише мітки, необов’язкові). Решта сутностей — Recipe, FeatureRecipe, Manifest, Release, Plugin — не приймають metadata.labels чи metadata.annotations на рівні оболонки.

metadata.environment у сутності Release — обов’язкове. Схема сутності Release перелічує environment як обов’язкове поле metadata; збірка проставляє його значення у відрендереному виводі як мітку aggrega.ai/environment. Див. entities/release.md, де розділ Environment Metadata описує п’ять практичних випадків використання (атрибуція витрат OTel/FinOps, фільтрування трасувань і журналів OTel, націлювання операторів Kubernetes, розрізнення продакшн-середовищ у кількох регіонах, визначення меж відповідності вимогам).

Див. 02-naming-conventions.md щодо правил регістру полів, які застосовуються до ключів metadata, а також довідкові сторінки окремих сутностей щодо форм оболонок, які кожна сутність приймає сьогодні.

Команди CLI

CLI Aggrega реєструє конвеєр збирання та засоби інтроспекції. Статус окремих команд:

  • aggrega build — доступна. Читає файл сутності Release, розв’язує Aggregate + Manifest, запускає конвеєр компіляції та записує згенеровані артефакти до граничних вихідних каталогів. Якщо lock-файл наявний, перевіряє залежності відповідно до нього; якщо його немає, зупиняється з вимогою виконати pull або спершу заповнює його, коли цього вимагає --auto-pull чи auto_pull.
  • aggrega inspect — доступна. Досліджує сутність каталогу, файл сутності, сутність, опубліковану в реєстрі, або сутність Release і повідомляє її розв’язану форму. Див. cli/aggrega-inspect.md.
  • aggrega pull — доступна. Розв’язує всі залежності сутності Release і записує lock-файл для кожної сутності Release, що фіксує кожну сутність каталогу та кожен вихідний артефакт за версією й дайджестом вмісту, а кожен зовнішній вхід, який запитує рендеринг сутності Release, — за дайджестом вмісту; кешує отриманий вміст у .aggrega/cache. --verify перевіряє наявний lock-файл відносно поточного стану. Див. cli/aggrega-pull.md.
  • aggrega push — доступна. Публікує сутність каталогу в реєстр OCI; aggrega push --list-kinds повідомляє, які види вона приймає. Див. cli/aggrega-push.md.
  • aggrega lint — доступна. Застосовує правила дисципліни публікації з рівнем серйозності warn до всього каталогу, замикання залежностей сутності Release або однієї сутності; для однієї сутності --pre-publish додає перевірку підвищення версії відносно поточної опублікованої версії сутності, а невідповідність зупиняє виконання. Правила постачаються як Wasm-плагін, що вмикається за бажанням. Див. cli/aggrega-lint.md.
  • aggrega serve — доступна. Довготривалий демон «компілятор як сервіс», що працює за протоколом JSON-RPC 2.0 через stdin/stdout, для інтеграції з редакторами та IDE. Методи, які він обслуговує, див. у cli/aggrega-serve.md.
  • aggrega version — доступна. Виводить версію CLI; -o json видає машинозчитуваний об’єкт версії.
  • aggrega validate — доступна. Перевіряє коректність усього каталогу, сутності Release або окремої сутності, повідомляючи діагностику без рендерингу артефактів.
  • aggrega search — доступна. Шукає опубліковані сутності в локальному індексі налаштованих реєстрів; індекс будує й оновлює aggrega registry update.
  • aggrega registry — доступна. Керує реєстрами та політикою довіри до їхніх підписів; registry add записує реєстр, а registry update будує локальний індекс, до якого звертається aggrega search.
  • aggrega push-artifact — доступна. Публікує окремий артефакт даних (наприклад, пакет документації) в реєстр OCI, на додачу до push, що публікує сутності.
  • aggrega sign — доступна. Підписує один або кілька вже опублікованих артефактів і долучає їхні підписи.
  • aggrega deprecate — доступна. Долучає підписану позначку застарілості до вже опублікованого артефакту.
  • aggrega login і aggrega logout — доступні. Автентифікують у реєстрі OCI та зберігають облікові дані або видаляють збережені облікові дані.
  • aggrega auth — доступна. Керує локальною ідентичністю підпису, що використовується для підписування артефактів.
  • aggrega config — доступна. Досліджує конфігурацію робочого простору й керує нею; підкоманди показують ефективну об’єднану конфігурацію та джерело кожного параметра, створюють робочу конфігурацію з реєстром і політикою довіри до його підписів, а також фіксують ефективну критичну для збирання конфігурацію в робочому просторі, щоб він збирався ідентично без залежності від глобальної конфігурації машини.
  • aggrega get-schema — доступна. Виводить JSON Schema для виду сутності або контракту.
  • aggrega plugin — доступна. Досліджує Wasm-плагіни, які може розв’язати CLI; підкоманди виводять їхній список, додають і видаляють налаштовані плагіни, синхронізують машинні записи плагіна та генерують їхнє подання у вигляді каталогу.
  • aggrega cache — доступна. Досліджує й обслуговує кеші на диску; підкоманди повідомляють стан, очищують застаріле, витісняють записи та повністю очищують кеш.
  • aggrega mcp — доступна. Запускає сервер Model Context Protocol через stdio або через HTTPS для клієнта на іншій машині, надаючи доступ до інтроспекції компілятора інтеграціям з AI-асистентами.
  • aggrega completion — доступна. Генерує скрипт автодоповнення оболонки для CLI.
  • Підкоманди-розширення CLI — доступні. Wasm-плагін, опублікований як гість pluginType: cli, розв’язується та реєструється як підкоманда aggrega, тож встановлене розширення запускається як aggrega <extension> поряд із вбудованими командами.
  • aggrega import — доступна. Перетворює стороннє декларативне джерело визначення агентів (Langflow, Flowise, n8n) на чернетки файлів авторингу Aggregate і Component, записуючи для кожного вузла детерміноване рішення про повторне використання каталогу з оцінкою впевненості. Специфічне для формату відображення надає плагін-імпортер, який робочий простір розв’язує для формату джерела, — той, що є в його каталозі, або один з імпортерів Langflow, Flowise і n8n компілятора, які збираються й публікуються з кожним випуском компілятора. Бінарний файл містить їхні сутності Plugin, але не їхні модулі, тож вони обслуговують свої формати в кожному робочому просторі: перший імпорт, якому потрібен імпортер, відсутній на машині, отримує його з типового реєстру робочого простору, перевіряє та зберігає в кеші вмісту для всіх подальших імпортів. Джерело розбирається парсером, який каталог робочого простору надає для його синтаксису, або, якщо каталог не надає жодного, — парсером, вбудованим у компілятор, тож робочий простір, каталог якого не містить парсера, імпортує через будь-який із них.
  • aggrega scaffold — доступна. Створює чернетку початкового документа для будь-якого виду сутності за схемою цього виду — з кожним обов’язковим полем і заповнювачем там, де потрібне значення, — і записує її в стандартний вивід; з --example записує в новий каталог один із готових до запуску прикладів документації, прочитаний із підписаного пакета документації.
  • aggrega explain — доступна. Пояснює умову зупинки, яку позначає короткий код (наприклад, E0007) або описовий код.
  • aggrega edit-document — доступна. Застосовує до документа одне обмежене структуроване редагування — додавання компонента, приєднання сутності Feature, підключення з’єднання або встановлення одного значення, — зберігаючи кожен байт, якого воно не торкається.
  • aggrega pin — доступна. Записує в entity.lock поруч із сутністю Recipe або FeatureRecipe закріплення вмісту для кожного входу, який сутність читає поза межами власного документа.
  • aggrega skills — доступна. Встановлює навичку Aggrega в AI-асистента.

Огляд CLI див. у 07-cli.md, а довідкові сторінки всіх команд — в індексі довідника мови.

Редактори та інші фронтенди

Кожен фронтенд показує те, що скомпілював двійковий файл aggrega; жоден не має власного компілятора. Стан за поверхнями:

  • Контракт IR-графа — доступно. Схема IR-графа, контракт, за яким кожен фронтенд читає граф, постачається у складі дистрибутива схем Aggrega; див. довідник схеми IR.
  • Читання графа з команди — доступно. aggrega build приймає --ir-graph, так само як aggrega inspect із сутністю Release та aggrega validate --release; прапорець виводить граф, розв’язаний під час цього запуску, у stdout як JSON на додачу до того, що команда вже створює. Сеанс демона читає той самий граф через aggrega/irGraph, а інструменти cli-inspect, cli-build і cli-validate MCP-сервера приймають його як свій аргумент ir_graph.
  • Граф топології у Visual Studio Code — доступно. Розширення Aggrega для Visual Studio Code малює IR-граф вибраної сутності Release як інтерактивний граф і приєднує з нього Features, звертаючись по обидва до демона aggrega serve.
  • Безголовий потоковий режим CLI — заплановано. Безголовий режим виводить IR-граф як JSON, розділений символами нового рядка, у stdout, щоб фронтенд споживав його в міру зміни топології. Наразі постачається один документ на виклик, а не потік: жодна команда не виводить послідовність графів в один stdout у міру зміни топології.

Як редактор, асистент і демон звертаються до компілятора, див. у ../architecture/15-editors-assistants-and-frontends.md.

Напрями проєктування

Наведена вище таксономія статусів класифікує стан кожної поверхні мови; у цьому розділі зафіксовано статус ширших напрямів проєктування, задокументованих у розділах про архітектуру.

Відповідність вимогам у масштабі всього середовища не є запланованим напрямом: сформулювати правило управління один раз так, щоб воно поширювалося на кожну збірку в робочому просторі, вже сьогодні доступно через сокет управління. Plugin, підключений за ключем plugins.governance конфігурації робочого простору, оцінює кожну збірку в цьому робочому просторі: роль вердикту відхиляє граф або відрендерений артефакт, що порушує правило, а роль перетворення надає похідні метадані, яких розробник ніколи не вводить вручну. Див. ../architecture/11-governance-and-compliance.md.

  • Паритет інтерфейсів і автоматична реалізація — доступно. Recipe, написаний для базової сутності Component, обслуговує кожну сутність Component, що її розширює, на будь-якій глибині ланцюжка, і архітекторові не потрібно створювати дублікат Recipe. Розширювальна сутність Component записує schema: inherited, тож не додає до values / infra / provides кореневих ключів, яких Recipe базової сутності не зміг би використати; сутність Component, що оголошує extends із власною схемою, відхиляється на оболонці свого документа. Manifest і далі зіставляє розширювальний тип окремим записом, а перевірка зіставлення приймає його, коли implements зіставленого Recipe називає цей тип або будь-який базовий тип, який він розширює. Задокументовано в ../architecture/02-ecosystem-philosophy.md.
  • Ghost Infrastructure Tracker — доступно. Запобіжник фази рендерингу видає попередження, коли ключ, оголошений автором, досягає вузла, але жоден шаблон, оголошений прив’язаним Recipe, його не читає, тож значення, оголошене автором і мовчки відкинуте шаблоном, називається, а не губиться. Це половина того самого дизайну зіставлення форм, що належить до фази рендерингу. Див. errors/warnings.md.

Розділи про архітектуру описують поверхні дизайну; ця сторінка відстежує статус реалізації.