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

Архитектурные инварианты

Эти восемь инвариантов — основополагающие правила Aggrega. Они действуют во всех выпусках, в ядре компилятора, на уровне схем, в каталоге и на поверхности плагинов Wasm. Каждое проектное решение, каждая функция и каждая созданная сущность их соблюдают.

Другие главы архитектуры ссылаются на инварианты по номеру. Когда последующая глава говорит «согласно инварианту 2» или «по правилу String Pipe (инвариант 3)», она отсылает сюда.

1. Компилятор нейтрален к содержимому, без собственного мнения и агностичен по отношению к намерениям пользователя

Компилятор Aggrega — это текстовый маршрутизатор Ahead-Of-Time (AOT). Он разбирает YAML, обходит графы, вычисляет пересечения меток и передаёт строки от источников к приёмникам. Он не контролирует, что авторы помещают в values, parameters, infra, provides или locals. Он не навязывает соглашения об именовании, соглашения о портах или семантические метки, которые придумывает Architect.

Многие правила, которые звучат как правила компилятора, — контракт Zero-Port, стиль каталога Naked-Base / Flavored-Edges, выбор операционного примитива, подходящего для конкретного компонента, — являются общественными договорами: лучшими практиками с запасными выходами, которые поддерживают архитекторы платформы, создающие каталог стандартной библиотеки. Компилятор их не интерпретирует.

Этот инвариант касается того, что компилятор выводит из создаваемого вами содержимого, и эта область — всё, что он охватывает. Небольшое число ключей принадлежит самой Aggrega — они зарезервированы, а допустимые для них значения записаны в опубликованной схеме, — и схема проверяет их так же, как любое другое объявленное поле. component.aggrega.ai/type — один из них: его множество значений закрыто, и документ со значением вне его отклоняется при загрузке. Это платформа определяет, что означает её собственный ключ, а не компилятор вчитывает смысл в написанную вами строку, и каждый ваш собственный ключ остаётся ровно настолько неконтролируемым, как говорит этот инвариант. Каталог, классифицирующий компоненты по оси, которую Aggrega не определяет, создаёт собственный ключ метки, который схема принимает с любым строковым значением и который каждая поверхность селекторов читает одинаково.

То, что компилятор действительно обеспечивает, узко: валидация схем, разбор YAML, построение графа, вычисление шаблонов и простая текстовая маршрутизация контракта внедрения. Всё остальное — соглашение, применяемое при создании каталога или внутри необязательного сокета управления Wasm.

Предприятия, создающие собственные внутренние каталоги, явно вольны нарушать соглашения стандартной библиотеки. Компилятор принимает всё, что они напишут, при условии что это проходит валидацию схемы. Архитектура продвигает лучшие практики; она не строит тюрем.

2. Чистота AOT: у компилятора нет доступа к информации времени выполнения

Aggrega — компилятор Ahead-Of-Time. Во время компиляции:

  • Он не аутентифицируется в облачных API.
  • Он не получает актуальные IP-адреса, DNS-имена или URL-адреса, сгенерированные облаком.
  • Он не раскрывает секреты в открытый текст — секреты остаются указателями на метаданные во всём промежуточном представлении (Intermediate Representation).
  • Он не знает состояния целевых кластеров или сервисов во время выполнения.
  • Он не может получить данные, которых ещё не существует (конечные точки после подготовки ресурсов, динамически назначаемые порты, автоматически генерируемые имена ресурсов).

Всё, что зависит от состояния во время выполнения, выражается как детерминированная строка-указатель — стабильное DNS-имя, строка интерполяции Terraform, ссылка на ресурс CloudFormation, — которую предоставляет сущность Ops Recipe. Компилятор передаёт указатель дальше, не раскрывая его. Окончательные физические данные раскрывает среда выполнения (кластер, менеджер состояния IaC).

Это истинная инверсия управления (True Control Inversion): разработчики задают Injection Contract в сущности Aggregate, компилятор заранее связывает детерминированные указатели, а среда выполнения раскрывает окончательные физические данные. Требования, которым действительно нужно разрешение во время выполнения, относятся к конвейеру Wasm сущности Ops Recipe, а не к ядру компилятора.

3. String Pipe: компилятор не может выводить смысл

Компилятор не интерпретирует смысл передаваемых значений. Когда сущность Component A использует сущность Component B, компилятор берёт скаляр, который Recipe сущности Component B производит через provides, — строку, число или булево значение — и передаёт его в контекст Recipe сущности Component A, детерминированно преобразованным в строку на границе внедрения. Является ли это значение FQDN, локальным именем хоста, литералом IP, номером порта или DSN, отформатированным Wasm, не имеет значения: компилятор не проверяет маршрутизируемость, корректность протокола или семантическую уместность.

