Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Contratos sociais

O Aggrega é, por design, um compilador sem opiniões próprias. Conforme os invariantes fundadores documentados em architecture/05-invariants.md, o compilador analisa YAML, percorre grafos, avalia interseções de rótulos e canaliza strings entre componentes — mas não fiscaliza o que os desenvolvedores colocam em values, parameters, infra, provides ou locals; não impõe convenções de nomenclatura, convenções de portas nem os rótulos semânticos que um Arquiteto inventa; não adivinha a finalidade de um componente a partir dos nomes. Muitas disciplinas que soam como regras do compilador são, na verdade, contratos sociais: boas práticas sustentadas por uma convenção de autoria, e não pela imposição do schema ou em tempo de execução.

Onde essa neutralidade termina merece ser dito com clareza, porque é uma única linha e é fácil interpretá-la além da conta. Algumas chaves são do próprio Aggrega — reservadas, com os valores que aceitam escritos no schema publicado — e essas o schema de fato verifica, do mesmo modo que verifica qualquer outro campo declarado. Declarar o conjunto de valores de uma chave que a própria plataforma define não é o compilador lendo um significado no que você escreveu; é a plataforma dizendo o que sua própria chave significa. Tudo o que você escreve sob uma chave sua continua exatamente tão sem fiscalização quanto esta página descreve.

Esta página é o inventário canônico dos contratos sociais da linguagem. Autores que aprendem os contratos nesta página podem entender por que o compilador aceita um build malformado segundo a convenção (ele aceita — o compilador não interpreta a convenção) e onde está a responsabilidade por detectar a violação (disciplina de autoria, atenção dos revisores ou um plugin linter executado por aggrega lint).

Três classes de disciplina

As disciplinas do Aggrega se dividem em três classes segundo como a disciplina é imposta. A classificação importa porque cada classe tem um modo de falha diferente quando a disciplina é violada.

Imposta pelo schema

A disciplina é imposta pela validação JSON Schema 2020-12 no momento do carregamento (o JSON Schema do envelope da entidade, mais as declarações schema: no nível do pilar nas entidades Component e Feature). Uma violação produz uma parada fatal antes que o build avance; o compilador se recusa a prosseguir. Autores que tentam violar uma disciplina imposta pelo schema veem um erro de validação explícito que aponta o campo e a restrição.

Exemplos: os campos obrigatórios do envelope da entidade (apiVersion / kind / metadata.name / metadata.version); a regex SemVer em metadata.version; o conjunto fechado de valores do rótulo reservado component.aggrega.ai/type; a proibição mecânica de blocos values: no schema da Release (conforme o Invariante 5); a rejeição de extends junto com aggregate na Release (o invariante da fonte única da verdade); as regras de forma da Recipe que impõem o contrato de composição dos tipos de entrada.

As disciplinas impostas pelo schema são as garantias mais fortes que a linguagem oferece. O compilador se recusa a renderizar qualquer coisa que as viole.

Imposta por um plugin de políticas

A disciplina é imposta por um plugin Wasm executado em um dos pontos de socket documentados (o papel de governança label-transform na construção da topologia; o papel de governança ir-verdict na análise estática; o socket do linter fora de banda). Uma violação produz uma falha de política que interrompe o build (sockets em banda) ou um aviso consultivo (sockets fora de banda), conforme a semântica de bloqueio do socket.

Uma disciplina só é imposta dessa forma onde é executado um plugin que a verifica: o runtime Wasm invoca plugins nos pontos de socket documentados, e uma disciplina que nenhum plugin verifica continua sendo uma convenção. O linter de publicação, que o aggrega lint executa, verifica parte de uma convenção desta página — veja Convenções que uma regra do linter verifica. Nenhuma regra do linter de publicação verifica a hermeticidade (a FuncMap do Sprig expõe helpers que quebram o determinismo da saída, conforme a ressalva sobre o determinismo em templates/sprig-functions.md) nem a nomenclatura de recursos de nuvem (Recipes cujas saídas de valuesMapping: referenciam campos de nomes de recursos de nuvem sem interpolação de release_name / instance_id, conforme entities/recipe.md “Cloud-resource naming discipline (Disciplina de nomenclatura de recursos de nuvem)”); um plugin linter próprio pode verificar qualquer um dos dois.

