extends e implements
Herança via extends
As entidades do catálogo (Component, Feature) oferecem suporte a herança simples por meio da palavra-chave extends, que permite aos arquitetos de plataforma construir entidades especializadas sobre uma base compartilhada. A mesclagem profunda do envelope YAML é comum aos dois tipos: os metadados, os rótulos e as tabelas estruturais declarativas da entidade que estende sobrescrevem as chaves correspondentes na base, e os mapas aninhados são mesclados recursivamente. Os dois tipos se separam nos pilares de dados.
Esta página trata dos tipos do catálogo, e eles não são os únicos tipos que declaram extends. Uma Release e um Manifest também o declaram, e ambos são documentos do lado da implantação escritos um ao lado do outro, em vez de entidades indexadas no catálogo — por isso as suas referências nomeiam arquivos, não entidades do catálogo, e o que é mesclado é uma superfície de autoria, não um esquema. Para eles, veja entities/release.md e entities/manifest.md.
O extends de um Component compõe a estrutura e herda os pilares por inteiro
Para um Component, extends compõe metadata.labels, metadata.annotations, spec.featuresSchema (slots de vinculação), spec.usesSchema (sockets de topologia) e spec.inject (a allowlist do self-inject, cujas entradas são concatenadas começando pela base e sem duplicatas). Os três pilares de dados — values, infra, provides — não são compostos. Um Component que estende não escreve conteúdo de pilar: ele escreve o marcador literal schema: inherited e recebe o bloco schema: da base exatamente como a base o escreveu, em qualquer profundidade de uma cadeia.
O esquema Component publicado torna esse marcador ao mesmo tempo obrigatório e exclusivo, e rejeita cada desvio em relação a ele quando o documento é carregado, com um diagnóstico próprio para cada um: conteúdo de pilar escrito sob schema: em um Component que declara extends:; schema: omitido por completo nesse caso; e schema: inherited em um Component que não declara nenhum extends:.
Daí decorrem duas consequências, e elas puxam em direções opostas:
- O conjunto de chaves é fixado pela base. Um Component que estende não declara chaves de pilar, então não pode ocultar, remover ou mudar o tipo de uma que a base declara, e não acrescenta nenhuma própria. Uma instância da base e uma instância de qualquer coisa que a estenda são validadas contra o mesmo contrato de pilar.
- O reforço passa para
assertions:. Uma especialização que precisa admitir menos do que os pilares herdados admitem diz isso como um predicado sobre si mesma, não como uma folha de esquema restringida. Se uma basecore/base-serverdeclaratls_enabled: { type: boolean, default: true }, uma especialização que exige TLS incondicionalmente escreve:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/tls-only-server version: 1.0.0 labels: component.aggrega.ai/type: "server"spec: extends: core/base-server schema: inherited # values, infra and provides are the base's, verbatim assertions: tls-is-mandatory: | {{- if not .values.tls_enabled -}} {{- fail "this component requires tls_enabled: true" -}} {{- end -}}A regra rejeita um valor que o bloco de pilar herdado aceita, que é exatamente o que reforçar significa aqui. A direção inversa não tem nenhuma expressão: uma especialização não pode relaxar uma restrição herdada, porque não pode reformular a folha que a carrega. Veja entities/component.md “Catalog Authoring: Extending Base Components (Autoria de catálogo: estendendo Components base)” para a tabela de composição completa e o par completo de base e extensão.
O extends de uma Feature compõe os seus pilares
Para uma Feature, o schema: da filha se compõe com o da base segundo a semântica de composição do JSON Schema 2020-12, produzindo um único esquema mesclado contra o qual uma instância escrita é validada. As Features de credenciais — aquelas com o rótulo feature.aggrega.ai/kind: secret — usam isso para construir sobre uma base compartilhada: uma Feature de credenciais filha estende um pai para herdar o seu esquema de consulta ao vault enquanto estreita as restrições.
O compilador não toma posição sobre a direção dessa mudança. A composição é estrutural, então uma restrição da filha que amplia a da base é composta sem interromper o build e aparece como um aviso. Nada a rejeita: a restrição de uma base de Feature é uma expectativa compartilhada que os autores do catálogo mantêm por meio de revisão, não um contrato que a plataforma faz cumprir.
Ligação de interface por meio de implements
As Recipes e as FeatureRecipes se ligam a uma interface de Component ou de Feature por meio da palavra-chave implements: no topo do seu spec. A ligação declara de qual interface do catálogo esta Recipe / FeatureRecipe é a implementação concreta, e oferece suporte a três formas de correspondência de versões:
- Exata —
implements: core/api-server:1.0.0— corresponde a uma versão específica do tipo de Component. - Intervalo compatível com a versão principal —
implements: core/api-server:^1.0.0— corresponde a qualquer versão que satisfaça>=1.0.0, <2.0.0(compatível com a versão principal segundo o SemVer). Usado quando uma Recipe oferece suporte a um intervalo compatível em vez de uma única versão fixada. - Sem versão —
implements: core/api-server— corresponde a qualquer versão do tipo de Component. Usado quando uma Recipe atende a todas as versões do tipo.
implements: nunca seleciona uma Recipe: quem faz isso é o mapeamento do Manifest. O que a declaração determina é a verificação de consistência em cada entrada de mapeamento — a versão do tipo mapeado deve satisfazer o implements: da Recipe mapeada em uma das três formas, ou a Recipe deve implementar uma base que esse tipo estende — e a lista de candidatos que o diagnóstico de mapeamento ausente e o preenchimento automático do editor oferecem. Uma entrada de mapeamento cuja Recipe tem um implements: que não corresponde nem ao tipo mapeado nem a nenhuma das suas bases interrompe o build, nomeando o mapeamento, a Recipe e o seu valor implements:. Onde uma chave components.type alcança uma instância de componente em uma versão que a chave não nomeia — todas as instâncias, para uma chave escrita sem versão —, a verificação é feita novamente com o tipo próprio dessa instância, na versão com que o build a compila, e uma Recipe que não a satisfaz interrompe o build da mesma forma, nomeando a instância.
A ligação implements: é o mecanismo que faz funcionar “o mesmo tipo de Component, Recipes diferentes para provedores diferentes”: um Component core/postgres pode ter uma Recipe que o implementa para o provedor helm e outra Recipe que o implementa para o provedor compose. Cada Recipe declara o mesmo valor implements:, e o Manifest com o qual uma Release faz o build mapeia o tipo para a que ela deseja.
Uma Recipe escrita para uma base atende tudo o que a estende
implements: nomeia uma base, e uma Recipe que nomeia uma é a implementação concreta para todo Component que estende essa base, em qualquer profundidade da cadeia. Assim, uma especialização construída com extends não precisa de uma Recipe própria — e é isso que torna barato consumir um wrapper publicado: a equipe que o publica escreve um Component, e as equipes que o implantam reutilizam as Recipes da base em todos os destinos.
Aqui valem dois fatos ao mesmo tempo, e eles são separados. Um leitor que os reduz a “a especialização não precisa de nada” escreve um Manifest que falha, por um motivo que vai procurar no arquivo errado:
- A Recipe corresponde. A verificação de consistência entre a chave de tipo de um mapeamento do Manifest e o
implements:da Recipe mapeada aceita o mapeamento quando a Recipe implementa o próprio tipo mapeado ou qualquer base que esse tipo estende. As três formas de versão acima se aplicam a uma base exatamente como ao próprio tipo: uma Recipe que declaraimplements: core/base-server:^1.0.0satisfaz uma especialização cuja base está na versão1.4.0, e não satisfaz uma cuja base está em2.0.0. - O Manifest ainda mapeia o tipo próprio da especialização. A seleção da Recipe é feita pela chave de mapeamento exata. Uma instância de
enterprise/labelled-serverprecisa da sua própria entradamappings.components.type; ela não herda a entrada escrita paracore/base-server. Uma especialização sem entrada própria é interrompida com o diagnóstico de instância não mapeada mesmo quando a sua base está mapeada.
O custo de autoria de uma especialização é, portanto, uma linha de Manifest e nenhuma Recipe nova:
# The wrapper extends core/base-server and authors no pillars.# core/helm/base-server declares: implements: core/base-serverspec: mappings: components: type: enterprise/labelled-server:1.0.0: core/helm/base-server:1.0.0Quando a cadeia extends do tipo mapeado não pode ser percorrida — ela forma um ciclo, ou uma base que ela nomeia está ausente do catálogo —, o build é interrompido nessa falha da cadeia em vez de no mapeamento, porque um mapeamento não pode ser avaliado até que a cadeia da qual depende seja resolvida. A verificação percorre a cadeia apenas pelos Components que já estão nesta máquina — os de um diretório de catálogo e os que o cache local de artefatos guarda sob um pin do lockfile — e nunca consulta um registry, então uma base guardada apenas por um registry conta aqui como ausente. Buscá-la é o que aggrega pull faz: uma base é uma dependência de tudo o que a estende, então um pull segue toda cadeia extends: que a Release alcança, busca cada base que nenhum diretório de catálogo guarda e a fixa no lockfile, onde o build seguinte a encontra. O Manifest não precisa de nenhuma linha para a própria base, a menos que um Aggregate também declare uma instância da base.
As sugestões de Recipe continuam mais restritas do que essa regra de correspondência. A lista de candidatos que um diagnóstico de mapeamento ausente imprime, e a ordenação que o preenchimento automático do editor aplica a um valor de mapeamento, nomeiam as receitas que implementam o próprio tipo solicitado; elas não se ampliam para receitas que implementam uma das suas bases.
Para um passo a passo completo e executável — um wrapper publicado no catálogo, a única linha de Manifest que o consome, a Recipe da base dando forma à sua saída renderizada, e a interrupção que uma instância do wrapper sem mapeamento próprio produz —, veja o exemplo completo examples/extends-wrapper/.
Consumo de versões entre entidades
Todo tipo de entidade do Aggrega — Component, Feature, Aggregate, Recipe, FeatureRecipe, Manifest, Release, Plugin, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary — carrega um campo obrigatório metadata.version validado contra a mesma regex SemVer (MAJOR.MINOR.PATCH conforme architecture/02-ecosystem-philosophy.md). As versões são uniformes na forma; o consumo das versões varia por tipo de entidade. Algumas versões participam ativamente da resolução; outras são proveniência descritiva contra a qual o compilador não faz correspondência. A tabela abaixo cobre os tipos que não são bibliotecas, nomeando o que o compilador faz com o campo de versão de cada entidade e usando a taxonomia de status de quatro rótulos de 10-status.md para classificar cada regime de consumo. Os quatro tipos de biblioteca ficam fora da tabela porque o seu regime é uniforme e diferente: um consumidor referencia uma biblioteca pelo nome simples, pode afirmar um piso de versão mínima opcional :<version>, e o lockfile por Release detém a versão resolvida e o seu digest de conteúdo.
| Entidade | Regime de consumo | Status |
|---|---|---|
| Component | Resolução de referências de tipo; correspondência de implements: da Recipe | available — formas exata, de intervalo caret (^MAJOR.MINOR.PATCH) e sem versão em ambos (veja Resolução de versões e Status da linguagem → Correspondência de versões) |
| Feature | Resolução de referências de vinculação; correspondência de implements: da FeatureRecipe | Igual a Component |
| Recipe | Resolução dos níveis de mapeamento do Manifest | available — formas exata, de intervalo caret e sem versão em um valor de mapeamento, cada uma selecionando a versão mais alta que a satisfaz |
| FeatureRecipe | Resolução dos níveis de mapeamento do Manifest | Igual a Recipe |
| Aggregate | Resolução da referência aggregates[].type do pai | available — formas exata, de intervalo caret e sem versão, cada uma selecionando a versão mais alta que a satisfaz (veja Resolução de versões) |
| Plugin | Despacho do Provider por meio de recipe.spec.capability → spec.provider.capabilities | available — a capacidade simples seleciona o provedor, e um pin sobre ela (helm:<version>, helm:^<version>) seleciona qual versão desse plugin renderiza; a identidade do plugin é a referência oci://<repository> sem digest mais metadata.version, e o digest de conteúdo é registrado no lockfile da release contra o qual o build verifica os bytes baixados |
| Manifest | Proveniência do grafo IR (manifest_version) | available (lido apenas para a proveniência; nenhum papel no despacho da resolução) |
| Release | Proveniência do grafo IR (release_version) + metadados de template (.metadata.release_version) | Igual a Manifest |
Regimes de resolução do catálogo (Component, Feature, Aggregate, Plugin). Uma referência a um desses tipos — o type de um componente, o type de uma vinculação de funcionalidade, o aggregates[].type de uma importação de subagregado, o plugin de uma etapa de pipeline — é resolvida pela regra que Resolução de versões ensina: uma referência exata, de intervalo caret ou sem versão seleciona a versão mais alta que a satisfaz entre as que o catálogo contém, e o pull, o build, uma validação, o editor e as ferramentas voltadas ao assistente aplicam essa única regra da mesma forma. Para um Component ou uma Feature, a correspondência de implements: lê as mesmas três formas na direção oposta — uma versão concreta do tipo contra a forma que uma Recipe ou uma FeatureRecipe declara — como a verificação de consistência descrita abaixo, não como uma seleção. O despacho para o plugin de renderização do Provider usa uma forma mais simples: ele procura pelo nome a recipe.spec.capability simples nas spec.provider.capabilities do plugin de renderização do provedor, e um pin de versão escrito sobre a capacidade seleciona qual versão desse plugin renderiza, interrompendo quando nenhuma versão o satisfaz.
Resolução dos níveis de mapeamento do Manifest. O mecanismo de resolução plano mappings.{components,features} do Manifest (com os níveis name e type, o nome prevalecendo sobre o tipo, e o tipo com versão prevalecendo sobre o tipo sem versão) está documentado em entities/manifest.md. O resolvedor consome esses mapeamentos: a seleção de Recipe e de FeatureRecipe é uma busca direta do valor de mapeamento no lockfile e no catálogo, e um componente ou uma vinculação cujo tipo não tem mapeamento interrompe o build. spec.implements não seleciona uma Recipe — é a verificação de consistência no carregamento sobre um mapeamento que o autor já escreveu, e a fonte da lista de candidatos que o diagnóstico de mapeamento ausente e o preenchimento automático do editor oferecem. O despacho de capacidades parte então do campo spec.capability da Recipe resolvida, não da forma estrutural do Manifest.
Regimes de proveniência descritiva (Manifest, Release). O metadata.version do Manifest e o metadata.version da Release são lidos quando o compilador preenche a proveniência, e aparecem no bloco de proveniência do grafo IR como manifest_version e release_version; nenhum rótulo na saída renderizada carrega nenhum dos dois. Os templates também veem a versão da Release exposta como .metadata.release_version. Nenhuma das duas versões é comparada com a versão de outra entidade para o despacho da resolução; são pura proveniência.
Lendo a tabela. A classificação de quatro rótulos distingue “o campo de versão é aceito pelo esquema e existe na entidade” (sempre verdadeiro — regex SemVer uniforme) de “o compilador faz correspondência com esta versão durante a resolução” (varia por entidade).
Canalização entre pilares por ponte de esquema: ligando a intenção à infraestrutura
O Aggrega expressa uma forte separação de responsabilidades entre o Domínio 1 e o Domínio 4: o desenvolvedor escreve a lógica cognitiva no bloco values, enquanto o operador dita o dimensionamento físico no bloco infra. O esquema Aggregate.yaml impõe um corolário concreto: a palavra-chave infra está ausente das instâncias de componente do Aggregate e das suas vinculações features e, combinada com additionalProperties: false, é rejeitada pela validação do esquema. Os desenvolvedores não devem ditar o dimensionamento físico dentro da intenção do desenvolvedor; quando um valor específico se encaixa no caso da aplicação (por exemplo, uma porta fixada no código ou um número específico de CPUs), o arquiteto pode expô-lo explicitamente na declaração schema: do Component, e o valor flui por values.
Para os casos em que uma restrição de infraestrutura específica é parte intrínseca do contrato de um componente — um banco de dados de trading de alta vazão que precisa ter 10.000 IOPS provisionadas, uma carga de trabalho de ML que precisa rodar em exatamente 4 GPUs —, os arquitetos de plataforma expõem a restrição por meio de um Component construído para esse fim, usando o padrão de canalização entre pilares por ponte de esquema.
O padrão de ponte de esquema para componentes cientes da infraestrutura. O Component expõe o controle de infraestrutura específico dentro do bloco values do desenvolvedor por meio da sua declaração schema:, e o template valuesMapping: da Recipe associada canaliza o valor para a saída renderizada com a forma de infra:. O resultado é uma ponte tipada entre a intenção cognitiva e o dimensionamento físico: o desenvolvedor dita a restrição de hardware por meio de um campo validado, e a restrição flui para Ops sem que nenhum dos lados escreva código de infraestrutura bruto. O controle é uma chave de pilar, então é declarado no Component cujo contrato o possui — um Component que faz extends: de uma base não declara chaves de pilar e, portanto, não pode introduzir uma.
# Domain 2: The Platform Catalog (the schema-bridge Component)apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/high-perf-postgres version: 1.0.0 labels: component.aggrega.ai/type: "stateful-server"spec: schema: values: # Expose the dial safely to the Developer with a typed contract. required_iops: { type: integer, min: 1000, max: 100000, required: true } infra: # Operator-owned sizing the Recipe below reads alongside the dial. storage: { size: { type: string, default: 100Gi } } compute: { instance_class: { type: string, default: db.m5.large } }# Domain 2: The Platform Catalog (the Recipe pipes the dial into provider infra)apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-rds-high-perf-postgres version: 1.0.0spec: implements: core/high-perf-postgres:^1.0.0 capability: terraform source: ./modules/rds valuesMapping: | # The Recipe pipes the developer's values.required_iops into the provider's infra-side knob. iops: {{ .values.required_iops }} allocated_storage: "{{ .infra.storage.size }}" instance_class: "{{ .infra.compute.instance_class }}"# Domain 1: The Developer Intent (remains capability-agnostic)components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: 10000 # Developer dictates the hardware constraint safelyEscalonamento multiambiente (o requisito de elevação de parâmetros). Para escalonar essa restrição de hardware entre ambientes GitOps (Dev vs. Prod) sem alterar o Aggregate.yaml do desenvolvedor, o desenvolvedor eleva o valor para o contrato tipado parameters. Ops atende o requisito específico de IOPS por meio de arquivos Release específicos de cada ambiente. A ordem de execução do compilador protege o fluxo: a validação do contrato de parâmetros é executada na resolução; a interpolação resolve o parâmetro na string values: circundante; o template valuesMapping: da Recipe canaliza o valor resolvido para a saída renderizada.
1. A intenção do desenvolvedor (abstraindo o controle). O desenvolvedor sabe que precisa controlar as IOPS, mas abstrai o número explícito para o nível do ambiente por meio do contrato tipado parameters.
spec: parameters: env_iops: type: integer min: 1000 max: 100000 description: Provisioned IOPS for the trading-db instance components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: {{ .parameters.env_iops }} # Hoisted to the environment2. As Releases de GitOps (atendimento por Ops). Ops atende o contrato parameters em arquivos Release específicos de cada ambiente. O contrato tipado valida cada valor fornecido pela Release antes que a interpolação seja executada.
- Ambiente Dev (
release-dev.yaml):env_iops: 1000 - Ambiente Prod (
release-prod.yaml):env_iops: 25000
A ordem de compilação. Esse mecanismo é protegido pela ordem de execução estrita do compilador na resolução:
- Validação do contrato de parâmetros. Cada valor de parâmetro fornecido pela Release é validado contra a declaração tipada
parameters:do Aggregate. Um valor de Prod de25000é válido (dentro demin: 1000, max: 100000); um valor de500interromperia com um erro claro. - Interpolação. O compilador lê os valores de parâmetros da
Releasede Prod e interpola25000na string YAML doAggregateemvalues.required_iops. O mapa de parâmetros mesclado permanece ativo durante a renderização para que as superfícies de template de caminho possam ler.parameters.<slot>diretamente; as superfícies de template de valor consomem o literal pós-interpolação já escrito no blocovalues:do Aggregate. O mapa permanece legível até que toda fase de renderização seja concluída, e só pode ser alcançado a partir da compilação para a qual foi resolvido. - Validação de esquema. A declaração
schema:do Component valida o dicionáriovalues:resultante;values.required_iops: 25000satisfaz omin: 1000, max: 100000do esquema. - Renderização do valuesMapping da Recipe. O template
valuesMapping:da Recipe associada canalizavalues.required_iopspara a saída com a forma deinfrado provedor (iops: 25000). O plugin Wasm do provedor gera a configuração física correta do banco de dados. O desenvolvedor obtém o seu controle explícito de hardware, Ops obtém o seu escalonamento específico de cada ambiente, e oAggregatecontinua agnóstico em relação às capacidades.