Отсюда следуют два вывода:

  • Компилятор не угадывает назначение компонента по имени. Компонент с именем database-production не распознаётся как база данных. Семантические метки типа, такие как component.aggrega.ai/type (если они есть), — это непрозрачные метаданные, используемые для сопоставления меток, а не логика ветвления компилятора.
  • Компилятор не отличает имя хоста от имени базы данных, номера порта или произвольного непрозрачного значения. Все они — скалярные записи в контексте внедрения, доставляемые как строки.

Триада топологии — provides в производящей сущности Recipe, uses в потребляющей сущности Aggregate, inject на ребре — это Injection Contract. Компилятор вычисляет метки и передаёт строки; интерпретация — это авторский договор между сущностями Recipe и Component.

4. Никакой призрачной инфраструктуры: компилятор никогда не выдумывает вычислительные ресурсы или функции

Компилятор никогда не внедряет молча вычислительные ресурсы, сущности Features, аннотации, маршрутизирующие прокси или любые другие ресурсы, которые автор явно не объявил. Нарушения политик порождают громкие ограничители (Loud Guardrails) — сборка останавливается с конкретной ошибкой, сообщающей автору, что исправить в написанном им документе, — а не молчаливые изменения, создающие инфраструктурные загадки при отладке.

Ресурсы попадают в граф через явные объявления во время создания:

  • Сущность Aggregate разработчика (компоненты, рёбра uses, подключения сущностей Feature).
  • Подключения сущностей Feature в сущности Release (добавления на уровне оператора).
  • Развёртывание на основе аннотаций (сущность Manifest объявляет привязки аннотация → Feature; аннотация на сущности Component или границе является явным объявлением).
  • Создание ресурсов на уровне сущности Recipe: рендеринг source сущности Recipe создаёт основной артефакт; синтез workload выдаёт специфичную для провайдера форму развёртывания (спецификация Pod, сервис Compose и т. д.); записи artifacts: (встроенные или загруженные через $import:) выдают вспомогательные манифесты, присущие сущности Recipe; генерация ресурсов сущности FeatureRecipe выдаёт вспомогательные ресурсы для каждой сущности Feature, запускаемые явным подключением сущности Feature.

Пути на уровне сущности Recipe — это объявления времени создания, отстоящие на один шаг: автор сущности Recipe пишет source / workload / artifacts / valuesMapping в соответствии с контрактом сущности Component, а сущность Aggregate разработчика выбирает, какие сущности Components участвуют. Ресурс, появляющийся в отрендеренном выводе, прослеживается либо до объявления в сущности Aggregate, в сущности Release или в привязке аннотации, либо до содержимого сущности Recipe, выбранного типами компонентов сущности Aggregate.

Синтез преобразует объявленные автором формы в специфичные для провайдера форматы вывода. Спецификация сущности Workload, написанная как карта контейнеров, может быть отрендерена как спецификация Pod Kubernetes, блок сервиса Compose или модуль Terraform — преобразование управляется провайдером, но ресурсы прослеживаются до объявления сущности Workload автора.

Сокет управления несёт роль для каждого подключения, и именно роль — а не вид плагина — определяет, что подключение может делать со сборкой. Плагин управления, подключённый в роли вердикта, — проверяющий граф IR (ir-verdict) или отрендеренные артефакты (render-verdict), — может отклонить сборку, но не может её изменить. Если такой вердикт хочет, чтобы был добавлен ресурс, он проваливает сборку с указанием на исправление, чтобы автор сам добавил ресурс; хост читает вывод вердикта только как принятие или отклонение и никогда не применяет его как изменение, поэтому непрошеное переписывание графа до состояния соответствия — именно та призрачная инфраструктура, которую запрещает этот инвариант, — не может исходить из роли вердикта. Плагин управления, подключённый в роли преобразования (label-transform или annotation-transform), — узкое, явное исключение: оператор, который его подключает, — по собственному выбору, через конфигурацию plugins.governance рабочего пространства, — объявил это преобразование, поэтому вносимые им изменения являются явным объявлением с тем же статусом, что и развёртывание на основе аннотаций, а не молчаливым внедрением. Различие — в приглашении: незапрошенный вердикт не может переписать сборку, а явно подключённое преобразование может, потому что оператор его запросил. Поскольку преобразование формирует отрендеренный вывод, оно закрепляется в файле блокировки, как и любой плагин, формирующий вывод, — применяемое преобразование фиксируется в момент pull, поэтому его изменение означает повторный pull, а не молчаливый сдвиг между сборками; вердикт не формирует никакого вывода и не закрепляется.

5. Сущность Aggregate — поверхность создания; сущность Release не может объявлять values:

