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

Component

Концептуальну роль сутності Component (абстрактного інтерфейсу обчислювального вузла в Домені 2) описано в architecture/04-entity-taxonomy.md. Ця сторінка охоплює поверхню авторингу сутності Component: таксономію семантичних міток, за допомогою якої архітектори накладають когнітивну ідентичність поверх операційної базової онтології, оголошення schema: для стовпів даних, декларативні таблиці usesSchema і featuresSchema для топологічних сокетів і слотів приєднання, вимоги присутності, механізм успадкування extends: та блок міжпольових правил assertions:.

Таксономія семантичних міток (домовленість стандартної бібліотеки)

Якщо базові типи суто хмарні (cloud-native), то операційний і когнітивний інтелект архітектури нашаровується повністю через семантичну качину типізацію.

Ядро компілятора на Go не інтерпретує ці мітки. Компілятор будує плаский граф проміжного представлення (IR), не інтерпретуючи семантику міток. Ці мітки становлять домовленість стандартної бібліотеки — незмінні «генетичні маркери», які створює архітектор платформи в домені 2. Вони надають явні семантичні гачки, за допомогою яких валідатори політик Wasm і фізичні операційні Recipes керують архітектурою.

(A) Загальний хмарний рівень Ці мітки описують універсальні поведінки, що дає змогу рушіям політик і згенерованим проксі L7 керувати стандартними корпоративними архітектурами без потреби нативно розуміти фреймворки ШІ.

Префікс міткиДопустимі значення (домовленість)Навіщо це потрібно Platform Ops (гачок політики)
tool.aggrega.ai/impactread-only, mutatingДає змогу рушіям політик оцінювати авторизацію за принципом найменших привілеїв. Змінювальні інструменти можуть автоматично запускати політики, які вимагають приєднання суворих сайдкарів-шлюзів схвалення.
datastore.aggrega.ai/enginerelational, document, kv, vector, graph, semantic-memory, search (набір значень стабілізується відповідно до наповненого каталогу)Дає змогу рушіям політик забезпечувати типобезпеку між вузлами (наприклад, не дати агенту спробувати надіслати SQL-навантаження до векторної БД).
gateway.aggrega.ai/intelligencesemantic, l4-meshВизначає, які можливості маршрутизатор може фізично підтримувати (наприклад, не дає Feature, що маршрутизує за моделлю, яку називає запит, як-от ланцюжок резервування, приєднатися до стандартної TCP-мережі).
dataplane.aggrega.ai/request-mirroringfull-rate, sampledДає змогу Feature, що копіює живий трафік до другого призначення, вибрати проксі, який узагалі здатен копіювати, і відрізнити той, що копіює кожен відповідний запит, від того, у якого частку скопійованих запитів можна налаштувати.
dataplane.aggrega.ai/caller-identityclient-certificate, injected-headerДає змогу Feature, якій потрібно, щоб первинного викликача було ідентифіковано для сервісу за проксі, вибрати компонент, що може передати цю ідентичність, і прочитати, який механізм її передає — передані далі дані власного TLS-сертифіката клієнта чи заголовок, який проксі сам формує після автентифікації викликача.
dataplane.aggrega.ai/content-maskingentity-recognition, pattern-listДає змогу Feature, що маскує чутливий текст, вибрати компонент, здатний замінити його заповнювачем у навантаженні чату та завершень, яке він маршрутизує, перш ніж текст піде далі. Значення називає точність: з entity-recognition компонент замінює збіги шаблонів, заданих у його конфігурації, а також типи сутностей, які виявляє сервіс розпізнавання, що його він викликає; з pattern-list він замінює лише збіги шаблонів, заданих у його конфігурації, і не викликає жодного сервісу розпізнавання.
dataplane.aggrega.ai/prompt-guardpattern-list, classifierДає змогу Feature, що перевіряє промпти моделі, вибрати компонент, здатний аналізувати навантаження чату та завершень, яке він маршрутизує, і відхиляти запит за його вмістом. Значення називає точність: з pattern-list збіг шукається за шаблонами, заданими в його конфігурації, у навантаженні моделі, а не в довільному тілі HTTP; з classifier вердикт виносить навчений текстовий класифікатор через сервіс виявлення, який викликає компонент, відносно порогу, заданого в його конфігурації.
dataplane.aggrega.ai/upstream-tlstrust-anchorДає змогу Feature, яка вимагає, щоб проксі перевіряв, з ким він спілкується, вибрати компонент, здатний перевірити сертифікат вищого сервера відносно якоря довіри, який надає Release.
dataplane.aggrega.ai/upstream-pinningpublic-keyДає змогу Feature, що закріплює, який ключ може пред’явити вищий сервер, вибрати компонент, здатний відхилити вищий сервер, якщо пред’явлений ним сертифікат не містить одного з відкритих ключів, які надає Release. Це інше твердження, ніж upstream-tls: закріплення каже, яким ключем має бути сертифікат, а якір — що він має стверджувати.
dataplane.aggrega.ai/period-budgetcost, tokensДає змогу Feature, що обмежує, скільки трафік може спожити за період, вибрати компонент, здатний відхиляти запити до моделей, щойно підраховане ним за період перевищить ліміт, заданий у його конфігурації. Значення називає, що він рахує: cost — вартість трафіку, оцінену за таблицею, яку компонент веде для кожної моделі; tokens — токени, які, за звітом відповіді кожної моделі, було прочитано, записано або і те, і те; компонент їх рахує і нічого не оцінює.
dataplane.aggrega.ai/concurrency-captotal, per-targetДає змогу Feature, що обмежує, скільки запитів компонент обробляє одночасно, вибрати компонент, здатний затримати або відхилити запит понад ліміт, заданий у його конфігурації. Значення називає, що рахує один ліміт: total — кожен запит, який пересилає компонент, відносно одного ліміту; per-target — запити в обробці до кожної вищої цілі, до якої він надсилає, з лімітом для кожної і без ліміту на їхню суму.

Ключі dataplane.aggrega.ai/ називають позицію на шляху трафіку, а не вид компонента, тож проксі, вхідний шлюз і сервісна мережа описують себе одним словником, замість того щоб кожному потрібен був власний. Дві властивості цієї родини варто прочитати уважно, бо обидві легко перевернути:

  • Значення несе точність, а не лише наявність можливості. Два компоненти можуть обидва дзеркалити запити й усе ж відрізнятися так, що це важливо для Feature, тож відмінність передається в значенні, а Feature вибирає потрібну їй точність. Компонент, що пропонує вищу точність, несе сильніше значення і жодного іншого.
  • Значення стверджує, що продукт здатен робити, і ніколи — що розгортання ввімкнуло. Ці два твердження читаються однаково, і лише перше є властивістю компонента. Проксі, що може перевірити сертифікат вищого сервера, несе upstream-tls: trust-anchor незалежно від того, чи вмикає будь-яке конкретне розгортання цю перевірку, бо мітка — це те, за чим Feature вибирає ще до того, як щось налаштовано.

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

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

Префікс міткиДопустимі значення (домовленість)Навіщо це потрібно Platform Ops (гачок політики)
model.aggrega.ai/capabilitygenerative, embedding, transcriptionВикористовується рядками селекторів usesSchema (які компілятор на Go обчислює нативно під час статичного аналізу), щоб гарантувати, що розробник випадково не спрямує генеративне текстове навантаження до ендпоінта ембедингів.
model.aggrega.ai/apiopenai, anthropic, gemini, nativeНазиває, який API моделі відповідає за адресою, яку публікує компонент: openai, коли це OpenAI API — власний від постачальника чи його реалізація на сервері, anthropic, коли це Messages API від Anthropic — власний від постачальника чи його реалізація на сервері, gemini, коли це Gemini API від Google, і native, коли це власний API продукту і жоден із наведених. Її несе кожен компонент моделі, а також шлюз, здатний обслуговувати API моделі, тож сокет, що вибирає component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api, приймає модель або такий шлюз і відхиляє шлюз, що не обслуговує жодного, тоді як сокет, що називає одне значення, як-от model.aggrega.ai/api=anthropic, приймає лише те, що обслуговує цей API. Мітка називає, що обслуговує продукт, а не що під’єднує один Release: шлюз, моделі якого під’єднуються до його власного сокета, несе її і тоді, коли нічого не під’єднано. Мітка — це рядок, з яким зіставляється селектор; ніщо не перевіряє, що насправді відповідає за адресою.
agent.aggrega.ai/autonomyautonomous, copilotВизначає ризик виконання когнітивного циклу, що дає змогу політикам вимагати можливостей схвалення людиною для повністю автономних агентів.

(C) Наскрізні мітки (врядування, стан і апаратне забезпечення) Це базові корпоративні теги, що керують валідацією Zero-Trust і маршрутизацією на апаратне забезпечення.

Префікс міткиДопустимі значення (домовленість)Навіщо це потрібно Platform Ops (гачок політики)
component.aggrega.ai/hostingself-hosted, managed, external, mixedФіксує, хто експлуатує базовий ресурс компонента, — вісь межі довіри. Рушії політик читають її, щоб оцінити ризик витоку даних (наприклад, внутрішні дані, спрямовані до стороннього API managed, виходять за межу оператора). Наскрізна: ті самі значення однаково описують керовану базу даних, керований API моделі та самостійно запущений сервер інференсу. mixed позначає компонент, чиї сутності Recipes охоплюють більше ніж один режим експлуатації, — сховище даних, яке його Recipes для Helm і Compose запускають самостійно, а Recipes для RDS роблять керованим, — тож режим експлуатації сутності Release визначає сутність Recipe, яку вибирає її Manifest.
compliance.aggrega.ai/data-classpublic, internal, restrictedКлас даних, які зберігає компонент. Компілятор передає його до графа збірки як рядок і нічого не ранжує; політика, яку оператор підключає в ролі ir-verdict, задає класам порядок у власних налаштуваннях і читає мітку вздовж маршрутів, які перелічує компілятор, — зупиняючи, наприклад, збірку, де компонент restricted досягає компонента іншого класу без підключеної на маршруті сутності Feature, що знімає гриф (policy-data-class-route). Жодна сутність Component стандартної бібліотеки його не має: клас — це твердження про те, як середовище використовує компонент, і його несе власна сутність Component цього середовища — наприклад, спеціалізація через extends.
compliance.aggrega.ai/contains-piitrue, falseЯвно позначає робочі навантаження, що підпадають під дію GDPR/CCPA. Політика, яку підключає оператор, може читати її, щоб вимагати певних сутностей Features на маршрутах, якими йде трафік такого навантаження, — наприклад, core/data-masking на AI-шлюзі, через який воно надсилає трафік до моделі; саме таку форму policy-data-class-route перевіряє для класу даних. Жодна сутність Component стандартної бібліотеки її не має; як і клас даних, це твердження середовища про власні компоненти.
hardware.aggrega.ai/acceleratorgpu, tpu, npuВикористовується DevOps у файлі Release. Вони явно спрямовують ці компоненти в межі фізичних пулів обладнання (наприклад, кластер із GPU) через мапу components: {}, тоді як роль вердикту управління може забезпечувати, що компоненти з міткою GPU ніколи не розміщуються в межах без GPU.
state.aggrega.ai/retentionretain, deleteУсуває розрив видалення AOT. Якщо розробник видаляє базу даних зі свого Aggregate, оркестратор GitOps фізично знищить диск. Крок pipeline: сутності Recipe може прочитати мітку retain і додати до відрендерених артефактів нативний для оркестратора захист (наприклад, helm.sh/resource-policy: keep).
state.aggrega.ai/backup-tiermission-critical, standard, ephemeralХук доступності SOC2. Повідомляє операційному FeatureRecipe, чи фізично генерувати для ресурсу конфігурації автоматичних знімків і резервного копіювання томів.

