appliesTo und Selektoren
Das Modifikatorsystem regelt, an welche Knoten ein Feature angebunden wird. Ein Feature deklariert Label-Selektoren; die native Label-Matching-Engine des Compilers wertet sie während der Stufe der statischen Analyse gegen die metadata.labels jeder Ziel-Component aus. Dieselbe Engine — und dieselbe Selektorgrammatik — wertet auch Socket-Selektoren usesSchema für knotenübergreifende Typsicherheit aus, sodass ein einziges Vokabular jeder Selektoroberfläche der Sprache dient.
Die zwei Hüllen
Eine Feature-Spec trägt bis zu zwei Selektorfelder:
appliesTo— die Oberfläche für AND-Komposition. Ein einzelner Label-Selektor-String im Kubernetes-Stil; jede kommagetrennte Anforderung muss erfüllt sein, damit die Anbindung gültig ist.appliesToAnyOf— die Oberfläche für OR-Komposition. Eine Liste von Selektorelementen; ein einziges passendes Element erfüllt die Anbindung. Jedes Element ist entweder ein Selektor in String-Form (dieselbe Grammatik wieappliesTo, Anforderungen innerhalb des Strings werden per AND verknüpft) oder eine flache Schlüssel-Wert-Map, die nur auf Gleichheit geprüft wird.
Wenn ein Feature beide deklariert, werden die Ergebnisse über die Hüllen hinweg per AND verknüpft: Der String appliesTo muss erfüllt sein, und mindestens ein Element von appliesToAnyOf muss passen. Ein ausgelassener oder leerer Selektor deklariert keine Einschränkung und passt auf jede Label-Menge — ein Feature ohne eines der beiden Felder wird überall angebunden, wo der Entwickler es platziert.
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)"Die String-Grammatik
Der Selektor-String folgt der Label-Selektor-Syntax, die kubectl get -l akzeptiert: kommagetrennte Anforderungen, per AND verknüpft, jede in einer von sechs Formen:
| Form | Bedeutung |
|---|---|
key=value | das Label existiert mit genau diesem Wert |
key!=value | das Label fehlt oder ist mit einem anderen Wert vorhanden |
key in (v1, v2) | der Wert des Labels ist einer aus der Menge |
key notin (v1, v2) | das Label fehlt, oder sein Wert liegt außerhalb der Menge |
key | das Label existiert (beliebiger Wert) |
!key | das Label fehlt |
Schlüssel können Präfixe im DNS-Stil tragen (team.aggrega.ai/owner). Das Operatorvokabular ist eine geschlossene Menge von sechs; die Engine unterstützt keine regulären Ausdrücke, keine Teilstrings und keine numerischen Vergleiche.
appliesTo: "component.aggrega.ai/type in (server, worker), !legacy.aggrega.ai/exempt"Eine Anforderung außerhalb der sechs Formen wird zurückgewiesen, nie erraten:
- Eine leere Anforderung — ein führendes, abschließendes oder doppeltes Komma oder ein String, der nur aus Trennzeichen besteht.
"tier=frontend,"und" , , "werden zurückgewiesen, statt als weniger Anforderungen oder als gar keine gelesen zu werden. - Ein Schlüssel, der Leerraum oder eines der eigenen Zeichen der Grammatik enthält —
=,!,(,)und das Komma, die eine Form von einer anderen unterscheiden.!benennt einen Label-Schlüssel und nichts anderes, daher wird!tier=frontendzurückgewiesen: Geschrieben, um Frontends auszuschließen, würde es sonst als „das Label namenstier=frontendfehlt“ gelesen, was jede Komponente erfüllt.tier!=frontendist die Art, einen Wert auszuschließen. Ebenso wirdtier in frontendzurückgewiesen — eine Menge wirdtier in (frontend)geschrieben — und ebensotier: frontend. - Eine nicht geschlossene Menge —
in (odernotin (ohne ihr).
Ein Wert ist an keinen Zeichensatz gebunden: Er ist der Text nach dem Operator, ohne umgebenden Leerraum, verglichen mit dem Wert des Labels, wie er geschrieben ist. So fragt tier==frontend nach einem Label, dessen Wert =frontend ist; == ist keine zweite Schreibweise der Gleichheit. Über die obige Schlüsselregel hinaus wird weder ein Schlüssel noch ein Wert beurteilt — Labels sind opake Strings, die die Engine vergleicht.
Wo die Validierung stattfindet
Zwei Ebenen prüfen einen Selektor, mit bewusst unterschiedlicher Strenge:
- Das
patterndes JSON Schema ist ein lockeres äußeres Tor. Das Feature-Schema deklariertappliesTo(und Elemente vonappliesToAnyOfin String-Form) als Strings mit einem begrenzenden Muster, das nur offensichtlich fehlerhafte Formen zurückweist. Es ist bewusst nachsichtig — das Schema weist nie einen Selektor zurück, den die Engine auswerten würde. - Der Parser ist der Validator. Der Selektorparser des Compilers besitzt die Grammatik: Ein Selektor, den er zurückweist — eine der obigen Formen —, hält den Build mit einer Diagnose an, die den Selektor, das ihn deklarierende Feature, den Socket oder Slot sowie die Anforderung nennt, die er nicht lesen konnte. Parse-Fehler sind laut und konkret, nie stillschweigend übersprungen. In einem Build läuft der Parser dort, wo ein Selektor ausgewertet wird — für jede Anbindung eines Feature, jede über einen Socket verdrahtete Kante, jede Befüllung eines Slots.
aggrega validateliest, über den ganzen Katalog oder über eine einzelne Component oder ein einzelnes Feature, zudem jeden Socket- und Slot-Selektor, den das Dokument der Entität deklariert, sodass ein fehlerhafter Selektor an einem Socket oder Slot, den nichts verwendet, dort zurückgewiesen wird, unter dem Code und mit den Worten, die ein Build verwendet. Ein fehlerhaftesappliesToan einem Feature, das nichts anbindet, wird erst gemeldet, wenn etwas es tut.
Ein Selektor, der geparst wird, aber nicht passt, ist an sich kein Fehler — er ist eine unerfüllte Einschränkung. Bei der statischen Analyse erzeugt jede Feature-Anbindung, deren Ziel-Labels die Selektoren des Feature nicht erfüllen, eine Verletzungsdiagnose, die die Funktionsinstanz, den Zielknoten, seine Labels und die Einschränkung nennt; der Analysator sammelt jede Verletzung, bevor er anhält, sodass ein einziger Kompiliervorgang alle sichtbar macht.
Was der Compiler nicht tut
Der Compiler ist agnostisch gegenüber der Semantik von Labels. Er wertet alle Label-Strings aus, die er findet — er erkennt component.aggrega.ai/type nicht als besonders, prüft nicht, ob ein Kategoriewert zur geschlossenen Menge des Standardkatalogs gehört, und leitet keine Bedeutung aus Schlüsselnamen ab. Das Label-Vokabular selbst — der operative Typvertrag, die kognitive Kategorienachse, die rollenbezogenen Fähigkeits-Labels — ist eine Konvention der Standardbibliothek, die von Katalogautoren und dem Veröffentlichungs-Linter getragen wird, nicht vom Compiler. Unternehmen, die eigene Kataloge verfassen, können ihr eigenes Label-Vokabular definieren; die Selektor-Engine wertet es identisch aus. Zum Drei-Achsen-Label-Schema, das der Standardkatalog verwendet, siehe architecture/13-catalog-and-registry.md; zur Darstellung der einzelnen Labels siehe architecture/09-ai-features.md §1.2.
Verwandtschaft der Selektoren in der gesamten Sprache
Socket-Selektoren usesSchema (selector: "component.aggrega.ai/type=stateful-server") und die daraus synthetisierten Annotationen x-aggrega-selector: verwenden dieselbe Grammatik und dieselbe Engine wie das appliesTo eines Feature. Authoring-Wissen lässt sich eins zu eins übertragen: Ein String, der als Socket-Selektor funktioniert, funktioniert auch als Anbindungsselektor. Zur Darstellung auf der Socket-Seite siehe topology-triad.md und entities/component.md.
Zur Authoring-Oberfläche auf der Feature-Seite — den Spec-Feldern, ausgearbeiteten Anbindungsbeispielen und dem Zusammenspiel mit der Vererbung über extends — siehe entities/feature.md §Label-Based Attachment (Label-basierte Anbindung).