Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Общественные договоры

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 предоставляет их согласно разделу «Determinism caveat» в templates/sprig-functions.md; эта дисциплина поддерживается авторами, которые не используют такие хелперы в шаблонах пути рендеринга, и рецензентами, выявляющими их использование при ревью PR.

Где описано: templates/sprig-functions.md, «Determinism caveat».

Последствия нарушения: вывод сборки различается между запусками на одном и том же вводе. Расхождение проявляется при сравнении в GitOps, когда инструменты ниже по цепочке (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, «Pillar boundaries and authoring discipline».

Последствия нарушения: утечка между столпами — когнитивная нагрузка разработчика содержит детали физического сайзинга, или сайзинг, заданный 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, «Cloud-resource naming discipline».

Последствия нарушения: две Releases одного и того же Aggregate (prod-billing и staging-billing) пытаются развернуть ресурс с одинаковым глобальным именем; второе развёртывание завершается ошибкой во время выполнения из-за отказа на стороне облака. Сборка Aggrega проходит успешно; сбой развёртывания проявляется только при применении второй сущности Release.

Ни одно правило линтера публикации не проверяет поля имён облачных ресурсов на наличие обязательных интерполяций; собственный плагин линтера может это делать (см. Соглашения, которые проверяет правило линтера).

9. Гранулярность Component — один целостный сервис на Component

Component моделирует один целостный сервис — один публикуемый сервис либо рабочую нагрузку (нагрузки) одного сервиса вместе с его внутренними вспомогательными нагрузками. Когда чарт объединяет сервисы, которые другой компонент мог бы осмысленно использовать (use) по отдельности, — особенно стороннюю инфраструктуру, такую как база данных, кэш или брокер сообщений, которую Aggrega уже моделирует как отдельный Component, — стандартная библиотека собирает Components для каждого сервиса в модуль-подагрегат (spec.aggregates + exportedComponents), а не оборачивает весь продукт в один непрозрачный Component. Дисциплина: несколько рабочих нагрузок внутри Component допустимы; независимая используемость — это граница, по которой один Component разделяется на стек.

Компилятор агностичен по отношению к этой гранулярности. Он рендерит всё, что проходит валидацию схемы, — он не проверяет, сколько сервисов объединяет Recipe сущности Component и можно ли использовать какой-либо из них независимо. Автор, обернувший продукт из пяти сервисов в один 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 — правила линтера публикации и подключение собственных линтеров.