(D) Динамічний бізнес-контекст (каскадні анотації) Тоді як labels визначають незмінну ДНК каталогу, динамічні бізнес-контексти (як-от межі аудиту SOC2 чи облік витрат FinOps) змінюються залежно від того, хто розгортає застосунок і де він працює. Ними керують анотації, які динамічно вносять subsystems розробника, операційні межі Release або плагін управління, підключений у ролі annotation-transform.

Префікс анотаціїДопустимі значення (домовленість)Навіщо це потрібно Platform Ops (гачок політики)
business.aggrega.ai/cost-centerнаприклад, finance, ai-researchПотрібна плагінам рендерингу Wasm, щоб вносити фізичне тегування (наприклад, теги AWS або мітки K8s) у фінальні згенеровані артефакти для панелей хмарного білінгу.
business.aggrega.ai/ownerнаприклад, team-alpha@corp.comМаршрутизація реагування на інциденти. Гарантує, що інфраструктуру зіставлено з командою людей.
compliance.aggrega.ai/frameworksнаприклад, soc2, hipaaТригер області SOC2. Вноситься через Release середовища. Плагіни Wasm читають цей рядок, щоб автоматично генерувати суворі sidecar-контейнери журналювання аудиту й вимикати порти налагодження, коли застосунок входить у продакшн-межу відповідності.

Таксономія — це домовленість каталогу, а не правило компілятора. Підприємства можуть ігнорувати її, видалити або вигадати власний словник міток (mycompany.com/custom-trait). Плагіни Wasm оцінюють будь-які ключі міток, які створює підприємство.

Створення схем

Схема Component (і її відповідник Feature, зокрема облікові Features із міткою feature.aggrega.ai/kind: secret) оголошує контракт валідації для створених розробником values через блок spec.schema:. Блок приймає JSON Schema 2020-12, записану або в компактній скороченій формі YAML (типово; близько 15 ключових слів, які механічно перетворюються на JSON Schema під час компіляції), або в повній формі JSON Schema YAML (розлога форма), із міждокументними посиланнями через $ref: на записи SchemaLibrary, спільні для кількох Components.

  • Вбудована компактна форма (типовий спосіб створення): вбудований блок YAML, що містить листки компактної форми безпосередньо в YAML сутності Component. Підходить для переважної більшості вмісту схем каталогу й займає лише частку рядків повної JSON Schema. Словник ключових слів і домовленості щодо створення див. у vocabulary/compact-form-authoring.md.
  • Вбудована JSON Schema YAML: розлога форма, придатна, коли схемі потрібні ключові слова JSON Schema 2020-12, яких компактна форма безпосередньо не підтримує ($dynamicRef, глибокі unevaluatedProperties, складна композиція not:). Компактну форму й JSON Schema можна поєднувати на межі будь-якого вузла в межах одного блоку schema: через запасний вихід $jsonschema:.
  • Міждокументне посилання ($ref: на запис SchemaLibrary): нативне для JSON Schema посилання $ref:, що вказує на запис SchemaLibrary за ідентичністю (Datastores#/schemas/MariaDBValues чи подібне). Корпоративні схеми на сотні рядків, які повторно використовуються кількома Components, зберігаються в сутностях SchemaLibrary; сутність Component, що їх використовує, посилається на запис, не вбудовуючи вміст. Про сутність бібліотеки та семантику розв’язання див. entities/schemalibrary.md і vocabulary/cross-document-ref.md.

Три наведені вище форми створюють вміст стовпів, і вони доступні сутності Component, яка нічого не розширює. Сутність Component, що оголошує extends:, взагалі не створює вмісту стовпів: вона записує буквальний маркер schema: inherited і отримує блок стовпів своєї бази точно в тому вигляді, у якому його створила база. Цей маркер — єдине значення, яке schema: набуває в такій сутності Component. Див. «Створення каталогу: розширення базових Components» нижче.

Компілятор розв’язує блок schema: — розгортає компактну форму, розіменовує URL-адреси $ref:, застосовує ланцюжки SchemaLibrary від бібліотеки до бібліотеки — і уніфікує отриману JSON Schema з автоматично згенерованими базами, похідними від usesSchema і featuresSchema (див. розділ нижче), під час проходу валідації сутності Component. Валідація виконується щодо розв’язаної схеми; шлях створення непрозорий для наступних етапів конвеєра.

Створені екземпляри валідуються щодо цієї розв’язаної схеми під час збирання: створені розробником values екземпляра компонента й розв’язані оператором infra, а також values/infra будь-якого приєднання Feature, мають відповідати оголошеним стовпам — значення неправильного типу, число поза діапазоном, рядок, що не має оголошеного format, відсутнє обов’язкове поле або (для values, що валідуються як закриті) неоголошена властивість зупиняють збирання в місці їх створення, а не породжують зламаний маніфест під час розгортання. Стовп, схема якого називає format, що його компілятор не перевіряє — будь-що поза email, uri, hostname, ipv4, ipv6, uuid, date-time і date, зокрема password, — відхиляється під час завантаження каталогу з переліком підтримуваних назв; що перевіряє кожна назва, див. у vocabulary/compact-form-authoring.md. Екземпляр сутності Component, що extends: базу, валідується щодо блоку стовпів бази, який розширювальна сутність Component успадковує без змін, — тож екземпляр бази й екземпляр будь-чого, що її розширює, мають однаковий контракт стовпів. Діагностику й правила для кожного стовпа (зокрема як infra валідується щодо об’єднання ключів сутності Component і провайдера) див. у errors/fatal-halts.md §«Authored values or infra do not conform to the declared schema (Створені values або infra не відповідають оголошеній схемі)».

Оголошені типові значення матеріалізуються в зрендерених стовпах. Окрім валідації, default:, оголошений для поля values (або поля infra), під час збирання підставляється в зрендерений стовп для кожного ключа, який автор пропустив, — тож шаблон сутності Recipe, що читає {{ .values.charset }}, отримує оголошене в схемі utf8mb4, а не порожнє значення. Значення, надані автором, завжди мають пріоритет; вкладені об’єкти заповнюються для кожного пропущеного дочірнього елемента. Оскільки матеріалізація використовує те саме розв’язання схеми, що й валідація, типові значення, досяжні через міждокументне $ref: у SchemaLibrary, теж матеріалізуються — як у разі посилання на весь стовп (values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}), так і у формі «база плюс варіант» (базове $ref: поряд із сусідніми properties, кожна з власними типовими значеннями). Типові значення, оголошені лише всередині локального внутрішньодокументного посилання #/$defs/ або в гілці allOf / oneOf / anyOf, не матеріалізуються; стандартна бібліотека компонує стовпи через міждокументне $ref:, яке матеріалізується.

Стовп values

Схема Component розділяє три стовпи за належністю: values заповнює розробник в Aggregate (когнітивний намір — назва бази даних, версія, кодування), infra заповнює оператор у Release (операційне розмірування — обчислення, сховище, HA), а provides задає Recipe (публічний контракт API — хост, порт, протокол). Розробник ніколи не бачить infra; оператор ніколи не бачить values. Recipes споживають обидва стовпи під час базового рендерингу, відображаючи абстрактні стовпи в конкретну форму, якої очікує їхній цільовий провайдер. Цей розділ описує поверхню створення стовпа values. Ширшу таксономію стовпів і дисципліну міжстовпового каскаду див. у vocabulary/data-pillars.md.

values несе когнітивний намір розробника — вибір, що описує, чим є або що робить застосунок, а не як він масштабується чи працює. Назва бази даних, кодування, версія рушія, рівень журналювання, прапорці функцій, параметри рівня застосунку, які змінюються між версіями застосунку, але лишаються стабільними між середовищами, — типовий вміст values. Оператор ніколи не перевизначає values: (схема Release механічно відхиляє блок values: згідно з architecture/06-data-taxonomy-and-composition.md §8 Обмеження 4); варіативність між середовищами проходить через підняття параметрів (Parameter Hoisting) — Aggregate надає типізовані parameters.*, шаблон values сутності Component посилається на них, а Release заповнює ці параметри.

# Component schema declares the values shape:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
charset: { type: string, default: utf8mb4, enum: [utf8mb4, latin1, ascii] }
engine_version: { type: string, default: "10.11" }
log_level: { type: string, default: info, enum: [debug, info, warn, error] }
# Aggregate fragment — the developer fills values:
components:
customer-db:
type: core/datastore/mariadb
values:
database_name: customers
charset: utf8mb4
engine_version: "{{ .parameters.mariadb_version }}" # Parameter Hoisting
log_level: info

Споживання на боці Recipe. Recipes читають розв’язані значення через .values.<field> у valuesMapping:, provides:, assertions: та інших поверхнях шаблонів — матрицю доступності для кожного шаблону див. у entities/recipe.md. Компілятор уніфікує схему values сутності Component з будь-якими схемами values: приєднань Feature на тому самому вузлі Component, тож розв’язаний контекст шаблону містить кожне застосовне поле.

Міжстовпова дисципліна. values — єдиний стовп, який розробник створює в Aggregate. Сюди належать суто орієнтовані на розробника поля; операційні параметри (кількість реплік, межі CPU/пам’яті) належать до стовпа infra сутності Component, щоб вони перебували в Release; публічний вихід (хост, порт) належить до provides сутності Recipe. Змішування цього порушує інваріант належності; рідкісні випадки, коли навмисна передача між стовпами виправдана, див. у vocabulary/data-pillars.md, розділ «Cross-pillar mechanics».

Стовп infra

Схема Component розділяє три стовпи за власністю: values заповнює розробник в Aggregate (когнітивний намір — назва бази даних, версія, кодування), infra заповнює оператор у Release (операційне масштабування — обчислення, сховище, HA; резервне копіювання сховища даних тут не масштабують — це Feature core/backup, яку оператор приєднує в Release), а provides задає Recipe (публічний контракт API — хост, порт, протокол). Розробник ніколи не бачить infra; оператор ніколи не бачить values. Recipes використовують обидва під час базового рендерингу, відображаючи абстрактні стовпи в конкретну форму, якої очікує їхній цільовий провайдер.

