Contratos sociais
O Aggrega é, por conceção, 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 etiquetas e encaminha strings entre componentes — mas não fiscaliza o que os programadores colocam em values, parameters, infra, provides ou locals; não impõe convenções de nomenclatura, convenções de portas nem as etiquetas semânticas que um Arquiteto inventa; não adivinha a finalidade de um componente a partir dos nomes. Muitas disciplinas que soam a regras do compilador são, na verdade, contratos sociais: boas práticas mantidas 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 para 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 verifica de facto, da mesma forma que verifica qualquer outro campo declarado. Declarar o conjunto de valores de uma chave que a própria plataforma define não é o compilador a ler um significado naquilo que foi escrito; é a plataforma a dizer o que significa a sua própria chave. Tudo o que se escreve sob uma chave própria 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. Os autores que aprendem os contratos nesta página podem perceber por que razão o compilador aceita uma compilação malformada segundo a convenção (aceita — o compilador não interpreta a convenção) e onde está a responsabilidade de detetar 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 dividem-se em três classes consoante a forma 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: ao nível do pilar nas entidades Component e Feature). Uma violação produz uma paragem fatal antes de a compilação avançar; o compilador recusa-se a prosseguir. Os autores que tentam violar uma disciplina imposta pelo schema veem um erro de validação explícito que aponta para o campo e para 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 da etiqueta reservada component.aggrega.ai/type; a proibição mecânica de blocos values: no schema da Release (segundo o Invariante 5); a rejeição de extends em conjunto com aggregate na Release (o invariante da fonte única de 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 recusa-se a renderizar tudo o que as viole.
Imposta por um plugin de políticas
A disciplina é imposta por um plugin Wasm executado num 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 a compilação (sockets em banda) ou um aviso consultivo (sockets fora de banda), consoante a semântica de bloqueio do socket.
Uma disciplina só é imposta desta 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 a ser uma convenção. O linter de publicação, que o aggrega lint executa, verifica parte de uma convenção desta página — consulte 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, segundo 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, segundo entities/recipe.md «Cloud-resource naming discipline (Disciplina de nomenclatura de recursos de nuvem)»); um plugin linter próprio pode verificar qualquer uma delas.
Para a superfície do contrato de plugins Wasm e o critério de colocação (o socket do linter versus os papéis de veredicto de governança), consulte 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 assinala. Os autores aprendem a disciplina na documentação, seguem-na porque a forma arquitetural depende dela e contam com a revisão de PR para detetar falhas. Uma violação não produz nenhum sinal em tempo de compilação — a compilação é bem-sucedida, a saída renderizada funciona tanto quanto o compilador sabe, e a violação da disciplina só aparece quando ferramentas a jusante 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 têm de aprender na documentação. O compilador não as interpreta; errá-las não quebra a compilação, mas quebra a forma arquitetural de que o Aggrega depende. A maior parte desta página documenta-as.
As convenções
Os contratos sociais seguintes são mantidos por convenção. Cada entrada indica a disciplina, a superfície onde a convenção está documentada e o modo de falha em caso de violação. Cada um mantém o seu número onde quer que esteja: o contrato 3, a disciplina dos 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
A etiqueta reservada component.aggrega.ai/type indica 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 pertença a esse conjunto é imposta pelo schema, não mantida por convenção. O Aggrega define esta chave e os valores que aceita, o schema do Component enumera-os, e um documento com qualquer outro valor é recusado ao ser carregado — E0215, a condição entity-envelope-invalid, indica a etiqueta e lista os valores que aceita. Essa recusa é o que esta entrada não cobre.
O que continua a ser convenção é qual dos valores se ajusta ao componente em causa. Nada verifica se uma base de dados relacional está etiquetada como stateful-server em vez de server, ou se um consumidor de fila é worker em vez de task; o seletor avalia qualquer valor que encontre sem lhe atribuir significado. O Arquiteto que cria um Component escolhe o valor que descreve como a infraestrutura o deve tratar, e os seletores a jusante, os plugins de políticas e os plugins de renderização Wasm dependem todos de que essa escolha seja honesta.
Classificar num eixo próprio. O conjunto fechado rege apenas esta chave reservada e mais nada. Um catálogo que precise 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 — acrescenta a sua própria chave de etiqueta ao lado da reservada. O schema do Component aceita qualquer outra chave de etiqueta com um valor de cadeia, e o mesmo mecanismo de seletores lê-a, pelo 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 visar qualquer uma delas. A extensão faz-se numa chave própria, nunca num 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 induz em erro tudo o que lê a etiqueta. Um armazenamento de dados etiquetado como server é recusado por uma Feature ou por um socket que seleciona stateful-server — uma paragem que indica o seletor, não a etiqueta errada — e um plugin de políticas ou um plugin de renderização que lê a etiqueta trata-o como computação sem estado. Onde apenas esses leitores o veem, a compilação é bem-sucedida; o erro só aparece quando os artefactos renderizados chegam ao cluster.
2. Separação de .context.annotations.* em três contentores
As anotações em cascata chegam a três contentores com nome — .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, gerido por Ops»; catalog é «o que este componente é, criado pelo Arquiteto»; aggregate é «o que este componente faz, criado pelo Programador».
O compilador não impõe as fronteiras entre os contentores. Os três contentores partilham 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 contentor certo e pelos revisores que detetam fugas entre contentores.
Documentado em: labels-and-annotations.md (a separação em três contentores é um contrato social).
Modo de falha: A lógica de encaminhamento que depende da distinção de intenção entre contentores (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 contentor, independentemente da intenção de autoria. A compilação é bem-sucedida; a saída renderizada pode conter valores semanticamente errados.
4. Autocontenção de provides: na Recipe
Os templates provides: da Recipe fecham-se apenas sobre os dados do próprio nó — .values, .infra, .context.instance_id, .context.rendered_name onde o fornecedor do nó indica um, os .locals resolvidos do nó, mais cadeias estáticas. As referências a .context.inject e .context.uses são proibidas porque a avaliação de provides executa esses templates por qualquer ordem; ler dados de outros nós acoplá-la-ia à 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 dos seus provides, e são locais ao nó, pelo que lê-los não tem qualquer custo em termos de ordem. Indicar uma chave que o bloco locals não declara provoca uma paragem.
Esta é uma regra com duas metades, cada uma a indicar onde é verificada. O compilador verifica a primeira: a avaliação de provides verifica cada template contra uma allowlist positiva das raízes que o seu contexto define antes de o template ser executado, pelo que uma leitura de .context.inject / .context.uses para com um erro explícito em vez de renderizar vazia; 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 deteta as referências proibidas e interrompe a compilação no momento da avaliação dos templates quando estas aparecem diretamente em provides:. A disciplina mais ampla de público versus privado (não expor estado interno através de chaves de provides:) é apenas convenção — os autores que tratam provides: como um espaço de nomes interno da Recipe produzem contratos de que os chamadores dependem; a refatoração torna-se uma alteração 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). Os autores que invocam estes helpers a partir de um template que contribui para a saída renderizada quebram o contrato de determinismo.
O compilador não deteta nem bloqueia a utilização de helpers não herméticos. A FuncMap do Sprig expõe-nos segundo templates/sprig-functions.md «Determinism caveat (Ressalva sobre o determinismo)»; a disciplina é mantida pelos autores que evitam estes helpers em templates do caminho de renderização e pelos revisores que detetam a sua utilização na revisão de PR.
Documentado em: templates/sprig-functions.md «Determinism caveat (Ressalva sobre o determinismo)».
Modo de falha: A saída da compilação difere entre execuções da mesma entrada. A divergência aparece no momento do diff do GitOps, quando ferramentas a jusante (ArgoCD, Flux) veem um desvio inesperado entre o manifesto submetido e o estado do cluster, ou no momento de uma auditoria, quando duas compilações da mesma entrada produzem artefactos 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, pelo que um plugin linter próprio o pode encontrar (consulte 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 uma imposição da linguagem. O motor de templates permite leituras entre pilares em qualquer ponto, salvo quando proibidas explicitamente por regras de autocontenção (por exemplo, provides: e source: da Recipe que leem .context.inject / .context.uses). Os autores devem:
- Ler
.valuespara a carga útil cognitiva (intenção criada pelo programador). - Ler
.infrapara o dimensionamento físico (dimensionamento criado por Ops). - Ler
.context.uses.<alias>.provides.<key>para cadeias de ponteiro entre componentes. - Ler
.context.injectpara 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 (a quem pertencem os dados) e não 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 criação)».
Modo de falha: Fuga entre pilares — a carga útil cognitiva do programador contém detalhes de dimensionamento físico, ou o dimensionamento criado por Ops contém metadados cognitivos. A compilação é bem-sucedida; a divisão de autoria em quatro domínios esbate-se com o tempo à medida que os autores contornam os pilares; a manutenção a jusante torna-se 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 através de expressões de template Go: literais do pilar do programador (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 consoante 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 indicar a intenção (esta entrada é local ao componente; aquela entrada é derivada de outros componentes) para que os futuros responsáveis pela manutenção possam ler que entradas dependem de que saídas da hidratação de inject.
Documentado em: entities/workload.md «Field-semantics essentials (Aspetos essenciais da semântica dos campos)» (variables).
Modo de falha: Os autores que não distinguem as duas fontes perdem o rasto de «que entradas estão acopladas aos provides: de que destino». Refatorar as chaves de provides: de um destino quebra silenciosamente todas as entradas variables: do chamador que liam através do pipe de inject.
8. Disciplina de nomenclatura de recursos de nuvem
As Recipes que emitem nomes de recursos de nuvem (nomes de buckets S3, identificadores de bases de dados RDS, nomes de funções IAM, nomes de stacks CloudFormation — qualquer campo cujo valor ocupe um espaço de nomes global no fornecedor de nuvem) têm de concatenar {{ .metadata.release_name }} e/ou {{ .context.instance_id }} no 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: à procura de campos de nomes de recursos de nuvem sem estas interpolações. A disciplina é mantida pelos autores da Recipe (que sabem que campos identificam recursos globalmente únicos para o fornecedor de destino) e pelos revisores (que detetam 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 implementar um recurso com o mesmo nome global; a segunda implementação falha em tempo de execução com uma rejeição do lado da nuvem. A compilação do Aggrega é bem-sucedida; a falha de implementaçã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 contêm as interpolações exigidas; um plugin linter próprio pode fazê-lo (consulte 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 juntamente com as suas cargas de trabalho auxiliares apenas internas. Quando um chart agrupa serviços que outro componente poderia, com sentido, usar através de use de forma isolada — sobretudo infraestrutura externa, como uma base de dados, uma cache ou um message broker, que o Aggrega já modela como um Component próprio — a biblioteca padrão compõe Components por serviço num 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 numa stack.
O compilador é agnóstico em relação a esta granularidade. Renderiza tudo o que passe na validação do schema — não inspeciona quantos serviços a Recipe de um Component agrupa, nem se algum deles é utilizável de forma independente. Um autor que envolva um produto de cinco serviços como um único Component produz um Component que o compilador aceita e renderiza sem objeções; 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 compila com sucesso, mas os serviços agrupados ficam invisíveis para a topologia, o seletor e as políticas — não podem ser escalados, substituídos nem usados como dependência de forma independente. Refatorar mais tarde o monólito em Components por serviço é uma alteração incompatível para todos os consumidores que referenciavam o único nó empacotado.
Porque existem as convenções
Cada uma destas convenções é disciplina de autoria por conceção, embora um schema ou uma política Wasm pudesse impor qualquer uma delas. O raciocínio por tipo de contrato:
Extensibilidade. A disciplina dos prefixos reservados (contrato 3) descreve o vocabulário da biblioteca padrão, não o universo do vocabulário válido. Os catálogos empresariais criam os seus próprios prefixos e chaves de etiqueta para estender a biblioteca padrão; impor por schema a convenção dos 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 numa superfície diferente: a chave reservada que o Aggrega define tem um conjunto fechado, imposto pelo schema, e um catálogo faz a extensão acrescentando uma chave de etiqueta 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 do determinismo (contrato 5) exigem a inspeção do 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 o compilador de depender do estado em tempo de execução; a inspeção estática dos templates é viável (um plugin linter lê os templates da entidade tal como estão 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 retira estas verificações do compilador e coloca-as em plugins Wasm, segundo 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 exprimir um padrão que respeita a disciplina ou um que a viola; tornar a disciplina uma verificação em tempo de execução exigiria que o compilador interpretasse uma intenção de autoria a que 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 enquadra aqui: as empresas podem envolver um produto com a granularidade que o seu catálogo preferir, e o compilador — neutro quanto ao conteúdo e sem opiniões próprias segundo o Invariante 1 — não tem forma de saber se uma carga de trabalho agrupada é utilizável de forma independente, pelo que a fronteira de um serviço coerente continua a ser disciplina de autoria e não um muro de schema. A escolha do tipo operacional (contrato 1) tem a mesma forma: o schema estabelece que valores existem, mas qual deles descreve um dado componente é um juízo de modelação sobre a forma como a infraestrutura o deve tratar, e nada numa Recipe ou num bloco values diz ao compilador se o juízo 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 deteta 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) está ancorada na convenção, porque o compilador não consegue determinar que cadeias devem permanecer internas à Recipe sem a intenção de autoria.
As três vias importam porque cada uma indica onde reside a responsabilidade de detetar 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. Os autores que interiorizam as vias percebem que erros o compilador irá detetar e quais passarão silenciosamente para as ferramentas a jusante 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. A sua constatação é consultiva, e a parte da convenção que não alcança é mantida por convenção, tal 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 se aplica às chaves de etiqueta 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 inclui.
As restantes convenções (1, 2, 4, 6, 7, 9) dependem do que o autor pretendia, que nenhuma regra lê a partir do que foi escrito. A separação em contentores é motivada pela extensibilidade (os catálogos empresariais redefinem-na) — a imposição por schema entraria em conflito com essa flexibilidade. O que resta do eixo do tipo operacional depois de o schema estabelecer 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 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 a partir da sintaxe dos templates. A autocontenção de provides: na Recipe é parcialmente imposta; a disciplina mais ampla de público versus privado depende das chaves que o autor pretendia manter internas, algo que nada na Recipe declara. A granularidade do Component também é motivada pela intenção de autoria — saber se uma carga de trabalho agrupada é utilizável de forma independente é um juízo de modelação que o compilador não consegue ler no conteúdo da Recipe.
3. Disciplina dos prefixos reservados
As chaves de anotação e de etiqueta seguem a forma <namespace>/<name>. Cinco prefixos reservados têm 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>/ (empresa / comunidade).
O compilador não rejeita uma anotação criada sob um prefixo reservado numa entidade do catálogo ou numa Release; apenas um binding de anotação de um Manifest ou uma etiqueta de saída de uma Recipe que reivindique uma chave sob aggrega.ai/ interrompe a compilação. Uma empresa que declare 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 contentores; as 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: As anotações personalizadas sob prefixos reservados colidem com futuras anotações da plataforma com o mesmo nome; o comportamento esperado da plataforma substitui silenciosamente o valor criado pela empresa ou coexiste com ele, consoante a ordem.
O linter de publicação, executado pelo aggrega lint, assinala uma chave de anotação de uma entidade do catálogo sob aggrega.ai/ que não seja uma das anotações conhecidas da plataforma, e uma sob feature.aggrega.ai/ numa entidade que não seja uma Feature, como constatação consultiva (E0277). As chaves de etiqueta, os outros prefixos reservados e as anotações fora de metadata.annotations de uma entidade — as que uma Release escreve, por exemplo — não são verificados, pelo que, para eles, a disciplina continua a ser uma convenção.
Referências cruzadas
architecture/05-invariants.md— os oito invariantes fundadores que sustentam a formulação do Aggrega «o compilador é neutro quanto ao conteúdo»; cada convenção está em tensão com um ou mais deles.architecture/02-ecosystem-philosophy.md— a fundamentação completa do design da ontologia operacional.vocabulary/labels-and-annotations.md— a separação em três contentores como contrato social; disciplina dos prefixos reservados.vocabulary/data-pillars.md— as fronteiras dos pilares como sinais; a formulação de público versus privado deprovides:elocals:.templates/sprig-functions.md— a ressalva sobre o determinismo que indica os helpers não herméticos.entities/recipe.md— disciplina de nomenclatura de recursos de nuvem + exemplos práticos.entities/workload.md— semântica de dupla origem devariables:do Workload.templates/expansion-matrix.md— a autocontenção deprovides:na Recipe como regra imposta pelo compilador.plugins/plugin-contract.md— o critério de colocação do socket do linter.cli/aggrega-lint.md— as regras do linter de publicação e como anexar linters próprios.