Catálogo e registo
Este capítulo define a forma como a plataforma escala na empresa através do catálogo Open Container Initiative (OCI): como o catálogo está 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 registo
O compilador Aggrega depende de um registo estritamente tipado, inspirado no OAM, para resolver a intenção abstrata do programador (Domínio 1) na realidade concreta de Ops (Domínio 3). Para suportar um ecossistema aberto e distribuído mantendo uma experiência de programador fluida, todos os esquemas, associações de infraestrutura, políticas programáveis e plugins adaptadores seguem uma taxonomia de URI Open Container Initiative (OCI) normalizada. Como todas as entidades de catálogo são endereçáveis por URI, aggrega pull obtém para a cache as que uma Release precisa e fixa-as no seu lockfile, e uma compilação lê-as a partir daí. O espaço de trabalho local do programador contém apenas os seus ficheiros de Aggregate e de Release, não uma cópia do catálogo.
1. Estrutura de diretórios central (o catálogo)
A pasta aggrega-catalog da biblioteca padrão (e qualquer catálogo de terceiros conforme) está organizada de forma a impor fisicamente a separação de responsabilidades. A estrutura separa explicitamente as interfaces abstratas das suas implementações concretas de infraestrutura.
Para Components e Features, os segmentos de URI correspondem 1:1 aos segmentos do caminho no sistema de ficheiros. Os Components usam um URI de três segmentos ({publisher}/{category}/{name}) em que o segmento de categoria contém uma de um conjunto fechado de categorias cognitivas — a mesma palavra que a etiqueta 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 lentamente. A classificação na ontologia operacional (stateful-server, server, etc.) vive na etiqueta component.aggrega.ai/type, nunca na estrutura de diretórios; as etiquetas de capacidade cognitiva (datastore.aggrega.ai/engine, agent.aggrega.ai/autonomy, …) sobrepõem subconjuntos comportamentais. A interface web do hub usa etiquetas para filtragem e pesquisa; as categorias servem tanto a navegação no sistema de ficheiros como o eixo de navegação do catálogo.
A árvore abaixo é ilustrativa no seu conteúdo e exata na sua forma. Quando uma entidade é desenhada por inteiro, desce até ao seu ficheiro folha, pelo que um caminho real completo pode ser lido no diagrama: que nível de diretório contém que segmento de URI, onde fica o segmento de versão obrigatório e que nome de ficheiro cada tipo de entidade usa na folha. Mostra algumas entradas por nível em vez de todo o conteúdo do catálogo — ... assinala 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 ficheiros — é a autoridade sobre as categorias. Um valor de categoria ainda sem nenhuma entidade é vocabulário reservado: o eixo de navegação mantém-se estável e um autor sabe onde ficará um componente futuro, pelo que uma prateleira vazia está correta e não é uma vaga à espera de ocupante. Como o catálogo não contém ficheiros de marcação de lugar, o diretório de um valor destes é criado quando chega a sua primeira entidade.
A lista de referência — cada categoria, o que contém, os valores operacionais de type que as suas entidades transportam tipicamente e que diretórios existem — é a secção Component Categories do guia de convenções do catálogo, publicado ao lado do catálogo da biblioteca padrão que rege.
O eixo type contém apenas as primitivas operacionais — o vocabulário cognitivo nunca aparece nele, e o esquema de Component publicado enumera os valores que a chave reservada aceita, pelo que uma palavra cognitiva aí escrita é 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 é, espelhado pelo diretório) e etiquetas de capacidade por papel (subconjuntos comportamentais — uma entidade é category: datastore mais o valor de datastore.aggrega.ai/engine que a identidade do seu próprio produto tiver, pelo que core/datastore/qdrant transporta vector e core/datastore/redis transporta kv, e ambos os eixos são consultáveis). Uma capacidade cuja veracidade dependa do que um autor configura não é transportada no catálogo: é injetada em tempo de compilação pelo papel label-transform do socket de governação, que lê os values declarados pelo programador. As categorias puramente de IA têm o prefixo ai-; as categorias de dupla utilização aparecem sem prefixo, sendo o seu carácter de IA expresso por etiquetas de capacidade. As categorias são escolhidas pela forma como os utilizadores navegam e procuram, não pela forma como o compilador classifica — o vocabulário de categorias e as etiquetas de capacidade são termos com os quais o compilador compara seletores sem lhes atribuir significado. O nome de um componente não repete a sua categoria: o modelo 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 ponte
Para eliminar o boilerplate 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 vive o seu objeto:
usesSchema(YAML declarativo). Declara os sockets de topologia que uma entidade de catálogo oferece e dá a cada um um contrato. A CLI Go lê-o nativamente para extrair as cadeiasselector:para a correspondência de etiquetas durante a análise estática e para validar os mecanismosinjectpermitidos. Cada entrada de socket suporta um campo opcionalrequired: true(predefiniçãofalse) — quando definido, o compilador emite um erro de validação se nenhuma dependência for declarada nesse socket. É a contrapartida, para sockets, da semânticarequired: truenas entradas defeaturesSchema: ambas interrompem a compilação. Declarar aqui um socket é o que o catálogo da biblioteca padrão faz e continua a ser o melhor caminho — mas não é a única forma de um programador traçar uma aresta. Um autor de Aggregate pode nomear no seu próprio componente um socket que esteusesSchemanão declara, incluindo numa entidade que não declare nenhumusesSchema; um socket ad hoc destes não transporta seletor, allowlistinjectnem esquema por aresta, precisamente porque não há aqui nenhuma entrada para os transportar. Ousesde um anexo de Feature e ousespor aresta de uma Release não estão abertos dessa forma — ambos só podem nomear um socket declarado. Ver dependency-resolution §«Domínio 2: o esquema dividido» para o contrato completo e para aquilo de que um socket ad hoc abdica.- Dessugarização. Se os programadores usarem a abreviatura de array YAML (
uses: databases: ["db1"]), a CLI normaliza-a num mapa ({"db1": {"target": "db1"}}). - Síntese da ponte. O compilador projeta a tabela de slots
featuresSchema:num fragmento JSON Schema 2020-12 — uma propriedade por slot de anexo, que descreve a forma de um preenchimento que o pode associar, com uma palavra-chave de extensãox-aggrega-inject:num slot que declare uma allowlistinject. A validação JSON Schema ignora as palavras-chave de extensão durante a validação estrutural, e nada a volta a ler do fragmento: uma verificação que precise da allowlist 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 Architect escreveu e são lidos daí, e ovalueSchema:/infraSchema:por aresta de um socket é envolvido e compilado por si, sem nenhuma restrição inventada à sua volta. - Composição. O Platform Architect 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 por si: nem o fragmento de slots nem a tabela de sockets são incorporados nela. Cada superfície é verificada onde vive o seu objeto, pelo que uma falha de socket é reportada sobre a entrada de socket que o Architect escreveu, e não num caminho dentro do blocoschema:— e o Architect continua a não escrever nenhum boilerplateuses.
Exemplo — uma declaração de socket e o que o compilador faz com ela: O YAML do Platform Architect
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 é: a cadeia selector: vai para o motor nativo de correspondência de etiquetas, e a lista inject: restringe os mecanismos de entrega que uma aresta através desse socket pode nomear. O bloco schema: é compilado em separado, como o contrato values / infra / provides próprio da entidade. O analisador estático lê a cadeia selector: da entrada de socket que o Architect escreveu — juntamente com appliesTo / appliesToAnyOf das entidades Feature — e avalia a correspondência de etiquetas face aos metadata.labels de cada destino para validar a segurança de tipos entre nós.
Seletores ao estilo Kubernetes no usesSchema
O motor nativo de correspondência de etiquetas do compilador Go avalia as cadeias de seletor com a semântica de seleção normal ao estilo Kubernetes (AND através de vírgula, OR através de in(), NOT através de !=/notin()). Este mesmo motor — e a mesma gramática de cadeias de seletor — também avalia os seletores de anexo de Features (appliesTo e cada item de appliesToAnyOf). A camada de seletores é estritamente a barreira de topologia — as declarações schema: por pilar validam o conteúdo values, infra e provides de forma independente. Depois de o compilador Go traçar as arestas topológicas na construção da topologia, o analisador estático lê as cadeias selector das entradas de socket que o Architect escreveu e avalia-as face à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 motor não consiga ler como uma das suas seis formas de requisito — um requisito vazio, uma chave que contenha espaços em branco ou um de =, !, (, ) e a vírgula, um conjunto não fechado — interrompe a compilação em cada aresta que protege, em vez de ser lido como outro seletor. A gramática de seletores lista as formas e todas as recusas.
3. Formatos de esquema e composição
Para fornecer simultaneamente uma validação estrita e metadados de catálogo normais (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: incorporadas, expressas em forma compacta (a predefinição; ~15 palavras-chave, transformadas mecanicamente em JSON Schema 2020-12) ou em JSON Schema YAML completo.
Porque é que cada YAML de catálogo repete o envelope. O envelope (apiVersion, kind, bloco metadata) aparece no topo de cada ficheiro de catálogo — Component, Feature, Recipe, FeatureRecipe, Aggregate, Manifest, Release, Plugin — independentemente de quão curto seja o corpo. A repetição é deliberada: cada ficheiro foi concebido para ser analisado, validado, sujeito a lint e inspecionado como um artefacto autónomo. Um único ficheiro obtido do registo OCI, colocado numa sandbox de CI ou aberto num editor de terceiros tem de conter autodescrição suficiente para que as ferramentas a jusante consigam identificar que tipo de entidade representa e que versão de esquema se aplica. A localização do diretório nunca substitui o envelope: todos os analisadores, validadores e linters leem o tipo da entidade e a versão de esquema do envelope. O custo é um boilerplate mecânico por ficheiro; o benefício é que a garantia de ferramentas autónomas se mantém na superfície de distribuição OCI, no sistema de ficheiros local e nas superfícies de IDE / CI / inspeção. Os autores copiam o envelope de ficheiros 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), o catálogo emprega dois mecanismos de composição distintos:
- Entradas de SchemaLibrary partilhadas (
$ref:entre documentos): as definições JSON Schema reutilizáveis são guardadas em entidades de catálogo SchemaLibrary (nível 3). São referenciadas pela identidade através de$ref:entre documentos (<library>#/schemas/<entry>, sem host — a versão vem do lockfile) a partir de qualquer esquema consumidor de Component ou de Feature. A cadeia é percorrida em tempo de compilação. Ver entities/schemalibrary para a forma de autoria da entidade de biblioteca e vocabulary/cross-document-ref para a semântica da resolução. - Herança simples (
extends): para baselines de componentes completas, as entidades podem usar a propriedadeextends: "URI". O compilador Go lê recursivamente a cadeia de pais e funde em profundidade os metadados YAML (substituindo as etiquetas em caso de conflito e acrescentando aos arrays). Os dois tipos de catálogo separam-se então nos pilares de dados. Oschema:de uma Feature compõe-se com o da sua base segundo a composição JSON Schema 2020-12. Um Component que estende não escreve qualquer conteúdo de pilar: escreve o marcador literalschema: inheritede recebe o blocoschema:da sua base exatamente como a base o escreveu, a todas as profundidades de uma cadeia. O que um Component destes compõe, em vez disso, é estrutura — os seus slots de anexo (featuresSchema), sockets de topologia (usesSchema), allowlist de autoinjeção (inject) eassertionsnomeadas fundem-se todos ao longo da cadeia. Ver 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 a ser uma regra de disciplina de publicação.
Ver entities/component para os exemplos de extensão de componentes base e filho, e entities/recipe para a autoria de Recipes de ponteiro e mapeador, com exemplos completos.
4. A configuração do espaço de trabalho (.aggrega-config.yaml)
O ficheiro .aggrega-config.yaml na raiz do espaço de trabalho é a configuração do espaço de trabalho do projeto — a declaração própria do espaço de trabalho, adequada ao controlo de versões tal como go.mod ou package.json. Por convenção, o diretório .aggrega/ fica fora do controlo de versões — inclua-o em .gitignore, tal como faria com node_modules/ ou .terraform/.
A secção workspace é o marcador da raiz: a sua presença marca a raiz do espaço de trabalho, e contém 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 definições ficam no nível superior. Muitas são valores únicos; outras são secções que reúnem as definições de uma preocupação sob uma única chave. Todos os campos são opcionais, com predefinições documentadas. O conjunto completo e atual de chaves de nível superior, cada uma com o seu tipo, predefinição e significado, é gerado a partir do esquema em schema/other/aggrega-config; o exemplo abaixo mostra o marcador da raiz ao lado de algumas das definiçõ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: contém as predefinições de assinatura de artefactos usadas por aggrega push --sign e aggrega sign, tanto ao nível superior (global) como por registo:
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 registo > signing global > predefinição pública. O Fulcio e o Rekor usam por predefinição as instâncias públicas do Sigstore, pelo que são opcionais; timestamp_url não tem predefinição — o carimbo temporal fidedigno sem chave vem da inclusão no registo de transparência do Rekor, e uma autoridade de carimbo temporal RFC3161 é opcional (defina timestamp_url, ou --timestamp-url, com um endpoint completo para ativar uma). Segurança: o bloco signing: não contém 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 através de um fluxo no navegador num terminal interativo ou a partir do workflow no GitHub Actions e, caso contrário, passado com --identity-token ou exportado como AGGREGA_IDENTITY_TOKEN ou SIGSTORE_ID_TOKEN), e a chave privada nunca é inline; key_path é um caminho para um ficheiro de chave. É esta a assimetria deliberada em relação ao lado da verificação, que fixa uma chave pública inline, mas apenas um caminho de chave do lado da assinatura.
Marque uma raiz sem catálogos incorporados escrevendo workspace: {}. A lista catalog_dirs suporta configurações de monorepo em que um catálogo partilhado vive num diretório irmão. O compilador verifica cada diretório em sequência. A flag offline: true impede qualquer acesso à rede — o compilador usa apenas caminhos locais e a cache, interrompendo a compilação se uma entidade não for encontrada localmente. As definições por secções reúnem, cada uma, uma preocupação. Entre elas: os controlos de rigor em tempo de compilação e as sugestões de autoria; os sockets de anexo Wasm ao nível do espaço de trabalho (governance, linter, importer, providers, cli), cada um com uma lista de referências de plugins; o rigor de lint por regra, incluindo os interruptores de política da disciplina de publicação; a afinação da cache de análise do daemon e a dimensão do seu conjunto de workers de despacho de pedidos; e o limite de tamanho do armazenamento de módulos compilados de toda a máquina. Outras ainda contêm as predefinições de assinatura e de confiança em assinaturas e o comportamento próprio do daemon. Cada chave de nível superior está documentada por completo em schema/other/aggrega-config.
São configuráveis três caches distintas, e vale a pena distingui-las, porque os seus nomes são semelhantes e os seus âmbitos não. artifact_cache_dir nomeia a cache de conteúdo em disco por espaço de trabalho descrita abaixo. parse_cache limita a cache de análise em memória do daemon, que só vive enquanto o daemon viver. compiled_module_cache limita o armazenamento em disco do código máquina compilado dos plugins — uma das caches partilhadas por todos os espaços de trabalho 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 capDas caches que todos os projetos da máquina partilham, é a que pode vir a dominar a utilização de cache em disco, uma vez que cada plugin que a máquina executa é compilado para ela uma vez e mantido, pelo que é a única com um limite de tamanho permanente. Cada invocação que abre o armazenamento aplica o limite antes de compilar o que quer que seja, removendo entradas inteiras, das compiladas há mais tempo para as mais recentes, até que o restante caiba. (Uma compilação executada com --disable-plugin-cache compila para a memória, pelo que nem faz crescer o armazenamento nem o reduz.) Remover uma entrada custa uma recompilação posterior e nada mais, o que torna o limite seguro de baixar e seguro de aplicar enquanto outras compilações correm na mesma máquina. Defina-o acima do que uma única compilação compila: como o limite é aplicado antes de compilar, um limite abaixo do conjunto de trabalho de uma compilação faz com que todas as compilações descartem e recompilem os mesmos módulos e, pela mesma razão, o armazenamento pode ficar acima do limite entre compilações e é reduzido de novo no início da seguinte. aggrega cache status reporta o tamanho do armazenamento, e aggrega cache evict --max-size reduz-o a pedido para um limite indicado na linha de comandos.
A raiz artifact_cache_dir contém três subárvores paralelas que uma invocação de aggrega pull povoa uniformemente, 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 os Plugins com os executáveis que publicam), em que o tipo é aquele sob o qual a entidade é publicada, pelo que duas entidades de tipos diferentes que partilham 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 artefactos de origem obtidos a partir dos campos spec.source de Recipes / FeatureRecipes (charts Helm, fragmentos compose); e <artifact_cache_dir>/inputs/sha256/<hex-digest> para inputs externos — os documentos remotos que um provider pede ao anfitrião enquanto renderiza, como um $ref no values.schema.json de um chart que aponta para um URL. Cada slot de cache de artefacto de origem contém o arquivo .tgz de referência, um diretório extracted/ derivado, regenerado em cada leitura da compilação, e um ficheiro metadata.yaml que regista a identidade {kind, url, version, digest, mediatype, pulled_at} do artefacto. Cada slot de cache de entidade contém o artefacto publicado tal como foi obtido e o manifesto OCI face ao qual é verificado. O slot de cada tipo cujo documento pode nomear um ficheiro ao lado dele — uma Recipe, uma FeatureRecipe, um Component, uma Feature — contém também um diretório extracted/ derivado com os ficheiros que esse artefacto transporta, num diretório com o nome do digest de conteúdo do artefacto: o documento e os ficheiros que a entidade declarou, quando foi publicada como arquivo, e apenas o documento, quando foi publicada como o seu documento (§6). O diretório da entidade é aí disposto a partir do artefacto verificado em cada leitura, da mesma forma que os ficheiros de um artefacto de origem: cada ficheiro é verificado face ao artefacto, um ficheiro alterado ou acrescentado à mão nesse diretório é descartado em vez de lido, nada mais sob extracted/ é lido, e um artefacto que falhe a verificação é recusado antes de qualquer coisa ser disposta. Uma leitura reescreve apenas o que difere do artefacto, pelo que compilações que leem uma mesma cache ao mesmo tempo — pedidos que aggrega serve trata lado a lado, ou dois comandos sobre um mesmo espaço de trabalho — encontram cada uma os ficheiros que lhe foram entregues completos. O segmento <digest-prefix> de 12 caracteres separa em slots distintos o mesmo {kind, url, version} reetiquetado em digests upstream diferentes. Um input externo não precisa de um slot destes: é guardado como um único ficheiro com o nome do digest de conteúdo a que o lockfile o fixa, pelo que o que uma compilação posterior lê é endereçado pela fixação e não pelo URL de onde os bytes chegaram — o que permite a essa compilação servir o input com a rede negada.
Podem aparecer mais três diretórios ao lado desses três, e nenhum contém conteúdo de dependências fixadas: index/ contém os instantâneos pesquisáveis por registo que aggrega registry update escreve (§8), signatures/ coloca em cache cada pacote de assinatura verificado sob o seu próprio digest, para que uma leitura posterior volte a verificar o blob em cache face ao digest sob o qual foi registado, em vez de obter de novo o pacote, e catalog-snapshots/ guarda cada instantâneo publicado do catálogo que uma importação leu (§8) — o arquivo e o seu manifesto num slot com o nome do digest do manifesto, com a árvore do catálogo disposta a partir do arquivo a cada leitura, e um ficheiro current que indica o instantâneo que o workspace lê quando nada indica outro.
O pacote de documentação não está entre eles. Os seus bytes dependem apenas do registo em que é publicado e da versão com que é publicado, pelo que é mantido uma vez por máquina, ao lado do armazenamento de módulos compilados, sob a mesma raiz de cache por utilizador, em docs-bundles/<encoded-reference>/<encoded-version>/ abaixo dessa raiz: o pacote, o manifesto face ao qual é verificado e as assinaturas que as suas obtenções verificaram. artifact_cache_dir não o alcança. Antes de uma página ser lida dele, essas assinaturas são verificadas de novo segundo a verificação de assinaturas do próprio espaço de trabalho que lê, para o registo do pacote, pelo que uma cópia que as definições mais permissivas de um espaço de trabalho deixaram entrar não é servida a um espaço de trabalho cuja verificação a recusa — ver aggrega-explain e aggrega-cache.
artifact_cache_dir é escrito relativamente à raiz do espaço de trabalho, e designa o mesmo diretório seja qual for o diretório a partir do qual um comando é invocado ou os diretórios de catálogo que estejam a ser analisados. Um valor absoluto é recusado quando a configuração é carregada, com um diagnóstico que nomeia o campo: todos os leitores da definição a resolvem face à raiz do espaço de trabalho, pelo que um caminho absoluto designaria uma localização que nenhum deles alcança, e a falha seria, de outro modo, silenciosa — a cache que um pull escreve deixaria discretamente de ser a cache que uma compilação lê. A cache pode estar dentro de um diretório de catálogo, e na organização predefinida está, uma vez que um diretório de catálogo é muitas vezes a própria raiz do espaço de trabalho. O que não pode é ser um diretório de catálogo: uma análise do catálogo salta a cache, pelo que um diretório de cache que seja também um diretório de catálogo retira todo o conteúdo desse diretório de todas as análises. artifact_cache_dir: . designa a raiz do espaço de trabalho, que na organização predefinida é exatamente isso, e é recusado quando a configuração é carregada, com um diagnóstico que nomeia o campo — tal como qualquer outra grafia que se reduza à raiz do espaço de trabalho. Essas duas formas, juntamente com o caminho absoluto acima, são as que a verificação da configuração consegue reconhecer por si. Um valor que designe outro diretório de catálogo — sub, num espaço de trabalho cujo catalog_dirs liste sub — carrega sem queixas, e o único sintoma é que as entidades nele deixam de ser encontradas. Manter a cache fora de todos os diretórios listados em workspace.catalog_dirs faz, por isso, parte de escrever a configuração, e não algo que ela verifique por si.
Saltar a cache é o que impede que um artefacto de resolução seja lido como se um autor o tivesse escrito. Um slot de cache contém bytes que uma obtenção do registo lá colocou, guardados sob a coordenada em que foram obtidos e garantidos por um digest do lockfile; uma análise que os apanhasse como conteúdo de catálogo escrito estaria a usar bytes que nada verificou, num caminho que o autor não pode editar. Vale a pena enunciar claramente uma consequência: se a cache contiver uma entidade que nenhum lockfile fixa — deixada por um pull interrompido, copiada à mão ou abandonada quando uma Release deixou de a referenciar —, essa entidade não é visível para uma análise do catálogo, e uma compilação ou validação que dependa dela é interrompida, indicando que a entidade não foi encontrada. A solução é fazer de novo o pull da Release, para que a entidade seja resolvida através do lockfile e o seu digest fique registado; a interrupção nomeia a entidade, para que a fixação em falta possa ser identificada. A alternativa — resolvê-la mesmo assim — é a leitura não verificada que saltar a cache existe para impedir.
O lockfile é por Release: resolver release.yaml escreve release.lock ao lado dele (o nome base do ficheiro da Release mais .lock). aggrega pull resolve as dependências e escreve o lockfile; aggrega build lê-o e usa as versões fixadas independentemente do estado do registo no momento da compilação. Os espaços de trabalho fazem commit do lockfile quando a reprodutibilidade das compilações entre máquinas é importante; depois de uma entidade, uma biblioteca, um plugin ou a própria Release mudar no espaço de trabalho, aggrega pull --release <release> atualiza-o, voltando a resolver 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 registo passe a oferecer. O lockfile regista cada entidade resolvida com o seu tipo, o seu URI tal como foi escrito, a versão resolvida, o digest de conteúdo e os locais que a referenciam. O tipo e o URI identificam em conjunto uma entrada, pelo que uma Release cujo Aggregate e cujo Manifest partilham um nome regista uma entrada para cada um, e uma edição a qualquer um deles interrompe a compilação seguinte até que um pull a registe:
# 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 contém o tipo + o URI + a versão resolvida + o digest endereçável por conteúdo. O digest é verificado em cada obtenção; bytes que não correspondam ao digest fixado interrompem a compilação com um erro de integridade. O digest de uma entidade é calculado sobre o que uma publicação dela transporta — o seu documento e cada ficheiro que declara ao lado dele, cada um pelo seu caminho e pelos seus bytes — e não sobre os bytes em que viaja, pelo que a mesma entidade regista o mesmo digest quer seja lida de um diretório de catálogo, quer obtida de um registo, seja qual for a compressão do seu arquivo e quaisquer que sejam os bits de permissão, incluindo o bit de execução, que um checkout tenha dado aos seus ficheiros. O próprio digest do registo sobre os bytes publicados é aquilo face ao qual uma obtenção é verificada primeiro, através do manifesto, cujo digest uma entrada resolvida pelo registo regista ao lado do seu.
5. O modelo de resolução de entidades em três níveis
O compilador resolve cada referência de entidade encontrada durante a compilação através de uma consulta em cascata estrita. Os três níveis — caminho local, espaço de trabalho e cache, e registo — correspondem a três fluxos de trabalho de autoria que coexistem num projeto Aggrega saudável: uma Release que nomeia os ficheiros ao seu lado, uma equipa a consumir um catálogo com commit no repositório mais uma cache obtida anteriormente, e um pull a recorrer ao registo para um artefacto ainda não obtido. O nível de espaço de trabalho e cache e o nível de registo da mesma cascata avaliam os campos type nos Aggregates, os valores de URI nos mapeamentos do Manifest, as declarações implements nas Recipes e FeatureRecipes e as referências plugin dentro dos pipelines de Recipe e de FeatureRecipe; o nível de caminho local só é alcançado pelos ficheiros que uma Release e o seu Manifest nomeiam.
Caminho local. Uma referência aggregate, manifest ou extends de uma Release, ou o extends de um Manifest, que comece por ./ ou ../ (um prefixo de caminho relativo POSIX) é lida diretamente do disco, relativamente à Release. Sem consulta ao catálogo, sem chamada ao registo. O prefixo explícito distingue a intenção de caminho local da consulta por nome ao nível sintático: uma Release que escreva aggregate: ./aggregate.yaml nomeia um ficheiro; aggregate: checkout nomeia um Aggregate pelo seu metadata.name. O resolvedor nunca examina o conteúdo da cadeia para decidir que nível se aplica — o prefixo é o discriminador. Qualquer outra referência, incluindo um type de Component num Aggregate, resolve-se através do nível de espaço de trabalho e cache e do nível de registo: uma entidade escrita localmente coloca-se em catalog/ na raiz do espaço de trabalho ou num diretório que workspace.catalog_dirs lista, e um type escrito como caminho de ficheiro relativo interrompe a compilação como uma entidade que nenhum catálogo contém.
Espaço de trabalho e cache. Uma referência sem prefixo explícito de caminho local é procurada primeiro nos diretórios listados em workspace.catalog_dirs (árvores de catálogo locais ao projeto, escritas ou incorporadas no repositório — ver §4 para a forma da configuração) — ou, para uma Release a que a configuração dá diretórios próprios em workspace.releases, nos dessa Release —, depois no diretório catalog/ da raiz do espaço de trabalho e depois em artifact_cache_dir (a localização .aggrega/cache/, ignorada pelo git, que contém artefactos obtidos em resoluções anteriores no registo e cujas subárvores o §4 descreve). O acerto na cache na segunda compilação e nas seguintes é o que mantém o ciclo interno sem rede, mesmo quando o projeto depende de conteúdo de catálogo remoto.
Registo. Se o nível de espaço de trabalho e cache não devolver nenhuma correspondência, aggrega pull — ou uma compilação executada com --auto-pull ou com a definição auto_pull do espaço de trabalho — faz um pull OCI baseado no ORAS a partir de default_registry (predefinição hub.aggrega.ai), desempacota o artefacto na cache para as compilações seguintes e continua com a entidade resolvida. Uma compilação sem nenhum dos dois lê apenas o que o seu lockfile fixa e, quando o lockfile falta, é interrompida indicando aggrega pull. A forma de URI OCI que a chamada ao registo constrói segue a taxonomia de tipos de entidade descrita no §6 (empacotamento de artefactos e taxonomia OCI). Os URIs abreviados nos Aggregates e nos Manifests são expandidos para a sua forma OCI completa antes da chamada ao registo; as regras de inferência que orientam 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 > espaço de trabalho e cache > registo. Uma entidade num diretório de catálogo local com a mesma identidade de uma entidade do registo sombreia a entidade do registo — isto é intencional e permite aos autores de catálogos experimentar modificações antes de as publicar. O mesmo sombreamento aplica-se entre catalog_dirs e a cache: uma entidade presente num diretório de catálogo do espaço de trabalho é preferida a uma cópia em cache, garantindo que as edições locais a um catálogo incorporado produzem efeito imediatamente.
Dentro do nível de espaço de trabalho e cache, catalog_dirs é uma pilha de precedência em que o primeiro ganha, ordenada. Quando a mesma identidade de entidade aparece em mais do que um diretório de catálogo listado, o diretório listado primeiro ganha e a ocorrência posterior é sombreada — substituída, não carregada, e sem ser um erro. Isto permite a um projeto colocar o seu próprio diretório de catálogo à frente de um partilhado ou incorporado e substituir entidades selecionadas pela identidade, enquanto as restantes recaem sobre o diretório partilhado. A substituição é observável: o detalhe da resolução reporta que diretório ganhou e qual foi sombreado, pelo que uma sobreposição nunca é silenciosa. O sombreamento aplica-se apenas entre diretórios; dois ficheiros num único diretório que reclamem a mesma identidade são um erro de autoria e interrompem o carregamento. Um diretório nomeado mais do que uma vez — por uma flag --catalog e em catalog_dirs, ou duas vezes na lista — é uma única entrada da pilha, pesquisada uma vez no lugar em que foi nomeado primeiro, pelo que um sombreamento é sempre entre dois ficheiros diferentes e nunca um diretório lido contra si mesmo. Como a precedência segue a ordem dos diretórios controlada pelo autor, o conjunto resolvido é determinístico.
O diretório catalog/ da raiz do espaço de trabalho junta-se a essa pilha no seu fim, não no topo, e apenas quando o diretório existe — pelo que tudo o que um projeto liste ganha sobre ele numa colisão, e listar um diretório não relacionado nunca o deixa silenciosamente de ler. É ignorado quando uma entrada listada já o alcança, uma vez que o percurso de um diretório listado é recursivo e uma pilha que nomeie a raiz do espaço de trabalho já o leu. Omitir catalog_dirs e escrevê-lo como uma lista vazia são afirmações diferentes: se for omitido, o espaço de trabalho continua a ler catalog/; se for escrito como [], não lê nenhum catálogo local, que é a forma de um espaço de trabalho declarar que não tem nenhum.
Compilações isoladas da rede. Definir offline: true (§4) ignora por completo o nível de registo. Uma referência que não se resolva no nível de caminho local ou no nível de espaço de trabalho e cache produz um erro de entidade em falta, em vez de tentar silenciosamente uma chamada de rede, o que dá aos pipelines de CI que legalmente não podem aceder à rede um contrato determinístico de falha rápida.
Onde a cascata atua. A cascata obtém a entidade para a memória; os mecanismos de resolução adicionais sobrepostos — a consulta em dois níveis type vs name do Manifest, a correspondência de versões em três formas de implements (exata / intervalo compatível com a versão principal / sem versão) em vocabulary/inheritance-and-interface e a seleção de Recipes por eixo, por provider e por instância de componente — atuam sobre entidades que o resolvedor já obteve através desta cascata.
6. Empacotamento de artefactos e a taxonomia OCI (a capacidade como segmento inicial)
O Aggrega trata a lógica de infraestrutura da mesma forma que o Docker trata as imagens de contentores, utilizando as normas Open Container Initiative (OCI) através do ORAS (OCI Registry As Storage). Os utilizadores podem alojar o seu catálogo Aggrega em qualquer registo normal (GHCR, AWS ECR, Aggrega Hub).
Como as Recipes são estritamente 1:1 com uma capacidade de renderização — uma Recipe nomeia uma capacidade em spec.capability e não pode visar duas —, a forma mais limpa de as organizar num registo 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 tipo — o kind da entidade, em minúsculas — seguido da identidade da entidade, toda em minúsculas:
hub.aggrega.ai/component/core/datastore/mariadb:1.0.0— Component, editorcore, categoriadatastorehub.aggrega.ai/component/core/compute/api-server:1.0.0— Component, editorcore, categoriacomputehub.aggrega.ai/feature/core/data-masking:1.0.0— Feature, editorcore(plana, 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 esquema partilhadas; ometadata.nameem PascalCaseAIDatastorespassa a minúsculas no nome do repositóriohub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0— MappingLibrary, fragmentos de mapeamento em templates Go partilhadoshub.aggrega.ai/plugin/provider/helm:0.5.0— Plugin, tipo de socketprovider(o segmentometadata.pluginType)
Os tipos publicáveis abrangem os tipos de autoria do catálogo, juntamente com o Aggregate, um módulo reutilizável (publicável quer venha mais tarde a ser referenciado como o spec.aggregate de nível superior de uma Release, quer aninhado no bloco aggregates: de outro Aggregate), e o Plugin, uma referência endereçada por conteúdo a um artefacto WebAssembly que o compilador encaminha e que o runtime executa. O Plugin é um artefacto publicável estrutural e não um tipo de autoria do catálogo. A Release e o Manifest são inputs do lado da implementação que vivem no controlo de versões e nunca são enviados — aggrega push rejeita-os —, pelo que não têm mediatype de publicação. aggrega push --list-kinds reporta o conjunto que o binário instalado publica, um tipo por linha. Cada tipo publicável tem o seu próprio mediatype OCI em cada uma das duas formas que uma publicação assume:
| Tipo de entidade | Publicado como o seu documento | Publicado com os ficheiros 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 ficheiro |
| SchemaLibrary | application/vnd.aggrega.schemalibrary.v1beta1+yaml | — não declara nenhum ficheiro |
| MappingLibrary | application/vnd.aggrega.mappinglibrary.v1beta1+yaml | — não declara nenhum ficheiro |
| WorkloadLibrary | application/vnd.aggrega.workloadlibrary.v1beta1+yaml | — não declara nenhum ficheiro |
| ArtifactLibrary | application/vnd.aggrega.artifactlibrary.v1beta1+yaml | — não declara nenhum ficheiro |
| Plugin | application/vnd.aggrega.wasmplugin.v1beta1+yaml | — publica através do seu próprio manifesto |
O que uma publicação transporta, e portanto a sua forma, decorre do que a entidade declara — não do seu tipo, nem do que está no seu diretório. Uma publicação transporta o documento da entidade e os ficheiros que a própria entidade nomeia ao lado dele: o source: local de uma Recipe ou de uma FeatureRecipe — um diretório viaja com todos os ficheiros sob ele que as regras de exclusão registadas no seu entity.lock mantêm —, cada ficheiro que as suas entradas valuesMapping:, workload: e artifacts: importam com $import: e o entity.lock que o seu passo de fixação escreveu; e cada ficheiro de esquema que um Component ou uma Feature importa, incluindo todos os ficheiros de uma cadeia de importação. Nada mais no diretório viaja: uma nota, um README ou o resultado de uma compilação ao lado da entidade não fazem parte do que ela publica, seja qual for o seu nome, e não alteram a forma em que publica. Uma entidade que não nomeia nada publica como o seu documento escrito, byte a byte, sob o mediatype +yaml do seu tipo; uma que nomeia um ficheiro publica como um tar comprimido com gzip do documento e desses ficheiros, sob o mediatype +tar+gz do seu tipo. Um Aggregate, um Plugin e os tipos de biblioteca não declaram nenhum ficheiro ao lado do seu documento, pelo que publicam sempre como o documento — incluindo um Aggregate na raiz de um espaço de trabalho, uma vez que cada caminho que declara nomeia outra entidade e não um ficheiro que transporte; uma Recipe cujo conteúdo seja todo inline também. Uma fonte remota é uma referência e não um ficheiro, pelo que não transporta nada, embora o entity.lock que regista a sua fixação faça de uma Recipe dessas um arquivo. O segmento de versão de cada mediatype é comum a todos os tipos publicáveis, e o segmento de codificação diz qual das duas formas os bytes têm. As ferramentas a jusante despacham com base na cadeia completa do mediatype — tipo, versão e codificação em conjunto.
Há uma forma escrita que não nomeia nenhum diretório que uma publicação possa conhecer: uma fonte local escrita como template. O seu diretório só é escolhido quando uma Release preenche o template, pelo que a entidade transporta todos os ficheiros do seu próprio diretório que as suas regras de exclusão registadas mantêm, para que, seja qual for o diretório que uma Release escolha, ele tenha viajado; aggrega push indica-o quando isso acontece. Transportar apenas o que é nomeado tem um custo, e esse custo recai sobre o consumidor: um ficheiro que uma entidade lê e não nomeia em lado nenhum não viaja, e é a compilação de um consumidor — não o push do editor — que dá com a sua ausência, nomeando o caminho em falta dentro do seu slot de cache.
Que ficheiros de um diretório de origem pertencem à entidade é decidido uma vez, quando a entidade é fixada, e fica registado. O plugin que serve a capacidade da entidade no espaço de trabalho do autor declara o que o seu ecossistema nunca distribui — os diretórios de controlo de versões de um plugin de charts e o respeito pelo .helmignore de um chart, o .terraform/ de um plugin de módulos — e o .aggregaignore do autor ao lado da entidade tem a última palavra. O passo de fixação regista esse plugin e as regras compostas no entity.lock, e a publicação, cada comparação das fixações da fonte, a linha da entidade no lockfile e a renderização aplicam todas as regras registadas, em vez de voltarem a perguntar a um plugin, pelo que o que é publicado é o que a própria compilação do autor renderiza, e uma associação alterada ou um binário mais recente não mexem em nenhum digest até a entidade ser fixada de novo. O compilador não tem opinião sobre nenhum ecossistema: as regras vêm do plugin e do autor, e o compilador limita-se a aplicá-las. Uma ligação simbólica entre os ficheiros de uma entidade é recusada em vez de seguida, uma vez que aquilo para que aponta viajaria com o seu nome. aggrega pin ensina as regras por completo.
O nome de uma Recipe não contém nem um prefixo de domínio nem a capacidade: o diretório do tipo de entidade e o segmento da capacidade já indicam 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 do editor 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 de forma simples, apenas pela folha. Os nomes das Recipes também NÃO incluem a capacidade, uma vez que esta já é o segmento inicial do URI canónico.
As Recipes utilizam a palavra-chave implements para se associarem à interface que cumprem. O campo implements suporta correspondência exata, por intervalo compatível com a versão principal ou sem versão (ver vocabulary/inheritance-and-interface para a correspondência de versões de implements). A Recipe de uma entrada de mapeamento do Manifest tem de 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 numa versão que não nomeia, na versão com que a compilação compila essa instância — pelo que 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 obtém-na através do modelo de resolução em três níveis, coloca-a em cache localmente em .aggrega/cache/ e dispõe o que ela transporta no slot de cache da entidade (§4) — os ficheiros de um arquivo, ou apenas o documento.
Uma entidade obtida lê os ficheiros que transporta exatamente como os lê ao lado dela num diretório de catálogo. A entidade é lida a partir do seu lugar nessa árvore disposta, pelo que um source: ou $import: relativo que declare — escrito por extenso ou produzido por um template — se resolve dentro do que foi publicado, e um caminho que saia do próprio diretório da entidade é aí recusado, tal como num diretório de catálogo. Nada fora da árvore é lido em seu lugar: nem o diretório a partir do qual uma compilação corre, nem um ficheiro colocado no slot de cache. Um Component ou uma Feature cujo esquema seja importado de um ficheiro transporta esse ficheiro, pelo que uma cópia obtida carrega o contrato que foi publicado e valida os valores escritos face a ele exatamente como o 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 identifica a entidade pelo que o documento é e não pelo nome que tem: o documento no topo do pacote cujo kind: seja um tipo de entidade publicável. O nome do ficheiro da entidade é uma convenção do catálogo e não um contrato, pelo que recipe.yaml é o que o catálogo da biblioteca padrão escreve e não o que o formato exige, e um ficheiro transportado ao lado da entidade — um template de chart, um fragmento compose — não é confundido com ela. A regra não pode ser a inversa, baseada no tipo que o consumidor procura: um tipo é lido a partir da entidade, que está dentro do pacote, pelo que, no momento em que o pacote tem de ser aberto, não há nenhum tipo em que basear-se. A extremidade de leitura interrompe em vez de escolher quando o topo de um pacote contém dois documentos de entidade — o pacote que outro cliente produz ao empacotar um diretório inteiro que contenha duas entidades, que ficaria então sob cada uma das suas coordenadas publicadas como um único artefacto. A publicação deste produto não o consegue produzir, porque cada entidade transporta apenas o que declara, e a extremidade de publicação recusa além disso um diretório desses: todos os tipos têm um diretório próprio exceto Aggregate, Release e Manifest, e aggrega pin e aggrega push recusam uma entidade de qualquer outro tipo com outra entidade ao lado, enquanto um carregamento do catálogo, um lint e uma compilação deixam o diretório em paz. O nome de um diretório não é julgado em nenhuma das extremidades: a organização <name>/<version>/ é a convenção do catálogo da biblioteca padrão.
Uma entidade publicada é lida através do mesmo passo. Uma coordenada contém exatamente uma cópia da sua entidade, na forma que as suas declarações lhe deram, e uma pessoa examina-a com aggrega inspect oci://<registry>/<repository>:<tag>, e não através de uma cópia legível publicada ao lado dela — pelo que não há uma segunda cópia que possa vir a discordar daquela que uma compilação resolve. O comando desempacota um arquivo segundo a regra acima, lê a entidade de um Plugin a partir do seu manifesto e não do executável publicado com ele, e renderiza o resultado como se renderiza um ficheiro desse tipo; ver Ler uma entidade publicada.
Anotações pesquisáveis no manifesto. Cada publicação carimba um pequeno conjunto de anotações pesquisáveis no manifesto OCI do artefacto, para que um índice de registo ou um navegador de catálogo possa filtrar artefactos pelos seus metadados de catálogo sem obter e analisar o corpo de cada entidade. Cada entidade transporta a sua descrição legível por humanos (a anotação de descrição OCI normal), mais a sua categoria e o seu tipo no catálogo. Um Plugin transporta adicionalmente o seu tipo de socket e as capacidades que serve. Estas anotações são o que aggrega registry update volta a ler para o índice pesquisável local (§8).
Cada ficheiro publicado tem nome. Cada ficheiro que uma publicação transporta é nomeado no manifesto com a anotação normal org.opencontainers.image.title, que é o nome com que um cliente OCI genérico escreve esse ficheiro quando obtém o artefacto para um diretório. O nome diz o que o ficheiro é, e a sua extensão segue o tipo de media do ficheiro:
| O que é publicado | O ficheiro que um cliente OCI genérico escreve |
|---|---|
| uma entidade publicada como o seu documento | entity.yaml |
| uma entidade publicada com os ficheiros que declara | entity.tar.gz |
| um Plugin | entity.yaml, a entidade, ao lado de entity.wasm, o seu executável |
| uma assinatura anexada a um artefacto | signature.json |
| um marcador de descontinuação anexado a um artefacto | deprecation.json |
um artefacto de dados publicado com aggrega push-artifact | o nome indicado 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 tal como foi publicada. O oras ignora um descritor que não tenha nome e reporta sucesso mesmo assim, razão pela qual cada descritor que uma publicação empacota tem um. O nome é derivado apenas do tipo de media, nunca do nome do ficheiro que foi publicado, pelo que os mesmos bytes publicados a partir de um ficheiro com outro nome produzem o mesmo manifesto. Uma entidade publicada com os seus ficheiros chega como o seu pacote: entity.tar.gz nomeia o pacote, e a entidade dentro dele é encontrada pela regra acima e não por qualquer nome de ficheiro. A própria resolução do Aggrega nunca lê estes nomes — seleciona cada ficheiro pelo seu tipo de media e confia nele pelo seu digest —, pelo que existem para todos os outros clientes.
7. A arquitetura das Recipes: ponteiros e mapeadores
Ver entities/recipe para a superfície de autoria completa de uma Recipe — source: (ponteiro), valuesMapping: (mapeador, com três modos de autoria: escalar de bloco inline, $import: de ficheiro, $import: de biblioteca para uma entrada de MappingLibrary), esquemas de origem orientados por Wasm, suporte nativo de IaC e exemplos completos.
8. O registo predefinido e os URIs abreviados sensíveis ao contexto
Para eliminar o excesso de YAML, o compilador resolve os URIs abreviados de forma sensível ao contexto, face à posição do esquema em que aparecem. O registo predefinido é configurado em .aggrega-config.yaml (com predefinição hub.aggrega.ai).
Um host de registo tem uma única leitura. Cada registries[].host é escrito como o próprio host — um nome de host em minúsculas que contenha um ponto, localhost, um nome simples seguido de uma porta, um endereço IPv4 ou um endereço IPv6 entre parênteses retos, cada um com um :port opcional, e sem esquema, caminho, credenciais nem maiúsculas —, porque essa grafia é a chave sob a qual se encontra cada política de confiança por registo, e o requisito de assinatura incorporado do hub oficial está associado a hub.aggrega.ai. default_registry nomeia um host da mesma forma e pode segui-lo com um caminho de repositório, como ghcr.io/acme: tudo o que é publicado através da predefinição fica então sob esse caminho, e cada referência curta resolve-se sob ele, enquanto a confiança continua a ser decidida apenas pelo host. Em alternativa, default_registry pode ser escrito como o name: de uma entrada registries, representando então o host dessa entrada. O nome é lido uma vez, à medida que a configuração é resolvida, face às entradas em vigor depois de todos os ficheiros de configuração e do ambiente, pelo que todos os leitores da predefinição — a publicação, a associação de localização, a verificação de assinaturas e todas as consultas de confiança — leem o host dessa única entrada, e nenhum deles alcança um host escrito como o nome; um nome seguido de um caminho é recusado, uma vez que um nome representa uma entrada e não uma localização. Um nome é comparado antes de uma grafia de host, e um nome que duas entradas tenham é recusado por ser ambíguo. A mesma leitura decide três coisas que um pull faz com o host: a localização de registo a que uma identidade de catálogo sem host fica associada, se o artefacto obtido nomeia um registo cuja assinatura seja de todo verificada, e face a que política de confiança corre essa verificação. Uma grafia que possa alcançar um registo falhando a sua política — maiúsculas, uma porta HTTPS predefinida explícita, um esquema, credenciais, um caminho no host de uma entrada registries — é recusada onde é configurada, nomeando a grafia a escrever, tal como um nome simples sem porta que não nomeie nenhuma entrada, que é a forma do primeiro segmento de uma identidade de catálogo e não a de um host. A recusa aplica-se em todas as camadas que podem definir o valor: o ficheiro de configuração, onde o esquema enuncia a mesma forma como um padrão em cada registries[].host; a variável de ambiente AGGREGA_DEFAULT_REGISTRY; e a linha de comandos. Assim, cada host que uma configuração pode nomear é um cujos artefactos são verificados segundo a política escrita para ele. O host é julgado apenas pela sua grafia; se o nome se resolve, ou se um registo responde lá, é estado de tempo de execução que o compilador nunca obtém. configuration detalha as formas aceites com exemplos.
Os URIs abreviados resolvem-se de forma sensível ao contexto face ao Manifest; ver ../language-reference/entities/manifest.md §URIs abreviados sensíveis ao contexto para as regras de inferência específicas.
Gerir registos
aggrega registry gere os registos que o espaço de trabalho conhece e a sua política de confiança em assinaturas. A identidade de um registo é o seu host; os subcomandos partilham um único modelo de endereçamento:
aggrega registry add <host>regista um registo e fixa a sua política de confiança, obtendo a política anunciada pelo registo no primeiro contacto, a menos que flags de confiança forneçam uma à mão. Um--name <alias>opcional associa um alias amigável à mesma entrada indexada pelo host — o host continua a ser a identidade, e o alias resolve-se para ele sempre que um registo é nomeado. Um alias é único entre registos.aggrega registry listimprime todos os registos configurados — host, alias, um resumo curto da postura de confiança e um marcador na predefinição — por ordem crescente de host. Lê a configuração resolvida e não contacta nenhuma rede.aggrega registry remove <name|host>elimina a entrada de política de confiança de um registo, endereçada pelo seu host ou pelo seu alias. Remove apenas a política de confiança: o ponteirodefault_registryfica intacto e a capacidade de fazer push para esse host não é afetada, pelo que o host volta à confiança predefinida em vez de ficar inalcançável. Umdefault_registryescrito como o nome da entrada removida deixa de nomear o que quer que seja, e é recusado até ser reescrito.aggrega registry updateatualiza o índice pesquisável local, descrito abaixo.
Sempre que um registo é nomeado — um argumento de subcomando registry ou a flag --registry em aggrega push e aggrega push-artifact —, o mesmo resolvedor interpreta o token: um alias configurado resolve-se para o seu host, e qualquer outro token é lido como o host que nomeia, descartando o esquema, o caminho e as credenciais de uma referência. Quando esse host se torna algo face ao qual é tomada uma decisão de assinatura — o destino de aggrega push ou de aggrega push-artifact, ou a chave sob a qual aggrega registry add escreve uma entrada —, fica sujeito à leitura única acima e é recusado, nomeando a grafia a escrever, quando não estiver escrito dessa forma. Um host não registado que esteja escrito dessa forma é um destino legítimo e é aceite.
O índice pesquisável local
aggrega registry update [<name|host>] constrói um índice pesquisável local dos registos que o espaço de trabalho conhece. Percorre os repositórios de cada registo configurado, seleciona a versão publicada mais alta de cada um, lê as anotações pesquisáveis do manifesto dessa versão (§6) e escreve um índice por registo na cache de artefactos. Sem argumento, indexa todos os registos configurados; com um único argumento de registo (um host ou um alias), indexa apenas esse.
O índice segue o modelo de atualização explícita habitual nos gestores de pacotes: registry update é o comando que contacta os registos, e um aggrega search posterior lê o índice escrito offline. O ficheiro de registos de um registo é determinístico — duas atualizações sobre o mesmo estado do registo produzem bytes idênticos, e o carimbo temporal de atualidade vive num ficheiro irmão para nunca perturbar os registos. Um repositório sem nenhuma versão publicada, ou que não possa ser lido, é ignorado, para que um único repositório ilegível nunca faça abandonar o índice inteiro.
O instantâneo publicado do catálogo
Cada publicação do catálogo da biblioteca padrão publica também o catálogo como um todo: um único artefacto OCI, um tar comprimido com gzip de todos os ficheiros que a árvore do catálogo contém no commit que essa publicação publicou, em catalog/snapshot sob o registo onde o catálogo é publicado — hub.aggrega.ai/catalog/snapshot para o hub oficial. Só é enviado depois de todas as entidades dessa publicação estarem no registo, pelo que não nomeia nenhuma entidade que o registo não contenha. É etiquetado com o commit a partir do qual foi construído e com latest, e é assinado sem chave pelo publicador, tal como todas as entidades da publicação, pelo que a identidade do publicador o verifica segundo a política de confiança do registo; latest só passa para um instantâneo depois de este estar assinado. O arquivo é escrito segundo uma única disposição fixa — entradas por ordem crescente dos seus nomes, cada uma com o mesmo modo, o mesmo proprietário e a mesma hora de modificação — pelo que um mesmo commit produz sempre o mesmo tar.
O seu único leitor é uma importação cujo workspace não indica 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, pelo que cada um obtém o instantâneo da mesma forma. A importação obtém-no a partir do registo predefinido do workspace através do mesmo controlo do tráfego de saída e da mesma autenticação que um pull, verifica a sua assinatura segundo a política de confiança desse registo antes de guardar o que quer que seja, guarda-o na cache de artefactos do workspace e lê-o aí como uma pasta de catálogo, vinculado ao seu digest — assim, são oferecidos ao importador os Components do catálogo, e --target rascunha um Manifest a partir das suas Recipes, exatamente pelo caminho que uma pasta de catálogo segue. O registo que a importação escreve ao lado dos seus rascunhos identifica o instantâneo pelo digest do seu manifesto, pelo que uma importação posterior dos mesmos rascunhos lê o mesmo catálogo sem nenhum pedido, e aggrega import --upgrade obtém o instantâneo mais recente e passa a importar face a ele. No modo offline, uma importação que tivesse de obter um instantâneo interrompe-se, indicando o que executar. Um workspace que indica uma pasta de catálogo importa face a ela e não obtém nenhum instantâneo. Nenhum outro comando lê o instantâneo: um pull, um build e uma validação resolvem cada entidade através dos níveis do §5 e fixam-na no lockfile, e os rascunhos de uma importação referenciam entidades do catálogo pelo nome, pelo que construí-los resolve essas entidades da mesma forma.
9. Fixação no lockfile e imutabilidade dos artefactos
A disciplina de fixação no lockfile ancora cada dependência a um artefacto específico endereçável por conteúdo. Na primeira resolução do lockfile (aggrega pull), o resolvedor consulta o registo, escolhe uma versão segundo a restrição de três formas do URI (exata / intervalo / sem versão) e escreve 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 registo; podem ser publicadas novas versões sem afetar o lockfile existente.
O modelo de fixação assenta numa regra fundamental: depois de um name:version ser publicado num registo 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 isto em cada publicação: resolve o artefacto existente em name:version no registo de destino; se existir e o digest corresponder ao conteúdo prestes a ser enviado, o push não carrega nada e anexa apenas o que falta ainda a essa publicação — a sua data de publicação e, quando o push assina, a sua assinatura; se existir e o digest for diferente, o push é interrompido com um erro de violação de imutabilidade que cita ambos os digests.
A imutabilidade é importante por duas consequências:
- As fixações do lockfile são fiáveis. Quando o lockfile regista
mariadb:1.0.0no digestD, uma compilação que obtenha por digest recebe os bytes deD. Sem imutabilidade, uma mutação do lado do registo poderia substituir os bytes deDpor baixo da fixação do lockfile, minando a estabilidade entre o momento do bloqueio e o momento da compilação. As compilações reproduzíveis assentam nesta garantia. - As alterações de metadados após a publicação têm um caminho claro. Marcar uma versão publicada como descontinuada, rodar chaves de assinatura ou corrigir atestações não pode ser feito alterando o artefacto publicado (a regra proíbe-o). Tem de ser feito publicando uma nova versão de patch ou um artefacto sidecar que registe a alteração de metadados em separado. Qualquer dos caminhos é auditável — uma nova versão ou um sidecar aparece como uma entrada distinta no registo — e nenhum altera os bytes do artefacto original.
A regra de imutabilidade aplica-se uniformemente a todos os artefactos Aggrega publicados em OCI (entidades, SchemaLibrary, MappingLibrary, plugins Wasm referenciados por pipeline[].plugin: de Recipe / pipeline[].plugin: de FeatureRecipe / plugins.{governance,linter,importer}[]: da configuração do espaço de trabalho). Tudo o que seja fixado por name:version mais um digest de conteúdo no lockfile está sujeito à imutabilidade.
A imutabilidade é incondicional, e nenhuma configuração a atenua. Não existe nenhuma flag nem nenhuma definição da configuração do espaço de trabalho que permita uma substituição, porque o registo não expõe nenhum caminho de substituição a que um operador possa aderir. O conteúdo que mudou é publicado sob uma nova versão, e aggrega lint --pre-publish verifica que o incremento de versão corresponde à classificação da alteração.
A re-resolução para uma versão mais recente exige uma ação explícita do utilizador: aggrega pull --upgrade --release <release> <uri> volta a resolver uma única dependência mantendo todas as outras fixações, e aggrega pull --upgrade --release <release> volta a resolver todas as dependências face ao estado atual do registo. As dependências em forma de intervalo e sem versão voltam a resolver-se para a versão correspondente mais recente; as fixações em forma exata não se movem a menos que o utilizador atualize explicitamente para uma versão exata diferente. O lockfile é a fonte de verdade para as compilações; a forma escrita pelo utilizador exprime a restrição de versão no momento da autoria.
10. Imposição da forma dos nomes das entidades de catálogo
Os nomes das 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. São uma superfície diferente dos nomes de instância que um programador escreve num Aggregate ou numa Release, que partilham 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 ao URI de referência canónico da entidade: Component e Feature incorporam diretamente os segmentos de editor e de agrupamento em metadata.name; Recipe e FeatureRecipe declaram um metadata.name só com a folha, e o seu URI canónico de dois segmentos junta essa folha ao spec.capability que a entidade declara; cada tipo de biblioteca declara um token em PascalCase em metadata.name.
Formas por tipo de entidade:
- Component — três segmentos em kebab-case
{publisher}/{category}/{name}declarados emmetadata.name. Exemplo:core/datastore/postgres. - Feature — dois segmentos em kebab-case
{publisher}/{name}declarados emmetadata.name. Exemplo:core/data-masking. - Recipe — uma única folha em kebab-case em
metadata.name(por exemplo,postgres). O URI de referência canónico{capability}/{name}(segundo o §6 acima) junta ospec.capabilitydeclarado da entidade a essa folha; o segmento inicial é comparado comspec.capability, não com a localização da entidade no disco, pelo que mover umrecipe.yamlnão altera a forma como é 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 do URI. Uma referência também pode nomear a recipe de forma simples — apenas a folha, sem segmento de capacidade —, que é a forma dominante na prática e se resolve sempre que uma única recipe do catálogo tenha esse nome. Nenhum segmento de editor aparece num URI de Recipe, e uma referência que contenha um terceiro segmento não corresponde a nenhuma recipe. - FeatureRecipe — uma única folha em kebab-case em
metadata.name(por exemplo,k8s-secret-from-parameter), simétrica com a Recipe: URI canónico{capability}/{name}a partir dospec.capabilitydeclarado mais a folha, a folha simples aceite da mesma forma, e a árvore<catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yamla espelhar a coordenada por convenção. - Os tipos de biblioteca — SchemaLibrary, MappingLibrary, WorkloadLibrary e ArtifactLibrary — um token único em PascalCase em
metadata.nameque corresponda a^[A-Z][A-Za-z0-9]*$(por exemplo,BaseComponents,AIDatastores,BaseWorkloads). A forma é a mesma em todos os tipos de biblioteca, pelo que mover uma entrada entre bibliotecas nunca implica mudar o nome para 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 cadeia não vazia, pelo que nada na forma é estrutural para esses tipos. Cada forma documentada — incluindo a dos tipos de biblioteca, cujos envelopes também declaram o seu padrão — é verificada pelo plugin de disciplina de publicação, que contém os padrões como uma fonte de verdade em regex partilhada 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 efetua, e só corre quando um autor a pede. Os dois comandos que mais frequentemente se presume que a efetuam não o fazem:
aggrega lintreporta violações da forma dos nomes. O plugin compara ometadata.namede cada entidade com o padrão do seu tipo. A verificação corre quando um autor invocaaggrega lint— sobre uma única entidade, sobre o fecho de dependências de uma Release com--release, ou sobre todas as entidades de catálogo quando invocado sem argumento — e o mesmo conjunto de regras está acessível a partir da superfície de ferramentas para editores que a CLI expõe. Os resultados são consultivos: são reportados com a 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-]*$)O resultado começa pela sua severidade e pelo código curto sob o qual a sua regra está registada, que aggrega explain E0278 desenvolve. O caminho do ficheiro infrator é impresso acima do resultado, e uma execução sobre todo o catálogo termina com uma contagem das entidades verificadas e dos resultados consultivos levantados.
aggrega buildnão verifica a forma dos nomes. A saída renderizada não depende dos nomes das entidades Aggrega, pelo que uma compilação sobre um catálogo com nomes não conformes não emite nenhum aviso nem diagnóstico, e é bem-sucedida exatamente como o seria de outro modo.aggrega pushtambém não verifica a forma dos nomes. A publicação recusa por outros motivos — sobretudo a regra de imutabilidade acima, em que republicar umname:versionexistente com conteúdo diferente interrompe o push. Quando uma recusa nomeiaaggrega lint --pre-publish, está a indicar ao autor que comando executar; o push não o executa.
Como nem a compilação nem a publicação verificam a forma, um catálogo que queira que a convenção seja respeitada executa aggrega lint deliberadamente — num hook de pre-commit ou como passo de um pipeline. Note-se que um resultado sobre a forma dos nomes é consultivo: aggrega lint reporta-o e termina na mesma com sucesso, pelo que um pipeline que queira condicionar à convenção lê os resultados reportados em vez de depender do código de saída.
Uma política por espaço de trabalho suprime a regra:
# .aggrega-config.yaml — lint sectionlint: publishing_discipline: allow_nonstandard_names: true # default falseCom a política definida, a regra da forma dos nomes não reporta absolutamente nada. Também pode ser definida para uma única invocação com aggrega lint --allow-nonstandard-names, ou desativada de novo à força com --no-allow-nonstandard-names. Os usos legítimos são catálogos que nunca serão publicados, experiências com vários editores e entidades para fins especiais.
11. Expansão de Features guiada por anotações
O bloco mappings.features.annotations do Manifest declara associações entre chaves de anotação e tipos de Feature, mais uma tabela de encaminhamento agrupada por pilar (maps.infra, maps.values) que nomeia as propriedades do esquema da Feature que cada anotação pode preencher. A subfase de expansão de anotações da resolução percorre as fronteiras da Release de fora para dentro e os subsistemas do Aggregate de fora para dentro, calcula os conjuntos efetivos de anotações por componente através de cascata e substituição, com exclusão por null do valor inteiro e por subchave, e injeta anexos de Features sintéticos que transportam origin: annotation na sua proveniência IR. A forma completa das associações e o ensino da sua autoria estão em language-reference/entities/manifest.md e language-reference/providers/well-known-annotations.md; esta secção documenta os mecanismos em tempo de carregamento do catálogo e em tempo de inspeção de que o caminho de expansão depende.
Cache de compilação de esquemas. O spec.schema.{infra,values} de cada Feature é compilado uma vez por compilação e reutilizado entre percursos de cascata. A validação de tipos repetida por subchave face ao mesmo esquema de Feature (um âmbito de cascata por componente, para centenas de componentes) lê o esquema compilado em vez de o compilar novamente. Nada é guardado entre compilações, pelo que um esquema de Feature alterado é compilado de raiz pela compilação seguinte.
Validação dos destinos de associação (carregamento do catálogo). No carregamento do catálogo, o compilador percorre cada associação features.annotations do Manifest e verifica que cada caminho com pontos declarado em maps.infra e maps.values corresponde a uma propriedade que o spec.schema.<pillar> da Feature referenciada declara efetivamente. Uma associação que encaminhe para um caminho que o esquema da Feature não lista interrompe o carregamento do catálogo com um OPS_ERROR claro que nomeia a chave da associação, o caminho em falta, o URI da Feature e a localização na origem.
Lint de sobreposição de pilares do esquema (carregamento do catálogo). É emitido um aviso consultivo quando o spec.schema de uma Feature declara o mesmo nome de propriedade nos pilares infra e values. A sobreposição raramente é intencional — propriedades com o mesmo nome em pilares diferentes confundem a intenção de autoria (que pilar é acionado quando uma anotação visa o nome partilhado?) e complicam as mensagens de diagnóstico. O aviso não é bloqueante e não tem exclusão: um autor que pretende a sobreposição mantém-na juntamente com o aviso, e um que não a pretende muda o nome da propriedade num dos pilares.
Lint de sobreposição do mapa de associações (resolução). É emitido um aviso consultivo quando um caminho de subchave aparece tanto em maps.infra como em maps.values nas associações do Manifest. Um caminho que apareça em ambas as listas de pilares é incoerente — uma única subchave de anotação não pode encaminhar para ambos os pilares em simultâneo, e o desempate determinístico que o compilador aplica (um caminho presente em ambas as listas encaminha para infra; uma anotação escrita no Aggregate só pode encaminhar através de values, pelo que uma escrita aí para esse caminho é recusada) é uma rede de segurança, não uma forma de autoria pretendida. O aviso não é bloqueante; os autores que correm com o aviso ignorado obtêm mesmo assim uma compilação limpa, com o desempate visível na proveniência da IR.
Renderização da proveniência em aggrega inspect. O comando inspect renderiza um parêntese por anexo de Feature, registando a origem de cada folha preenchida:
[explicit]— a Feature foi anexada explicitamente através de um blocofeatures:de um Aggregate ou de uma Release.[annotation: <key> from <source>]— todas as folhas preenchidas vieram da mesma chave de anotação. O parêntese nomeia a chave e o local onde a anotação foi declarada: o ficheiro e o caminho de chave com pontos dentro dele.- Parênteses por folha — composição entre lados em que cada folha preenchida é renderizada com o seu próprio parêntese de origem (umas
[explicit], outras[annotation: <key> from <source>]). Esta forma evidencia a fusão em que o explícito ganha por campo: quando um anexo explícito e uma contribuição de anotação visam a mesma instância de Feature no mesmo Component mas escrevem folhas diferentes, ambas as contribuições se mantêm nas respetivas folhas e o output do inspect nomeia individualmente a origem de cada folha.
A renderização do inspect lê os mapas values_provenance e infra_provenance por pilar da IR — preenchidos durante a expansão de anotações, ao lado da injeção dos anexos sintéticos — e emite a forma de parêntese que melhor resume a origem coletiva das folhas. O mecanismo de inspect é a superfície de introspeção canónica para perceber porque é que um dado anexo de Feature foi parar a um dado Component e de onde vieram os seus valores.