Схема сущности Release механически запрещает блок values:. Операторы не могут из сущности Release записывать values в сущность Component или сущность Feature. Это обеспечение на уровне схемы JSON Schema — не общественный договор и не соглашение, — и оно громкое: каждый документ сущности при загрузке проверяется по схеме своего вида, поэтому сущность Release, содержащая values:, останавливает сборку с диагностикой, называющей файл и проблемный ключ, а не игнорируется молча.

Это не означает, что значения одинаковы во всех средах. Поддерживаемый путь для вариативности по средам — подъём параметров (Parameter Hoisting):

  1. Разработчик открывает в сущности Aggregate типизированное поле parameters.*.
  2. Шаблон values сущности Component ссылается на него: storage_size: "{{ .parameters.db_size }}".
  3. Сущность Release заполняет параметр: parameters: { db_size: "100Gi" }.
  4. Отрендеренный вывод отражает значение, специфичное для среды.

Сущность Aggregate остаётся единственным источником истины о том, какие значения открыты для вариативности по средам (объявление parameters) и как они попадают в значения компонента (ссылка в шаблоне). Сущность Release заполняет; она не переопределяет.

Тот же инвариант защищают ещё два ограничения:

  • Когда сущность Release использует extends, объявление указателя aggregate: запрещено схемой. Дочерняя сущность Release должна развёртывать то же намерение разработчика (Developer Intent), что и её родительская.
  • Сущность Release не может добавлять вычислительные ресурсы, которые не объявила сущность Aggregate, и не может перенаправлять ребро, объявленное разработчиком. В пределах сокетов, которые объявил Architect, сущность Release может соединять и настраивать рёбра между существующими компонентами: она задаёт infra для ребра на ребре, которое соединил разработчик, или соединяет с существующим компонентом ребро к объявленному, но не привязанному сокету. Она не может объявлять values для ребра (они остаются в сущности Aggregate), привязывать сокет, который не объявляет usesSchema сущности Component, или направлять ребро на несуществующий компонент — каждый из этих случаев останавливает сборку. Обратите внимание, какое объявление имеет в виду средняя часть предложения: сокет должен присутствовать в usesSchema каталожной сущности Component. Автор сущности Aggregate может назвать сокет, который не объявляет его тип компонента, а поверхность сущности Release намеренно не открыта так же — оператор соединяет и настраивает в рамках архитектуры, а не изобретает её.

Конфигурация соединения для ребра ограничена потребителем: values и infra, которые несёт ребро, появляются только в контексте рендеринга узла, создавшего ребро, и никогда — в контексте цели. Поэтому собственный отрендеренный вывод компонента инвариантен относительно соединений, которые устанавливают с ним другие компоненты, — соединение или настройка ребра к цели никогда не возмущает того, что рендерит сущность Recipe цели. Единственное место, где эти соединения видны, — сущность Feature, подключённая к цели: её сущность FeatureRecipe может прочитать, какие компоненты используют цель, поэтому выдаваемые ею ресурсы — скажем, политика, допускающая ровно объявленных вызывающих, — следуют за соединениями, тогда как собственный вывод цели — нет. Даже там values и infra для ребра остаются у потребителя.

6. Граница ABI WebAssembly: предметно-специфичный интеллект живёт в Wasm

Хостовый бинарный файл Go не содержит никакой логики, специфичной для облака или инфраструктуры. Весь предметно-специфичный интеллект, рендеринг шаблонов и форматирование живут строго внутри плагинов WebAssembly, выполняемых встроенной средой выполнения Wazero. Хост Go оркестрирует конвейер и передаёт полезные нагрузки через ABI гостям Wasm в виде указателей на память, в кодировке, которую несёт каждый сокет.

Отсюда следуют два следствия:

  • Логика, специфичная для сущности Provider (рендеринг, специфичный для Helm, форматирование, специфичное для Terraform, слияние, специфичное для Compose), никогда не живёт в ядре компилятора Go. Компилятор разрешает имя провайдера, которое сущность Recipe объявляет в spec.capability, в обслуживающую его сущность Plugin рендеринга провайдера и передаёт узел этому плагину; сам перевод целиком выполняется в госте Wasm. Хост не содержит кода Go для отдельных провайдеров в случае стандартного провайдера, поэтому в процессе нет ничего, к чему можно было бы откатиться, — имя провайдера, которое не разрешается ни в одну обслуживающую сущность Plugin, останавливает сборку вместо рендеринга какого-то встроенного значения по умолчанию.
  • Логика политик (правила безопасности, проверки соответствия, расчёты FinOps) никогда не живёт в ядре компилятора Go. Политики относятся к сокету управления Wasm, который предприятия подключают по собственному выбору, — плагину, подключённому в роли вердикта (ir-verdict / render-verdict), чтобы принять или отклонить сборку, или в роли преобразования (label-transform / annotation-transform), чтобы формировать метки или аннотации.

