appliesTo e seletores
O sistema de modificadores governa a quais nós uma Feature se vincula. Uma Feature declara seletores de rótulos; o motor nativo de correspondência de rótulos do compilador os avalia em relação aos metadata.labels de cada Component de destino durante a etapa de análise estática. O mesmo motor — e a mesma gramática de seletores — também avalia os seletores de socket usesSchema para a segurança de tipos entre nós, de modo que um único vocabulário serve a todas as superfícies de seletor da linguagem.
Os dois envelopes
Uma spec de Feature carrega até dois campos de seletor:
appliesTo— a superfície de composição AND. Uma única string de seletor de rótulos no estilo Kubernetes; cada requisito separado por vírgulas precisa ser atendido para que a vinculação seja válida.appliesToAnyOf— a superfície de composição OR. Uma lista de itens de seletor; qualquer item correspondente satisfaz sozinho a vinculação. Cada item é ou um seletor em forma de string (a mesma gramática deappliesTo, com os requisitos dentro da string combinados em AND) ou um mapa plano de chave-valor comparado apenas por igualdade.
Quando uma Feature declara ambos, os resultados se combinam em AND entre os envelopes: a string appliesTo precisa ser atendida e pelo menos um item de appliesToAnyOf precisa corresponder. Um seletor omitido ou vazio não declara nenhuma restrição e corresponde a qualquer conjunto de rótulos — uma Feature sem nenhum dos dois campos se vincula onde quer que o desenvolvedor a coloque.
spec: appliesTo: "compliance.aggrega.ai/scope in (pci), tier notin (dev, staging)" appliesToAnyOf: - { component.aggrega.ai/type: stateful-server } - "datastore.aggrega.ai/engine in (relational, document, vector)"A gramática da string
A string do seletor segue a sintaxe de seletores de rótulos que kubectl get -l aceita: requisitos separados por vírgulas, compostos em AND, cada um em uma de seis formas:
| Forma | Significado |
|---|---|
key=value | o rótulo existe com exatamente este valor |
key!=value | o rótulo está ausente, ou presente com um valor diferente |
key in (v1, v2) | o valor do rótulo é um dos do conjunto |
key notin (v1, v2) | o rótulo está ausente, ou seu valor está fora do conjunto |
key | o rótulo existe (qualquer valor) |
!key | o rótulo está ausente |
As chaves podem carregar prefixos no estilo DNS (team.aggrega.ai/owner). O vocabulário de operadores é um conjunto fechado de seis; o motor não suporta expressões regulares, substrings nem comparações numéricas.
appliesTo: "component.aggrega.ai/type in (server, worker), !legacy.aggrega.ai/exempt"Um requisito fora das seis formas é recusado, nunca adivinhado:
- Um requisito vazio — uma vírgula inicial, final ou duplicada, ou uma string formada apenas por separadores.
"tier=frontend,"e" , , "são recusadas em vez de lidas como menos requisitos, ou como nenhum. - Uma chave que contém espaços em branco ou um dos caracteres próprios da gramática —
=,!,(,)e a vírgula, que são o que distingue uma forma da outra.!nomeia uma chave de rótulo e nada mais, então!tier=frontendé recusado: escrito para excluir os frontends, ele seria lido de outra forma como “o rótulo chamadotier=frontendestá ausente”, o que todo componente satisfaz.tier!=frontendé a forma de excluir um valor. Da mesma maneira,tier in frontendé recusado — um conjunto é escritotier in (frontend)— etier: frontendtambém. - Um conjunto que não está fechado —
in (ounotin (sem o seu).
Um valor não está sujeito a nenhum conjunto de caracteres: é o texto após o operador, sem os espaços em branco ao redor, comparado com o valor do rótulo tal como está escrito. Assim, tier==frontend pede um rótulo cujo valor é =frontend; == não é uma segunda grafia da igualdade. Além da regra sobre chaves acima, nem uma chave nem um valor são julgados — os rótulos são strings opacas que o motor compara.
Onde fica a validação
Duas camadas verificam um seletor, com rigor deliberadamente diferente:
- O
patterndo JSON Schema é uma barreira externa folgada. O schema da Feature declaraappliesTo(e os itens deappliesToAnyOfem forma de string) como strings com um padrão delimitador que recusa apenas formas claramente malformadas. Ele é deliberadamente permissivo — o schema nunca recusa um seletor que o motor avaliaria. - O parser é o validador. O parser de seletores do compilador é dono da gramática: um seletor que ele recusa — qualquer uma das formas acima — interrompe o build com um diagnóstico que nomeia o seletor, a Feature, o socket ou o slot que o declara, e o requisito que ele não conseguiu ler. As falhas de parsing são explícitas e específicas, nunca ignoradas em silêncio. Em um build, o parser é executado onde um seletor é avaliado — para cada vinculação de uma Feature, cada aresta conectada por meio de um socket, cada preenchimento de um slot.
aggrega validate, sobre o catálogo inteiro ou sobre um único Component ou Feature, também lê cada seletor de socket e de slot que o documento da entidade declara, então um seletor malformado em um socket ou slot que nada usa é recusado ali, com o código e nas palavras que um build usa. UmappliesTomalformado em uma Feature que nada vincula não é reportado até que algo o faça.
Um seletor que é analisado mas não corresponde não é um erro em si — é uma restrição não satisfeita. Na análise estática, cada vinculação de Feature cujos rótulos de destino não satisfazem os seletores da Feature produz um diagnóstico de violação que nomeia a instância da funcionalidade, o nó de destino, seus rótulos e a restrição; o analisador coleta todas as violações antes de interromper, de modo que uma única compilação revela todas elas.
O que o compilador não faz
O compilador é agnóstico em relação à semântica dos rótulos. Ele avalia quaisquer strings de rótulo que encontre — não reconhece component.aggrega.ai/type como especial, não valida se um valor de categoria pertence ao conjunto fechado do catálogo padrão e não infere significado a partir dos nomes das chaves. O próprio vocabulário de rótulos — o contrato do tipo operacional, o eixo de categoria cognitiva, os rótulos de capacidade por papel — é uma convenção da biblioteca padrão mantida pelos autores do catálogo e pelo linter de publicação, não pelo compilador. As empresas que escrevem seus próprios catálogos são livres para definir seu próprio vocabulário de rótulos; o motor de seletores o avalia de forma idêntica. Para o esquema de rótulos de três eixos que o catálogo padrão usa, consulte architecture/13-catalog-and-registry.md; para a explicação rótulo a rótulo, consulte architecture/09-ai-features.md §1.2.
Parentesco dos seletores em toda a linguagem
Os seletores de socket usesSchema (selector: "component.aggrega.ai/type=stateful-server") e as anotações x-aggrega-selector: sintetizadas a partir deles usam a mesma gramática e o mesmo motor que o appliesTo de uma Feature. O conhecimento de autoria se transfere de um para um: uma string que funciona como seletor de socket funciona como seletor de vinculação. Para a explicação do lado do socket, consulte topology-triad.md e entities/component.md.
Para a superfície de autoria do lado da Feature — os campos da spec, exemplos de vinculação detalhados e a interação com a herança extends —, consulte entities/feature.md §Label-Based Attachment (Anexação baseada em labels).