Para a superfície do contrato de plugins Wasm e o critério de posicionamento (o socket do linter versus os papéis de veredito de governança), veja plugins/plugin-contract.md.

Mantida por convenção

A disciplina é mantida apenas pela disciplina de autoria e pela atenção dos revisores. O compilador não a impõe; nenhum schema rejeita a violação; nenhum plugin Wasm a sinaliza. Os autores aprendem a disciplina na documentação, a seguem porque a forma arquitetural depende dela e contam com a revisão de PR para detectar deslizes. Uma violação não produz nenhum sinal em tempo de compilação — o build é bem-sucedido, a saída renderizada funciona até onde o compilador sabe, e a violação da disciplina só aparece quando ferramentas posteriores ou o comportamento em tempo de execução dependem da convenção.

As disciplinas mantidas por convenção são a lista essencial que os autores precisam aprender na documentação. O compilador não as interpreta; errá-las não quebra o build, mas quebra a forma arquitetural da qual o Aggrega depende. A maior parte desta página as documenta.

As convenções

Os contratos sociais a seguir são mantidos por convenção. Cada entrada nomeia a disciplina, a superfície em que a convenção é documentada e o modo de falha em caso de violação. Cada um mantém seu número onde quer que esteja: o contrato 3, a disciplina de prefixos reservados, é verificado por uma regra do linter para chaves de anotação e está descrito em Convenções que uma regra do linter verifica.

1. Escolher o tipo operacional adequado ao componente

O rótulo reservado component.aggrega.ai/type nomeia que tipo de coisa um componente é, a partir de um conjunto fechado de primitivas universais de nuvem: server, worker, task, function, stateful-server, resource. A pertinência a esse conjunto é imposta pelo schema, não mantida por convenção. O Aggrega define essa chave e os valores que ela aceita, o schema do Component os enumera, e um documento com qualquer outro valor é recusado no carregamento — E0215, a condição entity-envelope-invalid, nomeia o rótulo e lista os valores que ele aceita. Essa recusa é o que esta entrada não cobre.

O que continua sendo convenção é qual dos valores se ajusta ao componente à sua frente. Nada verifica se um banco de dados relacional está rotulado como stateful-server em vez de server, ou se um consumidor de fila é worker em vez de task; o seletor avalia qualquer valor que encontrar sem atribuir significado a ele. O Arquiteto que escreve um Component escolhe o valor que descreve como a infraestrutura deve tratá-lo, e os seletores posteriores, os plugins de políticas e os plugins de renderização Wasm dependem todos de que essa escolha seja honesta.

Classificar em um eixo próprio. O conjunto fechado rege apenas essa chave reservada e nada mais. Um catálogo que precisa de uma classificação que o Aggrega não define — um nível, uma zona de dados, uma classe de serviço ou uma divisão mais fina das primitivas operacionais — adiciona sua própria chave de rótulo ao lado da reservada. O schema do Component aceita qualquer chave de rótulo adicional com um valor de string, e o mesmo mecanismo de seletores a lê, de modo que acme.aggrega.ai/storage-tier: oltp fica ao lado de component.aggrega.ai/type: stateful-server e o appliesTo de uma Feature ou o selector de um socket podem apontar para qualquer uma das duas. A extensão acontece em uma chave própria, nunca em um valor dentro da chave do Aggrega.

Documentado em: architecture/02-ecosystem-philosophy.md (a ontologia operacional) + labels-and-annotations.md (disciplina de prefixos) + errors/sentinels.md (E0215).