Граница ABI сохраняет ядро Go компактным, проверяемым и независимым от облака. Замена логики рендеринга провайдера — это замена артефакта Wasm, а не перекомпиляция самой Aggrega.

7. Разделение ответственности (деление на четыре домена) — ориентир, а не тюрьма

Проектные рекомендации Aggrega разделяют создание на четыре домена:

  • Developer Intent — Aggregate.
  • Platform Architect — каталожные сущности Component и Feature.
  • Platform Ops — Recipe, FeatureRecipe, Plugin (включая сущность Plugin рендеринга провайдера).
  • Platform Operator — Manifest, Release.

Типичное хорошо работающее развёртывание следует этому делению: разработчики пишут намерение приложения, а не физическую инфраструктуру; команда Ops пишет физическую инфраструктуру, а не логику приложения. Aggrega спроектирована для такого использования, а официальная документация, примеры и каталог стандартной библиотеки написаны в соответствии с этим делением.

Деление на четыре домена — это ориентир и проектная рамка, а не обеспечение компилятором. Компилятор (согласно инварианту 1) без собственного мнения. Пользователи вольны:

  • Объединять роли (один человек пишет и сущности Aggregates, и сущности Recipes).
  • Смешивать ответственность (Architects жёстко прописывают метки соответствия прямо в сущностях Components core/*, когда этого требуют корпоративные каталоги).
  • Пересекать границы доменов (разработчики используют подъём параметров, чтобы внедрять инфраструктурные аспекты в сущность Aggregate, когда этого требует унаследованный код).

Компилятор принимает любой шаблон создания, проходящий валидацию схемы. Архитектура продвигает лучшие практики; ограничения на уровне схемы (такие как запрет values: в сущности Release из инварианта 5) — единственные пересечения доменов, которые компилятор действительно отклоняет. Любое другое разделение — это общественный договор, который поддерживают авторы каталогов и, там где предприятия его подключают, сокет управления Wasm.

8. Детерминированный вывод

При идентичном вводе компилятор создаёт побайтово идентичный вывод. Две компиляции одних и тех же сущностей Aggregate + Release + Manifest с одним и тем же каталогом дают отрендеренные артефакты, совпадающие побайтово.

Это контракт, на который опираются инструменты GitOps и процессы ревью на основе diff. Pull request, не изменивший ввод, не должен порождать никакого diff в отрендеренном выводе. Pull request, изменивший ввод, должен показывать только diff, вытекающий из этого изменения, — без ложных перестановок, без колебаний временных меток, без артефактов итерации карт.

Детерминированный вывод обеспечивают три принципа:

  • Карты, упорядоченные автором: каждая карта, порядок итерации которой может повлиять на отрендеренный вывод, использует контейнер упорядоченной карты, так что итерация следует порядку объявления автора, а не порядку хешей.
  • Никакого содержимого, зависящего от часов или случайного, в отрендеренных артефактах, если автор явно не внедрил его через ввод шаблона.
  • Рендеринг чист: один и тот же вызов гостя Wasm с одним и тем же вводом даёт один и тот же вывод.

Флаг компилятора --trace (см. language-reference/cli/aggrega-build.md) даёт авторам и операторам поверхность проверки этого инварианта. Две компиляции одного и того же ввода с включённым --trace создают побайтово идентичные дампы трассировки; любой diff на отдельном проходе локализует регрессию. Детерминированность — не только свойство момента выпуска: её можно наблюдать в каждом промежуточном состоянии компилятора через раскладку трассировки по узлам.

Детерминированный вывод — это контракт, благодаря которому Aggrega безопасно использовать как источник истины в цикле GitOps.

Область инвариантности по уровням разрешения

Гарантия побайтово идентичного вывода распространяется на артефакты, закреплённые в файле блокировки, — сущности, разрешённые через артефакты реестра, дайджесты которых записывает файл блокировки (уровень реестра в трёхуровневой модели разрешения сущностей). Когда сборка читает файлы, которые сущность Release указывает по пути (локальные пути, начинающиеся с ./ или ../), или сущности в каталожных директориях рабочего пространства (catalog_dirs:, на уровне рабочего пространства и кеша), инвариантность зависит от того, останутся ли эти файлы неизменными между сборками. Файл блокировки записывает сущность из каталожной директории рабочего пространства по дайджесту её документа и объявленных ею файлов, поэтому сборка останавливается на сущности, изменившейся после pull, вместо того чтобы её рендерить, — с одним исключением: сущность Recipe или FeatureRecipe, которую сущность Manifest называет ссылкой, одновременно являющейся именем сущности Component или Feature, записывается под этой ссылкой как Component или Feature, поэтому её вводы удерживаются только закреплениями рядом с ней в файле блокировки, а правка её собственного документа не обнаруживается. Сохранять файлы такими, какими они были, — ответственность системы контроля версий (обычно Git).

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