Для кожної сутності Component зі стандартної бібліотеки, агностичної щодо можливостей, важать три домовленості infra: відкрита структура як запасний вихід для специфічних для провайдера параметрів, необов’язкове перевизначення версії вихідного артефакту та словник на основі наміру для полів високої доступності. Канонічним еталонним Component є core/datastore/mariadb у каталозі стандартної бібліотеки — його можуть реалізувати Helm Recipes, що запускають офіційний образ mariadb або передають власний ресурс MariaDB контролеру mariadb-operator, Terraform Recipes на основі AWS RDS, CloudFormation Recipes на основі тієї ж поверхні RDS і Compose Recipes на основі локального контейнера — і його блок infra ілюструє перший і третій шаблони.

infra.overrides

Універсальні поля infra — compute, storage, ha — покривають більшу частину операційного масштабування для різних провайдерів. Решта неусувно специфічна для провайдера: Kubernetes Recipe потребує nodeSelector, RDS Terraform Recipe потребує instance_class, CloudFormation RDS Recipe потребує DBInstanceClass, Compose Recipe потребує перевизначення image. Схема Component надає справді відкриту мапу як запасний вихід, щоб ці параметри проходили без роздування схеми:

infra:
# ... universal fields ...
# Provider-specific overrides. Accepts any nested structure.
# Each Recipe documents which keys it reads.
overrides:
type: object
additionalProperties: true # genuinely open map: arbitrary nested structure permitted

Явний type: object з additionalProperties: true вмикає семантику відкритої мапи. Компілятор передає структуру без змін; тіло шаблону Recipe читає ті ключі, які знає, і ігнорує решту. Кожен Recipe документує онтологію ключів перевизначення у своєму коментарі-заголовку, тож оператор, який створює Release для конкретної комбінації Component × Recipe, знає, які параметри надає Recipe.

Фрагмент Release з перевизначеннями:

components:
main-db:
infra:
compute: { cpu: "2", memory: 8Gi }
storage: { size: 40Gi, type: balanced-csi }
overrides:
nodeSelector:
kubernetes.io/hostname: cluster1-worker1
service_type: LoadBalancer
metrics:
enabled: true
image:
repository: bitnamilegacy/mysqld-exporter

Розробник ніколи не бачить overrides — воно міститься в Release, який належить до сфери оператора.

infra.source_version

Поле source сутності Recipe посилається на вихідний артефакт конкретної версії (Helm-чарт 25.0.8, модуль Terraform 4.2.0, тег образу OCI). Жорстке задання версії всередині Recipe змушує супровідника каталогу публікувати новий Recipe при кожному сумісному підвищенні версії вихідного артефакту. Схема Component надає необов’язкове перевизначення:

infra:
source_version:
type: string
description: |
Source artifact version. A Recipe versions its artifact from this key
where its source resolution reads it, and is unaffected where it does not.
Changing from the version a Recipe was authored against does not
guarantee value mapping compatibility.

Recipe читає його через помічник optional у своєму блоці source, тож за відсутності закріплення використовується версія, для якої було створено Recipe:

source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "{{ optional .infra `source_version` `25.0.8` }}"

Рядки source сутності Recipe (і рядкові підполя структурованої мапи source:) обчислюються як шаблони Go. Віддалена координата — як-от version вище — обчислюється, коли aggrega pull закріплює артефакт, за .values, .infra і .locals без кореня .context; джерело, що називає шлях у робочому просторі, обчислюється під час рендерингу сутності в тому самому самодостатньому контексті, що й locals сутності Recipe — .context.instance_id, .values, .infra і всі розв’язані .locals вузла. В обох випадках .context.inject, .context.uses і .provides заборонені. Саме наявність .infra у цьому контексті забезпечує роботу наведеного вище перевизначення, а .locals дає змогу Recipe обчислити фрагмент джерела один раз і прочитати його тут. Шаблон джерела ніколи не читає provides власного вузла: цей стовп не входить до контексту, і шаблон, що звертається до нього, зупиняє збірку — це незмінна властивість поверхні, а не прогалина, яку закриють пізніше. Повні правила доступності див. у рядку №5 матриці розгортання шаблонів. Зміна infra.source_version щодо типового значення Recipe не гарантує, що valuesMapping сутності Recipe буде сумісним на рівні протоколу з новою версією вихідного артефакту; це попередження містить description оголошення source_version у схемі Component.

infra.ha.*

Поля високої доступності використовують словник наміру, а не словник механізму:

infra:
ha:
enabled: { type: boolean, default: false }
read_replicas: { type: integer, min: 0, default: 0 }

infra.ha.enabled означає «зробити цей Component високодоступним», а infra.ha.read_replicas — «я хочу N копій лише для читання». Кожен Recipe вирішує, чим стає намір у його провайдера. Recipes стандартної бібліотеки для core/datastore/mariadb під іменами, якими їх відображає Manifest:

Recipeha.enabled: true відображається вha.read_replicas: N відображається в
helm/mariadb (StatefulSet на офіційному образі mariadb)запускає один сервер, тож збірка зупиняється, називаючи ключзапускає один сервер, тож N більше за 0 зупиняє збірку
helm/mariadb-cluster (власний ресурс MariaDB, який узгоджує контролер mariadb-operator)вмикає автоматичне перемикання при відмові (replication.primary.autoFailover: true); перемикання відбувається на репліку для читання, тож N, що дорівнює 0, зупиняє збіркувстановлює spec.replicas у N + 1 і вмикає реплікацію; provides.host стає Service <name>-primary
terraform/mariadb-rds (AWS RDS)задає multi_az = true для основного aws_db_instanceстворює N окремих ресурсів-реплік для читання aws_db_instance
terraform/mariadb-rds-module, terraform/mariadb-rds-terraform-aws-modules (AWS RDS через модуль)передає модулю multi_az = trueстворює один екземпляр, тож N більше за 0 зупиняє збірку
cloudformation/mariadb-rds (AWS RDS)задає MultiAZ: true для AWS::RDS::DBInstanceстворює один екземпляр, тож N більше за 0 зупиняє збірку
compose/mariadb (локальний контейнер розробки)запускає один сервер, тож збірка зупиняється, називаючи ключзапускає один сервер, тож N більше за 0 зупиняє збірку

Словник механізму (infra.primary.replicas) природний для одного провайдера (поди Kubernetes є репліками StatefulSet), а для інших є категорійною помилкою — RDS не має поняття «реплік» для основного екземпляра, CloudFormation віддзеркалює RDS, а Compose взагалі не має абстракції горизонтальних реплік. Словник наміру перекладається: кожен провайдер має якесь поняття «зробити цю базу даних високодоступною» і якесь поняття «я хочу N копій лише для читання», а Recipe виконує переклад для конкретного провайдера. Якщо реалізація не має такого механізму, її Recipe може зупинити збірку, назвавши ключ, як це роблять helm/mariadb і compose/mariadb для обох ключів і одноекземплярні RDS Recipes для реплік читання.

infra.ha.read_replicas: 0 — типове значення; коли обидва ключі мають типові значення, helm/mariadb-cluster рендерить одноекземплярну MariaDB без блоку replication, а не реплікацію над одним екземпляром. compose/mariadb запускає один сервер на локальному хості Docker, тож infra.ha.enabled: true або ненульове infra.ha.read_replicas зупиняє збірку, називаючи ключ, а повідомлення вказує на helm/mariadb-cluster, що забезпечує перемикання при відмові та репліки для читання.

Стовп provides

provides — це публічний API, який визначає автор Recipe: значення, які розв’язаний Recipe сутності Component надає низхідним викликачам через їхню поверхню .context.uses.<alias>.provides.<provided-name> (або, коли викликач оголошує на ребрі список дозволених inject:, через свій канал .context.inject). Схема Component оголошує форму (назви ключів і типи); блок provides: прив’язаного Recipe надає значення. Розробник, який створює Aggregate, бачить форму provides на сторінці Component як контракт, на який можуть покладатися викликачі; автор Recipe виконує цей контракт для конкретної реалізації, яку він обгортає.

Виконання контракту забезпечується як гучний запобіжник (Loud Guardrail): прив’язаний Recipe мусить створити кожен ключ provides, який оголошує його Component. Якщо прив’язаний Recipe пропускає оголошений ключ, збірка зупиняється й називає відсутній ключ, замість того щоб мовчки нічого не передати викликачам, які на нього посилаються. Створювати додаткові ключі понад оголошений набір дозволено. Перевіряється лише наявність ключів: створені значення — це непрозорі рядки, які компілятор передає далі, тож їхні оголошені типи залишаються контрактом, який читають викликачі, а не значенням, яке перевіряє компілятор.

# Component schema declares the provides contract:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
provides:
host: { type: string }
port: { type: integer }
database: { type: string }
# Recipe fulfills the contract:
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-bitnami
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "25.0.8"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
database: "{{ .values.database_name }}"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

Розділення обчислення на provides і inject. Компілятор обчислює шаблони provides: на етапі обчислення provides у самодостатньому контексті шаблону (.context.instance_id, .context.rendered_name, якщо провайдер вузла його повідомляє, .values, .infra і розв’язані locals: сутності Recipe на тому самому вузлі) — жоден стан викликача не видно. Локальні значення вузла розв’язуються в преамбулі цього етапу, перед його provides, і саме це дозволяє шаблону provides: читати .locals. На етапі гідратації inject, який виконується далі, компілятор обходить ребра uses: і розв’язує .context.uses.<alias>.provides.<provided-name> кожного викликача відносно розв’язаних значень provides. Розділення цих двох етапів гарантує ациклічне розв’язання: provides: не може посилатися на викликача, а inject: викликача не може посилатися на ще не розв’язаний вихід провайдера, доки не виконано гідратацію inject.

Еволюція контракту. Перейменування або вилучення поля provides є несумісною зміною для кожного викликача, що покладається на стару назву. metadata.version сутності Component (і декларація implements: сутності Recipe) несе сигнал еволюції контракту; низхідні викликачі, закріплені за конкретною мажорною версією, бачать стабільну форму provides.

Пояснення з боку Recipe. Граматику написання шаблонів provides:, матрицю доступності для кожного шаблону та робочі приклади маршрутизації між просторами імен і між регіонами див. у entities/recipe.md, розділ «Блок provides:», та в architecture/06-data-taxonomy-and-composition.md §3.

Обов’язкова присутність: features.aggrega.ai/requiredType.<label>

Сутність Component може оголосити, що кожен її екземпляр мусить мати прикріплення заданого типу Feature. Це вимога присутності, і вона записується як повторювана анотація у власних метаданих сутності Component:

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/payment-processor
version: 1.0.0
labels:
component.aggrega.ai/type: server
annotations:
features.aggrega.ai/requiredType.audit: core/audit-logging
features.aggrega.ai/requiredType.compliance: core/pci-compliance
spec:
schema:
values:
processor_endpoint: { type: string, required: true }

Ключ — це префікс features.aggrega.ai/requiredType., за яким іде обрана вами мітка; значення — URI типу Feature, який має мати принаймні одне прикріплення. Мітка називає вимогу в діагностиці, яку видає невиконана вимога, — audit і compliance вище, — і це все її призначення. Ключі з мітками дають змогу сутності Component оголосити кілька вимог одночасно: анотації — це пласка мапа рядків, і вона не може містити дубльований ключ.