Modo de falha: Um valor do conjunto que não se ajusta ao componente engana tudo o que lê o rótulo. Um armazenamento de dados rotulado como server é recusado por uma Feature ou um socket que seleciona stateful-server — uma parada que nomeia o seletor, não o rótulo errado — e um plugin de políticas ou um plugin de renderização que lê o rótulo o trata como computação sem estado. Onde apenas esses leitores o veem, o build é bem-sucedido; o erro só aparece quando os artefatos renderizados chegam ao cluster.

2. Separação de .context.annotations.* em três contêineres

As anotações em cascata chegam a três contêineres nomeados — .context.annotations.release, .context.annotations.catalog, .context.annotations.aggregate — cada um com uma intenção diferente. O objetivo da disciplina: release é “onde este componente é executado, governado por Ops”; catalog é “o que este componente é, escrito pelo Arquiteto”; aggregate é “o que este componente faz, escrito pelo Desenvolvedor”.

O compilador não impõe as fronteiras entre os contêineres. Os três contêineres compartilham uma forma plana string → string; o template de uma Recipe pode ler os três, e nada impede que uma anotação da fronteira da Release seja interpretada como metadados cognitivos ou que uma anotação do catálogo seja encaminhada para infra:. A separação é mantida pelos autores que escrevem as anotações no contêiner certo e pelos revisores que detectam vazamentos entre contêineres.

Documentado em: labels-and-annotations.md (a separação em três contêineres é um contrato social).

Modo de falha: A lógica de roteamento que depende da distinção de intenção entre contêineres (por exemplo, uma Recipe que encaminha .context.annotations.release.aggrega.ai/region para um campo region do Terraform) consome silenciosamente qualquer anotação que apareça no contêiner, independentemente da intenção de autoria. O build é bem-sucedido; a saída renderizada pode conter valores semanticamente errados.

4. Autocontenção de provides: na Recipe

Os templates provides: da Recipe se fecham apenas sobre os dados do próprio nó — .values, .infra, .context.instance_id, .context.rendered_name onde o provedor do nó informa um, os .locals resolvidos do nó, mais strings estáticas. Referências a .context.inject e .context.uses são proibidas porque a avaliação de provides executa esses templates em qualquer ordem; ler dados de outros nós a acoplaria à ordem de iteração topológica, que o design evita deliberadamente. .locals faz parte da superfície em vez de ficar de fora: os locals do nó são resolvidos no preâmbulo da mesma etapa, antes de seus provides, e são locais ao nó, de modo que lê-los não custa nada em termos de ordem. Nomear uma chave que o bloco locals não declara provoca uma parada.

Esta é uma regra com duas metades, cada uma indicando onde é verificada. O compilador verifica a primeira: a avaliação de provides verifica cada template contra uma allowlist positiva das raízes que seu contexto define antes que o template seja executado, de modo que uma leitura de .context.inject / .context.uses para com um erro explícito em vez de renderizar vazio; a regra também está documentada em templates/expansion-matrix.md, linha 6. A convenção mantém a segunda: o padrão mais amplo (provides-is-public; locals-is-private) está ancorado na convenção.

Documentado em: templates/expansion-matrix.md linha 6 + vocabulary/data-pillars.md “provides: and locals: — public face vs private face (provides: e locals: — face pública versus face privada)”.

Modo de falha: o compilador detecta as referências proibidas e interrompe o build no momento da avaliação dos templates quando elas aparecem diretamente em provides:. A disciplina mais ampla de público versus privado (não expor estado interno por meio de chaves de provides:) é apenas convenção — autores que tratam provides: como um espaço de nomes interno da Recipe produzem contratos dos quais os chamadores dependem; a refatoração se torna uma mudança incompatível.

5. Determinismo — helpers não herméticos em templates do caminho de renderização

