Суспільні договори
Aggrega за задумом є компілятором без власної позиції. Згідно з основоположними інваріантами, задокументованими в architecture/05-invariants.md, компілятор розбирає YAML, обходить графи, обчислює перетини міток і передає рядки між компонентами, але не контролює, що розробники записують у values, parameters, infra, provides чи locals; він не забезпечує дотримання домовленостей щодо іменування, домовленостей щодо портів чи семантичних міток, які вигадує архітектор; він не вгадує призначення компонента з його назви. Багато дисциплін, що звучать як правила компілятора, насправді є суспільними договорами: найкращими практиками, яких дотримуються завдяки домовленості авторів, а не завдяки перевірці схемою чи під час виконання.
Варто прямо сказати, де закінчується ця нейтральність, бо це одна межа і її легко витлумачити ширше, ніж вона є. Кілька ключів належать самій Aggrega: вони зарезервовані, а допустимі для них значення записано в опублікованій схемі, і ці ключі схема перевіряє так само, як будь-яке інше оголошене поле. Оголошення набору значень для ключа, який визначає сама платформа, — це не компілятор, що вкладає зміст у написане вами; це платформа, що каже, що означає її власний ключ. Усе, що ви пишете під власним ключем, залишається так само неконтрольованим, як описано на цій сторінці.
Ця сторінка є канонічним переліком суспільних договорів мови. Автори, які вивчать договори з цієї сторінки, зможуть зрозуміти, чому компілятор приймає збірку, некоректну з погляду домовленості (він її приймає — компілятор не інтерпретує домовленість), і на кому лежить відповідальність за виявлення порушення (дисципліна авторів, увага рецензента або плагін лінтера, який запускає aggrega lint).
Три класи дисципліни
Дисципліни Aggrega поділяються на три класи за тим, як дисципліну забезпечено. Класифікація важлива, бо кожен клас має інший режим збою, коли дисципліну порушено.
Забезпечується схемою
Дисципліну забезпечує валідація JSON Schema 2020-12 під час завантаження (JSON Schema оболонки сутності, а також оголошення schema: на рівні стовпів у сутностях Component і Feature). Порушення спричиняє фатальну зупинку до того, як збирання просунеться далі; компілятор відмовляється продовжувати. Автори, які намагаються порушити дисципліну, що забезпечується схемою, бачать явну помилку валідації, що вказує на поле та обмеження.
Приклади: обов’язкові поля оболонки сутності (apiVersion / kind / metadata.name / metadata.version); регулярний вираз SemVer для metadata.version; закрита множина значень зарезервованої мітки component.aggrega.ai/type; механічна заборона блоків values: у схемі сутності Release (згідно з інваріантом 5); відхилення поєднання extends і aggregate у сутності Release (інваріант єдиного джерела істини); правила форми сутності Recipe, що забезпечують контракт композиції вхідних типів.
Дисципліни, що забезпечуються схемою, — найсильніші гарантії, які має мова. Компілятор відмовляється рендерити будь-що, що їх порушує.
Забезпечується плагіном політики
Дисципліну забезпечує Wasm-плагін, що працює в одній із задокументованих точок сокетів (роль керування label-transform під час побудови топології; роль керування ir-verdict під час статичного аналізу; позасмуговий сокет лінтера). Порушення спричиняє або збій політики, що зупиняє збирання (внутрішньосмугові сокети), або дорадче попередження (позасмугові сокети), залежно від семантики блокування сокета.
Дисципліна забезпечується в такий спосіб лише там, де працює плагін, що її перевіряє: середовище виконання Wasm викликає плагіни в задокументованих точках сокетів, а дисципліна, яку не перевіряє жоден плагін, залишається домовленістю. Лінтер публікації, який запускає aggrega lint, перевіряє частину однієї домовленості на цій сторінці — див. Домовленості, які перевіряє правило лінтера. Жодне правило лінтера публікації не перевіряє герметичність (Sprig FuncMap надає допоміжні функції, що порушують детермінованість виводу, згідно із застереженням щодо детермінованості в templates/sprig-functions.md) чи іменування хмарних ресурсів (сутності Recipes, чиї виходи valuesMapping: посилаються на поля імен хмарних ресурсів без інтерполяції release_name / instance_id, згідно з розділом «Cloud-resource naming discipline» у entities/recipe.md); власний плагін лінтера може перевіряти і те, і інше.
Про поверхню контракту Wasm-плагінів і критерій розміщення (сокет лінтера чи ролі вердикту керування) див. plugins/plugin-contract.md.
Підтримується домовленістю
Дисципліну підтримують лише дисципліна авторів і уважність рецензентів. Компілятор її не забезпечує; жодна схема не відхиляє порушення; жоден Wasm-плагін його не позначає. Автори дізнаються про дисципліну з документації, дотримуються її, бо від неї залежить архітектурна форма, і покладаються на рецензування PR, щоб виявляти недогляди. Порушення не дає жодного сигналу під час компіляції — збирання успішне, рендерений вивід працює, наскільки відомо компілятору, а порушення дисципліни виявляється лише тоді, коли від домовленості залежать подальші інструменти або поведінка під час виконання.
Дисципліни, що підтримуються домовленістю, — це ключовий перелік, який автори мають засвоїти з документації. Компілятор їх не інтерпретує; помилка в них не ламає збирання, але ламає архітектурну форму, від якої залежить Aggrega. Більша частина цієї сторінки документує саме їх.
Домовленості
Наведені нижче суспільні договори підтримуються домовленістю. Кожен запис називає дисципліну, місце, де задокументовано домовленість, і наслідки її порушення. Кожен запис зберігає свій номер, де б він не стояв: договір 3, дисципліну зарезервованих префіксів, перевіряє правило лінтера для ключів анотацій, і її описано в розділі Домовленості, які перевіряє правило лінтера.
1. Вибір операційного типу, що відповідає компоненту
Зарезервована мітка component.aggrega.ai/type визначає, чим є компонент, і бере значення із закритого набору універсальних хмарних примітивів: server, worker, task, function, stateful-server, resource. Належність до цього набору забезпечується схемою, а не підтримується домовленістю. Aggrega визначає цей ключ і допустимі для нього значення, схема Component перелічує їх, а документ із будь-яким іншим значенням відхиляється під час завантаження — E0215, умова entity-envelope-invalid, називає мітку й перелічує допустимі значення. Саме цього відхилення цей запис не стосується.
Домовленістю залишається те, яке зі значень відповідає вашому компоненту. Ніщо не перевіряє, що реляційна база даних має мітку stateful-server, а не server, або що споживач черги — worker, а не task; селектор обчислює будь-яке знайдене значення, не вкладаючи в нього сенсу. Архітектор, який створює Component, обирає значення, що описує, як інфраструктура має з ним поводитися, і подальші селектори, плагіни політик і Wasm-плагіни рендерингу покладаються на чесність цього вибору.
Класифікація за власною віссю. Закритий набір стосується лише цього одного зарезервованого ключа. Каталог, якому потрібна класифікація, якої Aggrega не визначає, — рівень, зона даних, клас сервісу чи дрібніший поділ операційних примітивів, — додає власний ключ мітки поруч із зарезервованим. Схема Component приймає будь-який додатковий ключ мітки з рядковим значенням, і той самий механізм селекторів його читає, тож acme.aggrega.ai/storage-tier: oltp стоїть поруч із component.aggrega.ai/type: stateful-server, а appliesTo сутності Feature чи selector сокета може націлюватися на будь-який із них. Розширення відбувається на власному ключі, ніколи — на значенні всередині ключа Aggrega.
Задокументовано в: architecture/02-ecosystem-philosophy.md (операційна онтологія) + labels-and-annotations.md (дисципліна префіксів) + errors/sentinels.md (E0215).
Наслідки порушення: значення з набору, яке не відповідає компоненту, вводить в оману все, що читає мітку. Сховище даних із міткою server відхиляється сутністю Feature або сокетом, що вибирає stateful-server, — зупинка вказує на селектор, а не на хибну мітку, — а плагін політики чи плагін рендерингу, що читає мітку, поводиться з ним як з обчисленням без стану. Там, де його бачать лише такі читачі, збірка успішна; помилка виявляється лише тоді, коли відрендерені артефакти потрапляють у кластер.
2. Розділення .context.annotations.* на три кошики
Каскадні анотації потрапляють у три іменовані кошики — .context.annotations.release, .context.annotations.catalog, .context.annotations.aggregate, — кожен із яких несе інший намір. Мета дисципліни: release — це «де працює цей компонент, під керуванням Ops»; catalog — «чим є цей компонент, визначено архітектором»; aggregate — «що робить цей компонент, визначено розробником».
Компілятор не забезпечує меж між кошиками. Усі три кошики мають однакову пласку форму string → string; шаблон Recipe може читати всі три, і ніщо не заважає інтерпретувати межову анотацію сутності Release як когнітивні метадані чи спрямувати анотацію каталогу в infra:. Розділення підтримують автори, які записують анотації у правильний кошик, і рецензенти, які виявляють витоки між кошиками.
Задокументовано в: labels-and-annotations.md (Розділення на три кошики — суспільний договір).
Наслідки порушення: логіка маршрутизації, що залежить від розрізнення намірів кошиків (наприклад, Recipe, що спрямовує .context.annotations.release.aggrega.ai/region у поле Terraform region), мовчки споживає будь-яку анотацію з кошика незалежно від наміру автора. Збірка успішна; відрендерений результат може містити семантично хибні значення.
4. Самодостатність provides: у Recipe
Шаблони provides: у Recipe замикаються лише на власних даних вузла — .values, .infra, .context.instance_id, .context.rendered_name (там, де провайдер вузла його повідомляє), розв’язаних .locals вузла, а також статичних рядках. Посилання на .context.inject і .context.uses заборонені, бо обчислення provides виконує ці шаблони в довільному порядку; читання даних інших вузлів прив’язало б його до топологічного порядку обходу, чого дизайн свідомо уникає. .locals входить до дозволеного набору: locals вузла розв’язуються в преамбулі того самого етапу, до його provides, і є локальними для вузла, тож їх читання нічого не коштує з погляду порядку. Звернення до ключа, якого блок locals не оголошує, зупиняє збірку.
Це правило з двох половин, і для кожної вказано, де її перевіряють. Першу перевіряє компілятор: обчислення provides перевіряє кожен шаблон за позитивним списком дозволених коренів, визначених його контекстом, ще до виконання шаблону, тож читання .context.inject / .context.uses зупиняється з явною помилкою, а не рендериться порожнім; правило також задокументовано в templates/expansion-matrix.md, рядок 6. Другу підтримує домовленість: ширший патерн (provides — публічне; locals — приватне) спирається на домовленість.
Задокументовано в: templates/expansion-matrix.md, рядок 6 + vocabulary/data-pillars.md «provides: і locals: — публічне обличчя проти приватного».
Наслідки порушення: компілятор виявляє заборонені посилання та зупиняє збірку під час обчислення шаблонів, коли вони трапляються безпосередньо в provides:. Ширша дисципліна публічного й приватного (не розкривати внутрішній стан через ключі provides:) тримається лише на домовленості — автори, які використовують provides: як внутрішній простір імен Recipe, створюють контракти, від яких залежать викликачі; рефакторинг стає несумісною зміною.
5. Детермінізм — негерметичні допоміжні функції в шаблонах шляху рендерингу
Інваріант детермінованого виводу Aggrega (Інваріант 8 в architecture/05-invariants.md) вимагає побайтово ідентичного виводу для побайтово ідентичного входу. Повний FuncMap Sprig надає допоміжні функції, що читають зовнішній стан (читачі системного годинника now / date; генератори випадкових значень randAlpha / uuidv4; читачі середовища env / expandenv; мережеві резолвери getHostByName). Автори, які викликають ці функції з шаблону, що впливає на рендерений вивід, порушують контракт детермінізму.
Компілятор не виявляє і не блокує використання негерметичних допоміжних функцій. FuncMap Sprig надає їх згідно з templates/sprig-functions.md «Застереження щодо детермінізму»; дисципліну підтримують автори, які уникають цих функцій у шаблонах шляху рендерингу, і рецензенти, які виявляють їх використання під час рецензування PR.
Задокументовано в: templates/sprig-functions.md «Застереження щодо детермінізму».
Наслідок порушення: вивід збірки відрізняється між запусками з тим самим входом. Розбіжність проявляється під час GitOps diff, коли подальші інструменти (ArgoCD, Flux) бачать неочікуваний дрейф між закоміченим маніфестом і станом кластера, або під час аудиту, коли дві компіляції того самого входу дають різні артефакти.
Жодне правило лінтера публікації не перевіряє шаблони на виклики негерметичних допоміжних функцій. Назву допоміжної функції записано в шаблоні, тож власний плагін лінтера може її знайти (див. Домовленості, які перевіряє правило лінтера).
6. Межі стовпів (вказівники, а не стіни)
Межі стовпів — це авторська дисципліна, а не обмеження мови. Шаблонний рушій дозволяє читання між стовпами в будь-якому місці, якщо це явно не заборонено правилами самодостатності (наприклад, читання .context.inject / .context.uses у provides: і source: сутності Recipe). Авторам слід:
- Читати
.valuesдля когнітивного вмісту (намір, визначений розробником). - Читати
.infraдля фізичного розміру (розміри, визначені Ops). - Читати
.context.uses.<alias>.provides.<key>для рядків-вказівників між компонентами. - Читати
.context.injectдля каналу доставки після гідратації.
Шаблонний рушій не обмежує читання. Шаблон Recipe, який читає .infra.replicas, щоб заповнити поле values:, працює; ніщо не перешкоджає маршруту між стовпами. Мета дисципліни — вказівники: межі описують авторський намір (хто володіє даними), а не обмеження під час виконання.
Задокументовано в: vocabulary/data-pillars.md «Межі стовпів і авторська дисципліна».
Наслідок порушення: витік між стовпами — когнітивний вміст розробника містить деталі фізичного розміру, або розміри, визначені Ops, містять когнітивні метадані. Збірка успішна; поділ авторства на чотири домени з часом розмивається, коли автори обходять стовпи; подальша підтримка ускладнюється, оскільки відповідність між стовпами й потоками даних слабшає.
7. Подвійне джерело в containers.<name>.variables сутності Workload
Мапа variables: поєднує два різні джерела даних через вирази шаблонів Go: літерали стовпа розробника (записи, що читають .values / .infra / .locals) і дані каналу між компонентами (записи, що читають .context.inject.env.<KEY>). Автори обирають одне джерело для кожного запису залежно від того, чи значення локальне для компонента, чи походить з іншого компонента.
Компілятор не розрізняє ці два джерела; обидва потрапляють до того самого списку Kubernetes env: у рендереному Deployment. Подвійне джерело існує лише на етапі авторства — дисципліна полягає в називанні наміру (цей запис локальний для компонента; той запис походить з іншого компонента), щоб майбутні супровідники могли бачити, які записи залежать від яких результатів гідратації inject.
Задокументовано в: entities/workload.md, «Field-semantics essentials» (variables).
Наслідок порушення: автори, які не розрізняють два джерела, втрачають слід «які записи пов’язані з provides: якої цілі». Рефакторинг ключів provides: цілі непомітно ламає кожен запис variables: викликача, що читав через канал inject.
8. Дисципліна іменування хмарних ресурсів
Recipes, що генерують імена хмарних ресурсів (імена бакетів S3, ідентифікатори баз даних RDS, імена ролей IAM, імена стеків CloudFormation — будь-яке поле, значення якого займає глобальний простір імен у хмарного провайдера), мають додавати {{ .metadata.release_name }} та/або {{ .context.instance_id }} до рендереного імені, щоб уникнути колізій, коли той самий Recipe виконується в кількох Releases або екземплярах компонента.
Компілятор не перевіряє виводи valuesMapping: на поля імен хмарних ресурсів без цих інтерполяцій. Дисципліну підтримують автори сутностей Recipe (які знають, які поля називають глобально унікальні ресурси цільового провайдера) і рецензенти (які виявляють шаблони з неіменованими ресурсами під час рецензування PR).
Задокументовано в: entities/recipe.md «Дисципліна іменування хмарних ресурсів».
Наслідок порушення: два Releases того самого Aggregate (prod-billing і staging-billing) намагаються розгорнути ресурс з однаковим глобальним іменем; друге розгортання завершується помилкою під час виконання через відмову з боку хмари. Збірка Aggrega успішна; збій розгортання проявляється лише під час застосування другого Release.
Жодне правило лінтера публікації не перевіряє поля імен хмарних ресурсів на наявність потрібних інтерполяцій; власний плагін лінтера може це робити (див. Домовленості, які перевіряє правило лінтера).
9. Гранулярність компонентів — один цілісний сервіс на Component
Component моделює один цілісний сервіс — один відкритий сервіс або робоче навантаження (навантаження) одного сервісу разом з його лише внутрішніми допоміжними навантаженнями. Коли чарт об’єднує сервіси, які інший компонент міг би змістовно use окремо — особливо стороння інфраструктура, як-от база даних, кеш чи брокер повідомлень, яку Aggrega вже моделює як окремий Component, — стандартна бібліотека компонує посервісні Components у модуль-підагрегат (spec.aggregates + exportedComponents), а не загортає весь продукт в один непрозорий Component. Дисципліна: кілька навантажень у межах одного Component — це нормально; незалежна придатність до використання — це межа, що розділяє один Component на стек.
Компілятор агностичний щодо цієї гранулярності. Він рендерить усе, що проходить валідацію схеми, — не перевіряє, скільки сервісів об’єднує Recipe компонента, і чи придатний якийсь із них до незалежного використання. Автор, який загортає продукт із п’яти сервісів в один Component, отримує Component, який компілятор приймає й рендерить без зауважень; домовленість підтримується авторською дисципліною та увагою рецензентів.
Задокументовано в: ../../architecture/06-data-taxonomy-and-composition.md (Один цілісний сервіс на Component — межа одного навантаження).
Наслідок порушення: монолітна обгортка кількох сервісів успішно збирається, але об’єднані сервіси невидимі для топології, селектора й політик — їх не можна незалежно масштабувати, замінювати чи робити залежностями. Подальший рефакторинг моноліту в посервісні Components стає критичною зміною для кожного споживача, що посилався на єдиний обгорнутий вузол.
Навіщо існують домовленості
Кожна з цих домовленостей за задумом є дисципліною авторингу, хоча будь-яку з них могла б забезпечити схема або політика Wasm. Обґрунтування за типом договору:
Розширюваність. Дисципліна зарезервованих префіксів (контракт 3) описує словник стандартної бібліотеки, а не всесвіт допустимих словників. Корпоративні каталоги створюють власні префікси та ключі міток, щоб розширити стандартну бібліотеку; примусове застосування домовленості про префікси через схему перетворило б «дисципліну стандартної бібліотеки» на «єдину дозволену мовою форму» — це та стіна, якої архітектура свідомо уникає. Вісь операційного типу (контракт 1) зберігає ту саму розширюваність на іншій поверхні: зарезервований ключ, який визначає Aggrega, має закритий набір значень, що перевіряється схемою, а каталог розширюється, додаючи поруч власний ключ мітки, а не значення всередині ключа Aggrega. Схема перевіряє набір значень одного ключа, яким вона володіє; відкритим залишається кожен інший ключ, і саме там живе власний словник каталогу.
Чистота AOT. Дисципліна іменування хмарних ресурсів (договір 8) і дисципліна детермінізму (договір 5) потребують аналізу вмісту шаблонів, щоб визначити, чи є поле іменем хмарного ресурсу або викликом негерметичного помічника. Чистота AOT (інваріант 2) не дає компілятору залежати від стану під час виконання; статичний аналіз шаблонів можливий (плагін лінтера читає шаблони сутності в тому вигляді, в якому їх написано), але його виконання всередині ядра компілятора пов’язує внутрішню логіку компілятора з предметно-специфічними питаннями авторингу. Архітектура виносить ці перевірки з компілятора у Wasm-плагіни згідно з інваріантом 6 (межа Wasm ABI).
Гнучкість авторингу. Дисципліна меж стовпів (контракт 6) і семантика подвійного джерела variables (контракт 7) описують шаблони авторингу, а не обмеження під час виконання. Той самий синтаксис шаблонів може виразити шаблон, що дотримується дисципліни, або такий, що її порушує; перетворення дисципліни на перевірку під час виконання вимагало б від компілятора інтерпретувати наміри автора, до яких він не має доступу. Архітектура розглядає домовленість як документацію, з якої вчаться автори, а не як інваріант часу виконання. Сюди ж належить гранулярність сутностей Component (контракт 9): підприємства можуть обгортати продукт із будь-якою гранулярністю, якій надає перевагу їхній каталог, а компілятор — нейтральний щодо вмісту і без власної позиції згідно з інваріантом 1 — ніяк не може знати, чи придатний вбудований робочий навантаження до незалежного використання, тож межа «один цілісний сервіс» залишається дисципліною авторингу, а не стіною схеми. Вибір операційного типу (контракт 1) має ту саму форму: схема визначає, які значення існують, але яке з них описує певний компонент — це судження моделювання про те, як інфраструктура має з ним поводитися, і ніщо в сутності Recipe чи в блоці values не підказує компілятору, чи було це судження правильним.
Забезпечення у двох половинах. Самодостатність provides: у сутності Recipe (договір 4) частково забезпечується компілятором — шлях рендерингу виявляє читання .context.inject / .context.uses у шаблонах provides: і зупиняється. Ширша дисципліна публічного й приватного (не розкривати внутрішній стан) спирається на домовленість, бо компілятор не може визначити без наміру автора, які рядки мають залишатися внутрішніми для Recipe.
Ці три шляхи важливі, бо кожен вказує, на кому лежить відповідальність за виявлення порушень. Забезпечується схемою: компілятор. Забезпечується плагіном політики: плагін, що її перевіряє, там, де він працює. Підтримується домовленістю: автори та рецензенти. Автори, які засвоїли ці шляхи, розуміють, які помилки виявить компілятор, а які непомітно пройдуть далі до інструментів нижчого рівня або до часу виконання.
Домовленості, які перевіряє правило лінтера
Лінтер публікації, який запускає aggrega lint, частково перевіряє одну домовленість на цій сторінці: ключі анотацій договору 3, описаного нижче. Його знахідка є рекомендаційною, а частина домовленості, якої він не сягає, підтримується домовленістю, як і записи вище.
Жодне правило лінтера публікації не перевіряє інших домовленостей на цій сторінці. Дві з них можна перевірити правилом лінтера, бо порушення записане в сутності: детермінізм (договір 5) — шаблон, що викликає негерметичну допоміжну функцію, — та іменування хмарних ресурсів (договір 8) — вихід valuesMapping:, що називає хмарний ресурс без інтерполяції release_name / instance_id. Так само можна перевірити ключі міток під зарезервованими префіксами (договір 3). Робочий простір може під’єднати власні плагіни лінтера в plugins.linter, поряд із лінтером публікації, щоб перевіряти будь-яку з них; The discipline rules перелічує правила, які має лінтер публікації.
Інші домовленості (1, 2, 4, 6, 7, 9) залежать від того, що мав на увазі автор, а жодне правило не прочитає цього з написаного. Розділення на кошики зумовлене розширюваністю (корпоративні каталоги перевизначають його) — забезпечення через схему суперечило б цій гнучкості. Те, що залишається від осі операційного типу після того, як схема визначає множину значень, — вибір примітиву, який пасує компоненту, — зумовлене авторським наміром: компілятор не може відрізнити вдало обраний операційний тип від невдало обраного, бо обидва є значеннями, які він приймає. Дисципліна меж стовпів і семантика variables з двома джерелами зумовлені авторським наміром — компілятор не може визначити намір лише із синтаксису шаблону. Самодостатність provides: у сутності Recipe частково забезпечується; ширша дисципліна публічного й приватного залежить від того, які ключі автор мав намір залишити внутрішніми, а в Recipe про це нічого не сказано. Гранулярність сутності Component так само зумовлена авторським наміром — чи можна окремо використовувати об’єднане робоче навантаження, є судженням моделювання, яке компілятор не може прочитати з вмісту Recipe.
3. Дисципліна зарезервованих префіксів
Ключі анотацій і міток мають форму <namespace>/<name>. П’ять зарезервованих префіксів мають особливі правила створення: aggrega.ai/ (лише для платформи), feature.aggrega.ai/ (офіційні скорочення Feature), component.aggrega.ai/ (властиві Component риси), aggregate.aggrega.ai/ (ідентичність модуля Aggregate) і <any-other-domain>/ (підприємство / спільнота).
Компілятор не відхиляє анотацію, записану під зарезервованим префіксом у сутності каталогу чи в Release; збірку зупиняє лише прив’язка анотації в Manifest або вихідна мітка Recipe, що претендує на ключ під aggrega.ai/. Підприємство, яке оголошує aggrega.ai/internal-billing-tag: "..." поза словником платформи, створює анотацію, яку компілятор приймає й каскадно передає через систему кошиків; подальші оновлення платформи, що вводять справжній aggrega.ai/internal-billing-tag, мовчки з нею конфліктують.
Задокументовано в: labels-and-annotations.md (Дисципліна префіксів) + providers/well-known-annotations.md.
Наслідки порушення: власні анотації під зарезервованими префіксами конфліктують із майбутніми анотаціями платформи з тією самою назвою; очікувана поведінка платформи мовчки перезаписує значення підприємства або співіснує з ним залежно від порядку.
Лінтер публікації, який запускає aggrega lint, позначає як рекомендаційну знахідку (E0277) ключ анотації сутності каталогу під aggrega.ai/, що не є однією з відомих анотацій платформи, а також ключ під feature.aggrega.ai/ у сутності, відмінній від Feature. Ключі міток, інші зарезервовані префікси та анотації поза metadata.annotations сутності — наприклад, ті, що записує Release, — не перевіряються, тож для них дисципліна залишається домовленістю.
Перехресні посилання
architecture/05-invariants.md— вісім засадничих інваріантів, на яких ґрунтується положення Aggrega «компілятор нейтральний щодо вмісту»; кожна домовленість перебуває в напрузі з одним або кількома з них.architecture/02-ecosystem-philosophy.md— повне обґрунтування дизайну операційної онтології.vocabulary/labels-and-annotations.md— розділення на три групи як суспільний договір; дисципліна зарезервованих префіксів.vocabulary/data-pillars.md— межі стовпів як орієнтири; поділ на публічне й приватне дляprovides:іlocals:.templates/sprig-functions.md— застереження щодо детермінізму з переліком негерметичних допоміжних функцій.entities/recipe.md— дисципліна іменування хмарних ресурсів і розібрані приклади.entities/workload.md— семантика подвійного джерелаvariables:у сутності Workload.templates/expansion-matrix.md— самодостатністьprovides:у сутності Recipe як правило, яке забезпечує компілятор.plugins/plugin-contract.md— критерій розміщення в сокеті лінтера.cli/aggrega-lint.md— правила лінтера публікації та під’єднання власних лінтерів.