Компілятор перевіряє кожен мандат щодо остаточного набору прикріплень екземпляра — після того, як каскад 5-рівневої моделі «цибулі» згорнув усі області: блоки features: рівня компонента й рівня підсистеми в сутності Aggregate, блоки features: рівня межі й рівня компонента в сутності Release, а також прикріплення, створені розгортанням на основі анотацій. Будь-яке з них задовольняє мандат — правило перевіряє, що присутнє, а не як воно там опинилося. Тож сутність Component, мандат якої виконано лише тому, що оператор задав анотацію моніторингу в сутності Release, проходить перевірку так само, як та, до якої розробник прикріпив Feature вручну.

Вимога, яку не задовольняє жодне прикріплення, зупиняє збирання з діагностикою, що називає екземпляр компонента, мітку вимоги та потрібний тип. Значення анотації — непрозорий рядок, тож ніщо не перевіряє його форму, перш ніж компілятор його прочитає; тому значення, яке не є URI типу Feature, або ключ без мітки після префікса зупиняє збирання з окремою діагностикою, яка повідомляє, що оголошення некоректне. Ці дві діагностики навмисно розрізнено: зламане оголошення виправляють у сутності каталогу, а невиконану вимогу усувають прикріпленням Feature — і помилка друку ніколи не повинна виглядати як виконана вимога.

Обидві діагностики описано в errors/fatal-halts.md «Required feature not attached (Потрібну функцію не прикріплено)».

Вимога — це не слот. Ці дві поверхні відповідають на різні запитання, і різниця не косметична:

Слот featuresSchemaвимога присутності
Оголошуєіменовану точку прив’язкиобмеження на те, що має бути присутнім
Ім’я можна розіменуватитак — from: <slot> і .features.<slot>.provides.*ні — мітка лише називає вимогу
Кратністьрівно одне заповнення на слотпринаймні одне прикріплення цього типу
Обмежує заповненняselector, inject, sensitiveнічим, крім типу
Задовольняється вільним прикріпленнямні — слот заповнюється за ім’ямтак — у будь-якій області, під будь-яким ім’ям
Коли вимогу не виконанозупиняє, коли задано required: true і ніщо не прив’язує ім’я слотазупиняє, коли жодне прикріплення не має цього типу

Обидві вимоги перевіряються щодо тих самих вхідних даних — остаточного набору прикріплень екземпляра — і обидві зупиняють збирання з власною діагностикою, бо ставлять до них різні запитання: чи прив’язано одну іменовану точку прив’язки, чи якесь прикріплення має іменований тип. Жодна не відповідає за іншу.

Використовуйте слот, коли сутності Recipe потрібно прочитати те, що прикріплено. Використовуйте вимогу, коли контракт сутності Component вимагає наявності можливості й не зважає на те, який екземпляр її надає. Сутність Component для обробки платежів, що вимагає core/audit-logging, отримує журналювання аудиту в кожному розгортанні, незалежно від того, чи не забув розробник його прикріпити; сутність Component, сумісну з PCI, що вимагає core/pci-compliance, неможливо випустити без прикріпленої десь у розгортанні Feature відповідності.

Успадкування. Вимогу, оголошену в базовій сутності Component, успадковує кожна сутність Component, яка її розширює через extends:, бо анотації метаданих зливаються вздовж ланцюжка розширення, і для кожного ключа перемагає нащадок. Тому нащадок може перенацілити успадковану вимогу, повторно оголосивши ту саму мітку з іншим типом, або додати власні вимоги під новими мітками; прибрати вимогу, оголошену в базовій сутності, він не може.

Топологічні сокети: usesSchema

Сутність Component може оголошувати топологічні сокети через блок usesSchema: — декларативну YAML-мапу, паралельну до featuresSchema. Кожен запис іменує сокет, через який Component приймає залежності між компонентами, і визначає, які форми Component розробник може підключати до цього сокета. Компілятор автоматично генерує правила валідації JSON Schema 2020-12 з оголошених сокетів і об’єднує їх зі schema: сутності Component під час розв’язання Component; розробники не пишуть вручну стовп uses: усередині schema:, оскільки структура походить із usesSchema.

# Component declares the sockets it accepts:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/ai-agent/orchestrator
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
primary_datastore:
required: true
selector: "datastore.aggrega.ai/engine=vector"
inject: [env]
cache:
required: false
selector: "datastore.aggrega.ai/engine=kv"
inject: [env, file]
log_destination:
required: false
selector: "component.aggrega.ai/category=messaging"
inject: []
# Aggregate fragment — developer wires the sockets:
components:
agent:
type: core/ai-agent/orchestrator
uses:
primary_datastore:
main: { target: vector-db-instance }
log_destination:
audit: { target: audit-sink }

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

uses:
# Compact form — a list of target names. Each entry produces an edge
# whose alias equals its target. Use it for the single-target case, and
# when one socket connects to several peers of the same shape.
shards: [orders-db, customers-db, inventory-db]
# Verbose form — an alias-keyed map. Each alias maps to an entry object
# carrying its own `target:`, and may carry its own inject directives.
# Use when the connections need distinct names or per-edge inject.
databases:
primary: { target: orders-db, inject: { env: [{ in: DB_URL, from: url }] } }
replica: { target: orders-db-ro, inject: { env: [{ in: DB_REPLICA_URL, from: url }] } }

Псевдонім завжди відображається на об’єкт запису, ніколи на голе ім’я цілі: databases: { primary: orders-db } відхиляється під час завантаження, як і об’єкт запису без target:. Щоб підключити одну ціль, не вигадуючи псевдоніма, скористайтеся компактною формою — primary_datastore: [vector-db-instance], — яка називає ціль один раз і виводить із неї псевдонім.

Кожен запис — елемент списку або псевдонім мапи — стає одним ребром, що зберігається в порядку написання. selector: сокета застосовується до кожної цілі, підключеної через нього (кожне ребро перевіряється на типи незалежно під час статичного аналізу), а required: true означає, що має бути підключена принаймні одна ціль.

Семантика полів:

ПолеТипЗа замовчуваннямЗначення
requiredboolfalseЯкщо true, розробник має підключити до цього сокета принаймні одну залежність. Якщо false, сокет необов’язковий.
selectorstring—Селектор міток у граматиці, яку використовує appliesTo сутності Feature, якому має задовольняти ціль кожного ребра, підключеного через цей сокет. Він читається як рядок, записаний тут, і обчислюється щодо міток цілі під час статичного аналізу: ціль, мітки якої йому не задовольняють, зупиняє збірку, так само як і селектор, який граматика відхиляє, із зазначенням вимоги, яку не вдалося прочитати. Порожній селектор не накладає обмежень на ціль.
injectstring[]—Список дозволених механізмів доставки inject (паралельно до featuresSchema[].inject). Відсутність або [] (порожній) означає «чорну скриньку» — блок inject: у записі uses: розробника не дозволено; доставку контролює Recipe. [env, file, arg] (непорожній) означає прозорість — розробник може визначати, який механізм доставляє значення provides залежності. Перевіряється: див. «Де перевіряється список дозволених inject сокета» нижче.
valueSchemaobject—Необов’язковий контракт на рівні ребра для написаних розробником values на ребрі, підключеному через цей сокет (пишеться в Aggregate). JSON Schema 2020-12 у тих самих формах запису, що й schema:. Відсутність означає, що сокет не оголошує контракту values.
infraSchemaobject—Необов’язковий контракт на рівні ребра для написаного оператором infra на ребрі, підключеному через цей сокет (пишеться в Release). Ті самі форми запису, що й valueSchema. Відсутність означає, що сокет не оголошує контракту infra.
featuresSchemamap—Слоти вкладень, які може заповнити кожне з’єднання, підключене через цей сокет, з ключами за іменем слота; кожен слот приймає ті самі ключі, що й слот рівня Component. Відсутність означає, що з’єднання через цей сокет не несе вкладень. Див. «Слоти, які заповнює кожне з’єднання» нижче.

Де перевіряється список дозволених inject сокета. Цей список — це твердження сокета про те, чи може споживач узагалі обирати форму доставки, і якщо так, то які форми, — тому він перевіряється щодо кожного ребра uses:, підключеного через сокет, щойно доступні і ребро, і оголошення сокета. З одного правила випливають дві відмови, і обидві зупиняють збірку:

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

Сокет читається з тієї сутності, яка його оголосила, і це не завжди компонент, від якого відходить ребро: ребро, написане в uses: вкладення Feature, розв’язується щодо usesSchema вкладеної Feature, а кожне інше ребро — написане в Aggregate, підключене з Release або досягнуте через субагрегат — щодо схеми споживаючої сутності Component. Сокет, успадкований через extends, читається точно так само, як і написаний самою сутністю.

Ребро, яке нічого не визначає, не зачіпає жодна з відмов, хоч би що оголошував сокет: читання значень залежності з .context.uses.<alias>.provides.<name> у споживаючому Recipe не потребує блоку inject: і доступне завжди. Обидві діагностики див. у errors/fatal-halts.md.

Контракти з’єднання на рівні ребра — valueSchema та infraSchema. Окрім визначення того, які Components можна підключати до сокета, сокет може оголошувати, яку конфігурацію несе кожне з’єднання. Дві необов’язкові схеми на рівні сокета валідують конфігурацію з’єднання на кожному ребрі, підключеному через сокет:

  • valueSchema — контракт для написаного розробником блоку values на ребрі uses: налаштування окремого з’єднання, які розробник задає в Aggregate (наприклад, розмір пулу з’єднань або режим клієнта).
  • infraSchema — контракт для написаного оператором блоку infra на ребрі uses: експлуатаційне розмірування окремого з’єднання, яке оператор задає в Release.

Обидві приймають JSON Schema 2020-12 у тих самих формах, що й поле schema:, — вбудована компактна форма, вбудований JSON Schema YAML або міждокументне посилання $ref: на запис SchemaLibrary. Це контракти на рівні ребра, які валідуються щодо конфігурації кожного ребра незалежно; вони не входять до власної схеми values споживаючої сутності Component. Сокет, який не задає схеми на рівні ребра для стовпа, не оголошує там контракту, і будь-яка конфігурація для цього стовпа не валідується. Конфігурація на рівні ребра валідується як закрита, і валідація враховує значення за замовчуванням в обох стовпах: ключ, якому схема задає default:, вважається наданим, навіть якщо автор його пропускає.

Оголошений default: також матеріалізується в обох стовпах. Пропущений автором ключ потрапляє в контекст рендерингу споживаючого Recipe зі своїм оголошеним значенням за замовчуванням, точно як пропущений ключ value або infra компонента, — тож достатньо оголосити значення за замовчуванням на сокеті, і шаблон Recipe не потребує для нього резервного виразу. Написане значення завжди переважає оголошене за замовчуванням і заповнює лише той ключ, який надає: ребро, що задає один ключ контракту сокета, все одно отримує оголошені значення за замовчуванням для інших ключів цього контракту. Значення за замовчуванням прив’язуються до ребер, тож непідключений сокет нічого не додає.