O Invariante de Saída Determinística do Aggrega (Invariante 8 em architecture/05-invariants.md) exige saída idêntica byte a byte para entrada idêntica byte a byte. A FuncMap completa do Sprig expõe helpers que leem o estado do ambiente (leitores de relógio now / date; geradores aleatórios randAlpha / uuidv4; leitores de variáveis de ambiente env / expandenv; resolvedores de rede getHostByName). Autores que invocam esses helpers a partir de um template que contribui para a saída renderizada quebram o contrato de determinismo.

O compilador não detecta nem bloqueia o uso de helpers não herméticos. A FuncMap do Sprig os expõe conforme templates/sprig-functions.md “Determinism caveat (Ressalva sobre o determinismo)”; a disciplina é mantida pelos autores que evitam esses helpers em templates do caminho de renderização e pelos revisores que detectam seu uso na revisão de PR.

Documentado em: templates/sprig-functions.md “Determinism caveat (Ressalva sobre o determinismo)”.

Modo de falha: A saída do build difere entre execuções da mesma entrada. A divergência aparece no momento do diff do GitOps, quando ferramentas posteriores (ArgoCD, Flux) veem um desvio inesperado entre o manifesto commitado e o estado do cluster, ou no momento de uma auditoria, quando duas compilações da mesma entrada produzem artefatos diferentes.

Nenhuma regra do linter de publicação verifica nos templates invocações de helpers não herméticos. O nome do helper está escrito no template, então um plugin linter próprio pode encontrá-lo (veja Convenções que uma regra do linter verifica).

6. Fronteiras dos pilares (sinais, não muros)

As fronteiras dos pilares são disciplina de autoria, não imposição da linguagem. O motor de templates permite leituras entre pilares em qualquer ponto, a menos que sejam explicitamente proibidas por regras de autocontenção (por exemplo, provides: e source: da Recipe lendo .context.inject / .context.uses). Os autores devem:

  • Ler .values para a carga útil cognitiva (intenção escrita pelo desenvolvedor).
  • Ler .infra para o dimensionamento físico (dimensionamento escrito por Ops).
  • Ler .context.uses.<alias>.provides.<key> para strings de ponteiro entre componentes.
  • Ler .context.inject para o pipe de entrega pós-hidratação.

O motor de templates não controla a leitura. Um template de Recipe que lê .infra.replicas para alimentar um campo values: funciona; nada impede o caminho entre pilares. O objetivo da disciplina são sinais — as fronteiras descrevem a intenção de autoria (quem é dono dos dados) em vez de uma restrição em tempo de execução.

Documentado em: vocabulary/data-pillars.md “Pillar boundaries and authoring discipline (Fronteiras dos pilares e disciplina de autoria)”.

Modo de falha: Vazamento entre pilares — a carga útil cognitiva do desenvolvedor contém detalhes de dimensionamento físico, ou o dimensionamento escrito por Ops contém metadados cognitivos. O build é bem-sucedido; a divisão de autoria em quatro domínios se dilui com o tempo à medida que os autores pegam atalhos pelos pilares; a manutenção posterior fica mais difícil à medida que a correspondência entre pilares e fluxo de dados enfraquece.

7. Semântica de dupla origem de containers.<name>.variables do Workload

O mapa variables: combina duas fontes de dados distintas por meio de expressões de template Go: literais do pilar do desenvolvedor (entradas que leem .values / .infra / .locals) e dados do pipe entre componentes (entradas que leem .context.inject.env.<KEY>). Os autores escolhem uma fonte por entrada conforme o valor seja local ao componente ou derivado de outros componentes.

O compilador não distingue as duas fontes; ambas fluem para a mesma lista env: do Kubernetes no Deployment renderizado. A semântica de dupla origem existe apenas no momento da autoria — a disciplina consiste em nomear a intenção (esta entrada é local ao componente; aquela entrada é derivada de outros componentes) para que futuros mantenedores possam ler quais entradas dependem de quais saídas da hidratação de inject.

