Catálogo e registro
Este capítulo define como a plataforma escala por toda a empresa por meio do Catálogo OCI (Open Container Initiative): como o catálogo é organizado, como uma referência é resolvida, como uma entidade é publicada e fixada, e as formas de nome que as entidades do catálogo seguem.
O catálogo do Aggrega: taxonomia e resolução do registro
O compilador do Aggrega se baseia em um registro estritamente tipado e inspirado no OAM para resolver a intenção abstrata do desenvolvedor (Domínio 1) em uma realidade concreta de Ops (Domínio 3). Para dar suporte a um ecossistema aberto e distribuído mantendo uma experiência de desenvolvimento fluida, todos os schemas, vínculos de infraestrutura, políticas programáveis e plugins adaptadores seguem uma taxonomia de URI padronizada da Open Container Initiative (OCI). Como toda entidade do catálogo é endereçável por URI, aggrega pull busca para o cache as que uma Release precisa e as fixa em seu lockfile, e um build as lê de lá. O workspace local do desenvolvedor contém apenas seus arquivos Aggregate e Release, não uma cópia do catálogo.
1. Estrutura de diretórios principal (o catálogo)
A pasta aggrega-catalog da biblioteca padrão (e qualquer catálogo de terceiros em conformidade) é organizada para impor fisicamente a separação de responsabilidades. A estrutura separa explicitamente as interfaces abstratas de suas implementações concretas de infraestrutura.
Para Components e Features, os segmentos de URI correspondem 1:1 aos segmentos de caminho do sistema de arquivos. Os Components usam um URI de três segmentos ({publisher}/{category}/{name}) em que o segmento de categoria carrega uma de um conjunto fechado de categorias cognitivas — a mesma palavra do rótulo component.aggrega.ai/category do componente (o espelho 1:1 do diretório, verificado pela regra category-matches-directory do linter de publicação). As Features continuam planas ({publisher}/{name}) — um conjunto pequeno, que cresce devagar. A classificação ontológica operacional (stateful-server, server etc.) fica no rótulo component.aggrega.ai/type, nunca na estrutura de diretórios; os rótulos de capacidade cognitiva (datastore.aggrega.ai/engine, agent.aggrega.ai/autonomy, …) sobrepõem subconjuntos comportamentais. A interface web do hub usa rótulos para filtragem e busca; as categorias servem tanto à navegação no sistema de arquivos quanto ao eixo de navegação do catálogo.
A árvore abaixo é ilustrativa em seu conteúdo e exata em sua forma. Onde uma entidade é desenhada por inteiro, ela desce até seu arquivo folha, de modo que um caminho real completo pode ser lido no diagrama: qual nível de diretório carrega qual segmento de URI, onde fica o segmento de versão obrigatório e qual nome de arquivo cada tipo de entidade usa na folha. Ela mostra um punhado de entradas por nível em vez de todo o conteúdo do catálogo — ... marca uma elisão, e os nomes escritos ao lado de uma são outras entradas desse mesmo nível.
aggrega-catalog/│├── schemalibrary/ # TIER 3: Reusable JSON Schema 2020-12 definitions│ │ # Shared shapes (BaseComponentParameter,│ │ # BaseDatastoreParameter) consumed from a Component or│ │ # Feature schema via $ref: <Library>#/schemas/<name>│ │ # Path: {name}/{version}/library.yaml│ ││ ├── ai-datastores/│ │ └── 1.0.0/│ │ └── library.yaml│ └── base-components/│ └── 1.0.0/│ └── library.yaml│├── workloadlibrary/ # TIER 3: Reusable Workload template fragments│ │ # Shared bodies (StatelessService) consumed from a│ │ # Recipe via workload: { $import: <Library>#/workloads/<name> }│ │ # Path: {name}/{version}/library.yaml│ ││ └── base-workloads/│ └── 1.0.0/│ └── library.yaml│├── component/ # DOMAIN 2: Abstract Interfaces│ │ # URI: {publisher}/{category}/{name}│ │ # Path: {publisher}/{category}/{name}/{version}/component.yaml│ │ # type: core/datastore/mariadb:1.0.0│ │ # → component/core/datastore/mariadb/1.0.0/component.yaml│ ││ ├── core/ # "core" = official Aggrega standard library│ │ ├── ai-agent/ # AI agent frameworks, platforms, patterns│ │ │ └── ... # anthropic, crewai, langflow, pydantic-ai, …│ │ ├── ai-model/ # model providers and inference runtimes│ │ │ └── ... # ai21, anthropic, azure-openai, openai, …│ │ ├── ai-tool/ # tools agents invoke│ │ │ └── ... # browser, mcp, search, …│ │ ├── ai-pipeline/ # AI data/processing pipelines│ │ │ └── ... # argo-workflows, temporal│ │ ├── datastore/ # persistent datastores│ │ │ ├── mariadb/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ ├── postgres/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ └── ... # etcd, ferretdb, qdrant, redis, valkey, …│ │ ├── gateway/ # API and AI gateways│ │ │ └── ... # apisix, contour, kong, nginx, …│ │ ├── compute/ # generic compute primitives│ │ │ └── ... # function, keda, server, task, worker, …│ │ ├── messaging/ # event buses, queues│ │ │ └── ... # kafka, nats, rabbitmq, …│ │ ├── observability/ # metrics, logs, traces│ │ │ └── ... # grafana, loki, otel-collector, prometheus, tempo, …│ │ ├── security/ # identity, secrets, certificates│ │ │ └── ... # cert-manager, external-secrets, keycloak, …│ │ ├── devtool/ # developer-facing tooling│ │ │ └── ... # adminer, promptlayer, …│ │ └── storage/ # object/file storage, and the backup controllers│ │ │ # that copy a cluster's resources, or its│ │ │ # volumes' files, into a bucket│ │ ├── s3-object-store/│ │ │ └── 1.0.0/│ │ │ └── component.yaml│ │ └── ... # barman-cloud-plugin, gcs, k8up, velero, …│ └── example/ # a second publisher, same three-segment shape│ └── compute/│ └── greeter/│ └── 1.0.0/│ └── component.yaml│├── feature/ # DOMAIN 2: Abstract Interfaces│ │ # Flat: {publisher}/{name} (no category segment)│ │ # Path: {publisher}/{name}/{version}/feature.yaml│ │ # type: core/data-masking:1.0.0│ │ # → feature/core/data-masking/1.0.0/feature.yaml│ ││ ├── core/│ │ ├── data-masking/│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ ├── secret-value/ # feature.aggrega.ai/kind: secret│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ └── ... # k8s-dns-resolver, public-ingress, retry-policy, …│ └── ... # other publishers, same flat shape│├── aggregate/ # DOMAIN 1: Reusable Aggregate Modules│ │ # Path: {publisher}/{name}/{version}/aggregate.yaml│ └── core/│ ├── keycloak/│ │ └── 1.0.0/│ │ └── aggregate.yaml│ └── ... # agenta, apisix, dify, harbor, kong, thanos, …│├── recipe/ # DOMAIN 3: Concrete Implementations│ │ # Organized by CAPABILITY (the one a Recipe declares│ │ # in spec.capability).│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ │ # The version directory may bundle the Recipe's own│ │ # source charts or modules beside recipe.yaml.│ │ # OCI: hub.aggrega.ai/recipe/helm/mariadb:1.0.0│ ││ ├── helm/│ │ ├── mariadb/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── postgres/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── compose/│ │ └── mariadb/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── terraform/│ │ └── mariadb-rds-module/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── module/ # bundled Terraform source│ │ ├── main.tf│ │ └── variables.tf│ └── cloudformation/│ └── postgres-rds/│ └── 1.0.0/│ └── recipe.yaml│├── feature-recipe/ # DOMAIN 3: Concrete Implementations│ │ # Capability leads the path, same as recipes.│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ ││ ├── helm/│ │ ├── k8s-secret-from-parameter/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── public-ingress/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── chart/ # bundled Helm source│ │ ├── Chart.yaml│ │ └── templates/│ │ └── ingress.yaml│ ├── compose/│ │ └── dotenv-secret/│ │ └── 1.0.0/│ │ └── recipe.yaml│ └── ... # terraform, cloudformation│└── plugin/ # ARTIFACTS: Plugin entities, each a content-addressed │ # reference to a Wasm artifact. The compiled artifact │ # is published separately and is not stored here. │ # Path: {pluginType}/{name}/{version}/plugin.yaml │ ├── linter/ │ └── publishing/ │ └── 0.5.0/ │ └── plugin.yaml └── provider/ # the directory mirrors metadata.pluginType ├── helm/ │ └── 0.5.0/ │ └── plugin.yaml └── ... # cloudformation, compose, helm-chart, terraformAs categorias de componentes são um conjunto fechado, e é esse conjunto — não o sistema de arquivos — a autoridade sobre as categorias. Um valor de categoria que ainda não tem nenhuma entidade é vocabulário reservado: o eixo de navegação permanece estável e um autor sabe onde um componente futuro vai parar, então uma prateleira vazia é correta, e não uma vaga à espera de um ocupante. Como o catálogo não contém arquivos de espaço reservado, o diretório de um valor assim é criado quando sua primeira entidade chega.
A lista oficial — cada categoria, o que ela contém, os valores operacionais de type que suas entidades costumam carregar e quais diretórios existem — é a seção Categorias de Component do guia de convenções do catálogo, publicado junto com o catálogo da biblioteca padrão que ele rege.
O eixo type carrega apenas as primitivas operacionais — o vocabulário cognitivo nunca aparece nele, e o schema publicado do Component enumera os valores que a chave reservada aceita, de modo que uma palavra cognitiva escrita ali é recusada quando o documento é carregado. A divisão em três eixos: type operacional (como a infraestrutura trata o componente), category cognitiva (o que ele é, espelhada pelo diretório) e rótulos de capacidade por função (subconjuntos comportamentais — uma entidade é category: datastore mais o valor de datastore.aggrega.ai/engine que sua própria identidade de produto carregar, de modo que core/datastore/qdrant carrega vector e core/datastore/redis carrega kv, e ambos os eixos são consultáveis). Uma capacidade cuja veracidade depende do que um autor configura não é carregada no catálogo: ela é injetada em tempo de compilação pela função label-transform do socket de governança, que lê os values declarados pelo desenvolvedor. Categorias puramente de IA carregam o prefixo ai-; categorias de uso duplo aparecem sem prefixo, com o caráter de IA expresso por rótulos de capacidade. As categorias são escolhidas pela forma como os usuários navegam e exploram, não pela forma como o compilador classifica — o vocabulário de categorias e os rótulos de capacidade são termos com os quais o compilador compara seletores e aos quais não atribui nenhum significado. O nome de um componente não repete sua categoria: o modelo da OpenAI da biblioteca padrão é core/ai-model/openai, não core/ai-model/openai-model.
2. O esquema dividido e o pipeline de síntese da bridge
Para eliminar o código repetitivo por Component em torno das declarações de sockets de topologia, o Aggrega divide a validação em duas partes e controla cada uma onde reside o seu objeto:
usesSchema(YAML declarativo). Declara os sockets de topologia que uma entidade do catálogo oferece e atribui a cada um deles um contrato. A CLI em Go o lê nativamente para extrair as stringsselector:usadas na correspondência de labels durante a análise estática e para validar os mecanismosinjectpermitidos. Cada entrada de socket aceita um campo opcionalrequired: true(padrãofalse) — quando definido, o compilador emite um erro de validação se nenhuma dependência for declarada nesse socket. É a contraparte para sockets da semântica derequired: truenas entradas defeaturesSchema: ambas interrompem o build. Declarar um socket aqui é o que o catálogo da biblioteca padrão faz e continua sendo o melhor caminho — mas não é a única forma de um desenvolvedor traçar uma aresta. O autor de um Aggregate pode nomear em seu próprio componente um socket que esteusesSchemanão declara, inclusive em uma entidade que não declara nenhumusesSchema; um socket ad hoc desse tipo não traz seletor, nem lista de permissõesinject, nem esquema por aresta, justamente porque não há aqui nenhuma entrada para trazê-los. Osusesde um acoplamento de Feature e osusespor aresta de uma Release não são abertos dessa forma — ambos só podem nomear um socket declarado. Consulte dependency-resolution §“Domínio 2: o esquema dividido” para o contrato completo e para aquilo de que um socket ad hoc abre mão.- Desaçucaramento. Se os desenvolvedores usarem a forma abreviada de array YAML (
uses: databases: ["db1"]), a CLI a normaliza em um mapa ({"db1": {"target": "db1"}}). - Síntese da bridge. O compilador projeta a tabela de slots
featuresSchema:em um fragmento JSON Schema 2020-12 — uma propriedade por slot de acoplamento, descrevendo a forma de um preenchimento que pode vinculá-lo, com uma palavra-chave de extensãox-aggrega-inject:em um slot que declara uma lista de permissõesinject. A validação JSON Schema ignora palavras-chave de extensão durante a validação estrutural, e nada lê nenhuma delas de volta a partir do fragmento: uma verificação que precise da lista de permissões de um slot lê o próprio slot. A tabela de socketsusesSchema:não é projetada em nenhum fragmento. Oselector:e oinject:de um socket permanecem no YAML tipado que o arquiteto escreveu e são lidos de lá, e ovalueSchema:/infraSchema:por aresta de um socket é encapsulado e compilado separadamente, sem nenhuma restrição inventada ao seu redor. - Composição. O arquiteto de plataforma escreve uma declaração
schema:estrita (forma compacta ou JSON Schema 2020-12 completo) que definevalues,infraeprovides. Essa declaração é o contrato próprio da entidade e é compilada separadamente: nem o fragmento de slots nem a tabela de sockets são incorporados a ela. Cada superfície é verificada onde reside o seu objeto, de modo que uma falha de socket é relatada na entrada de socket que o arquiteto escreveu, e não em um caminho dentro do blocoschema:— e o arquiteto continua sem escrever nenhum código repetitivo deuses.
Exemplo — uma declaração de socket e o que o compilador faz com ela: O YAML do arquiteto de plataforma
spec: usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: ["env", "file", "ssm_param"] # env and file are core mechanisms; ssm_param is a user-provided mechanism
schema: values: ha_mode: { type: boolean, default: false } infra: replicas: { type: integer, min: 1 } provides: host: { type: string, required: true }
assertions: # The Architect can write cross-pillar invariants against the unified instance content. ha-mode-needs-two-databases: | {{- if eq .values.ha_mode true -}} {{- if lt (len .uses.databases) 2 -}} {{- fail "ha_mode=true requires at least two database attachments" -}} {{- end -}} {{- end -}}O que o compilador faz com ela A tabela de sockets é lida como o YAML tipado que ela é: a string selector: vai para o mecanismo nativo de correspondência de labels, e a lista inject: restringe quais mecanismos de entrega uma aresta que passe por esse socket pode nomear. O bloco schema: é compilado separadamente, como o contrato values / infra / provides próprio da entidade. O analisador estático lê a string selector: da entrada de socket que o arquiteto escreveu — junto com appliesTo / appliesToAnyOf das entidades Feature — e avalia a correspondência de labels em relação aos metadata.labels de cada destino para validar a segurança de tipos entre nós.
Seletores no estilo Kubernetes em usesSchema
O mecanismo nativo de correspondência de labels do compilador Go avalia strings de seletor usando a semântica de seleção padrão no estilo Kubernetes (AND por vírgula, OR por in(), NOT por !=/notin()). Esse mesmo mecanismo — e a mesma gramática de strings de seletor — também avalia os seletores de acoplamento de Feature (appliesTo e cada item de appliesToAnyOf). A camada de seletores é estritamente o portão da topologia — as declarações schema: por pilar validam o conteúdo de values, infra e provides de forma independente. Depois que o compilador Go traça as arestas topológicas na construção da topologia, o analisador estático lê as strings selector das entradas de socket que o arquiteto escreveu e as avalia em relação às labels de catálogo do nó de destino para validar a segurança de tipos entre nós.
usesSchema: # 1. The AND Operator (Comma) databases: selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
# 2. The OR Operator (Set-based 'in') datastores: selector: "datastore.aggrega.ai/engine in (relational, vector)"
# 3. The NOT Operator internal_systems: selector: "compliance.aggrega.ai/data-class!=public"Um seletor que o mecanismo não consegue ler como uma de suas seis formas de requisito — um requisito vazio, uma chave que contém espaço em branco ou um entre =, !, (, ) e a vírgula, um conjunto não fechado — interrompe o build em cada aresta que protege, em vez de ser lido como algum outro seletor. A gramática de seletores lista as formas e cada recusa.
3. Formatos e composição de esquemas
Para fornecer tanto validação estrita quanto metadados padrão de catálogo (autor, versão, descrição), as definições do Domínio 2 (Interfaces) e do Domínio 3 (Implementações) são escritas como envelopes YAML. O Domínio 2 utiliza declarações schema: embutidas, expressas em forma compacta (o padrão; ~15 palavras-chave, transformadas mecanicamente em JSON Schema 2020-12) ou em YAML de JSON Schema completo.
Por que todo YAML do catálogo repete o envelope. O envelope (bloco apiVersion, kind, metadata) aparece no topo de todo arquivo do catálogo — Component, Feature, Recipe, FeatureRecipe, Aggregate, Manifest, Release, Plugin — independentemente de quão curto seja o corpo. A repetição é deliberada: cada arquivo é projetado para ser analisado, validado, passado pelo linter e inspecionado como um artefato independente. Um único arquivo baixado do registry OCI, colocado em uma sandbox de CI ou aberto em um editor de terceiros precisa trazer autodescrição suficiente para que as ferramentas posteriores consigam identificar que tipo de entidade ele representa e qual versão de esquema se aplica. A localização do diretório nunca substitui o envelope: todo parser, validador e linter lê o tipo da entidade e a versão de esquema do envelope. O custo é código repetitivo mecânico por arquivo; o benefício é que a garantia de ferramentas independentes vale na superfície de distribuição OCI, no sistema de arquivos local e nas superfícies IDE / CI / inspect. Os autores copiam o envelope de arquivos existentes ao escrever novo conteúdo de catálogo, ou partem de aggrega scaffold <kind>, que imprime um documento inicial para o tipo com apiVersion e kind já preenchidos.
Para manter o princípio DRY (Don’t Repeat Yourself, “não se repita”), o catálogo emprega dois mecanismos de composição distintos:
- Entradas compartilhadas de SchemaLibrary (
$ref:entre documentos): Definições reutilizáveis de JSON Schema são armazenadas em entidades de catálogo SchemaLibrary (Tier 3). Elas são referenciadas por identidade via$ref:entre documentos (<library>#/schemas/<entry>, sem host — a versão vem do lockfile) a partir de qualquer esquema de Component ou Feature consumidor. A cadeia é percorrida em tempo de compilação. Consulte entities/schemalibrary para a forma de autoria da entidade de biblioteca e vocabulary/cross-document-ref para a semântica de resolução. - Herança simples (
extends): Para baselines completas de componentes, as entidades podem usar a propriedadeextends: "URI". O compilador Go lê recursivamente a cadeia de pais e faz o deep merge dos metadados YAML (sobrescrevendo labels em caso de conflito e acrescentando arrays). Os dois tipos de catálogo então seguem caminhos diferentes nos pilares de dados. Oschema:de uma Feature se compõe com o de sua base segundo a composição de JSON Schema 2020-12. Um Component que estende não escreve nenhum conteúdo de pilar: ele escreve o marcador literalschema: inheritede recebe o blocoschema:de sua base exatamente como a base o escreveu, em qualquer profundidade de uma cadeia. O que tal Component compõe, em vez disso, é estrutura — seus slots de acoplamento (featuresSchema), sockets de topologia (usesSchema), lista de permissões de autoinjeção (inject) eassertionsnomeadas se mesclam todos ao longo da cadeia. Consulte entities/component para os exemplos de extensão de componentes base e filho + governance-and-compliance §“Herança e disciplina de publicação” para o que a herança resolve por construção e o que continua sendo uma regra de disciplina de publicação.
Consulte entities/component para os exemplos de extensão de componentes base e filho, e entities/recipe para a autoria de Recipe com ponteiros e mapeadores, com exemplos completos.
4. A configuração do workspace (.aggrega-config.yaml)
O arquivo .aggrega-config.yaml na raiz do workspace é a configuração de workspace do projeto — a declaração própria do workspace, adequada ao controle de versão assim como go.mod ou package.json. Por convenção, o diretório .aggrega/ fica fora do controle de versão — liste-o no .gitignore, como você faria com node_modules/ ou .terraform/.
A seção workspace é o marcador de raiz: sua presença marca a raiz do workspace, e ela traz apenas os diretórios de catálogo que definem a raiz — catalog_dirs, e o mapa releases que dá a uma Release diretórios de catálogo próprios. Todas as outras configurações ficam no nível superior. Muitas são valores únicos; outras são seções que reúnem sob uma única chave as configurações de um mesmo aspecto. Todo campo é opcional, com padrões documentados. O conjunto completo e atual de chaves de nível superior, cada uma com seu tipo, padrão e significado, é gerado a partir do esquema em schema/other/aggrega-config; o exemplo abaixo mostra o marcador de raiz ao lado de algumas das configurações de valor único:
workspace: # Root marker; presence marks the workspace root catalog_dirs: # Ordered list of local catalog directories (checked before cache) - ./aggrega-catalogdefault_registry: hub.aggrega.ai # Default registry for unqualified URIsoffline: false # Set true for air-gapped environmentsauto_pull: true # Opt in to the implicit pull; the default is false, keeping build read-onlyartifact_cache_dir: .aggrega/cache # On-disk artifact cache rootUm bloco signing: traz os padrões de assinatura de artefatos usados por aggrega push --sign e aggrega sign, tanto no nível superior (global) quanto por registry:
signing: # Global signing defaults fulcio_url: https://fulcio.sigstore.dev # Keyless certificate authority (defaults to public-good) rekor_url: https://rekor.sigstore.dev # Keyless transparency log (defaults to public-good) timestamp_url: https://tsa.example.com/api/v1/timestamp # Optional RFC3161 timestamp authority (no default; opt-in) key_path: ./keys/signing.pem # Optional: path to a held keyed-key PEM (a pointer, never inline material)registries: - host: hub.example.com signing: # Per-registry override of the global signing block key_path: ./keys/hub.pemA precedência por campo é flag da CLI > signing por registry > signing global > padrão de interesse público. Fulcio e Rekor usam por padrão as instâncias de interesse público do Sigstore, portanto são opcionais; timestamp_url não tem padrão — o carimbo de tempo confiável sem chave vem da inclusão no log de transparência do Rekor, e uma autoridade de carimbo de tempo RFC3161 é opcional (defina timestamp_url, ou --timestamp-url, com um endpoint completo para habilitar uma). Segurança: o bloco signing: não traz material secreto — o token de identidade OIDC nunca é um campo de configuração (é um segredo de curta duração, fornecido no momento da assinatura: obtido por um fluxo no navegador em um terminal interativo ou do workflow no GitHub Actions, e, nos demais casos, passado com --identity-token ou exportado como AGGREGA_IDENTITY_TOKEN ou SIGSTORE_ID_TOKEN), e a chave privada nunca fica inline; key_path é um caminho para um arquivo de chave. Essa é a assimetria deliberada em relação ao lado da verificação, que fixa uma chave pública inline, enquanto no lado da assinatura há sempre apenas um caminho de chave.
Marque uma raiz sem catálogos vendorizados escrevendo workspace: {}. A lista catalog_dirs dá suporte a configurações de monorepo em que um catálogo compartilhado fica em um diretório irmão. O compilador verifica cada diretório em sequência. O flag offline: true impede qualquer acesso à rede — o compilador usa apenas caminhos locais e o cache, interrompendo-se se uma entidade não for encontrada localmente. As configurações em seções reúnem, cada uma, um aspecto. Entre elas: os controles de rigor em tempo de build e as dicas de autoria; os sockets de acoplamento Wasm no nível do workspace (governance, linter, importer, providers, cli), cada um recebendo uma lista de referências a plugins; o rigor do lint por regra, incluindo as chaves de política de disciplina de publicação; o ajuste do cache de parsing do daemon e o tamanho do seu pool de workers de despacho de requisições; e o limite de tamanho do armazenamento de módulos compilados compartilhado por toda a máquina. Outras ainda trazem os padrões de assinatura e de confiança em assinaturas e o comportamento do próprio daemon. Toda chave de nível superior está documentada por completo em schema/other/aggrega-config.
Três caches distintos são configuráveis, e vale a pena um momento para diferenciá-los, porque seus nomes são parecidos e seus escopos não. artifact_cache_dir designa o cache de conteúdo em disco por workspace descrito abaixo. parse_cache limita o cache de parsing em memória do daemon, que vive apenas enquanto o daemon vive. compiled_module_cache limita o armazenamento em disco do código de máquina de plugins compilados — um dos caches compartilhados por todos os workspaces da máquina, porque a forma compilada de um plugin depende do plugin e não do projeto que o usa:
# .aggrega-config.yaml — most at home in the global config file, since the store is machine-widecompiled_module_cache: max_bytes: 53687091200 # Default 50 GiB; 0 disables the capDos caches que todos os projetos da máquina compartilham, é o que pode vir a dominar o uso de cache em disco, já que todo plugin que a máquina executa é compilado nele uma vez e mantido, e por isso é o único com um limite de tamanho permanente. Toda invocação que abre o armazenamento aplica o limite antes de compilar qualquer coisa, removendo entradas inteiras, das compiladas há mais tempo para as mais recentes, até que o restante caiba. (Um build executado com --disable-plugin-cache compila em memória, de modo que não faz o armazenamento crescer nem o reduz.) Remover uma entrada custa uma recompilação posterior e nada mais, e é isso que torna seguro reduzir o limite e aplicá-lo enquanto outros builds estão em execução na mesma máquina. Defina-o acima do que um único build compila: como o limite é aplicado antes da compilação, um limite abaixo do conjunto de trabalho de um único build faz com que cada build descarte e recompile os mesmos módulos, e pelo mesmo motivo o armazenamento pode ficar acima do limite entre builds e é reduzido novamente no início do próximo. aggrega cache status informa o tamanho do armazenamento, e aggrega cache evict --max-size o reduz sob demanda a um limite informado na linha de comando.
A raiz artifact_cache_dir traz três subárvores paralelas que uma única invocação de aggrega pull preenche de forma uniforme, uma por classe de dependência fixada: <artifact_cache_dir>/entities/<encoded-kind>/<encoded-reference>/<encoded-version>/ para entidades de catálogo (Components, Features, Recipes, FeatureRecipes, Aggregates, as bibliotecas e Plugins com os executáveis que eles publicam), em que o tipo é aquele sob o qual a entidade é publicada, de modo que duas entidades de tipos diferentes que compartilham uma referência e uma versão — um Component e uma Recipe com o mesmo nome — ocupam dois slots; <artifact_cache_dir>/source-artifacts/<kind>/<host>/<path>/<version>/<digest-prefix>/ para artefatos de origem baixados dos campos spec.source de Recipe / FeatureRecipe (charts do Helm, fragmentos de compose); e <artifact_cache_dir>/inputs/sha256/<hex-digest> para entradas externas — os documentos remotos que um provider solicita ao host enquanto renderiza, como um $ref no values.schema.json de um chart que aponta para uma URL. Cada slot de cache de artefato de origem traz o arquivo .tgz de referência, um diretório derivado extracted/ regenerado a cada leitura de build e um arquivo metadata.yaml que registra a identidade {kind, url, version, digest, mediatype, pulled_at} do artefato. Cada slot de cache de entidade traz o artefato publicado tal como foi obtido e o manifesto OCI contra o qual ele é verificado. O slot de cada tipo cujo documento pode nomear um arquivo ao seu lado — uma Recipe, uma FeatureRecipe, um Component, uma Feature — traz também um diretório derivado extracted/ com os arquivos que esse artefato carrega, em um diretório nomeado pelo digest de conteúdo do artefato: o documento e os arquivos que a entidade declarou, quando foi publicada como arquivo compactado, e apenas o documento, quando foi publicada como seu documento (§6). O diretório da entidade é montado ali a partir do artefato verificado a cada leitura, da mesma forma que os arquivos de um artefato de origem: cada arquivo é verificado contra o artefato, um arquivo alterado ou adicionado à mão nesse diretório é descartado em vez de lido, nada mais sob extracted/ é lido, e um artefato que falha na verificação é recusado antes que qualquer coisa seja montada. Uma leitura reescreve apenas o que difere do artefato, de modo que builds que leem um mesmo cache ao mesmo tempo — requisições que aggrega serve trata lado a lado, ou dois comandos sobre um mesmo workspace — encontram, cada um, íntegros os arquivos que receberam. O segmento <digest-prefix> de 12 caracteres separa em slots distintos o mesmo {kind, url, version} remarcado com digests upstream diferentes. Uma entrada externa não precisa de um slot assim: ela é armazenada como um único arquivo nomeado pelo digest de conteúdo ao qual o lockfile a fixa, de modo que o que um build posterior lê é endereçado pela fixação, e não pela URL de onde os bytes vieram — e é isso que permite que esse build sirva a entrada com a rede negada.
Três outros diretórios podem aparecer ao lado desses três, e nenhum deles contém conteúdo de dependências fixadas: index/ traz os snapshots pesquisáveis por registry que aggrega registry update grava (§8), signatures/ armazena em cache cada pacote de assinatura verificado sob o seu próprio digest, de modo que uma leitura posterior verifica novamente o blob em cache contra o digest sob o qual ele foi registrado, em vez de buscar o pacote outra vez, e catalog-snapshots/ guarda cada snapshot publicado do catálogo que uma importação leu (§8) — o arquivo compactado e seu manifesto em um slot nomeado pelo digest do manifesto, com a árvore do catálogo disposta a partir do arquivo compactado a cada leitura, e um arquivo current que nomeia o snapshot que o workspace lê quando nada nomeia outro.
O pacote de documentação não está entre eles. Seus bytes dependem apenas do registry em que é publicado e da versão com que é publicado, por isso ele é mantido uma vez por máquina, ao lado do armazenamento de módulos compilados sob a mesma raiz de cache por usuário, em docs-bundles/<encoded-reference>/<encoded-version>/ abaixo dessa raiz: o pacote, o manifesto contra o qual ele é verificado e as assinaturas que suas buscas verificaram. artifact_cache_dir não o alcança. Antes que uma página seja lida dele, essas assinaturas são verificadas novamente sob a própria verificação de assinaturas do workspace que lê, para o registry do pacote, de modo que uma cópia admitida pelas configurações mais permissivas de um workspace não seja servida a um workspace cuja verificação a recusa — consulte aggrega-explain e aggrega-cache.
artifact_cache_dir é escrito em relação à raiz do workspace e designa o mesmo diretório independentemente do diretório a partir do qual um comando é invocado ou de quais diretórios de catálogo estão sendo varridos. Um valor absoluto é recusado quando a configuração é carregada, com um diagnóstico que nomeia o campo: todo leitor da configuração a resolve em relação à raiz do workspace, de modo que um caminho absoluto nomearia um local que nenhum deles alcança, e a falha seria, de outra forma, silenciosa — o cache que um pull grava deixaria discretamente de ser o cache que um build lê. O cache pode ficar dentro de um diretório de catálogo, e no layout padrão fica, já que um diretório de catálogo costuma ser a própria raiz do workspace. O que ele não deve fazer é ser um diretório de catálogo: uma varredura do catálogo pula o cache, de modo que um diretório de cache que também é um diretório de catálogo retira todo o conteúdo desse diretório de toda varredura. artifact_cache_dir: . nomeia a raiz do workspace, que no layout padrão é exatamente esse caso, e é recusado quando a configuração é carregada, com um diagnóstico que nomeia o campo — assim como qualquer outra grafia que se reduza à raiz do workspace. Essas duas formas, junto com o caminho absoluto acima, são as que a verificação de configuração consegue reconhecer por conta própria. Um valor que nomeia algum outro diretório de catálogo — sub, em um workspace cujo catalog_dirs lista sub — é carregado sem reclamação, e o único sintoma é que as entidades sob ele deixam de ser encontradas. Manter o cache fora de todo diretório listado em workspace.catalog_dirs faz parte, portanto, de escrever a configuração, e não é algo que ela verifique por você.
Pular o cache é o que impede que um artefato de resolução seja lido como se um autor o tivesse escrito. Um slot de cache contém bytes que uma busca no registry colocou ali, armazenados sob a coordenada de onde foram buscados e garantidos por um digest do lockfile; uma varredura que pegasse um deles como conteúdo de catálogo escrito por um autor estaria aceitando bytes que nada verificou, em um caminho que o autor não pode editar. Vale a pena declarar claramente uma consequência: se o cache contiver uma entidade que nenhum lockfile fixa — deixada por um pull interrompido, copiada à mão ou abandonada quando uma Release deixou de referenciá-la —, essa entidade não fica visível para uma varredura do catálogo, e um build ou uma validação que dependa dela é interrompido informando que a entidade não foi encontrada. A solução é fazer o pull da Release novamente, para que a entidade seja resolvida pelo lockfile e seu digest seja registrado; a interrupção nomeia a entidade para que a fixação ausente possa ser identificada. A alternativa — resolvê-la mesmo assim — é justamente a leitura não verificada que pular o cache existe para impedir.
O lockfile é por Release: resolver release.yaml grava release.lock ao lado dele (o nome base do arquivo da Release mais .lock). aggrega pull resolve as dependências e grava o lockfile; aggrega build o lê e usa as versões fixadas independentemente do estado do registry no momento do build. Os workspaces fazem commit do lockfile quando a reprodutibilidade do build entre máquinas importa; depois que uma entidade, uma biblioteca, um plugin ou a própria Release muda no workspace, aggrega pull --release <release> o atualiza, resolvendo novamente o que mudou e mantendo todas as outras fixações, e aggrega pull --upgrade --release <release> é a forma de adotar uma versão mais recente que um registry passou a oferecer. O lockfile registra cada entidade resolvida com seu tipo, seu URI como foi escrito, a versão resolvida, o digest do conteúdo e os locais que a referenciam. O tipo e o URI juntos identificam uma entrada, de modo que uma Release cujo Aggregate e cujo Manifest compartilham um nome registra uma entrada para cada um, e uma edição em qualquer um dos dois interrompe o build seguinte até que um pull a registre:
# release.lockentities: - kind: component uri: core/datastore/mariadb:1.0.0 resolved_version: 1.0.0 digest: sha256:5deeedb9acc1be00d4e0f98e55e01d301a0bcc01d702c015a9d9628ff573650a referenced_from: - aggregate.spec.components.db.type - kind: recipe uri: mariadb-bitnami:1.0.0 resolved_version: 1.0.0 digest: sha256:215b54e2da1ce512fcdccff87f6f71daac707bc77e4214b60b946b27a24e483a referenced_from: - manifest.spec.mappings.components.type.core/datastore/mariadb:1.0.0generated_at: "2026-06-11T16:48:15Z"mapping_libraries: []plugins: []release: release.yamlschema_libraries: []source_artifacts: []version: 1Cada entrada fixada traz o tipo + o URI + a versão resolvida + o digest endereçável por conteúdo. O digest é verificado a cada busca; bytes que não correspondem ao digest fixado interrompem o build com um erro de integridade. O digest de uma entidade é calculado sobre o que uma publicação dela carrega — seu documento e cada arquivo que ela declara ao lado dele, cada um pelo caminho e pelos bytes — e não sobre os bytes com que ela trafega, de modo que a mesma entidade registra o mesmo digest seja lida de um diretório de catálogo ou buscada em um registry, independentemente de como seu arquivo compactado foi comprimido e de quais bits de permissão, incluindo o bit de execução, um checkout deu aos seus arquivos. O digest que o próprio registry calcula sobre os bytes publicados é aquilo contra o que uma busca é verificada primeiro, por meio do manifest, cujo digest uma entrada resolvida pelo registry registra ao lado do seu próprio.
5. O modelo de resolução de entidades em três níveis
O compilador resolve cada referência a entidade encontrada durante a compilação por meio de uma busca em cascata estrita. Os três níveis — caminho local, workspace e cache, e registry — correspondem a três fluxos de trabalho de autoria que coexistem em um projeto Aggrega saudável: uma Release que nomeia os arquivos ao seu lado, uma equipe consumindo um catálogo versionado no repositório mais o cache baixado anteriormente, e um pull que recorre ao registry para um artefato ainda não baixado. O nível de workspace e cache e o nível de registry da mesma cascata avaliam os campos type nos Aggregates, os valores de URI nos mapeamentos do Manifest, as declarações implements em Recipes e FeatureRecipes, e as referências plugin dentro dos pipelines de Recipe e FeatureRecipe; o nível de caminho local só é alcançado pelos arquivos que uma Release e seu Manifest nomeiam.
Caminho local. Uma referência aggregate, manifest ou extends de uma Release, ou o extends de um Manifest, que começa com ./ ou ../ (um prefixo de caminho relativo POSIX) é lida diretamente do disco, relativa à Release. Nenhuma busca no catálogo, nenhuma chamada ao registry. O prefixo explícito distingue, no nível sintático, a intenção de caminho local da busca por nome: uma Release que escreve aggregate: ./aggregate.yaml nomeia um arquivo; aggregate: checkout nomeia um Aggregate pelo seu metadata.name. O resolvedor nunca inspeciona o conteúdo da string para decidir qual nível se aplica — o prefixo é o discriminador. Qualquer outra referência, incluindo um type de Component em um Aggregate, é resolvida pelo nível de workspace e cache e pelo nível de registry: uma entidade escrita localmente é colocada em catalog/ na raiz do workspace ou em um diretório listado por workspace.catalog_dirs, e um type escrito como caminho de arquivo relativo interrompe o build como uma entidade que nenhum catálogo contém.
Workspace e cache. Uma referência sem um prefixo explícito de caminho local é procurada primeiro nos diretórios listados em workspace.catalog_dirs (árvores de catálogo locais do projeto, escritas no repositório ou copiadas para ele — veja o §4 para o formato da configuração) — ou, para uma Release à qual a configuração atribui diretórios próprios em workspace.releases, nos dessa Release — depois no diretório catalog/ da raiz do workspace, e em seguida em artifact_cache_dir (o local .aggrega/cache/, ignorado pelo git, que guarda os artefatos baixados em resoluções anteriores no registry e cujas subárvores o §4 descreve). O acerto no cache a partir do segundo build é o que mantém o ciclo interno livre de rede mesmo quando o projeto depende de conteúdo de catálogo remoto.
Registry. Se o nível de workspace e cache não retornar nenhuma correspondência, aggrega pull — ou um build executado com --auto-pull ou com a configuração auto_pull do workspace — emite um pull OCI baseado em ORAS contra default_registry (padrão hub.aggrega.ai), descompacta o artefato no cache para os builds seguintes e continua com a entidade resolvida. Um build sem nenhum dos dois lê apenas o que seu lockfile fixa, e é interrompido indicando aggrega pull quando o lockfile está ausente. O formato de URI OCI que a chamada ao registry constrói segue a taxonomia por tipo de entidade descrita no §6 (Empacotamento de artefatos & taxonomia OCI). URIs abreviados em Aggregates e Manifests são expandidos para sua forma OCI completa antes da chamada ao registry; as regras de inferência que conduzem essa expansão estão na referência URIs abreviados sensíveis ao contexto do Manifest e no §8 abaixo.
Precedência e sombreamento. A precedência de resolução é estritamente caminho local > workspace e cache > registry. Uma entidade em um diretório de catálogo local com a mesma identidade de uma entidade do registry sombreia a entidade do registry — isso é intencional e permite que autores de catálogos experimentem modificações antes de publicar. O mesmo sombreamento se aplica entre catalog_dirs e o cache: uma entidade presente em um diretório de catálogo do workspace tem preferência sobre uma cópia em cache, garantindo que edições locais em um catálogo copiado para o repositório tenham efeito imediato.
Dentro do nível de workspace e cache, catalog_dirs é uma pilha de precedência ordenada em que o primeiro vence. Quando a mesma identidade de entidade aparece em mais de um diretório de catálogo listado, o diretório listado antes vence e a ocorrência posterior é sombreada — substituída, não carregada, e não é um erro. Isso permite que um projeto coloque seu próprio diretório de catálogo à frente de um compartilhado ou copiado para o repositório e substitua entidades selecionadas pela identidade, enquanto o restante recai no diretório compartilhado. A substituição é observável: o detalhe da resolução informa qual diretório venceu e qual foi sombreado, de modo que uma sobreposição nunca é silenciosa. O sombreamento só se aplica entre diretórios; dois arquivos em um único diretório que reivindicam a mesma identidade são um erro de autoria e interrompem o carregamento. Um diretório nomeado mais de uma vez — por um flag --catalog e em catalog_dirs, ou duas vezes na lista — é uma única entrada da pilha, pesquisada uma só vez no lugar em que foi nomeada primeiro, de modo que um sombreamento sempre envolve dois arquivos diferentes e nunca um diretório lido contra si mesmo. Como a precedência segue a ordem de diretórios controlada pelo autor, o conjunto resolvido é determinístico.
O diretório catalog/ da raiz do workspace entra nessa pilha no fim, não no início, e somente quando o diretório existe — assim, qualquer coisa que um projeto liste vence sobre ele em caso de colisão, e listar um diretório não relacionado nunca faz com que ele deixe de ser lido silenciosamente. Ele é ignorado quando uma entrada listada já o alcança, pois a varredura de um diretório listado é recursiva e uma pilha que nomeia a raiz do workspace já o leu. Omitir catalog_dirs e escrevê-lo como uma lista vazia são declarações diferentes: omitido, o workspace ainda lê catalog/; escrito como [], não lê nenhum catálogo local, e é assim que um workspace declara que não tem nenhum.
Builds isolados da rede. Definir offline: true (§4) ignora completamente o nível de registry. Uma referência que não é resolvida no nível de caminho local nem no de workspace e cache gera um erro de entidade ausente em vez de tentar silenciosamente uma chamada de rede, o que dá aos pipelines de CI que legalmente não podem acessar a rede um contrato determinístico de falha rápida.
Onde a cascata opera. A cascata carrega a entidade na memória; os mecanismos de resolução adicionais construídos sobre ela — a busca em dois níveis type vs name do Manifest, a correspondência de versão de implements em três formas (exata / intervalo compatível com a versão major / sem versão) em vocabulary/inheritance-and-interface, e a seleção da Recipe por eixo segundo o provider e a instância do componente — operam sobre entidades que o resolvedor já trouxe por meio dessa cascata.
6. Empacotamento de artefatos & a taxonomia OCI (a capacidade como segmento inicial)
O Aggrega trata a lógica de infraestrutura da mesma forma que o Docker trata imagens de contêiner, utilizando os padrões da Open Container Initiative (OCI) por meio do ORAS (OCI Registry As Storage). Os usuários podem hospedar seu catálogo do Aggrega em qualquer registry padrão (GHCR, AWS ECR, Aggrega Hub).
Como as Recipes são estritamente 1:1 com uma capacidade de renderização — uma Recipe nomeia uma única capacidade em spec.capability e não pode visar duas —, a forma mais limpa de organizá-las em um registry OCI é colocar a capacidade no segmento inicial do repositório.
A taxonomia OCI abrange todos os tipos de entidade. O nome de um repositório é o segmento do kind — o kind da entidade, em minúsculas — seguido da identidade da entidade, tudo em minúsculas:
hub.aggrega.ai/component/core/datastore/mariadb:1.0.0— Component, publicadorcore, categoriadatastorehub.aggrega.ai/component/core/compute/api-server:1.0.0— Component, publicadorcore, categoriacomputehub.aggrega.ai/feature/core/data-masking:1.0.0— Feature, publicadorcore(plano, sem categorias)hub.aggrega.ai/aggregate/core/db-module:1.0.0— Módulo Aggregate reutilizávelhub.aggrega.ai/recipe/helm/mariadb:1.0.0— Recipe, capacidadehelmhub.aggrega.ai/recipe/helm-chart/mariadb:1.0.0— Recipe, capacidadehelm-charthub.aggrega.ai/recipe/compose/mariadb:1.0.0— Recipe, capacidadecomposehub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0— FeatureRecipe, capacidadehelmhub.aggrega.ai/schemalibrary/aidatastores:1.0.0— SchemaLibrary, definições de schema compartilhadas; ometadata.nameem PascalCaseAIDatastorespassa para minúsculas no nome do repositóriohub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0— MappingLibrary, fragmentos de mapeamento Go-template compartilhadoshub.aggrega.ai/plugin/provider/helm:0.5.0— Plugin, tipo de socketprovider(o segmentometadata.pluginType)
Os kinds publicáveis abrangem os kinds de autoria do catálogo junto com o Aggregate, um módulo reutilizável (publicável seja ele depois referenciado como o spec.aggregate de nível superior de uma Release ou aninhado no bloco aggregates: de outro Aggregate), e o Plugin, uma referência endereçada por conteúdo a um artefato WebAssembly que o compilador roteia e o runtime executa. O Plugin é um artefato publicável estrutural, e não um kind de autoria do catálogo. Release e Manifest são entradas do lado da implantação que ficam no controle de versão e nunca são enviadas com push — aggrega push as rejeita —, portanto não têm mediatype de publicação. aggrega push --list-kinds informa o conjunto que o binário instalado publica, um kind por linha. Cada kind publicável tem seu próprio mediatype OCI em cada uma das duas formas que uma publicação assume:
| Kind da entidade | Publicada como seu documento | Publicada com os arquivos que declara |
|---|---|---|
| Component | application/vnd.aggrega.component.v1beta1+yaml | application/vnd.aggrega.component.v1beta1+tar+gz |
| Feature | application/vnd.aggrega.feature.v1beta1+yaml | application/vnd.aggrega.feature.v1beta1+tar+gz |
| Recipe | application/vnd.aggrega.recipe.v1beta1+yaml | application/vnd.aggrega.recipe.v1beta1+tar+gz |
| FeatureRecipe | application/vnd.aggrega.featurerecipe.v1beta1+yaml | application/vnd.aggrega.featurerecipe.v1beta1+tar+gz |
| Aggregate | application/vnd.aggrega.aggregate.v1beta1+yaml | — não declara nenhum arquivo |
| SchemaLibrary | application/vnd.aggrega.schemalibrary.v1beta1+yaml | — não declara nenhum arquivo |
| MappingLibrary | application/vnd.aggrega.mappinglibrary.v1beta1+yaml | — não declara nenhum arquivo |
| WorkloadLibrary | application/vnd.aggrega.workloadlibrary.v1beta1+yaml | — não declara nenhum arquivo |
| ArtifactLibrary | application/vnd.aggrega.artifactlibrary.v1beta1+yaml | — não declara nenhum arquivo |
| Plugin | application/vnd.aggrega.wasmplugin.v1beta1+yaml | — publica por meio do seu próprio manifest |
O que uma publicação carrega, e portanto sua forma, decorre do que a entidade declara — não do seu kind, nem do que está no seu diretório. Uma publicação carrega o documento da entidade e os arquivos que a própria entidade nomeia ao lado dele: o source: local de uma Recipe ou de uma FeatureRecipe — um diretório trafega com cada arquivo sob ele que as regras de exclusão registradas no seu entity.lock mantêm —, cada arquivo que suas entradas valuesMapping:, workload: e artifacts: importam com $import:, e o entity.lock que sua etapa de fixação gravou; e cada arquivo de schema que um Component ou uma Feature importa, incluindo cada arquivo de uma cadeia de importação. Nada mais no diretório trafega: uma nota, um README ou a saída de um build ao lado da entidade não faz parte do que ela publica, qualquer que seja o nome, e não muda a forma em que ela publica. Uma entidade que não nomeia nada é publicada como o documento escrito, byte a byte, sob o mediatype +yaml do seu kind; uma que nomeia um arquivo é publicada como um tar compactado com gzip do documento e desses arquivos, sob o mediatype +tar+gz do seu kind. Um Aggregate, um Plugin e os kinds de biblioteca não declaram nenhum arquivo ao lado do documento, portanto são sempre publicados como o documento — incluindo um Aggregate na raiz de um workspace, já que cada caminho que ele declara nomeia outra entidade e não um arquivo que ele carrega; o mesmo vale para uma Recipe cujo conteúdo é todo inline. Um source remoto é uma referência e não um arquivo, então não carrega nada, embora o entity.lock que registra sua fixação faça dessa Recipe um arquivo compactado. O segmento de versão de cada mediatype é comum a todos os kinds publicáveis, e o segmento de codificação diz qual das duas formas os bytes têm. As ferramentas downstream fazem o despacho pela string completa do mediatype — kind, versão e codificação juntos.
Uma forma escrita não nomeia nenhum diretório que uma publicação possa conhecer: um source local escrito como template. Seu diretório só é escolhido quando uma Release preenche o template, então a entidade carrega cada arquivo do seu próprio diretório que suas regras de exclusão registradas mantêm, para que qualquer diretório que uma Release escolha já tenha trafegado; aggrega push avisa quando isso acontece. Carregar apenas o que é nomeado tem um custo, e ele recai sobre o consumidor: um arquivo que uma entidade lê e não nomeia em lugar nenhum não trafega, e é o build de um consumidor — não o push do publicador — que se depara com a sua ausência, nomeando o caminho ausente dentro do seu slot de cache.
Quais arquivos de um diretório de origem pertencem à entidade é decidido uma única vez, quando a entidade é fixada, e registrado. O plugin que atende à capacidade da entidade no workspace do autor declara o que o seu ecossistema nunca distribui — os diretórios de controle de versão de um plugin de charts e o respeito dele ao .helmignore de um chart, o .terraform/ de um plugin de módulos — e o .aggregaignore do autor ao lado da entidade tem a palavra final. A etapa de fixação registra esse plugin e as regras compostas no entity.lock, e a publicação, cada comparação das fixações do source, a linha da entidade no lockfile e a renderização aplicam todas as regras registradas em vez de consultar novamente um plugin, de modo que o que é publicado é o que o próprio build do autor renderiza, e um binding alterado ou um binário mais recente não altera nenhum digest até que a entidade seja fixada novamente. O compilador não tem opinião sobre nenhum ecossistema: as regras vêm do plugin e do autor, e o compilador apenas as aplica. Um link simbólico entre os arquivos de uma entidade é recusado em vez de seguido, pois aquilo para o que ele aponta trafegaria sob o seu nome. aggrega pin explica as regras por completo.
O nome de uma Recipe não traz nem um prefixo de domínio nem a capacidade: o diretório do tipo de entidade e o segmento da capacidade já dizem ambos.
Convenção de nomenclatura: os Components (Domínio 2) usam {publisher}/{category}/{name}, e as Features (Domínio 2) e os Aggregates reutilizáveis (Domínio 1) usam {publisher}/{name}, em que o segmento publisher nomeia o fornecedor/autor (core = biblioteca padrão oficial, acme = empresa). As entidades do Domínio 3 (Recipe, FeatureRecipe) usam {capability}/{name}, em que a capacidade é o provider que a entidade declara em spec.capability; uma referência também pode nomear a entidade sem prefixo, apenas pela folha. Os nomes de Recipe também NÃO incluem a capacidade, pois ela já é o segmento inicial do URI canônico.
As Recipes utilizam a palavra-chave implements para se vincular à interface que cumprem. O campo implements aceita correspondência exata, por intervalo compatível com a versão major ou sem versão (veja vocabulary/inheritance-and-interface para a correspondência de versão de implements). A Recipe de uma entrada de mapeamento do Manifest precisa implementar o tipo para o qual está mapeada, ou uma base que esse tipo extends: a chave da entrada, e o tipo de cada instância de componente que a chave alcança em uma versão que ela não nomeia, na versão com que o build compila essa instância — assim, uma chave não pode enviar uma instância para uma Recipe escrita para outra versão do seu tipo.
Quando um engenheiro de Ops executa aggrega push, a CLI publica a entidade nessa forma, de modo imutável na sua versão. Um consumidor a busca por meio do modelo de resolução em três níveis, a armazena localmente em cache em .aggrega/cache/ e dispõe o que ela carrega no slot de cache da entidade (§4) — os arquivos de um arquivo compactado, ou apenas o documento.
Uma entidade baixada lê os arquivos que carrega exatamente como os lê ao seu lado em um diretório de catálogo. A entidade é lida a partir de seu lugar nessa árvore disposta, de modo que um source: ou $import: relativo que ela declara — escrito por extenso ou produzido por um template — é resolvido dentro do que foi publicado, e um caminho que sai do diretório próprio da entidade é recusado ali exatamente como em um diretório de catálogo. Nada fora da árvore é lido no lugar dela: nem o diretório a partir do qual um build é executado, nem um arquivo colocado no slot de cache. Um Component ou uma Feature cujo schema é importado de um arquivo carrega esse arquivo, de modo que uma cópia baixada carrega o contrato que foi publicado e valida os valores escritos contra ele exatamente como faz uma cópia lida de um diretório de catálogo.
Ler a entidade de volta a partir de um pacote é o passo inverso, e ele identifica a entidade pelo que o documento é, e não pelo nome que tem: o documento no nível superior do pacote cujo kind: é um tipo de entidade publicável. O nome do arquivo da entidade é uma convenção do catálogo e não um contrato, de modo que recipe.yaml é o que o catálogo da biblioteca padrão escreve, e não o que o formato exige, e um arquivo carregado ao lado da entidade — um template de chart, um fragmento de compose — não é confundido com ela. A regra não pode funcionar ao contrário, baseada no tipo que o consumidor procura: um tipo é lido a partir da entidade, que está dentro do pacote, então, no momento em que o pacote precisa ser aberto, não há tipo em que se basear. O lado de leitura é interrompido em vez de escolher quando o nível superior de um pacote contém dois documentos de entidade — o pacote que outro cliente produz ao empacotar um diretório inteiro que contém duas entidades, e que ficaria então sob cada uma das coordenadas publicadas delas como um único artefato. A publicação deste produto não pode produzi-lo, porque cada entidade carrega apenas o que declara, e o lado de publicação também recusa um diretório assim: cada tipo tem um diretório próprio, exceto Aggregate, Release e Manifest, e aggrega pin e aggrega push recusam uma entidade de qualquer outro tipo que tenha outra entidade ao lado, enquanto um carregamento de catálogo, um lint e um build deixam o diretório como está. O nome de um diretório não é julgado em nenhum dos lados: o layout <name>/<version>/ é a convenção do catálogo da biblioteca padrão.
Uma entidade publicada é lida pelo mesmo passo. Uma coordenada carrega exatamente uma cópia de sua entidade, na forma que suas declarações lhe deram, e uma pessoa a examina com aggrega inspect oci://<registry>/<repository>:<tag> em vez de por meio de uma cópia legível publicada ao lado — portanto, não existe uma segunda cópia que possa vir a divergir daquela que um build resolve. O comando descompacta um arquivo segundo a regra acima, lê a entidade de um Plugin a partir de seu manifesto em vez do executável publicado com ele, e exibe o resultado como um arquivo desse tipo é exibido; consulte Lendo uma entidade publicada.
Anotações de manifesto pesquisáveis. Cada publicação grava um pequeno conjunto de anotações pesquisáveis no manifesto OCI do artefato, para que um índice de registry ou um navegador de catálogo possa filtrar artefatos por seus metadados de catálogo sem baixar e analisar o corpo de cada entidade. Cada entidade carrega sua descrição legível por humanos (a anotação de descrição OCI padrão), além de sua categoria de catálogo e seu tipo. Um Plugin carrega também seu tipo de socket e as capabilities que atende. Essas anotações são o que aggrega registry update lê de volta para o índice pesquisável local (§8).
Todo arquivo publicado tem nome. Cada arquivo que uma publicação carrega é nomeado no manifesto com a anotação padrão org.opencontainers.image.title, que é o nome com o qual um cliente OCI genérico grava esse arquivo ao baixar o artefato para um diretório. O nome diz o que o arquivo é, e sua extensão segue o media type do arquivo:
| O que é publicado | O arquivo que um cliente OCI genérico grava |
|---|---|
| uma entidade publicada como seu documento | entity.yaml |
| uma entidade publicada com os arquivos que declara | entity.tar.gz |
| um Plugin | entity.yaml, a entidade, ao lado de entity.wasm, seu executável |
| uma assinatura anexada a um artefato | signature.json |
| um marcador de descontinuação anexado a um artefato | deprecation.json |
um artefato de dados publicado com aggrega push-artifact | o nome dado com --name |
Assim, oras pull hub.aggrega.ai/component/core/compute/server:1.0.0 -o ./server deixa a entidade publicada em ./server/entity.yaml, byte a byte como foi publicada. oras ignora um descritor que não tem nome e ainda assim informa sucesso, e é por isso que todo descritor que uma publicação empacota tem um. O nome é derivado apenas do media type, nunca do nome do arquivo que foi publicado, de modo que os mesmos bytes publicados a partir de um arquivo com outro nome produzem o mesmo manifesto. Uma entidade publicada com seus arquivos chega como seu pacote: entity.tar.gz nomeia o pacote, e a entidade dentro dele é encontrada pela regra acima, e não por qualquer nome de arquivo. A própria resolução do Aggrega nunca lê esses nomes — ela seleciona cada arquivo pelo seu media type e confia nele pelo seu digest —, então eles existem para todos os outros clientes.
7. A arquitetura da Recipe: ponteiros e mappers
Consulte entities/recipe para a superfície completa de autoria da Recipe — source: (ponteiro), valuesMapping: (mapper, com três modos de autoria: block scalar inline, $import: de arquivo, $import: de biblioteca para uma entrada de uma MappingLibrary), schemas de origem orientados por Wasm, suporte nativo a IaC e exemplos completos.
8. O registry padrão e as URIs abreviadas sensíveis ao contexto
Para eliminar o inchaço do YAML, o compilador resolve URIs abreviadas de forma sensível ao contexto, de acordo com a posição do schema em que aparecem. O registry padrão é configurado em .aggrega-config.yaml (com hub.aggrega.ai como padrão).
Um host de registry tem uma única leitura. Cada registries[].host é escrito como o próprio host — um nome de host em minúsculas contendo um ponto, localhost, um único nome seguido de uma porta, um endereço IPv4 ou um endereço IPv6 entre colchetes, cada um com um :port opcional, e sem esquema, caminho, credenciais ou letras maiúsculas —, porque essa grafia é a chave sob a qual cada política de confiança por registry é encontrada, e o requisito de assinatura integrado do hub oficial está vinculado a hub.aggrega.ai. default_registry nomeia um host da mesma forma e pode ser seguido de um caminho de repositório, como ghcr.io/acme: tudo o que é publicado por meio do padrão vai então para esse caminho, e toda referência curta é resolvida sob ele, enquanto a confiança continua sendo decidida apenas pelo host. default_registry pode, em vez disso, ser escrito como o name: de uma entrada de registries, e então representa o host dessa entrada. O nome é lido uma única vez, enquanto a configuração é resolvida, em relação às entradas em vigor após cada arquivo de configuração e o ambiente, de modo que todo leitor do padrão — a publicação, a vinculação de local, a verificação de assinaturas e toda consulta de confiança — lê o host dessa única entrada, e nenhum deles chega a um host escrito como o nome; um nome seguido de um caminho é recusado, já que um nome representa uma entrada e não um local. Um nome é comparado antes de uma grafia de host, e um nome que duas entradas têm é recusado como ambíguo. A mesma leitura decide três coisas que um pull faz com o host: o local de registry ao qual uma identidade de catálogo sem host é vinculada, se o artefato baixado sequer nomeia um registry cuja assinatura é verificada, e qual política de confiança essa verificação usa. Uma grafia que poderia alcançar um registry sem encontrar sua política — maiúsculas, uma porta HTTPS padrão explícita, um esquema, credenciais, um caminho no host de uma entrada de registries — é recusada onde é configurada, indicando a grafia a ser escrita, e o mesmo vale para um único nome sem porta que não nomeia nenhuma entrada, que é a forma do primeiro segmento de uma identidade de catálogo e não de um host. A recusa se aplica em cada camada que pode definir o valor: o arquivo de configuração, onde o schema declara a mesma forma como padrão em cada registries[].host; a variável de ambiente AGGREGA_DEFAULT_REGISTRY; e a linha de comando. Assim, todo host que uma configuração pode nomear é um cujos artefatos são verificados de acordo com a política escrita para ele. O host é julgado apenas por sua grafia; se o nome é resolvido, ou se um registry responde ali, é estado de tempo de execução que o compilador nunca consulta. configuração detalha as formas aceitas com exemplos.
URIs abreviadas são resolvidas de forma sensível ao contexto em relação ao Manifest; consulte ../language-reference/entities/manifest.md §URIs abreviadas sensíveis ao contexto para as regras de inferência específicas.
Gerenciando registries
aggrega registry gerencia os registries que o workspace conhece e sua política de confiança de assinaturas. A identidade de um registry é seu host; os subcomandos compartilham um único modelo de endereçamento:
aggrega registry add <host>registra um registry e fixa sua política de confiança, buscando a política anunciada pelo registry no primeiro contato, a menos que flags de confiança forneçam uma manualmente. Um--name <alias>opcional associa um alias amigável à mesma entrada indexada por host — o host continua sendo a identidade, e o alias é resolvido para ele onde quer que um registry seja nomeado. Um alias é único entre os registries.aggrega registry listexibe cada registry configurado — host, alias, um breve resumo da postura de confiança e um marcador no padrão — em ordem crescente de host. Ele lê a configuração resolvida e não acessa nenhuma rede.aggrega registry remove <name|host>remove a entrada de política de confiança de um registry, indicada pelo seu host ou pelo seu alias. Ele remove apenas a política de confiança: o ponteirodefault_registrypermanece intacto e a possibilidade de fazer push para esse host não é afetada, de modo que o host volta à confiança padrão em vez de se tornar inacessível. Umdefault_registryescrito como o nome da entrada removida deixa de nomear qualquer coisa e é recusado até ser reescrito.aggrega registry updateatualiza o índice pesquisável local, descrito a seguir.
Onde quer que um registry seja nomeado — um argumento de um subcomando registry ou a flag --registry em aggrega push e aggrega push-artifact —, o mesmo resolvedor interpreta o token: um alias configurado é resolvido para seu host, e qualquer outro token é lido como o host que nomeia, descartando o esquema, o caminho e as credenciais de uma referência. Onde esse host se torna algo em relação ao qual uma decisão de assinatura é tomada — o destino de aggrega push ou aggrega push-artifact, ou a chave sob a qual aggrega registry add grava uma entrada —, ele é submetido à única leitura descrita acima e recusado, indicando a grafia a ser escrita, quando não está escrito dessa forma. Um host não registrado escrito dessa forma é um destino legítimo e é aceito.
O índice pesquisável local
aggrega registry update [<name|host>] constrói um índice pesquisável local dos registries que o workspace conhece. Ele percorre os repositórios de cada registry configurado, seleciona a versão lançada mais alta de cada um, lê as anotações de manifesto pesquisáveis dessa versão (§6) e grava um índice por registry no cache de artefatos. Sem argumento, ele indexa cada registry configurado; com um único argumento de registry (um host ou um alias), indexa apenas esse.
O índice segue o modelo de atualização explícita conhecido dos gerenciadores de pacotes: registry update é o comando que contata os registries, e um aggrega search posterior lê o índice gravado offline. O arquivo de registros de um registry é determinístico — duas atualizações sobre o mesmo estado do registry produzem bytes idênticos, e o carimbo de data e hora de atualização fica em um arquivo irmão para nunca perturbar os registros. Um repositório sem nenhuma versão lançada, ou que não pode ser lido, é ignorado, de modo que um único repositório ilegível nunca faz abandonar o índice inteiro.
O snapshot publicado do catálogo
Cada publicação do catálogo da biblioteca padrão também publica o catálogo como um todo: um único artefato OCI, um tar compactado com gzip de todos os arquivos que a árvore do catálogo contém no commit que essa publicação publicou, em catalog/snapshot sob o registry no qual o catálogo é publicado — hub.aggrega.ai/catalog/snapshot para o hub oficial. Ele só é enviado depois que todas as entidades dessa publicação estão no registry, de modo que não nomeia nenhuma entidade que o registry não contenha. Ele recebe como tags o commit a partir do qual foi construído e latest, e é assinado sem chave pelo publicador, como toda entidade da publicação, de modo que a identidade do publicador o verifica sob a política de confiança do registry; latest passa para um snapshot somente depois que ele é assinado. O arquivo compactado é gravado em um único layout fixo — entradas em ordem crescente de nome, cada uma com o mesmo modo, proprietário e horário de modificação — de modo que um mesmo commit sempre produz o mesmo tar.
Seu único leitor é uma importação cujo workspace não nomeia nenhuma pasta de catálogo: nenhum workspace.catalog_dirs, nenhum AGGREGA_CATALOG_DIRS e nenhum diretório catalog/ na raiz do workspace. aggrega import, a importação da sessão do editor e a ferramenta de importação do assistente executam a mesma operação, de modo que cada um obtém o snapshot da mesma forma. A importação o busca no registry padrão do workspace pelo mesmo controle de tráfego de saída e o mesmo login de um pull, verifica sua assinatura sob a política de confiança desse registry antes de guardar qualquer coisa, guarda-o no cache de artefatos do workspace e o lê lá como uma pasta de catálogo, vinculado ao seu digest — assim o importador recebe os Components do catálogo, e --target rascunha um Manifest a partir de suas Recipes, exatamente pelo caminho que uma pasta de catálogo segue. O registro que a importação grava ao lado de seus rascunhos nomeia o snapshot pelo digest de seu manifesto, de modo que uma importação posterior dos mesmos rascunhos lê o mesmo catálogo sem nenhuma requisição, e aggrega import --upgrade busca o snapshot mais recente e passa a importar com base nele. No modo offline, uma importação que precisaria buscar um snapshot é interrompida, nomeando o que executar. Um workspace que nomeia uma pasta de catálogo importa com base nela e não busca nenhum snapshot. Nenhum outro comando lê o snapshot: um pull, um build e uma validação resolvem cada entidade pelos níveis da §5 e a fixam no lockfile, e os rascunhos de uma importação referenciam entidades do catálogo pelo nome, de modo que construí-los resolve essas entidades da mesma forma.
9. Fixação por lockfile e imutabilidade de artefatos
A disciplina de fixação por lockfile ancora cada dependência a um artefato específico endereçável por conteúdo. Na primeira resolução do lockfile (aggrega pull), o resolvedor consulta o registry, escolhe uma versão de acordo com a restrição de três formas da URI (exata / intervalo / sem versão) e grava a versão fixada + o digest no <release-stem>.lock da Release. As invocações seguintes de aggrega build usam os valores fixados independentemente da mutabilidade do registry; novas versões podem ser publicadas sem afetar o lockfile existente.
O modelo de fixação carrega uma regra fundamental: uma vez que um name:version é publicado em um registry e resolvido para o digest D, esse mapeamento é permanente. Republicar o mesmo name:version com conteúdo diferente é rejeitado no momento do push. O próprio aggrega push impõe isso em cada publicação: ele resolve o artefato existente em name:version no registry de destino; se estiver presente e o digest corresponder ao conteúdo prestes a ser enviado, o push não envia nada e anexa apenas o que ainda falta a essa publicação — sua data de publicação, e sua assinatura onde o push assina; se estiver presente e o digest for diferente, o push é interrompido com um erro de violação de imutabilidade que cita ambos os digests.
A imutabilidade importa por duas consequências:
- As fixações do lockfile são confiáveis. Quando o lockfile registra
mariadb:1.0.0no digestD, um build que busca por digest recebe os bytes deD. Sem imutabilidade, uma alteração no lado do registry poderia substituir os bytes deDpor baixo da fixação do lockfile, comprometendo a estabilidade entre o momento do lock e o momento do build. Builds reproduzíveis dependem dessa garantia. - Alterações de metadados após a publicação têm um caminho claro. Marcar uma versão publicada como descontinuada, rotacionar chaves de assinatura ou corrigir atestações não pode ser feito alterando o artefato publicado (a regra o proíbe). Isso deve ser feito publicando uma nova versão de patch ou um artefato sidecar que registre separadamente a alteração de metadados. Ambos os caminhos são auditáveis — uma nova versão ou um sidecar aparece como uma entrada distinta do registry — e nenhum altera os bytes do artefato original.
A regra de imutabilidade se aplica uniformemente a todo artefato do Aggrega publicado via OCI (entidades, SchemaLibrary, MappingLibrary, plugins Wasm referenciados pelo pipeline[].plugin: de uma Recipe / pelo pipeline[].plugin: de uma FeatureRecipe / pelo plugins.{governance,linter,importer}[]: da configuração do workspace). Tudo o que é fixado por name:version mais um digest de conteúdo no lockfile está sujeito à imutabilidade.
A imutabilidade é incondicional, e nenhuma configuração a relaxa. Não há nenhuma flag nem nenhuma configuração do workspace que permita uma sobrescrita, porque o registry não expõe nenhum caminho de sobrescrita que um operador possa ativar. Conteúdo que mudou é publicado sob uma nova versão, e aggrega lint --pre-publish verifica se o incremento de versão corresponde à classificação da mudança.
A nova resolução para uma versão mais recente exige uma ação explícita do usuário: aggrega pull --upgrade --release <release> <uri> resolve novamente uma única dependência mantendo todas as outras fixações, e aggrega pull --upgrade --release <release> resolve novamente todas as dependências em relação ao estado atual do registry. Dependências em forma de intervalo e sem versão são resolvidas novamente para a versão mais recente correspondente; fixações em forma exata não se movem, a menos que o usuário faça explicitamente o upgrade para outra versão exata. O lockfile é a fonte da verdade para os builds; a forma digitada pelo usuário expressa a restrição de versão no momento da autoria.
10. Aplicação da forma dos nomes de entidades de catálogo
Os nomes de entidades de catálogo seguem padrões por tipo de entidade — enumerados abaixo e detalhados por tipo na Visão geral da referência de entidades. Eles são uma superfície diferente dos nomes de instância que um desenvolvedor escreve em um Aggregate ou em uma Release, que compartilham um único padrão independentemente do tipo; esse padrão está em ../language-reference/02-naming-conventions.md “Nomes de instância”. O campo metadata.name que um YAML de catálogo declara nem sempre é idêntico à URI de referência canônica da entidade: Component e Feature incorporam os segmentos de publicador e de agrupamento diretamente em metadata.name; Recipe e FeatureRecipe declaram um metadata.name composto apenas pela folha, e sua URI canônica de dois segmentos combina essa folha com a spec.capability que a entidade declara; cada tipo de biblioteca declara um token PascalCase em metadata.name.
Formas por tipo de entidade:
- Component — três segmentos kebab-case
{publisher}/{category}/{name}declarados emmetadata.name. Exemplo:core/datastore/postgres. - Feature — dois segmentos kebab-case
{publisher}/{name}declarados emmetadata.name. Exemplo:core/data-masking. - Recipe — uma única folha kebab-case em
metadata.name(por exemplo,postgres). A URI de referência canônica{capability}/{name}(conforme o §6 acima) combina aspec.capabilitydeclarada da entidade com essa folha; o segmento inicial é comparado comspec.capability, não com a localização da entidade no disco, de modo que mover umrecipe.yamlnão muda a forma como ele é referenciado. O catálogo da biblioteca padrão coloca a entidade em<catalog-root>/recipe/<capability>/<name>/<version>/recipe.yamlpara que a árvore espelhe a coordenada, mas esse espelhamento é uma convenção do catálogo e não a origem da URI. Uma referência também pode nomear a receita sozinha — apenas a folha, sem segmento de capability —, que é a forma predominante na prática e é resolvida sempre que uma única receita no catálogo tem o nome. Nenhum segmento de publicador aparece em uma URI de Recipe, e uma referência com um terceiro segmento não corresponde a nenhuma receita. - FeatureRecipe — uma única folha kebab-case em
metadata.name(por exemplo,k8s-secret-from-parameter), simétrica à Recipe: URI canônica{capability}/{name}a partir daspec.capabilitydeclarada mais a folha, a folha sozinha aceita da mesma forma, e a árvore<catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yamlespelhando a coordenada por convenção. - Os tipos de biblioteca — SchemaLibrary, MappingLibrary, WorkloadLibrary e ArtifactLibrary — um único token PascalCase em
metadata.namecorrespondente a^[A-Z][A-Za-z0-9]*$(por exemplo,BaseComponents,AIDatastores,BaseWorkloads). A forma é a mesma em todos os tipos de biblioteca, de modo que mover uma entrada entre bibliotecas nunca significa renomeá-la segundo uma convenção diferente. O envelope JSON Schema de cada tipo de biblioteca também declara o padrão, além da verificação descrita abaixo.
Para Component, Feature, Recipe e FeatureRecipe, o JSON Schema de metadata.name aceita qualquer string não vazia, de modo que nada na forma é estrutural para esses tipos. Toda forma documentada — incluindo os tipos de biblioteca, cujos envelopes também declaram seu padrão — é verificada pelo plugin de disciplina de publicação, que carrega os padrões como uma fonte da verdade em regex compartilhada com a distribuição do compilador. Nenhum tipo recebe aqui uma forma que o plugin depois ignore.
A verificação é opcional: um único comando a executa, e ela só é executada quando um autor a solicita. Os dois comandos que com mais frequência se supõe que a executem não o fazem:
aggrega lintrelata violações da forma dos nomes. O plugin compara ometadata.namede cada entidade com o padrão do seu tipo. A verificação é executada quando um autor invocaaggrega lint— sobre uma única entidade, sobre o fechamento de dependências de uma Release com--release, ou sobre cada entidade do catálogo quando invocado sem argumento —, e o mesmo conjunto de regras pode ser acessado pela superfície de ferramentas voltada ao editor que a CLI expõe. As constatações são consultivas: são relatadas com severidadewarne não interrompem nada.
warn: E0278 name-shape: metadata.name "mariadbSynth" does not match the documented pattern for Recipe entities (^[a-z][a-z0-9-]*$)A constatação começa com sua severidade e o código curto sob o qual sua regra está registrada, que aggrega explain E0278 expande. O caminho do arquivo em questão é exibido acima da constatação, e uma execução sobre o catálogo inteiro termina com uma contagem das entidades verificadas e das constatações consultivas geradas.
aggrega buildnão verifica a forma dos nomes. A saída renderizada não depende dos nomes das entidades do Aggrega, de modo que um build sobre um catálogo com nomes não conformes não emite nenhum aviso nem nenhum diagnóstico e é bem-sucedido exatamente como seria de outra forma.aggrega pushtambém não verifica a forma dos nomes. A publicação recusa por outros motivos — principalmente a regra de imutabilidade acima, segundo a qual republicar umname:versionexistente com conteúdo diferente é interrompido. Quando uma recusa nomeiaaggrega lint --pre-publish, ela está dizendo ao autor qual comando executar; o push não o executa.
Como nem o build nem a publicação verificam a forma, um catálogo que deseja que a convenção seja seguida executa aggrega lint deliberadamente — em um hook de pre-commit ou como etapa de um pipeline. Observe que uma constatação de forma de nome é consultiva: aggrega lint a relata e ainda assim termina com sucesso, de modo que um pipeline que queira condicionar sua passagem à convenção lê as constatações relatadas em vez de depender do status de saída.
Uma política por workspace suprime a regra:
# .aggrega-config.yaml — lint sectionlint: publishing_discipline: allow_nonstandard_names: true # default falseCom a política definida, a regra de forma dos nomes não relata absolutamente nada. Ela também pode ser definida para uma única invocação com aggrega lint --allow-nonstandard-names, ou forçada a desligar novamente com --no-allow-nonstandard-names. Os usos legítimos são catálogos que nunca serão publicados, experimentos com vários publicadores e entidades de propósito especial.
11. Expansão de Feature orientada por anotações
O bloco mappings.features.annotations do Manifest declara vínculos entre chaves de anotação e tipos de Feature, além de uma tabela de roteamento agrupada por pilar (maps.infra, maps.values) que nomeia as propriedades do schema da Feature que cada anotação pode preencher. A subfase de expansão de anotações da resolução percorre os limites da Release de fora para dentro e os subsistemas do Aggregate de fora para dentro, calcula os conjuntos efetivos de anotações por componente por meio de cascata e sobrescrita com opt-out null do valor inteiro e por subchave, e injeta anexações sintéticas de Feature que trazem origin: annotation em sua proveniência IR. O ensino completo sobre a forma dos vínculos e a autoria está em language-reference/entities/manifest.md e language-reference/providers/well-known-annotations.md; esta seção documenta os mecanismos em tempo de carregamento do catálogo e em tempo de inspeção dos quais o caminho de expansão depende.
Cache de compilação de schemas. O spec.schema.{infra,values} de cada Feature é compilado uma vez por build e reutilizado entre os percursos em cascata. A validação de tipo repetida por subchave em relação ao mesmo schema de Feature (um escopo de cascata por componente, para centenas de componentes) lê o schema compilado em vez de compilá-lo novamente. Nada é mantido entre builds, de modo que um schema de Feature alterado é compilado do zero pelo build seguinte.
Validação dos destinos de vínculo (carregamento do catálogo). No carregamento do catálogo, o compilador percorre cada vínculo features.annotations do Manifest e verifica se cada caminho pontilhado declarado em maps.infra e maps.values corresponde a uma propriedade que o spec.schema.<pillar> da Feature referenciada realmente declara. Um vínculo que roteia para um caminho que o schema da Feature não lista interrompe o carregamento do catálogo com um OPS_ERROR claro que nomeia a chave do vínculo, o caminho ausente, a URI da Feature e o local no código-fonte.
Lint de sobreposição de pilares do schema (carregamento do catálogo). Um aviso consultivo é emitido quando o spec.schema de uma Feature declara o mesmo nome de propriedade nos dois pilares, infra e values. A sobreposição raramente é intencional — propriedades com o mesmo nome em pilares diferentes confundem a intenção de autoria (qual pilar é acionado quando uma anotação aponta para o nome compartilhado?) e complicam as mensagens de diagnóstico. O aviso não é bloqueante e não tem opt-out: um autor que pretende a sobreposição a mantém junto com o aviso, e um que não a pretende renomeia a propriedade em um pilar.
Lint de sobreposição dos mapas de vínculo (resolução). Um aviso consultivo é emitido quando um caminho de subchave aparece tanto em maps.infra quanto em maps.values nos vínculos do Manifest. Um caminho que aparece nas duas listas de pilares é incoerente — uma única subchave de anotação não pode rotear para os dois pilares simultaneamente, e o desempate determinístico que o compilador aplica (um caminho presente nas duas listas roteia para infra; uma anotação escrita no Aggregate só pode rotear por values, então uma escrita ali para esse caminho é recusada) é uma rede de segurança, não uma forma de autoria pretendida. O aviso não é bloqueante; os autores que executam ignorando o aviso ainda obtêm um build limpo, com o desempate visível na proveniência IR.
Exibição da proveniência em aggrega inspect. O comando inspect exibe um colchete por anexação de Feature, registrando a origem de cada folha preenchida:
[explicit]— a Feature foi anexada explicitamente por meio de um blocofeatures:de um Aggregate ou de uma Release.[annotation: <key> from <source>]— cada folha preenchida veio da mesma chave de anotação. O colchete nomeia a chave e onde a anotação foi declarada: o arquivo e o caminho de chave pontuado dentro dele.- Colchetes por folha — composição entre lados em que cada folha preenchida é exibida com seu próprio colchete de origem (algumas
[explicit], algumas[annotation: <key> from <source>]). Essa forma evidencia a mesclagem em que o explícito vence campo a campo: quando uma anexação explícita e uma contribuição de anotação apontam para a mesma instância de Feature no mesmo Component, mas escrevem folhas diferentes, ambas as contribuições permanecem em suas respectivas folhas e a saída do inspect nomeia individualmente a origem de cada folha.
A exibição do inspect lê os mapas por pilar values_provenance e infra_provenance da IR — preenchidos durante a expansão de anotações junto com a injeção das anexações sintéticas — e emite a forma de colchete que melhor resume a origem coletiva das folhas. O mecanismo do inspect é a superfície de introspecção canônica para entender por que uma determinada anexação de Feature foi parar em um determinado Component e de onde vieram seus valores.