spec:
usesSchema:
databases:
required: true
selector: "datastore.aggrega.ai/engine=relational"
inject: [env]
valueSchema: # developer per-edge values, authored in the Aggregate
pool_size: { type: integer, minimum: 1, maximum: 100, default: 10 }
tls_mode: { type: string, enum: [disable, require, verify-full], default: require }
infraSchema: # operator per-edge infra, authored in the Release
storage_class: { type: string, default: standard }

З таким оголошеним сокетом ребро, Aggregate якого пропускає pool_size, рендерить 10, а ребро, Release якого пропускає storage_class, рендерить standard. Написане значення переважає для кожного ключа в межах свого стовпа: Aggregate, що задає pool_size: 42, рендерить 42, тоді як tls_mode і далі заповнюється як require, а Release, що задає storage_class: gp3, рендерить gp3, не зачіпаючи жодного ключа розробника.

Recipe для споживаючої сутності Component читає розв’язану конфігурацію на рівні ребра зі збагаченого топологічного каналу за адресами .context.uses.<alias>.values.<key> та .context.uses.<alias>.infra.<key> — див. vocabulary/topology-triad.md.

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

spec:
usesSchema:
models:
selector: "component.aggrega.ai/category=ai-model"
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: The credential the consumer presents to the component this connection reaches.

З’єднання заповнює слот, коли несе прикріплення під іменем слота у власному features: — у записі з’єднання сутності Aggregate (Aggregate) або сутності Release (Release), — і це прикріплення стає одним із прикріплень споживацького компонента під іменем <alias>.<slot>.

Що саме робить ця декларація:

  • Імена слотів утворюють закриту множину. На відміну від власного featuresSchema сутності Component, який допускає вільне прикріплення під будь-яким іменем, слоти сокета — єдині імена, які може нести з’єднання через нього: будь-яке інше ім’я зупиняє збірку під час завантаження, а сокет, що не декларує featuresSchema, не допускає жодного прикріплення на своїх з’єднаннях. Ad-hoc сокет — той, якого цей usesSchema не декларує, — не декларує слотів, тож його з’єднання теж їх не несуть. Кожне з’єднання заповнює свої слоти саме: прикріплення ширшої області ніколи не каскадується на з’єднання, а ключ у Release, що записує складене ім’я прикріплення з’єднання, зупиняє збірку.
  • Інші ключі застосовуються до кожного з’єднання окремо. Слот тут приймає ті самі ключі, що й слот рівня Component, — required, selector, inject, sensitive, description, — і кожне з’єднання перевіряється за ними окремо. selector зіставляється з мітками сутності Feature, якою з’єднання заповнює слот, а заповнення, якого він не допускає, зупиняє збірку з позицією в записі цього з’єднання в документі, що записав заповнення. required: true має виконати кожне з’єднання через сокет: з’єднання, що залишає слот порожнім, зупиняє збірку з назвою цього з’єднання, тоді як сусіднє з’єднання, що заповнює слот, проходить. sensitive читається так само, як на слоті рівня Component: прикріплення, що заповнює слот, позначається як чутливе в графі збірки та в aggrega inspect. На з’єднанні, як і на компоненті, які значення прикріплення приховуються як чутливі, визначає лише власна схема прикріпленої сутності Feature. inject стосується запису Workload, що доставляє матеріал слота: прикріплення з’єднання не має власного блоку inject: — жоден документ не допускає його в записі з’єднання, — тож Workload доставляє його, називаючи з’єднання поруч зі слотом, і цей запис перевіряється за дозволеним списком слота сокета точно так, як запис, що називає слот рівня Component, перевіряється за списком того слота.

usesSchema сутності Feature не приймає featuresSchema: з’єднання, яке проводить Feature, не несе прикріплень, а Feature, що декларує слоти на сокеті, відхиляється під час завантаження. Облікові дані, потрібні такому з’єднанню, є слотом у власному featuresSchema сутності Feature.

Генерація схеми з usesSchema. Компілятор генерує базовий фрагмент JSON Schema 2020-12 з декларованих сокетів і компонує його з декларацією schema: користувача — за тим самим шаблоном, що й featuresSchema. Згенерована схема ніколи не записується на диск; вона існує лише в пам’яті під час проходу валідації Component. Мапа uses: розробника в Aggregate валідується за об’єднаною схемою; selector: кожного сокета обчислюється за мітками кандидатів Component під час статичного аналізу як перевірка безпеки типів між вузлами.

Семантика селектора — механізм розділеної схеми. Саме usesSchema[].selector: робить топологію Aggrega чимось більшим, ніж нетипізована передача рядків. Сокет, що декларує selector: "datastore.aggrega.ai/engine=vector", приймає з’єднання лише з Components, позначеними відповідною парою ключ-значення; агент, що намагається під’єднати свій сокет primary_datastore до relational Component, не проходить статичний аналізатор із чіткою діагностикою порушення селектора. Селектор — це рядок селектора міток у стилі Kubernetes: вимоги, об’єднані комою як І, у формах =, !=, in (...), notin (...), голий ключ і !key — та сама граматика, що й у Feature appliesTo; граматику див. у vocabulary/modifier-system.md, а семантику рушія — у architecture/13-catalog-and-registry.md §2 «Селектори в стилі Kubernetes». Вимога поза цими формами відхиляється, а не читається як інший селектор: порожня вимога (початкова, кінцева чи подвоєна кома), ключ із пробілом або з будь-яким із =, !, (, ) чи комою, або множина без закривної дужки зупиняє кожну збірку, що проводить ребро через сокет, із назвою вимоги. Тож сокет, призначений виключати фронтенди, записується як selector: "tier!=frontend"; "!tier=frontend" відхиляється, бо ! позначає ключ мітки й нічого іншого.

Ad-hoc сокети — що дає декларування сокета і що автор може зробити без нього. Автор Aggregate може записати запис uses: на власному компоненті під іменем сокета, якого цей usesSchema не декларує, зокрема на Component, що взагалі не декларує usesSchema. Ребро будується. Мовчання каталогу щодо сокета означає, що з’єднання не передбачалося, а не що воно заборонене, і топологією застосунку володіє розробник.

Такий ad-hoc сокет втрачає саме те, що надає декларований, бо все це міститься в записі usesSchema: немає selector, тож ніщо не обмежує, до якого компонента може вести ребро, і перевірці безпеки типів між вузлами нічого обчислювати; немає дозволеного списку inject:; немає valueSchema для ребра, тож values: ребра не має контракту для перевірки й декларованих значень за замовчуванням для успадкування. Він втрачає й infraSchema, хоча до цього контракту на такому сокеті все одно нічого не доходить: infra ребра записується в записі ребра Release, а запис Release може називати лише сокет, який декларує споживацька Component. Незмінним лишається те, що ребро може нести: from: кожного запису inject і далі має називати ключ, який декларує schema.provides цільової Component, а ціль і далі має існувати — обидва порушення зупиняють збірку так само, як на декларованому сокеті.

Читайте «немає allowlist inject:» як відсутність обмеження, а не як оголошення blackbox, бо ці два випадки виглядають однаково, а поводяться протилежно. Ребро через ad-hoc сокет може вільно диктувати доставку: немає allowlist, за межами якого міг би опинитися механізм, і жодна сутність не обіцяла обробляти значення внутрішньо. Відмова blackbox, описана вище, застосовується до сокета, який сутність таки оголосила й залишила без allowlist inject:, — таке пропущення є твердженням про з’єднання, яке сутність передбачила, а ad-hoc сокет такого твердження не робить.

Доставка йде тим самим шляхом, і відрендерений артефакт не фіксує різниці. Блок inject ad-hoc ребра розв’язується й доставляється так само, як блок декларованого сокета: кожен ключ from: зчитується з обчисленого provides цілі й потрапляє до контексту ін’єкції споживацького вузла під ключем доставки, який обрав автор, а звідти — до відрендереного артефакту. Шлях доставки один, і ніщо на ньому не розгалужується залежно від того, чи сокет декларовано. Декларований сокет може додати лише вміст — значення за замовчуванням для ребра, які заповнює його valueSchema або infraSchema, — тож там, де декларований сокет не несе такого контракту, те саме ребро рендериться однаково під обома видами сокетів. Декларація — це факт про з’єднання, а не вхідні дані для рендерингу.

values: ребра на ad-hoc сокеті приймається й доходить до споживацького Recipe у .context.uses.<alias>.values без валідації: без valueSchema, з яким його можна порівняти, жоден ключ не перевіряється й жоден не відхиляється. Це не особливість лише ad-hoc сокетів — декларований сокет, що не задає контракту для цього стовпа, обробляє свою конфігурацію ребра так само. Ad-hoc сокет змінює те, що контракт неможливо додати без декларування сокета. .context.uses.<alias>.infra на такому ребрі порожній, бо поверхня, що надає infra ребра, не може називати недекларований сокет.

Кожне ребро у виданому графі фіксує, до якого з двох видів воно належить, тож споживачеві ніколи не доводиться це виводити, а організація, яка хоче, щоб кожне з’єднання проходило через оголошений сокет, може вимагати цього як політики врядування. Оголошення сокета тут залишається кращим шляхом, і саме так робить каталог стандартної бібліотеки: оголошений сокет несе selector, що обмежує, яких компонентів може досягати ребро, список дозволених inject:, контракт на рівні ребра з власними значеннями за замовчуванням та опис — придатне до рецензування твердження про передбачене з’єднання, версіоноване разом із сутністю, що його робить. Ad-hoc форма — це запасний вихід, а не нове значення за замовчуванням. Дві поверхні навмисно не відкриті в такий спосіб — uses вкладення Feature може називати лише сокет, який оголошує вкладена сутність Feature, а uses на рівні ребра в сутності Release може називати лише сокет, який оголошує споживча сутність Component.

Робочий приклад examples/adhoc-uses-socket/ будує обидва види ребер на одному споживачі й показує два доставлені значення поруч у відрендереному результаті, разом із зупинкою, яку спричиняє неоголошений ключ from:.

Друкарські помилки в назвах сокетів виявляються як порада, а не зупинка. Оскільки неоголошена назва сокета допустима, хибно написана назва сокета стає окремим ad-hoc з’єднанням замість підключення сокета, який мав на увазі автор, — і збірка лишається зеленою, хоча нічого через нього не передається. Компілятор повідомляє про назву сокета, що відрізняється на одне редагування від назви, оголошеної в цьому usesSchema, попередженням, яке називає обидва написання, — див. errors/warnings.md «Uses-socket near-miss lint». Попередження ніколи не змінює вердикт збірки; компілятор не контролює, як автор називає сокет.