Documentado em: entities/workload.md “Field-semantics essentials (Fundamentos da semântica dos campos)” (variables).

Modo de falha: Autores que não distinguem as duas fontes perdem o rastro de “quais entradas estão acopladas aos provides: de qual destino”. Refatorar as chaves de provides: de um destino quebra silenciosamente toda entrada variables: do chamador que lia pelo pipe de inject.

8. Disciplina de nomenclatura de recursos de nuvem

Recipes que emitem nomes de recursos de nuvem (nomes de buckets S3, identificadores de bancos de dados RDS, nomes de papéis IAM, nomes de stacks CloudFormation — qualquer campo cujo valor ocupa um espaço de nomes global no provedor de nuvem) devem concatenar {{ .metadata.release_name }} e/ou {{ .context.instance_id }} ao nome renderizado para evitar colisões quando a mesma Recipe é executada em várias Releases ou instâncias de componentes.

O compilador não inspeciona as saídas de valuesMapping: em busca de campos de nomes de recursos de nuvem sem essas interpolações. A disciplina é mantida pelos autores de Recipe (que sabem quais campos nomeiam recursos globalmente únicos para o provedor de destino) e pelos revisores (que detectam padrões de recursos sem nome na revisão de PR).

Documentado em: entities/recipe.md “Cloud-resource naming discipline (Disciplina de nomenclatura de recursos de nuvem)”.

Modo de falha: Duas Releases do mesmo Aggregate (prod-billing e staging-billing) tentam ambas implantar um recurso com o mesmo nome global; a segunda implantação falha em tempo de execução com uma rejeição do lado da nuvem. O build do Aggrega é bem-sucedido; a falha de implantação só aparece quando a segunda Release é aplicada.

Nenhuma regra do linter de publicação verifica se os campos de nomes de recursos de nuvem têm as interpolações exigidas; um plugin linter próprio pode fazê-lo (veja Convenções que uma regra do linter verifica).

9. Granularidade do Component — um serviço coerente por Component

Um Component modela um serviço coerente — um único serviço exposto, ou a(s) carga(s) de trabalho de um serviço junto com suas cargas de trabalho auxiliares apenas internas. Quando um chart agrupa serviços que outro componente poderia, de forma significativa, usar com use isoladamente — especialmente infraestrutura externa, como um banco de dados, um cache ou um message broker, que o Aggrega já modela como seu próprio Component — a biblioteca padrão compõe Components por serviço em um módulo de subagregado (spec.aggregates + exportedComponents) em vez de envolver o produto inteiro como um único Component opaco. A disciplina: várias cargas de trabalho são aceitáveis dentro de um Component; a usabilidade independente é a linha que divide um Component em uma stack.

O compilador é agnóstico em relação a essa granularidade. Ele renderiza qualquer coisa que passe na validação do schema — não inspeciona quantos serviços a Recipe de um Component agrupa, nem se um deles é utilizável de forma independente. Um autor que envolve um produto de cinco serviços como um único Component produz um Component que o compilador aceita e renderiza sem reclamar; a convenção é mantida pela disciplina de autoria e pela atenção dos revisores.

Documentado em: ../../architecture/06-data-taxonomy-and-composition.md (um serviço coerente por Component — a fronteira da carga de trabalho única).

Modo de falha: Um empacotamento monolítico de vários serviços é compilado com sucesso, mas os serviços agrupados ficam invisíveis para a topologia, o seletor e as políticas — eles não podem ser escalados, substituídos nem usados como dependência de forma independente. Refatorar depois o monólito em Components por serviço é uma mudança incompatível para todo consumidor que referenciava o único nó empacotado.

Por que as convenções existem

Cada uma dessas convenções é disciplina de autoria por design, embora um schema ou uma política Wasm pudesse impor qualquer uma delas. O raciocínio por tipo de contrato:

Extensibilidade. A disciplina de prefixos reservados (contrato 3) descreve o vocabulário da biblioteca padrão, não o universo do vocabulário válido. Catálogos corporativos criam seus próprios prefixos e chaves de rótulo para estender a biblioteca padrão; impor por schema a convenção de prefixos converteria “a disciplina da biblioteca padrão” em “a única forma permitida da linguagem” — esse é o muro que a arquitetura evita deliberadamente. O eixo do tipo operacional (contrato 1) mantém a mesma extensibilidade em outra superfície: a chave reservada que o Aggrega define carrega um conjunto fechado, imposto pelo schema, e um catálogo estende adicionando uma chave de rótulo própria ao lado dela, em vez de um valor dentro da chave do Aggrega. O que o schema verifica é o conjunto de valores de uma chave que lhe pertence; o que fica aberto é qualquer outra chave, que é onde vive o vocabulário próprio de um catálogo.

Pureza AOT. A disciplina de nomenclatura de recursos de nuvem (contrato 8) e a disciplina de determinismo (contrato 5) exigem inspecionar o conteúdo dos templates para determinar se um campo é um nome de recurso de nuvem ou a invocação de um helper não hermético. A pureza AOT (Invariante 2) impede que o compilador dependa do estado em tempo de execução; a inspeção estática de templates é viável (um plugin linter lê os templates da entidade como foram escritos), mas fazê-la dentro do compilador central acopla a lógica interna do compilador a questões de autoria específicas de cada domínio. A arquitetura tira essas verificações do compilador e as coloca em plugins Wasm, conforme o Invariante 6 (a fronteira da ABI Wasm).

Flexibilidade de autoria. A disciplina das fronteiras dos pilares (contrato 6) e a semântica de dupla origem de variables (contrato 7) descrevem padrões de autoria, e não restrições em tempo de execução. A mesma sintaxe de template pode expressar um padrão que respeita a disciplina ou um que a viola; transformar a disciplina em uma verificação em tempo de execução exigiria que o compilador interpretasse uma intenção de autoria à qual não tem acesso. A arquitetura trata a convenção como documentação com a qual os autores aprendem, e não como um invariante em tempo de execução. A granularidade do Component (contrato 9) também se encaixa aqui: as empresas podem envolver um produto na granularidade que seu catálogo preferir, e o compilador — neutro quanto ao conteúdo e sem opiniões próprias conforme o Invariante 1 — não tem como saber se uma carga de trabalho agrupada é utilizável de forma independente, de modo que a fronteira de um serviço coerente continua sendo disciplina de autoria, e não um muro de schema. A escolha do tipo operacional (contrato 1) tem a mesma forma: o schema define quais valores existem, mas qual deles descreve um dado componente é um julgamento de modelagem sobre como a infraestrutura deve tratá-lo, e nada em uma Recipe ou em um bloco values diz ao compilador se o julgamento estava certo.

Imposição em duas metades. A autocontenção de provides: na Recipe (contrato 4) é parcialmente imposta pelo compilador — o caminho de renderização detecta leituras de .context.inject / .context.uses em templates provides: e para. A disciplina mais ampla de público versus privado (não expor estado interno) é ancorada na convenção, porque o compilador não consegue determinar quais strings devem permanecer internas à Recipe sem a intenção de autoria.

As três vias importam porque cada uma indica onde está a responsabilidade por detectar violações. Imposta pelo schema: o compilador. Imposta por um plugin de políticas: o plugin que a verifica, onde houver um em execução. Mantida por convenção: autores e revisores. Autores que internalizam as vias entendem quais erros o compilador vai detectar e quais vão passar silenciosamente para as ferramentas posteriores ou para o tempo de execução.

Convenções que uma regra do linter verifica

O linter de publicação, executado pelo aggrega lint, verifica em parte uma convenção desta página: as chaves de anotação do contrato 3, mais abaixo. Seu achado é consultivo, e a parte da convenção que ele não alcança é mantida por convenção, como as entradas acima.

