appliesTo et sélecteurs
Le système de modificateurs gouverne les nœuds auxquels une Feature se rattache. Une Feature déclare des sélecteurs de labels ; le moteur natif de correspondance de labels du compilateur les évalue par rapport aux metadata.labels de chaque Component cible pendant l’étape d’analyse statique. Le même moteur — et la même grammaire de sélecteurs — évalue aussi les sélecteurs de socket usesSchema pour la sûreté de typage entre nœuds, de sorte qu’un seul vocabulaire sert toutes les surfaces de sélecteur du langage.
Les deux enveloppes
Une spec de Feature porte jusqu’à deux champs de sélecteur :
appliesTo— la surface de composition AND. Une seule chaîne de sélecteur de labels de style Kubernetes ; chaque exigence séparée par des virgules doit être satisfaite pour que le rattachement soit valide.appliesToAnyOf— la surface de composition OR. Une liste d’éléments de sélecteur ; un seul élément correspondant suffit à satisfaire le rattachement. Chaque élément est soit un sélecteur sous forme de chaîne (même grammaire queappliesTo, les exigences à l’intérieur de la chaîne se combinant en AND), soit une map clé-valeur plate comparée uniquement par égalité.
Lorsqu’une Feature déclare les deux, les résultats se combinent en AND entre les enveloppes : la chaîne appliesTo doit être satisfaite et au moins un élément de appliesToAnyOf doit correspondre. Un sélecteur omis ou vide ne déclare aucune contrainte et correspond à tout ensemble de labels — une Feature sans aucun des deux champs se rattache partout où le développeur la place.
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)"La grammaire de la chaîne
La chaîne de sélecteur suit la syntaxe de sélecteur de labels qu’accepte kubectl get -l : des exigences séparées par des virgules, composées en AND, chacune sous l’une de six formes :
| Forme | Signification |
|---|---|
key=value | le label existe avec exactement cette valeur |
key!=value | le label est absent, ou présent avec une valeur différente |
key in (v1, v2) | la valeur du label fait partie de l’ensemble |
key notin (v1, v2) | le label est absent, ou sa valeur est hors de l’ensemble |
key | le label existe (n’importe quelle valeur) |
!key | le label est absent |
Les clés peuvent porter des préfixes de style DNS (team.aggrega.ai/owner). Le vocabulaire des opérateurs est un ensemble fermé de six ; le moteur ne prend en charge ni les expressions régulières, ni les sous-chaînes, ni la comparaison numérique.
appliesTo: "component.aggrega.ai/type in (server, worker), !legacy.aggrega.ai/exempt"Une exigence hors des six formes est refusée, jamais devinée :
- Une exigence vide — une virgule en tête, en fin ou doublée, ou une chaîne composée uniquement de séparateurs.
"tier=frontend,"et" , , "sont refusées plutôt que lues comme un nombre moindre d’exigences, ou comme aucune. - Une clé contenant des espaces ou l’un des caractères propres à la grammaire —
=,!,(,)et la virgule, qui sont ce qui distingue une forme d’une autre.!nomme une clé de label et rien d’autre, donc!tier=frontendest refusé : écrit pour exclure les frontends, il serait sinon lu comme « le label nommétier=frontendest absent », ce que satisfait tout composant.tier!=frontendest la manière d’exclure une valeur. De la même manière,tier in frontendest refusé — un ensemble s’écrittier in (frontend)— ettier: frontendl’est aussi. - Un ensemble non fermé —
in (ounotin (sans sa).
Une valeur n’est soumise à aucun jeu de caractères : c’est le texte qui suit l’opérateur, débarrassé des espaces qui l’entourent, comparé à la valeur du label telle qu’elle est écrite. Ainsi tier==frontend demande un label dont la valeur est =frontend ; == n’est pas une seconde écriture de l’égalité. Au-delà de la règle sur les clés ci-dessus, ni une clé ni une valeur ne sont jugées — les labels sont des chaînes opaques que le moteur compare.
Où se trouve la validation
Deux couches vérifient un sélecteur, avec une rigueur délibérément différente :
- Le
patterndu JSON Schema est une barrière externe souple. Le schéma de la Feature déclareappliesTo(et les éléments deappliesToAnyOfsous forme de chaîne) comme des chaînes avec un motif de délimitation qui ne refuse que les formes manifestement malformées. Il est délibérément permissif — le schéma ne refuse jamais un sélecteur que le moteur évaluerait. - L’analyseur est le validateur. L’analyseur de sélecteurs du compilateur possède la grammaire : un sélecteur qu’il refuse — l’une quelconque des formes ci-dessus — arrête le build avec un diagnostic qui nomme le sélecteur, la Feature, le socket ou le slot qui le déclare, et l’exigence qu’il n’a pas pu lire. Les échecs d’analyse sont bruyants et précis, jamais ignorés silencieusement. Dans un build, l’analyseur s’exécute là où un sélecteur est évalué — pour chaque rattachement d’une Feature, chaque arête câblée à travers un socket, chaque remplissage d’un slot.
aggrega validate, sur l’ensemble du catalogue ou sur un seul Component ou une seule Feature, lit aussi chaque sélecteur de socket et de slot que déclare le document de l’entité, de sorte qu’un sélecteur malformé sur un socket ou un slot que rien n’utilise y est refusé, sous le code et dans les termes qu’emploie un build. UnappliesTomalformé sur une Feature que rien ne rattache n’est pas signalé tant que quelque chose ne le fait pas.
Un sélecteur qui s’analyse mais ne correspond pas n’est pas une erreur en soi — c’est une contrainte non satisfaite. Lors de l’analyse statique, chaque rattachement de Feature dont les labels cibles ne satisfont pas les sélecteurs de la Feature produit un diagnostic de violation qui nomme l’instance de fonctionnalité, le nœud cible, ses labels et la contrainte ; l’analyseur collecte chaque violation avant de s’arrêter, de sorte qu’une seule compilation les fait toutes apparaître.
Ce que le compilateur ne fait pas
Le compilateur est agnostique vis-à-vis de la sémantique des labels. Il évalue toutes les chaînes de label qu’il trouve — il ne reconnaît pas component.aggrega.ai/type comme spéciale, ne valide pas qu’une valeur de catégorie appartient à l’ensemble fermé du catalogue standard et n’infère aucun sens des noms de clés. Le vocabulaire de labels lui-même — le contrat de type opérationnel, l’axe de catégorie cognitive, les labels de capacité par rôle — est une convention de la bibliothèque standard maintenue par les auteurs de catalogues et le linter de publication, pas par le compilateur. Les entreprises qui rédigent leurs propres catalogues sont libres de définir leur propre vocabulaire de labels ; le moteur de sélecteurs l’évalue de manière identique. Pour le schéma de labels à trois axes qu’utilise le catalogue standard, voir architecture/13-catalog-and-registry.md ; pour l’exposé label par label, voir architecture/09-ai-features.md §1.2.
Parenté des sélecteurs dans tout le langage
Les sélecteurs de socket usesSchema (selector: "component.aggrega.ai/type=stateful-server") et les annotations x-aggrega-selector: synthétisées à partir d’eux utilisent la même grammaire et le même moteur que l’appliesTo d’une Feature. Les connaissances de rédaction se transposent à l’identique : une chaîne qui fonctionne comme sélecteur de socket fonctionne comme sélecteur de rattachement. Pour l’exposé côté socket, voir topology-triad.md et entities/component.md.
Pour la surface de rédaction côté Feature — les champs de la spec, des exemples de rattachement détaillés et l’interaction avec l’héritage extends — voir entities/feature.md §Label-Based Attachment (Rattachement par labels).