Співвідношення usesSchema і featuresSchema. Обидва є декларативними таблицями й обидва несуть список дозволених inject: з ідентичною семантикою, але сокет і слот — різні речі й не взаємозамінні. usesSchema керує ребрами між компонентами — графом топології, — оголошуючи, які сокети несуть контракт. featuresSchema керує слотами вкладень, а слот — це іменована точка прив’язки, а не перелік: вкладення під назвою, яку не оголошує жоден слот, допустиме у власному блоці компонента. (Слоти, які сокет оголошує для своїх з’єднань, — єдина закрита множина, як зазначено вище в «Слоти, які заповнює кожне з’єднання».) Дві поверхні зійшлися в цьому пункті — власний запис uses: компонента під неоголошеною назвою сокета теж допустимий, — але вони лишаються різними: неоголошений слот — це вільне вкладення в сутності Component, оголошені слоти якої не зачіпаються, тоді як неоголошений сокет — це ребро без селектора й без контракту на рівні ребра. Багато сутностей Components оголошують обидві; дві таблиці компонуються незалежно.

Слоти приєднання: featuresSchema

Сутність Component може оголошувати слоти приєднання через блок featuresSchema. Кожен слот називає точку прив’язки, у якій Component очікує приєднання Feature, — пароль root, ключ API, токен автентифікації, прив’язку ідентичності, — і обмежує, яка Feature може його прив’язати та як може доставлятися матеріал заповнення.

Цей розділ стосується власних слотів Component. Слоти, які сокет оголошує для кожного з’єднання, натомість утворюють закритий набір — див. «Слоти, які заповнює кожне з’єднання» в розділі «Сокети топології».

Оголошення слота не закриває поверхню приєднання. Автор може приєднати Feature під іменем, якого не оголошує жоден слот, і таке приєднання є вільним приєднанням: цілком допустимим, просто не прив’язаним до оголошеного слота. Саме ця відкритість дає змогу одній сутності каталогу обслуговувати дві різні форми розгортання без форку каталогу:

  • Для кожного споживача. Кожен екземпляр заповнює слот власною Feature, тож кожен споживач отримує власні згенеровані облікові дані.
  • Спільно. Жоден екземпляр не заповнює слот; натомість одні облікові дані приєднуються один раз на ширшій області (підсистема або межа Release) і каскадно поширюються на кожен компонент у ній, тож кожен споживач заповнюється з цього одного оголошення. Що генерується, залежить від реалізації: за реалізації, яка генерує Secret, — один Secret на кожного споживача, кожен з тим самим матеріалом; за реалізації, яка спрямовує кожного споживача на вже наявний Secret, — жодного.

Автор обирає між ними тим, що приєднує. Сутність каталогу в обох випадках однакова.

Одна форма на цій відкритій поверхні зупиняє збирання: заповнення, записане на компоненті під іншим іменем. Коли приєднання, записане на самому компоненті — у його власному блоці features: в Aggregate або в записі Release для цього одного компонента, — має ім’я, якого не оголошує жоден слот, а його Feature задовольняє selector слота, який після згортання всіх областей на цьому компоненті ніщо не прив’язує, збирання зупиняється. Саме такої форми набуває заповнення, призначене для слота, коли його записано під неправильним іменем: без втручання воно було б вільним приєднанням, а слот лишався б порожнім, і необов’язковий порожній слот збирається успішно й нічого не доставляє. Повідомлення називає приєднання, компонент, Feature і кожен порожній слот, якому ця Feature відповідає, а виправлення полягає в тому, щоб приєднати її під іменем слота. Це стосується кожної Feature, а не лише облікових даних. Усе інше на поверхні лишається вільним: приєднання, Feature якого не відповідає жодному оголошеному слоту, додаткове приєднання після того, як кожен відповідний йому слот прив’язано, і приєднання, яке компонент успадковує від підсистеми чи межі Release, — тож описана вище спільна форма не зачіпається. Слот, що не оголошує selector, нічого не каже про те, для якої Feature він призначений, тож жодне приєднання не перевіряється щодо нього в такий спосіб. Цю зупинку описано в errors/fatal-halts.md під заголовком «An attachment written under another name fits a slot its component leaves empty (Приєднання, записане під іншим іменем, відповідає слоту, який його компонент лишає порожнім)».

Дві форми поєднуються, і ближча перемагає. Автор може зробити обидва водночас: приєднати Feature на ширшій області, щоб вона досягла кожного компонента в ній, і заповнити слот на тому одному компоненті, якому потрібне щось інше. Заповнення в області компонента перемагає — поле за полем, тож йому достатньо повторити лише змінювані поля, а решта й далі надходить із ширшого приєднання. Сусідні компоненти, які не заповнили слот, зберігають ширше приєднання без змін. Повне правило пріоритету, зокрема його взаємодію з приєднаннями на основі анотацій і зі складеними Aggregates, наведено в vocabulary/labels-and-annotations.md «Attachment precedence».

Визначення схеми в Component:

spec:
featuresSchema:
root_password:
inject: []
description: Root database password. Recipe controls delivery (Black-Box).
user_password:
inject: [env, file]
description: Application user password, auto-generated if omitted.
replication_password:
inject: []
description: Replication password for HA setups.

Семантика полів:

ПолеТипЗа замовчуваннямЗначення
requiredboolfalseОголошує, що слот зрештою має бути прив’язаний. Збирання зупиняється, коли ніщо не прив’язує ім’я слота на екземплярі цього Component; перевірка виконується щодо набору приєднань, який екземпляр має після всього каскаду приєднань, — тож приєднання, оголошене в області, від якої екземпляр успадковує, задовольняє слот так само, як заповнення, записане на самому екземплярі. Діагностика називає компонент і слот.
injectstring[]—Список дозволених механізмів доставки inject. [] (порожній) означає «чорну скриньку» — Recipe керує доставкою всередині, і матеріал ніколи не доставляється до робочого навантаження. [env, file] означає прозорість — матеріал заповнення може доставлятися переліченими механізмами. Та сама семантика, що й у usesSchema[].inject.
descriptionstring—Документація для людей, яку відображають IDE та хаб.
selectorstring—Необов’язковий селектор міток у стилі Kubernetes, що обмежує, яка Feature може заповнити цей слот, — аналог selector сокета usesSchema для слота, з тією самою граматикою й тим самим вбудованим механізмом зіставлення міток. Обчислюється щодо власних міток приєднаної Feature під час статичного аналізу; заповнення, мітки якого його не задовольняють, зупиняє збирання, як і селектор, який граматика відхиляє, — із зазначенням вимоги, яку не вдалося прочитати. Пропустіть, щоб не накладати обмежень на заповнення.
sensitiveboolfalseОголошує, що будь-що, що прив’язує цей слот, працює із секретним матеріалом. Це твердження про точку прив’язки, а не про конкретне заповнення; див. «Оголошення слота чутливим» нижче.

Слот обмежує, яке заповнення може його прив’язати, а не те, що заповнення налаштовує. Контракту values чи infra на рівні слота навмисно немає: цими стовпами володіє власна schema: приєднаної Feature, тож кожен контракт має рівно одне місце.

Через selector слота Component звужує, яка Feature може заповнити слот, — наприклад, до Feature облікових даних для конкретного провайдера (feature.aggrega.ai/kind=secret, provider=helm), — не називаючи FeatureRecipe, так само як селектор сокета usesSchema звужує ціль ребра залежності. Компілятор обчислює селектор щодо міток приєднаної Feature і нічого більше: він читає мітки, які має заповнення, і повідомляє, чи селектор їх допускає. Які мітки має сенс вимагати — це вибір автора каталогу, а не правило, яке накладає компілятор.

Помилки в іменах слотів виявляються як попередження, а не зупинка. Оскільки неоголошене ім’я приєднання допустиме, ім’я слота з помилкою стає вільним приєднанням, а не заповнює слот, який мав на увазі автор. Компілятор повідомляє про ім’я приєднання, що відрізняється від оголошеного імені слота на одну правку, попередженням, яке називає обидва написання, — див. errors/warnings.md «Attachment-slot near-miss lint». Попередження ніколи не змінює вердикт збирання; компілятор не контролює, як автор називає приєднання. Ім’я, що відрізняється на одну правку від слота, selector якого задовольняє Feature приєднання, попередження не викликає: якщо цей слот зрештою порожній, натомість про приєднання повідомляє описана вище зупинка, а якщо слот прив’язує щось інше, приєднання є звичайним додатковим.

Оголошення слота чутливим

sensitive: true на слоті виражає власну вимогу споживача: усе, що прив’язується до цієї точки, обробляє секретний матеріал.

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: "Optional database password credential."

Це справді інша інформація, ніж sensitive: true листка схеми, а не зручний дублікат, і каталогу стандартної бібліотеки потрібні обидва. Облікові дані, на які можна посилатися, публікують provides.name і provides.key — локатор ресурсу та ключ даних у ньому — і жоден із них не є чутливим: ім’я Kubernetes Secret публічне, так само як і ключ у ньому. Проте слот, який заповнюють ці облікові дані, безперечно обробляє секретний матеріал. Листок каже: ці дані є секретним матеріалом; слот каже: ця точка прив’язки обробляє секретний матеріал; ці два твердження стосуються різних речей і можуть бути істинними незалежно.

Практичний наслідок полягає в тому, що вимога супроводжує точку прив’язки, а не заповнення. Сутність Feature, яка взагалі не оголошує чутливого листка — бо обліковими даними володіє цільовий рушій, а автор нічого не пише, — усе одно прив’язується до чутливого слота як чутливе приєднання, бо так заявив слот. Справедливо й зворотне: заповнення, що оголошує чутливий листок, є чутливим приєднанням, навіть коли воно прив’язується до слота без такого оголошення або коли це вільне приєднання, не прив’язане до жодного слота.

Оголошення слідує за каскадом приєднань, а не за якимось одним написаним блоком. Вимога слота застосовується до того заповнення, яке виявиться прив’язаним після згортання всіх областей, тож заповнення на рівні компонента, яке витісняє ширше, успадковує вимогу без змін.

sensitive на слоті має ту саму межу, що й ключове слово на рівні листка, — воно анотує, але не шифрує, не валідує, не відхиляє, не нав’язує механізм доставки і не змінює жодного згенерованого байта. Повне формулювання — у vocabulary/compact-form-authoring.md, розділ «Чого ключове слово не робить».

sensitive і compliance.aggrega.ai/data-class — дві різні осі, задокументовані поруч і ніколи не змішувані. sensitive — це булеве значення на одному листку чи одному слоті: ці дані або ця точка прив’язки обробляють секретний матеріал. compliance.aggrega.ai/data-class — це градуйована мітка на цілому вузлі — public, internal, restricted, — що надає даним, які зберігає компонент, ідентичність у сенсі управління даними. Одна — для окремих даних і двійкова, інша — для вузла і впорядкована; жодна не замінює іншу, і сутність може мати обидві. Мітку описано в vocabulary/labels-and-annotations.md та architecture/08-credential-model.md, розділ «Управління даними навколо облікових даних».

Проєкція схеми з featuresSchema

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

Вхідний featuresSchema:

featuresSchema:
root_password:
inject: []
user_password:
inject: [env, file]

Спроєктований фрагмент (у пам’яті; компактне подання):

# The OUTER object is open: an attachment under a name no slot declares is
# admitted, because a free attachment is legal authoring.
root_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
# inject admits only an empty block — inject: [] means the Recipe controls
# delivery, so a fill may name no mechanism
inject: {}
user_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
inject:
env: { type: array }
file: { type: array }
# arg is absent — not in the inject allowlist

Дві глибини незалежні. Зовнішній об’єкт відкритий, тож оголошений слот ніколи не забороняє приєднань, яких сутність не перелічила. Власний фрагмент кожного оголошеного слота закритий, тож заповнення, яке таки прив’язується до оголошеного слота, все одно обмежене формою цього слота.

Фрагмент описує лише ФОРМУ. Він нічого не стверджує про те, які слоти мають бути прив’язані, бо слот із позначкою required може бути прив’язаний приєднанням, що каскадно надходить із ширшої області, — і тоді блок, який описує цей фрагмент, залишається порожнім. Тому вимога перевіряється за набором приєднань, який зрештою має компонент, а не за тим, що оголошує якийсь один блок, і ці два питання ніколи не суперечать одне одному, бо до написаного блоку ставиться лише одне з них.

Дозволені ключі віддзеркалюють ключі, які приєднання може мати будь-де, тож ключ, допустимий у вільному приєднанні, лишається допустимим і в заповненні слота. Кожен дозволений механізм доставки — це список записів доставки, тієї самої форми, яку inject: має всюди; слот обмежує, які НАЗВИ механізмів можуть з’являтися, а не те, як виглядає запис.

Де застосовується список дозволених inject

Список дозволених зв’язує обидва боки слота, на двох різних кроках.

Щодо сутності Workload у Recipe — на кроці рендерингу: Workload, що посилається на слот через записи приєднань свого контейнера, має назвати слот, який оголошує сутність, і вибрати механізм доставки, дозволений списком inject цього слота; посилання на слот типу blackbox (inject: []), на механізм поза списком дозволених або на слот, якого сутність ніколи не оголошувала, зупиняє збірку. Діагностика називає Recipe, шлях контейнера та проблемний слот і класифікується як помилка каталогу — помилився саме Recipe.

Щодо власного приєднання сутності Aggregate — коли розв’язуються її приєднання, ще до будь-якого рендерингу: блок inject: у заповненні, що прив’язується до оголошеного слота, може називати лише механізми, дозволені списком слота, а слот типу blackbox не дозволяє жодного — його порожній список каже «Recipe доставляє це внутрішньо; не диктуйте доставку», і опис доставки для нього зупиняє збірку. Діагностика прив’язана до приєднання й називає слот і проблемний механізм разом із механізмами, які слот дозволяє, якщо дозволяє хоч якісь; вона класифікується як помилка розробника, бо помилився саме Aggregate. Порожній блок inject: {} не називає жодного механізму, тож не диктує доставки й приймається в кожному слоті, зокрема й у слоті типу blackbox, — однаково на компоненті, який оголошує Aggregate, на компоненті, який вносить імпортований модуль, і на приєднанні, оголошеному в ширшій області. Вільне приєднання — під назвою, якої не оголошує жоден слот, — такого обмеження не має, бо список дозволених належить слоту, а не блоку.

Наскрізний потік через конвеєр компіляції — як приєднання в Aggregate з’єднується з сутністю Feature облікових даних (наприклад, core/secret-value), а потім із FeatureRecipe для конкретного провайдера, що доставляє облікові дані до запущеного робочого навантаження, — докладно розібрано в examples/05-credential-features.

Ключ, який пред’являє викликач, і ключ, який перевіряє сервер

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

  • Ключ, який пред’являє викликач, належить викликачу. Він розміщується у слоті, який сокет викликача оголошує для кожного з’єднання — див. «Слоти, які заповнює кожне з’єднання» вище, — тож викликач, що звертається до кількох цілей, тримає по одному ключу для кожної. Сокет model компонента core/ai-agent/crewai оголошує цей слот як credential, а його Recipes доставляють усе, що його заповнює, як OPENAI_API_KEY. Сокети models компонентів core/gateway/litellm, core/gateway/kong і core/gateway/apisix також його оголошують, а їхні Recipes доставляють ключ кожного з’єднання в окремій змінній, названій за псевдонімом з’єднання, тож кожна модель, яку обслуговує шлюз, має власний ключ. Натомість ключ, який сутність Component оголошує у власному слоті, — це один ключ для всіх її з’єднань.
  • Ключ, який перевіряє сервер, — це власний слот сервера. core/ai-model/vllm, core/ai-model/tei і core/ai-model/tgi кожен оголошує необов’язковий api_key, і кожен із їхніх Recipes доставляє все, що його заповнює, як змінну, з якої сервер читає свій ключ. Модель і шлюз LiteLLM оголошують api_key для ключа, який LiteLLM називає своїм головним ключем.
  • Жоден кінець не бачить прикріплень іншого. Прикріплення на з’єднанні — це одне з прикріплень викликача, і воно потрапляє лише до рендерингу викликача, а відрендерений вивід сервера однаковий, хоч би що несли з’єднання, які до нього ведуть. Слот, позначений required, має заповнити компонент, який його оголошує, а не компоненти, з’єднані з ним, і заповнення слота одного кінця нічого не заповнює на іншому — тож оголошення ключа на обох кінцях є мінімумом, а не дублюванням.
  • Обидва кінці читають один параметр, тож ключ, який пред’являє викликач, і ключ, який перевіряє сервер, неможливо записати по-різному.
# Aggregate fragment — one parameter feeds both ends
spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
agent:
type: core/ai-agent/crewai
# values (role, goal, backstory, …) elided
uses:
model:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

Сервер, що перевіряє один ключ, не може розрізнити своїх викликачів: vLLM, TEI і TGI кожен перевіряє єдиний ключ, тож кожен викликач пред’являє той самий ключ, хоч скільки з’єднань веде до сервера. Чи посилаються обидва кінці на один секрет, чи кожен тримає власний, залежить від того, де кожен провайдер розв’язує секрет за посиланням, а Manifest обирає реалізацію для кожного кінця — Модель облікових даних розбирає обидва випадки.

Облікові дані, які компонент тримає для себе — скажімо, ключ, яким він підписує власні сесії, — це слот його власного featuresSchema:, як і будь-який інший. Пароль, який він пред’являє сховищу даних, до якого звертається через один зі своїх сокетів, — це описаний вище ключ викликача, тож він розміщується на цьому з’єднанні як credential: його оголошує сокет backend компонента core/gateway/kong, і його Recipes синтезу робочого навантаження доставляють його як KONG_PG_PASSWORD, а сокет cache_store компонента core/gateway/litellm оголошує його для пароля, який семантичний кеш пред’являє сховищу, з доставкою як REDIS_PASSWORD. Коли одне з’єднання пред’являє пару — ідентифікатор ключа доступу та його секрет, — секретна половина є credential, а ідентифікатор — credential_id, як на сокеті store компонента core/ai-agent/agenta-api.

Самоін’єкція: spec.inject

Component може оголосити масив верхнього рівня spec.inject:, що задає дозволений перелік механізмів доставки для самоін’єкції. Якщо він присутній, розробники можуть використовувати блок inject: на рівні компонента в Aggregate, щоб ін’єктувати власні ключі values: або provides: сутності Component безпосередньо в її власний канал доставки (змінні середовища її контейнера, змонтовані файли або аргументи процесу). Якщо spec.inject: відсутній або порожній, самоін’єкцію на рівні компонента заборонено — Recipe керує всім внутрішнім зв’язуванням, що відповідає шаблону «чорної скриньки», який usesSchema[].inject: [] і featuresSchema[].inject: [] застосовують відповідно до міжкомпонентної доставки та доставки облікових даних.

# Component declares its self-inject allowlist:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/web-server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
inject: [env, file]
schema:
values:
log_level: { type: string, default: info }
tls_enabled: { type: boolean, default: false }
provides:
health_endpoint: { type: string }
# Aggregate fragment — developer dictates self-inject delivery:
components:
api:
type: core/web-server
values:
log_level: debug
tls_enabled: true
inject:
env:
- in: LOG_LEVEL
value: '{{"{{"}} .values.log_level }}'
- in: TLS_ENABLED
value: '{{"{{"}} .values.tls_enabled }}'
file:
- in: /etc/web/health-probe
from: health_endpoint