Nenhuma regra do linter de publicação verifica qualquer outra convenção desta página. Duas delas podem ser verificadas por uma regra do linter, porque a violação está escrita na entidade: o determinismo (contrato 5) — um template que chama um helper não hermético — e a nomenclatura de recursos de nuvem (contrato 8) — uma saída de valuesMapping: que nomeia um recurso de nuvem sem interpolação de release_name / instance_id. O mesmo vale para as chaves de rótulo sob os prefixos reservados (contrato 3). Um workspace pode anexar plugins linter próprios em plugins.linter, ao lado do linter de publicação, para verificar qualquer uma delas; As regras de disciplina lista as regras que o linter de publicação traz.

As demais convenções (1, 2, 4, 6, 7, 9) dependem do que o autor quis dizer, o que nenhuma regra lê a partir do que foi escrito. A separação em contêineres é motivada pela extensibilidade (catálogos corporativos a sobrescrevem) — a imposição por schema entraria em conflito com essa flexibilidade. O que resta do eixo do tipo operacional depois que o schema define o conjunto de valores — escolher a primitiva adequada ao componente — é motivado pela intenção de autoria: o compilador não consegue distinguir um tipo operacional bem escolhido de um mal escolhido, porque ambos são valores que ele aceita. A disciplina das fronteiras dos pilares e a semântica de dupla origem de variables são motivadas pela intenção de autoria — o compilador não consegue determinar a intenção apenas pela sintaxe dos templates. A autocontenção de provides: na Recipe é parcialmente imposta; a disciplina mais ampla de público versus privado depende de quais chaves o autor pretendia manter internas, algo que nada na Recipe declara. A granularidade do Component também é motivada pela intenção de autoria — se uma carga de trabalho agrupada é utilizável de forma independente é um julgamento de modelagem que o compilador não consegue ler no conteúdo da Recipe.

3. Disciplina de prefixos reservados

Chaves de anotação e de rótulo seguem a forma <namespace>/<name>. Cinco prefixos reservados carregam regras de autoria específicas: aggrega.ai/ (exclusivo da plataforma), feature.aggrega.ai/ (atalhos oficiais de Feature), component.aggrega.ai/ (características intrínsecas do Component), aggregate.aggrega.ai/ (identidade de módulo do Aggregate) e <any-other-domain>/ (corporativo / comunidade).

O compilador não rejeita uma anotação escrita sob um prefixo reservado em uma entidade do catálogo ou em uma Release; apenas um binding de anotação de um Manifest ou um rótulo de saída de uma Recipe que reivindique uma chave sob aggrega.ai/ interrompe o build. Uma empresa que declara aggrega.ai/internal-billing-tag: "..." fora do vocabulário da plataforma produz uma anotação que o compilador aceita e propaga em cascata pelo sistema de contêineres; atualizações posteriores da plataforma que introduzam um aggrega.ai/internal-billing-tag real colidem silenciosamente.

Documentado em: labels-and-annotations.md (Disciplina de prefixos) + providers/well-known-annotations.md.

Modo de falha: Anotações personalizadas sob prefixos reservados colidem com futuras anotações da plataforma com o mesmo nome; o comportamento esperado da plataforma sobrescreve silenciosamente o valor escrito pela empresa ou coexiste com ele, dependendo da ordem.

O linter de publicação, executado pelo aggrega lint, sinaliza uma chave de anotação de uma entidade do catálogo sob aggrega.ai/ que não é uma das anotações conhecidas da plataforma, e uma sob feature.aggrega.ai/ em uma entidade que não é uma Feature, como achado consultivo (E0277). Chaves de rótulo, os outros prefixos reservados e anotações fora de metadata.annotations de uma entidade — as que uma Release escreve, por exemplo — não são verificados, então para eles a disciplina continua sendo uma convenção.

Referências cruzadas