Кожен шаблон value: починається з {{"{{"}}, а не з {{. Увесь текст сутності Aggregate один раз читається як шаблон для інтерполяції параметрів, перш ніж виконується розв’язання самоін’єкції, і на той момент .values ще не існує; екранування повертає {{, щоб його обчислило розв’язання самоін’єкції. Див. Текст, що містить власні подвійні фігурні дужки.

Семантика поля. spec.inject: — це масив назв механізмів. Визначено три значення:

  • env — змінні середовища в контейнері.
  • file — шляхи змонтованих файлів.
  • arg — аргументи командного рядка процесу.

Семантика точно повторює usesSchema[].inject і featuresSchema[].inject — той самий словник, той самий шаблон «чорної скриньки», якщо поле пропущено, та сама форма запису на боці Aggregate. Відмінність — у джерелі: usesSchema[].inject визначає, як provides міжкомпонентної залежності потрапляє в канал доставки споживача; featuresSchema[].inject визначає, як облікові дані потрапляють у контейнер; spec.inject визначає, як власні values і provides сутності Component потрапляють у власний контейнер цієї сутності Component.

Дисципліна створення. Component core/web-server, що оголошує spec.inject: [env, file], обирає прозору доставку — автор Aggregate визначає, які назви змінних середовища несуть які значення. Component, що оголошує spec.inject: [] (або пропускає поле), зберігає доставку непрозорою — valuesMapping: сутності Recipe визначає, які поля потрапляють у які змінні контейнера, і розробник не може перевизначити це в Aggregate. Шаблон «чорної скриньки» підходить для стабільних контрактних Components (Component core/postgres-db, чий Recipe знає, як передати пароль БД у змінну середовища POSTGRES_PASSWORD); прозорий шаблон підходить для Components, де намір розробника обґрунтовано називає деталі доставки (core/web-server, застосунок якого читає LOG_LEVEL із нестандартної назви змінної, яку розробник хоче налаштувати).

Режими помилок. Aggregate розробника, що використовує блок inject: для Component, у якого spec.inject: відсутній або порожній, зупиняє збирання під час завантаження робочого простору («Self-inject on a component without an allowlist (Самоін’єкція в компоненті без дозволеного переліку)»). Блок inject:, що використовує механізм поза дозволеним переліком, зупиняє збирання за тієї ж умови, називаючи механізм і ті, які перелік дозволяє («Self-inject mechanism not in the component’s allowlist (Механізм самоін’єкції відсутній у дозволеному переліку компонента)»). Колізія ключів доставки між самоін’єкцією, міжкомпонентною ін’єкцією та ін’єкцією облікових даних також зупиняє збирання («Duplicate delivery key across inject sources (Дубльований ключ доставки в різних джерелах ін’єкції)»). Формат повідомлення для кожної помилки див. у errors/fatal-halts.md.

Створення каталогу: розширення базових Components

Архітектори платформи використовують ключове слово extends, щоб надбудовувати спеціалізовані інтерфейси над корпоративними або спільнотними базовими рівнями. Розширення компонує структуру і успадковує стовпи даних цілком. Компілятор обходить ланцюжок від бази донизу; дві половини поводяться по-різному, і ця різниця становить усю модель створення.

Що розширення компонує. Ці інструменти зливаються вздовж ланцюжка: для кожного ключа перемагає сутність Component, що розширює, а списки конкатенуються, починаючи з бази, без дублікатів:

ІнструментЯк компонується
metadata.labelsзливається за ключами; для спільного ключа перемагає значення сутності Component, що розширює
metadata.annotationsзливається за ключами з тим самим пріоритетом — саме тому вимога присутності бази поширюється на кожну сутність Component, що її розширює
spec.featuresSchemaоб’єднання слотів приєднання; слот, який сутність Component, що розширює, оголошує повторно, замінює запис бази з тією самою назвою
spec.usesSchemaоб’єднання топологічних сокетів, те саме правило заміни за назвою
spec.injectдва списки дозволених механізмів self-inject конкатенуються, спершу записи бази, дублікати відкидаються
spec.assertionsіменовані правила накопичуються, спершу правила бази — і лише цей інструмент не допускає заміни за назвою; див. «Успадкування тверджень є адитивним» нижче

Сокет, який додає сутність Component, що розширює, може мати власні valueSchema і infraSchema для кожного ребра; це контракти на ребрах цього сокета, а не доповнення до власних стовпів сутності Component.

Решта metadata: залишається в документі, що її оголошує. labels і annotations — єдині метадані, що передаються вниз ланцюжком. name, version, description, maintainers, license, repository, home і keywords належать самій сутності Component, що розширює, і читаються точно так, як вона їх записала: сутність Component, що пропускає description:, не має опису, а не запозичує опис бази. Ідентичність і походження належать документу, який ви читаєте, тож обгортку ніколи не сплутати з тим, що вона обгортає.

Що розширення успадковує цілком. Три стовпи даних — values, infra, provides — не компонуються. Сутність Component, що розширює, не містить вмісту стовпів: вона записує буквальний маркер schema: inherited і отримує блок schema: своєї бази точно в тому вигляді, у якому його записала база. У ланцюжку будь-якої глибини кожна сутність Component у ньому несе незмінний блок кореня ланцюжка, тож aggrega inspect --resolved для листка показує ті самі стовпи, що й для кореня.

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

  • extends: із вмістом стовпів у schema: відхиляється. Контракт сутності Component — це контракт її бази; другому, розбіжному контракту ніде існувати.
  • extends: із повністю пропущеним schema: відхиляється. Через пропуск читач не зміг би відрізнити успадкований блок стовпів від забутого.
  • schema: inherited без extends: відхиляється. Маркер указує, звідки беруться стовпи, а в цієї сутності Component немає бази, з якої їх узяти.

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

Спеціалізація посилюється через assertions:. Коли спеціалізація має допускати менше, ніж стовпи її бази, — вужчий числовий діапазон, підмножину успадкованого enum:, — вона вказує це у власному блоці assertions:: правило в ньому відхиляє значення, яке успадкована схема приймає. Саме тут відбувається посилення; див. «Блок assertions:» нижче.

Два останні абзаци — це одне правило, і кожна половина окремо вводить в оману: звуження набору ключів неможливе, посилення обмежень можливе. Якщо взяти лише першу, ви дійдете висновку, що спеціалізація нічого не може обмежити; якщо лише другу — що вона може змінити контракт. Жодне з цього не так: набір ключів фіксує база, а допустимі в ньому значення можна звузити предикатом.

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

Оскільки успадкування додає, а не замінює, сутність Component, що розширює, не може повторно використати назву успадкованого правила, щоб оголосити інше правило: це відхиляється під час розв’язання ланцюжка extends щодо каталогу з діагностикою, що називає обидві Components і спільну назву. Перевірці потрібна базова сутність Component, тож вона спрацьовує під час валідації каталогу або коли збірка розв’язує ланцюжок — валідація документа, що розширює, окремо цього не бачить. Назва правила — стабільний ідентифікатор, тож ні відкинути правило бази, ні непомітно перейменувати його не можна, і виправлення — перейменування в сутності Component, що розширює. Повторення успадкованого правила байт у байт під його власною назвою приймається як операція, що нічого не робить.

aggrega pull отримує базу. База є залежністю кожної сутності Release, що досягає сутності Component, яка її розширює, незалежно від того, чи називає її щось інше. aggrega pull проходить кожен extends: до кінця ланцюжка, отримує з реєстру базу, якої немає в жодній директорії каталогу, і записує кожну базу в lock-файл сутності Release з посиланням зі spec.extends сутності Component, що її називає; збірка читає базу звідти. Тож сутність Manifest зіставляє лише власний тип обгортки й нічого більше — базі потрібен власний рядок зіставлення лише там, де сутність Aggregate також оголошує екземпляр бази. aggrega validate для всього каталогу читає базу так само, тож база, опублікована в реєстрі, відхиляється там із зазначенням aggrega pull, доки pull її не отримає.

Формати вмісту схем див. у architecture/13-catalog-and-registry.md §3.

Приклад A: базова сутність Component (корпоративний базовий рівень) Архітектор платформи визначає базовий корпоративний сервер. Ця база задає обов’язкову мітку операційного хмарного примітива та встановлює обмеження безпеки в схемі. Оскільки блок стовпів успадковується незмінним, кожне обмеження тут доходить до кожної сутності Component, що розширює, точно в записаному вигляді.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/base-enterprise-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
inject: [env]
schema:
values:
# The corporate baseline constraint. Every Component extending this base
# receives this leaf verbatim; none of them can restate or loosen it.
tls_enabled: { type: boolean, enum: [true], default: true }
# An open range at the baseline. A specialization that needs a tighter
# bound expresses it as an assertion, not as a redeclared schema leaf.
timeout_ms: { type: integer, default: 5000 }
assertions:
# A baseline invariant. It is evaluated for instances of this Component AND
# for instances of every Component extending it, under this same name.
audit-window-is-observable: |
{{- if lt (int .values.timeout_ms) 100 -}}
{{- fail "the corporate baseline needs timeout_ms of at least 100 so requests are observable" -}}
{{- end -}}

Приклад B: сутність Component, що розширює (спеціалізація базового рівня) Шлюз спеціалізується з цього базового рівня. Він бере стовпи бази цілком, додає власну структуру — мітку, механізм self-inject, топологічний сокет зі слотом приєднання на ньому — і посилює успадкований тайм-аут через твердження. Він не повторює правило audit-window-is-observable базового рівня: це правило успадковується й обчислюється першим, тож екземпляр цього шлюзу має задовольняти обидві межі — щонайменше 100 і щонайбільше 2000.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/gateway/kong
version: 1.0.0
labels:
# Every Component declares the reserved base-ontology key, including one
# that extends: the envelope requires it on the document itself.
component.aggrega.ai/type: "server"
api.aggrega.ai/protocol: "http" # merged with the base's labels
spec:
extends: core/base-enterprise-server
schema: inherited # values, infra and provides are the base's, verbatim
inject: [file] # concatenates with the base's [env] -> [env, file]
usesSchema: # a socket of its own; the base declared none
backend:
required: true
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]
featuresSchema: # a slot each connection through it fills
credential:
sensitive: true
inject: [env]
description: Password the gateway presents to the configuration backend this connection reaches.
assertions:
# The tightening. The inherited schema admits any integer for timeout_ms;
# this gateway admits only 2000 or less, so the rule rejects a value the
# inherited pillar block would accept.
timeout-within-gateway-budget: |
{{- if gt (int .values.timeout_ms) 2000 -}}
{{- fail "the gateway must answer within 2000ms: set timeout_ms to 2000 or less" -}}
{{- end -}}

Сутність Recipe, що реалізує цей інтерфейс core/gateway/kong на основі фізичного Helm-чарта, див. у entities/recipe, приклад C (kong-gateway).

Блок assertions:

Component.spec.assertions: — необов’язкова мапа іменованих правил, що виражають архітектурні інваріанти контракту Component: міжпольові правила, яким має відповідати те, що записав розробник, незалежно від того, яка сутність Recipe прив’язується до сутності Component. Кожен ключ — ідентифікатор правила, що з’являється в повідомленні про помилку; кожне значення — тіло шаблону Go. Компілятор обчислює їх для кожного екземпляра після валідації схеми й до прив’язки Recipe, у порядку запису, і перше правило, що не виконується, зупиняє збірку з власним повідомленням про помилку цього правила згідно з контрактом Loud Guardrails.

spec:
assertions:
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt (int .values.secondary.replicaCount) 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}

Наведене вище правило — властивість контракту Component: хоч би яка сутність Recipe прив’язувалася (чарт Bitnami, власноруч написана альтернатива, майбутня реалізація), режим реплікації потребує щонайменше двох вторинних реплік.

assertions: — це місце, де сутність Component, що розширює, посилює обмеження. Сутність Component, що extends: базу, успадковує блок стовпів бази дослівно й не оголошує власного вмісту стовпів, тож спеціалізація, яка має допускати менше, ніж успадкована схема, формулює обмеження тут як предикат, а не як звужений листок схеми, — правило, що відхиляє значення, яке успадковані стовпи приймають. Робочу пару прикладів і повну поведінку успадкування наведено в розділі «Створення каталогу: розширення базових Components» вище: правила накопичуються вздовж ланцюжка від кореня, а повторне використання назви успадкованого правила для іншого правила відхиляється, а не замінює його.

Компілятор не перевіряє, чи можна задовольнити два правила одночасно. Правило — це шаблонний предикат, а не обмеження, про яке міркує компілятор, тож пара правил, яким жодне значення не може відповідати водночас, — база вимагає щонайменше 100, а спеціалізація щонайбільше 50, — не спричиняє попередження під час завантаження каталогу. Це виявляється звичайним чином: записується екземпляр, збірка зупиняється на тому з двох правил, що спрацює першим, і автор читає повідомлення цього правила. Не розраховуйте, що про суперечність повідомлять заздалегідь; перевіряйте посилення в спеціалізації щодо того, що вже вимагає її база.

Використовуйте assertions: для справжніх міжпольових правил. Обмеження окремих полів (діапазон, шаблон, enum) належать до ключових слів schema:; власні предикати окремих полів — до validate: компактної форми; умовна форма (чи застосовуються обмеження піддерева) — до when:. Повну граматику створення — поля контексту шаблону, домовленість щодо повідомлень {{ fail }}, фазу обчислення та робочі приклади для ролей Component і Recipe — див. у templates/assertions-block.md.