Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Component

Le rôle conceptuel de l’entité Component (l’interface abstraite d’un nœud de calcul dans le Domaine 2) est décrit dans architecture/04-entity-taxonomy.md. Cette page couvre la surface de rédaction du Component : la taxonomie des labels sémantiques que les architectes utilisent pour superposer une identité cognitive à l’ontologie opérationnelle de base, la déclaration schema: pour les piliers de données, les tables déclaratives usesSchema et featuresSchema pour les sockets de topologie et les emplacements de rattachement, les obligations de présence, le mécanisme d’héritage extends: et le bloc de règles inter-champs assertions:.

La taxonomie des labels sémantiques (la convention de la bibliothèque standard)

Si les types de base sont purement cloud-native, l’intelligence opérationnelle et cognitive de l’architecture est entièrement superposée par duck typing sémantique.

Le compilateur Go central n’interprète pas ces labels. Le compilateur construit le graphe plat de la représentation intermédiaire (IR) sans interpréter la sémantique des labels. Ces labels représentent la convention de la bibliothèque standard—des « marqueurs génétiques » immuables rédigés par l’architecte de plateforme dans le domaine 2. Ils fournissent les points d’ancrage sémantiques explicites que les validateurs de politiques Wasm et les Recipes physiques d’Ops utilisent pour gouverner l’architecture.

(A) La couche cloud générique Ces labels décrivent des comportements universels, permettant aux moteurs de politiques et aux proxys L7 générés de gouverner des architectures d’entreprise standard sans avoir besoin de comprendre nativement les frameworks d’IA.

Préfixe du labelValeurs autorisées (convention)Pourquoi Platform Ops en a besoin (le point d’ancrage de politique)
tool.aggrega.ai/impactread-only, mutatingPermet aux moteurs de politiques d’évaluer une autorisation au moindre privilège (Least-Privilege AuthZ). Les outils qui modifient des données peuvent déclencher automatiquement des politiques exigeant l’attachement de sidecars d’approbation stricts.
datastore.aggrega.ai/enginerelational, document, kv, vector, graph, semantic-memory, search (ensemble de valeurs en cours de stabilisation au regard du catalogue peuplé)Permet aux moteurs de politiques d’imposer la sûreté de typage entre nœuds (par exemple, en empêchant un agent de tenter d’envoyer des charges utiles SQL à une base de données vectorielle).
gateway.aggrega.ai/intelligencesemantic, l4-meshDétermine quelles fonctionnalités un routeur peut physiquement prendre en charge (par exemple, en empêchant une Feature qui route selon le modèle nommé par une requête, comme une chaîne de repli, de s’attacher à un maillage TCP standard).
dataplane.aggrega.ai/request-mirroringfull-rate, sampledPermet à une Feature qui copie le trafic réel vers une seconde destination de sélectionner un proxy capable de copier tout court, et de distinguer celui qui copie chaque requête correspondante de celui dont la part de requêtes copiées est paramétrable.
dataplane.aggrega.ai/caller-identityclient-certificate, injected-headerPermet à une Feature qui a besoin que l’appelant d’origine soit identifié auprès du service situé derrière le proxy de sélectionner un composant capable de transmettre cette identité, et de lire quel mécanisme la transmet — les détails du propre certificat TLS du client, relayés, ou un en-tête que le proxy compose lui-même après avoir authentifié l’appelant.
dataplane.aggrega.ai/content-maskingentity-recognition, pattern-listPermet à une Feature qui masque du texte sensible de sélectionner un composant capable de le remplacer par un espace réservé dans la charge utile de chat et de complétion qu’il route, avant que le texte n’aille plus loin. La valeur nomme la fidélité : avec entity-recognition, le composant remplace les correspondances des motifs fournis dans sa configuration, ainsi que les types d’entités que détecte un service de reconnaissance qu’il appelle ; avec pattern-list, il remplace uniquement les correspondances des motifs fournis dans sa configuration, et n’appelle aucun service de reconnaissance.
dataplane.aggrega.ai/prompt-guardpattern-list, classifierPermet à une Feature qui filtre les prompts de modèle de sélectionner un composant capable d’inspecter la charge utile de chat et de complétion qu’il route et de refuser une requête en fonction de son contenu. La valeur nomme la fidélité : avec pattern-list, la correspondance se fait avec des motifs fournis dans sa configuration, sur la charge utile du modèle et non sur un corps HTTP arbitraire ; avec classifier, le verdict est celui d’un classificateur de texte entraîné, atteint via un service de détection que le composant appelle, au regard d’un seuil fourni dans sa configuration.
dataplane.aggrega.ai/upstream-tlstrust-anchorPermet à une Feature qui exige que le proxy vérifie avec qui il communique de sélectionner un composant capable de vérifier le certificat d’un upstream au regard d’une ancre de confiance fournie par la Release.
dataplane.aggrega.ai/upstream-pinningpublic-keyPermet à une Feature qui épingle la clé qu’un upstream peut présenter de sélectionner un composant capable de refuser un upstream à moins qu’un certificat qu’il présente ne porte l’une des clés publiques fournies par la Release. Une assertion différente de upstream-tls : un épinglage dit quelle clé un certificat doit être, une ancre ce qu’il doit dire.
dataplane.aggrega.ai/period-budgetcost, tokensPermet à une Feature qui borne ce que le trafic peut consommer sur une période de sélectionner un composant capable de refuser les requêtes de modèle dès que ce qu’il a compté sur la période dépasse une limite définie dans sa configuration. La valeur nomme ce qu’il compte : cost, ce que le trafic a coûté, tarifé d’après une table que le composant tient par modèle ; tokens, les jetons que la réponse de chaque modèle déclare avoir lus, écrits ou les deux, que le composant compte sans rien tarifer.
dataplane.aggrega.ai/concurrency-captotal, per-targetPermet à une Feature qui plafonne le nombre de requêtes qu’un composant traite simultanément de sélectionner un composant capable de retenir ou de refuser une requête au-delà d’un plafond défini dans sa configuration. La valeur nomme ce que compte un plafond : total, chaque requête que le composant transmet, au regard d’un plafond unique ; per-target, les requêtes en cours vers chaque cible upstream à laquelle il envoie, avec un plafond pour chacune et aucun sur leur total.

Les clés dataplane.aggrega.ai/ nomment une position sur le chemin du trafic plutôt qu’un type de composant, de sorte qu’un proxy, une passerelle d’ingress et un service mesh se décrivent tous dans un seul vocabulaire au lieu d’avoir chacun le sien. Deux propriétés de cette famille méritent une lecture attentive, car toutes deux sont faciles à inverser :

  • La valeur porte la fidélité, pas seulement la présence de la capacité. Deux composants peuvent tous deux dupliquer des requêtes et différer néanmoins d’une manière qui importe à une Feature ; la distinction passe donc par la valeur, et une Feature sélectionne la fidélité dont elle a besoin. Un composant qui offre une fidélité plus forte porte la valeur la plus forte et aucune autre.
  • Une valeur affirme ce que le produit est capable de faire, jamais ce qu’un déploiement a activé. Les deux se lisent de la même façon, et seul le premier est une propriété du composant. Un proxy capable de vérifier le certificat d’un upstream porte upstream-tls: trust-anchor, qu’un déploiement donné active ou non la vérification, car le label est ce sur quoi une Feature sélectionne avant que quoi que ce soit ne soit configuré.

Un composant qui n’a rien à décrire sur l’un de ces axes n’y porte aucune valeur plutôt qu’une valeur la plus faible, exactement comme ailleurs dans la taxonomie : l’absence signifie que l’axe n’a pas d’objet sur ce composant, de sorte qu’une Feature exigeant une valeur quelconque sur cet axe, à juste titre, ne s’attache pas.

(B) La couche d’IA spécialisée (l’identité cognitive) Ces labels décrivent l’identité cognitive de la charge de travail, permettant à l’architecture de sécuriser les frameworks d’IA modernes.

Préfixe du labelValeurs autorisées (convention)Pourquoi Platform Ops en a besoin (le point d’ancrage de politique)
model.aggrega.ai/capabilitygenerative, embedding, transcriptionUtilisé par les chaînes de sélecteur de usesSchema (évaluées nativement par le compilateur Go pendant l’analyse statique) pour garantir qu’un développeur ne route pas par accident une charge utile de texte génératif vers un endpoint d’embedding.
model.aggrega.ai/apiopenai, anthropic, gemini, nativeNomme l’API de modèle qui répond à l’adresse publiée par un composant : openai lorsqu’il s’agit de l’API OpenAI, celle du fournisseur lui-même ou l’implémentation qu’en fait un serveur, anthropic lorsqu’il s’agit de la Messages API d’Anthropic, celle du fournisseur lui-même ou l’implémentation qu’en fait un serveur, gemini lorsqu’il s’agit de la Gemini API de Google, et native lorsqu’il s’agit de l’API propre au produit et d’aucune de celles-ci. Chaque composant de modèle le porte, de même qu’une passerelle capable de servir une API de modèle, de sorte qu’un socket sélectionnant component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api accepte un modèle ou une telle passerelle et refuse une passerelle qui n’en sert aucune, tandis qu’un socket nommant une seule valeur, comme model.aggrega.ai/api=anthropic, n’accepte que ce qui sert cette API. Il nomme ce que le produit sert, non ce qu’une Release donnée câble : une passerelle dont les modèles sont câblés à un socket qui lui est propre le porte même sans rien de câblé. Le label est une chaîne que le sélecteur compare ; rien ne vérifie ce qui répond réellement à l’adresse.
agent.aggrega.ai/autonomyautonomous, copilotIdentifie le risque d’exécution de la boucle cognitive, permettant aux politiques d’imposer des fonctionnalités d’approbation humaine pour les agents entièrement autonomes.

(C) Les éléments transversaux (gouvernance, état et matériel) Ils représentent les tags d’entreprise fondamentaux qui pilotent la validation Zero-Trust et le routage vers le matériel.

Préfixe du labelValeurs autorisées (convention)Pourquoi Platform Ops en a besoin (le point d’ancrage de politique)
component.aggrega.ai/hostingself-hosted, managed, external, mixedIndique qui exploite la ressource sous-jacente d’un composant — l’axe de la frontière de confiance. Les moteurs de politiques le lisent pour calculer le risque d’exfiltration de données (par exemple, des données internes routées vers une API tierce managed quittent la frontière de l’opérateur). Transversal : les mêmes valeurs décrivent indifféremment une base de données managée, une API de modèle managée et un serveur d’inférence auto-exploité. mixed marque un composant dont les Recipes couvrent plus d’un mode d’exploitation — un datastore auto-hébergé par ses Recipes Helm et Compose et managé par ses Recipes RDS — de sorte que le mode d’exploitation d’une Release suit la Recipe que sélectionne son Manifest.
compliance.aggrega.ai/data-classpublic, internal, restrictedLa classe des données qu’un composant contient. Le compilateur la transporte jusqu’au graphe de build sous forme de chaîne et n’établit aucun classement ; une politique qu’un opérateur attache au rôle ir-verdict donne aux classes leur ordre dans ses propres paramètres et lit le label le long des routes que le compilateur énumère — en interrompant, par exemple, un build où un composant restricted atteint un composant d’une autre classe sans qu’aucune Feature de déclassification ne soit attachée sur la route (policy-data-class-route). Aucun Component de la bibliothèque standard ne le porte : la classe est une affirmation sur la manière dont un parc utilise un composant, portée par le Component propre à ce parc — une spécialisation via extends, par exemple.
compliance.aggrega.ai/contains-piitrue, falseSignale explicitement les charges de travail relevant du RGPD/CCPA. Une politique qu’un opérateur attache peut le lire pour exiger des Features spécifiques sur les routes qu’emprunte le trafic d’une telle charge de travail — core/data-masking sur une passerelle d’IA par laquelle elle envoie du trafic de modèle, par exemple, la forme que policy-data-class-route vérifie pour une classe de données. Aucun Component de la bibliothèque standard ne le porte ; comme la classe de données, c’est une affirmation d’un parc sur ses propres composants.
hardware.aggrega.ai/acceleratorgpu, tpu, npuUtilisé par DevOps dans le fichier Release. Ils y routent explicitement ces composants vers les frontières physiques de pools matériels (par exemple, un cluster équipé de GPU) via la map components: {}, tandis qu’un rôle verdict de gouvernance peut imposer que les composants étiquetés GPU ne soient jamais placés dans des frontières sans GPU.
state.aggrega.ai/retentionretain, deleteRésout le problème de suppression AOT. Si un développeur supprime une base de données de son Aggregate, un orchestrateur GitOps supprimera physiquement le disque. Une étape pipeline: d’une Recipe peut lire le label retain et ajouter une protection native de l’orchestrateur aux artefacts rendus (par exemple, helm.sh/resource-policy: keep).
state.aggrega.ai/backup-tiermission-critical, standard, ephemeralPoint d’ancrage de disponibilité SOC2. Indique à la FeatureRecipe d’Ops s’il faut générer physiquement des configurations automatisées de Snapshot/Volume Backup pour la ressource.

(D) Le contexte métier dynamique (annotations en cascade) Alors que les labels définissent l’ADN immuable du catalogue, les contextes métier dynamiques (comme le périmètre d’audit SOC2 ou le suivi des coûts FinOps) changent selon qui déploie l’application et où elle s’exécute. Ils sont régis par des annotations injectées dynamiquement par les subsystems du développeur, les frontières de la Release d’Ops ou un plugin de gouvernance attaché dans le rôle annotation-transform.

Préfixe de l’annotationValeurs autorisées (convention)Pourquoi Platform Ops en a besoin (le point d’ancrage de politique)
business.aggrega.ai/cost-centerpar ex. finance, ai-researchRequis par les plugins de rendu Wasm pour injecter un étiquetage physique (par exemple, des tags AWS ou des labels K8s) dans les artefacts finaux générés, pour les tableaux de bord de facturation cloud.
business.aggrega.ai/ownerpar ex. team-alpha@corp.comRoutage de la réponse aux incidents. Garantit que l’infrastructure est associée à une équipe humaine.
compliance.aggrega.ai/frameworkspar ex. soc2, hipaaDéclencheur du périmètre SOC2. Injecté via la Release d’environnement. Les plugins Wasm lisent cette chaîne pour générer automatiquement des sidecars rigides de journalisation d’audit et désactiver les ports de débogage lorsqu’une application entre dans une frontière de conformité de production.

La taxonomie est une convention du catalogue, pas une règle du compilateur. Les entreprises peuvent l’ignorer, la supprimer ou inventer leur propre vocabulaire de labels (mycompany.com/custom-trait). Les plugins Wasm évaluent toutes les clés de label que l’entreprise rédige.

Rédaction du schéma

Le schéma Component (et son pendant Feature, y compris les Features d’identifiants étiquetées feature.aggrega.ai/kind: secret) déclare le contrat de validation des values rédigées par le développeur au moyen d’un bloc spec.schema:. Le bloc accepte du JSON Schema 2020-12 exprimé soit dans la notation abrégée YAML compacte (par défaut ; environ 15 mots-clés, transformés mécaniquement en JSON Schema à la compilation), soit en YAML JSON Schema complet (la forme verbeuse), avec des références inter-documents via $ref: pour les entrées SchemaLibrary partagées entre plusieurs Components.

  • Forme compacte inline (surface de rédaction par défaut) : un bloc YAML intégré portant des feuilles en forme compacte directement dans le YAML du Component. Couvre la grande majorité du contenu des schémas du catalogue avec une fraction du nombre de lignes d’un JSON Schema complet. Consultez vocabulary/compact-form-authoring.md pour le vocabulaire des mots-clés et les conventions de rédaction.
  • YAML JSON Schema inline : la forme verbeuse, adaptée lorsque le schéma a besoin de mots-clés de JSON Schema 2020-12 que la forme compacte ne porte pas directement ($dynamicRef, unevaluatedProperties profonds, composition not: complexe). Forme compacte et JSON Schema peuvent être mélangés à n’importe quelle frontière de nœud au sein d’un même bloc schema: via la porte de sortie $jsonschema:.
  • Référence inter-documents ($ref: vers une entrée SchemaLibrary) : un $ref: natif de JSON Schema pointant vers une entrée SchemaLibrary par identité (Datastores#/schemas/MariaDBValues ou similaire). Les schémas d’entreprise qui s’étendent sur des centaines de lignes et sont réutilisés dans plusieurs Components résident dans des entités SchemaLibrary ; le Component consommateur référence l’entrée sans en intégrer le contenu. Consultez entities/schemalibrary.md et vocabulary/cross-document-ref.md pour l’entité bibliothèque et la sémantique de résolution.

Les trois formes ci-dessus rédigent le contenu des piliers, et elles sont disponibles pour un Component qui n’étend rien. Un Component qui déclare extends: ne rédige aucun contenu de pilier : il écrit le marqueur littéral schema: inherited et reçoit le bloc de piliers de sa base exactement tel que la base l’a rédigé. Ce marqueur est la seule valeur que schema: accepte sur un tel Component. Voir « Rédaction du catalogue : étendre les Components de base » ci-dessous.

Le compilateur résout le bloc schema: — en développant la forme compacte, en déréférençant les URL $ref:, en appliquant les chaînes de bibliothèque à bibliothèque de SchemaLibrary — et unifie le JSON Schema obtenu avec les bases générées automatiquement à partir de usesSchema et featuresSchema (voir la section ci-dessous) pendant la passe de validation du Component. La validation s’exécute sur le schéma résolu ; le chemin de rédaction est opaque pour les étapes suivantes du pipeline.

Les instances rédigées sont validées par rapport à ce schéma résolu au moment du build : les values rédigées par le développeur pour une instance de composant et l’infra résolue de l’opérateur, ainsi que les values/infra de tout attachement de Feature, doivent être conformes aux piliers déclarés — une valeur de type incorrect, un nombre hors plage, une chaîne qui n’a pas son format déclaré, un champ obligatoire manquant ou (pour values, validé en mode fermé) une propriété non déclarée interrompt le build à sa source rédigée plutôt que de produire un manifeste défectueux au déploiement. Un pilier dont le schéma nomme un format que le compilateur ne vérifie pas — tout ce qui est hors de email, uri, hostname, ipv4, ipv6, uuid, date-time et date, password compris — est refusé au chargement du catalogue, avec la liste des noms pris en charge ; consultez vocabulary/compact-form-authoring.md pour ce que vérifie chaque nom. Une instance d’un Component qui étend une base par extends: est validée par rapport au bloc de piliers de la base, dont le Component qui l’étend hérite sans modification — ainsi une instance de la base et une instance de tout ce qui l’étend sont soumises au même contrat de piliers. Consultez errors/fatal-halts.md §« Authored values or infra do not conform to the declared schema (Les values ou l’infra rédigés ne sont pas conformes au schéma déclaré) » pour les diagnostics et les règles par pilier (y compris la manière dont infra est validée par rapport à l’union des clés du Component et du provider).

Les valeurs par défaut déclarées se matérialisent dans les piliers rendus. Au-delà de la validation, un default: déclaré sur un champ values (ou un champ infra) est inséré dans le pilier rendu au moment du build pour chaque clé que l’auteur omet — ainsi un template de Recipe qui lit {{ .values.charset }} reçoit le utf8mb4 déclaré par le schéma plutôt qu’une valeur vide. Les valeurs fournies par l’auteur l’emportent toujours ; les objets imbriqués sont complétés pour chaque enfant omis. Comme la matérialisation utilise la même résolution de schéma que la validation, les valeurs par défaut atteintes via un $ref: inter-documents vers une SchemaLibrary se matérialisent aussi — aussi bien une référence au pilier entier (values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}) que la forme base plus variante (un $ref: de base à côté de properties sœurs, chacune portant ses propres valeurs par défaut). Les valeurs par défaut déclarées uniquement à l’intérieur d’une référence locale au document #/$defs/, ou sous une branche allOf / oneOf / anyOf, ne sont pas matérialisées ; la bibliothèque standard compose les piliers via des $ref: inter-documents, qui le sont.

Le pilier values

Le schéma du Component sépare trois piliers selon leur propriétaire : values est renseigné par le développeur dans l’Aggregate (intention cognitive — nom de la base de données, version, charset), infra est renseigné par l’opérateur dans la Release (dimensionnement opérationnel — calcul, stockage, HA), et provides est défini par la Recipe (le contrat d’API publique — hôte, port, protocole). Le développeur ne voit jamais infra ; l’opérateur ne voit jamais values. Les Recipes consomment les deux piliers lors du rendu de base, en projetant les piliers abstraits sur la forme concrète qu’attend leur provider cible. Cette section couvre la surface de rédaction du pilier values. Consultez vocabulary/data-pillars.md pour la taxonomie plus large des piliers et la discipline de cascade entre piliers.

values porte l’intention cognitive du développeur — les choix qui décrivent ce qu’est ou ce que fait l’application, et non la façon dont elle est dimensionnée ou exécutée. Le nom de la base de données, le charset, la version du moteur, le niveau de journalisation, les indicateurs de fonctionnalité et les réglages de la couche applicative qui changent d’une version de l’application à l’autre mais restent stables d’un environnement à l’autre constituent le contenu typique de values. L’opérateur ne surcharge jamais values: (le schéma de la Release rejette mécaniquement un bloc values: conformément à architecture/06-data-taxonomy-and-composition.md §8 Contrainte 4) ; la variation par environnement passe par le Parameter Hoisting — l’Aggregate expose des parameters.* typés, le template values du Component les référence, et la Release satisfait les paramètres.

# Component schema declares the values shape:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
charset: { type: string, default: utf8mb4, enum: [utf8mb4, latin1, ascii] }
engine_version: { type: string, default: "10.11" }
log_level: { type: string, default: info, enum: [debug, info, warn, error] }
# Aggregate fragment — the developer fills values:
components:
customer-db:
type: core/datastore/mariadb
values:
database_name: customers
charset: utf8mb4
engine_version: "{{ .parameters.mariadb_version }}" # Parameter Hoisting
log_level: info

Consommation côté Recipe. Les Recipes lisent les valeurs résolues via .values.<field> dans valuesMapping:, provides:, assertions: et les autres surfaces de template — consultez entities/recipe.md pour la matrice de disponibilité par template. Le compilateur unifie le schéma values du Component avec les éventuels schémas values: des attachements de Feature sur le même nœud de Component, de sorte que le contexte de template résolu contienne chaque champ applicable.

Discipline entre piliers. values est le seul pilier que le développeur rédige dans l’Aggregate. Les champs strictement destinés au développeur ont leur place ici ; les réglages opérationnels (nombre de réplicas, limites de CPU/mémoire) ont leur place dans le pilier infra du Component afin de résider dans la Release ; la sortie publique (hôte, port) a sa place dans le provides de la Recipe. Les mélanger rompt l’invariant de propriété ; consultez vocabulary/data-pillars.md « Mécanique entre piliers » pour les rares cas où un acheminement délibéré entre piliers est justifié.

Le pilier infra

Le schéma du Component sépare trois piliers selon leur propriétaire : values est renseigné par le développeur dans l’Aggregate (intention cognitive — nom de la base de données, version, charset), infra est renseigné par l’opérateur dans la Release (dimensionnement opérationnel — calcul, stockage, HA ; la sauvegarde d’un datastore ne se dimensionne pas ici, elle est la Feature core/backup que l’opérateur attache dans la Release), et provides est défini par la Recipe (le contrat d’API publique — hôte, port, protocole). Le développeur ne voit jamais infra ; l’opérateur ne voit jamais values. Les Recipes consomment les deux lors du rendu de base, en projetant les piliers abstraits sur la forme concrète qu’attend leur provider cible.

Trois conventions de infra comptent pour chaque Component agnostique vis-à-vis des capacités de la bibliothèque standard : une porte de sortie à structure ouverte pour les réglages propres au provider, une surcharge facultative de la version de l’artefact amont et un vocabulaire fondé sur l’intention pour les champs de haute disponibilité. Le Component de référence canonique est core/datastore/mariadb dans le catalogue de la bibliothèque standard — réalisable par des Recipes Helm qui exécutent l’image officielle mariadb ou transmettent une ressource personnalisée MariaDB au contrôleur mariadb-operator, par des Recipes Terraform ciblant AWS RDS, par des Recipes CloudFormation ciblant la même surface RDS et par des Recipes Compose ciblant un conteneur local — et son bloc infra illustre la première et la troisième.

infra.overrides

Les champs universels de infra — compute, storage, ha — couvrent l’essentiel du dimensionnement opérationnel d’un provider à l’autre. La part restante est irréductiblement propre au provider : une Recipe Kubernetes a besoin d’un nodeSelector, une Recipe Terraform RDS a besoin d’un instance_class, une Recipe CloudFormation RDS a besoin d’un DBInstanceClass, une Recipe Compose a besoin d’une surcharge de image. Le schéma du Component expose une map réellement ouverte comme porte de sortie, afin que ces réglages passent sans alourdir le schéma :

infra:
# ... universal fields ...
# Provider-specific overrides. Accepts any nested structure.
# Each Recipe documents which keys it reads.
overrides:
type: object
additionalProperties: true # genuinely open map: arbitrary nested structure permitted

Le type: object explicite avec additionalProperties: true active la sémantique de map ouverte. Le compilateur transmet la structure sans la modifier ; le corps du template de la Recipe lit les clés qu’il connaît et ignore les autres. Chaque Recipe documente l’ontologie de ses clés de surcharge dans son commentaire d’en-tête, de sorte qu’un opérateur qui rédige une Release pour une combinaison Component × Recipe donnée sache quels réglages la Recipe expose.

Un fragment de Release utilisant des surcharges :

components:
main-db:
infra:
compute: { cpu: "2", memory: 8Gi }
storage: { size: 40Gi, type: balanced-csi }
overrides:
nodeSelector:
kubernetes.io/hostname: cluster1-worker1
service_type: LoadBalancer
metrics:
enabled: true
image:
repository: bitnamilegacy/mysqld-exporter

Le développeur ne voit jamais overrides — il réside dans la Release, qui est le domaine de l’opérateur.

infra.source_version

Le champ source d’une Recipe référence un artefact amont dans une version précise (chart Helm 25.0.8, module Terraform 4.2.0, tag d’image OCI). Coder la version en dur dans la Recipe oblige le mainteneur du catalogue à publier une nouvelle Recipe à chaque montée de version amont compatible. Le schéma du Component expose une surcharge facultative :

infra:
source_version:
type: string
description: |
Source artifact version. A Recipe versions its artifact from this key
where its source resolution reads it, and is unaffected where it does not.
Changing from the version a Recipe was authored against does not
guarantee value mapping compatibility.

La Recipe la lit via l’assistant optional dans son bloc source, de sorte qu’en l’absence d’épinglage, c’est la version pour laquelle la Recipe a été rédigée qui s’applique :

source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "{{ optional .infra `source_version` `25.0.8` }}"

Les chaînes source d’une Recipe (et les sous-champs à valeur chaîne d’une map source: structurée) sont évaluées comme des templates Go. Une coordonnée distante — comme la version ci-dessus — est évaluée lorsque aggrega pull épingle l’artefact, sur .values, .infra et .locals, sans racine .context ; une source qui désigne un chemin dans l’espace de travail est évaluée lors du rendu de l’entité, sur le même contexte autonome que les locals de la Recipe — .context.instance_id, .values, .infra et l’ensemble des .locals résolus du nœud. .context.inject, .context.uses et .provides sont interdits dans les deux cas. C’est la présence de .infra dans ce contexte qui fait fonctionner la surcharge ci-dessus, et .locals permet à une Recipe de calculer une fois un fragment de source et de le relire ici. Un template de source ne lit jamais les provides de son propre nœud : ce pilier ne fait pas partie du contexte, et un template qui tente d’y accéder arrête le build — une propriété fixe de la surface et non une lacune en attente de travaux ultérieurs. Consultez la ligne n° 5 de la matrice d’expansion des templates pour les règles de disponibilité complètes. Modifier infra.source_version par rapport à la valeur par défaut de la Recipe ne garantit pas que le valuesMapping de la Recipe soit compatible au niveau du format échangé avec la nouvelle version amont ; la description de la déclaration source_version dans le schéma du Component porte cet avertissement.

infra.ha.*

Les champs de haute disponibilité utilisent un vocabulaire d’intention, et non de mécanisme :

infra:
ha:
enabled: { type: boolean, default: false }
read_replicas: { type: integer, min: 0, default: 0 }

infra.ha.enabled dit « rends ce Component hautement disponible », et infra.ha.read_replicas dit « je veux N copies en lecture seule ». Chaque Recipe décide de ce que devient l’intention sur son provider. Les Recipes de la bibliothèque standard pour core/datastore/mariadb, nommées comme un Manifest les associe :

Recipeha.enabled: true correspond àha.read_replicas: N correspond à
helm/mariadb (un StatefulSet sur l’image officielle mariadb)exécute un seul serveur, le build s’arrête donc en nommant la cléexécute un seul serveur, donc un N supérieur à 0 arrête le build
helm/mariadb-cluster (une ressource personnalisée MariaDB que le contrôleur mariadb-operator réconcilie)active le basculement automatique (replication.primary.autoFailover: true) ; il bascule vers un réplica en lecture, donc un N égal à 0 arrête le builddéfinit spec.replicas à N + 1 et active la réplication ; provides.host devient le Service <name>-primary
terraform/mariadb-rds (AWS RDS)définit multi_az = true sur l’aws_db_instance primairecrée N ressources de réplica en lecture aws_db_instance distinctes
terraform/mariadb-rds-module, terraform/mariadb-rds-terraform-aws-modules (AWS RDS via un module)transmet multi_az = true au moduleprovisionne une seule instance, donc un N supérieur à 0 arrête le build
cloudformation/mariadb-rds (AWS RDS)définit MultiAZ: true sur l’AWS::RDS::DBInstanceprovisionne une seule instance, donc un N supérieur à 0 arrête le build
compose/mariadb (conteneur de développement local)exécute un seul serveur, le build s’arrête donc en nommant la cléexécute un seul serveur, donc un N supérieur à 0 arrête le build

Le vocabulaire de mécanisme (infra.primary.replicas) se lit naturellement pour un provider (les pods Kubernetes sont des réplicas d’un StatefulSet) et comme une erreur de catégorie ailleurs — RDS n’a pas de notion de « réplicas » sur l’instance primaire, CloudFormation reflète RDS, Compose n’a aucune abstraction de réplicas horizontaux. Le vocabulaire d’intention se transpose : chaque provider possède une notion de « rendre cette base de données hautement disponible » et une notion de « je veux N copies en lecture seule », et la Recipe porte la traduction propre à chaque provider. Là où une réalisation n’a pas de tel mécanisme, sa Recipe peut arrêter le build en nommant la clé, comme le font helm/mariadb et compose/mariadb pour les deux clés et les Recipes RDS à instance unique pour les réplicas en lecture.

infra.ha.read_replicas: 0 est la valeur par défaut ; avec les deux clés à leur valeur par défaut, helm/mariadb-cluster produit un MariaDB à instance unique sans bloc replication, plutôt qu’une réplication sur une seule instance. compose/mariadb exécute un seul serveur sur l’hôte Docker local, donc infra.ha.enabled: true ou un infra.ha.read_replicas non nul arrête le build en nommant la clé, et le message renvoie vers helm/mariadb-cluster, qui fournit le basculement et les réplicas en lecture.

Le pilier provides

provides est l’API publique rédigée par la Recipe — les valeurs que la Recipe résolue d’un Component apporte aux appelants en aval via leur surface .context.uses.<alias>.provides.<provided-name> (ou, lorsque l’appelant déclare une liste d’autorisation inject: sur l’arête, via son canal .context.inject). Le schéma du Component déclare la forme (noms de clés et types) ; le bloc provides: de la Recipe liée fournit les valeurs. Le développeur qui rédige un Aggregate voit la forme de provides sur la page du Component comme le contrat sur lequel les appelants peuvent compter ; l’auteur de la Recipe remplit le contrat pour l’implémentation spécifique qu’il encapsule.

Le respect du contrat est imposé sous forme de Loud Guardrail : une Recipe liée doit produire chaque clé de provides que son Component déclare. Si la Recipe liée omet une clé déclarée, le build s’arrête et nomme la clé manquante, au lieu de ne rien livrer silencieusement aux appelants qui la référencent. Produire des clés supplémentaires au-delà de l’ensemble déclaré est autorisé. Seule la présence des clés est vérifiée — les valeurs produites sont des chaînes opaques que le compilateur transmet, de sorte que leurs types déclarés restent un contrat que lisent les appelants, et non une valeur que le compilateur valide.

# Component schema declares the provides contract:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
provides:
host: { type: string }
port: { type: integer }
database: { type: string }
# Recipe fulfills the contract:
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-bitnami
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "25.0.8"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
database: "{{ .values.database_name }}"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

La séparation de l’évaluation entre provides et inject. Le compilateur évalue les templates provides: lors de l’évaluation des provides, sur le contexte de template autonome (.context.instance_id, .context.rendered_name lorsque le provider du nœud en signale un, .values, .infra et les locals: résolus de la Recipe sur le même nœud) — aucun état des appelants n’est visible. Les locals du nœud sont résolus dans le préambule de cette étape, avant ses provides, ce qui permet à un template provides: de lire .locals. Lors de l’hydratation des inject, qui s’exécute ensuite, le compilateur parcourt les arêtes uses: et résout le .context.uses.<alias>.provides.<provided-name> de chaque appelant par rapport aux valeurs de provides résolues. Séparer les deux garantit une résolution acyclique : provides: ne peut pas référencer un appelant, et l’inject: d’un appelant ne peut pas référencer la sortie d’un provider non encore résolu tant que l’hydratation des inject ne s’est pas exécutée.

Évolution du contrat. Renommer ou supprimer un champ de provides est un changement incompatible pour chaque appelant qui dépend de l’ancien nom. La metadata.version du Component (et la déclaration implements: de la Recipe) porte le signal d’évolution du contrat ; les appelants en aval épinglés à une version majeure précise voient une forme de provides stable.

Enseignement côté Recipe. Pour la grammaire de rédaction des templates provides:, la matrice de disponibilité par template et des exemples détaillés de routage entre namespaces et entre régions, consultez entities/recipe.md « Le bloc provides: » et architecture/06-data-taxonomy-and-composition.md §3.

Obligations de présence : features.aggrega.ai/requiredType.<label>

Un Component peut déclarer que chacune de ses instances doit porter un attachement d’un type de Feature donné. Il s’agit d’une obligation de présence, rédigée sous forme d’annotation répétable dans les métadonnées propres du Component :

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/payment-processor
version: 1.0.0
labels:
component.aggrega.ai/type: server
annotations:
features.aggrega.ai/requiredType.audit: core/audit-logging
features.aggrega.ai/requiredType.compliance: core/pci-compliance
spec:
schema:
values:
processor_endpoint: { type: string, required: true }

La clé est le préfixe features.aggrega.ai/requiredType. suivi d’un libellé de votre choix ; la valeur est l’URI du type de Feature qu’au moins un attachement doit porter. Le libellé nomme l’exigence dans le diagnostic que produit une obligation non satisfaite — audit et compliance ci-dessus — et c’est là tout son rôle. Les clés à libellé permettent à un Component de déclarer plusieurs obligations à la fois : les annotations forment une map plate de chaînes et ne peuvent pas contenir de clé en double.

Le compilateur évalue chaque obligation par rapport à l’ensemble final des attachements de l’instance, après que la cascade du 5-Tier Onion Model a replié chaque portée : les blocs features: de niveau composant et de niveau sous-système de l’Aggregate, les blocs features: de niveau frontière et de niveau composant de la Release, et les attachements produits par l’expansion pilotée par annotations. N’importe lequel d’entre eux satisfait l’obligation — la règle teste ce qui est présent, jamais comment cela y est arrivé. Ainsi, un Component dont l’obligation n’est satisfaite que parce qu’un opérateur a défini une annotation de supervision dans la Release passe exactement comme un Component auquel le développeur a attaché la Feature à la main.

Une obligation qu’aucun attachement ne satisfait arrête le build avec un diagnostic qui nomme l’instance de composant, le libellé de l’exigence et le type requis. Une valeur d’annotation est une chaîne opaque, si bien que rien n’en valide la forme avant que le compilateur ne la lise ; une valeur qui n’est pas un URI de type de Feature, ou une clé sans libellé après le préfixe, arrête donc le build avec un diagnostic distinct indiquant que la déclaration est mal formée. Les deux sont délibérément différents : une déclaration erronée se corrige dans l’entité du catalogue, tandis qu’une exigence non satisfaite se résout en attachant la Feature — et une faute de frappe ne doit jamais se lire comme une exigence satisfaite.

Les deux diagnostics sont documentés dans errors/fatal-halts.md « Required feature not attached (Fonctionnalité requise non attachée) ».

Une obligation n’est pas un slot. Les deux surfaces répondent à des questions différentes et la différence n’est pas cosmétique :

slot featuresSchemaobligation de présence
Déclareun point de liaison nomméune contrainte sur ce qui doit être présent
Le nom est déréférençableoui — from: <slot> et .features.<slot>.provides.*non — le libellé nomme l’exigence, rien d’autre
Cardinalitéexactement un remplissage par slotau moins un attachement du type
Contraint le remplissageselector, inject, sensitiverien au-delà du type
Satisfait par un attachement librenon — un slot se remplit par son nomoui — à n’importe quelle portée, sous n’importe quel nom
Lorsque l’exigence n’est pas satisfaitearrête le build lorsque required: true et que rien ne lie le nom du slotarrête le build lorsqu’aucun attachement ne porte le type

Les deux exigences sont vérifiées par rapport à la même entrée — l’ensemble final des attachements de l’instance — et chacune arrête le build avec son propre diagnostic, car elles lui posent des questions différentes : savoir si un point de liaison nommé est lié, ou si un attachement porte un type nommé. Aucune ne répond pour l’autre.

Optez pour un slot lorsque la Recipe doit lire ce qui a été attaché. Optez pour une obligation lorsque le contrat du Component exige qu’une capacité soit présente, sans se soucier de l’instance qui la fournit. Un Component de traitement des paiements qui impose core/audit-logging bénéficie de la journalisation d’audit dans chaque déploiement, que le développeur ait pensé ou non à l’attacher ; un Component conforme PCI qui impose core/pci-compliance ne peut pas être livré sans que la Feature de conformité soit attachée quelque part dans le déploiement.

Héritage. Une obligation déclarée sur un Component de base est héritée par chaque Component qui l’étend via extends:, car les annotations des métadonnées fusionnent le long de la chaîne extends, l’enfant l’emportant clé par clé. Un enfant peut donc réorienter une obligation héritée en redéclarant le même libellé avec un type différent, ou ajouter ses propres obligations sous de nouveaux libellés ; il ne peut pas en supprimer une que la base a déclarée.

Sockets de topologie : usesSchema

Un Component peut déclarer des sockets topologiques au moyen d’un bloc usesSchema: — une map YAML déclarative parallèle à featuresSchema. Chaque entrée nomme un socket par lequel le Component accepte des dépendances entre composants et détermine quelles formes de Component le développeur peut raccorder au socket. Le compilateur génère automatiquement des règles de validation JSON Schema 2020-12 à partir des sockets déclarés et les unifie avec le schema: du Component lors de la résolution du Component ; les développeurs n’écrivent pas à la main un pilier uses: dans schema:, car la structure provient de usesSchema.

# Component declares the sockets it accepts:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/ai-agent/orchestrator
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
primary_datastore:
required: true
selector: "datastore.aggrega.ai/engine=vector"
inject: [env]
cache:
required: false
selector: "datastore.aggrega.ai/engine=kv"
inject: [env, file]
log_destination:
required: false
selector: "component.aggrega.ai/category=messaging"
inject: []
# Aggregate fragment — developer wires the sockets:
components:
agent:
type: core/ai-agent/orchestrator
uses:
primary_datastore:
main: { target: vector-db-instance }
log_destination:
audit: { target: audit-sink }

Formes de raccordement — un socket accepte une ou plusieurs cibles. Les exemples ci-dessus raccordent chaque socket à une seule cible, mais un socket peut se ramifier vers plusieurs. La valeur d’un socket s’écrit sous l’une de deux formes :

uses:
# Compact form — a list of target names. Each entry produces an edge
# whose alias equals its target. Use it for the single-target case, and
# when one socket connects to several peers of the same shape.
shards: [orders-db, customers-db, inventory-db]
# Verbose form — an alias-keyed map. Each alias maps to an entry object
# carrying its own `target:`, and may carry its own inject directives.
# Use when the connections need distinct names or per-edge inject.
databases:
primary: { target: orders-db, inject: { env: [{ in: DB_URL, from: url }] } }
replica: { target: orders-db-ro, inject: { env: [{ in: DB_REPLICA_URL, from: url }] } }

Un alias correspond toujours à un objet d’entrée, jamais à un simple nom de cible : databases: { primary: orders-db } est rejeté au chargement, tout comme un objet d’entrée qui omet target:. Pour raccorder une seule cible sans avoir à inventer d’alias, utilisez la forme compacte — primary_datastore: [vector-db-instance] — qui nomme la cible une fois et en dérive l’alias.

Chaque entrée — élément de liste ou alias de map — devient une arête, conservée dans l’ordre d’écriture. Le selector: du socket s’applique à chaque cible raccordée par son intermédiaire (chaque arête fait l’objet d’une vérification de type indépendante pendant l’analyse statique), et required: true signifie qu’au moins une cible doit être raccordée.

Sémantique des champs :

ChampTypePar défautSignification
requiredboolfalseLorsque true, le développeur doit raccorder au moins une dépendance à ce socket. Lorsque false, le socket est facultatif.
selectorstring—Un sélecteur de labels, dans la grammaire qu’utilise appliesTo d’une Feature, que la cible de chaque arête raccordée par ce socket doit satisfaire. Il est lu comme la chaîne écrite ici et évalué par rapport aux labels de la cible pendant l’analyse statique : une cible dont les labels ne le satisfont pas interrompt le build, tout comme un sélecteur que la grammaire refuse, en nommant l’exigence qu’elle n’a pas pu lire. Un sélecteur vide n’impose aucune contrainte à la cible.
injectstring[]—Liste d’autorisation des mécanismes de livraison inject permis (parallèle à featuresSchema[].inject). Absente, ou [] (vide), signifie boîte noire — aucun bloc inject: autorisé sur l’entrée uses: du développeur ; la Recipe contrôle la livraison. [env, file, arg] (non vide) signifie transparent — le développeur peut imposer quel mécanisme livre les valeurs provides de la dépendance. Appliqué : voir « Où la liste d’autorisation inject d’un socket est appliquée » ci-dessous.
valueSchemaobject—Contrat facultatif par arête pour les values écrites par le développeur sur une arête raccordée par ce socket (écrites dans l’Aggregate). JSON Schema 2020-12 sous les mêmes formes d’écriture que schema:. En cas d’omission, le socket ne déclare aucun contrat values.
infraSchemaobject—Contrat facultatif par arête pour l’infra écrit par l’opérateur sur une arête raccordée par ce socket (écrit dans la Release). Mêmes formes d’écriture que valueSchema. En cas d’omission, le socket ne déclare aucun contrat infra.
featuresSchemamap—Les slots d’attachement que chaque connexion raccordée par ce socket peut remplir, indexés par nom de slot, chacun acceptant les clés qu’accepte un slot au niveau du Component. En cas d’omission, une connexion passant par ce socket ne porte aucun attachement. Voir « Slots que remplit chaque connexion » ci-dessous.

Où la liste d’autorisation inject d’un socket est appliquée. La liste d’autorisation est la déclaration par laquelle le socket indique si un consommateur peut choisir la forme de livraison et, le cas échéant, lesquelles — elle est donc vérifiée par rapport à chaque arête uses: raccordée par le socket, une fois que l’arête et la déclaration du socket sont toutes deux disponibles. Deux refus découlent d’une même règle, et tous deux interrompent le build :

  • Une arête qui impose un mécanisme que la liste d’autorisation ne mentionne pas interrompt le build, en nommant le socket, le mécanisme fautif et ce que le socket permet. Tous les mécanismes fautifs de l’arête sont signalés ensemble.
  • Une arête qui impose une quelconque livraison par un socket dont la liste d’autorisation est absente ou vide interrompt également le build. C’est la déclaration de boîte noire qui fait son travail : elle dit « la Recipe livre ceci en interne ; n’imposez pas la livraison », et une liste d’autorisation vide n’autorise rien au lieu de tout autoriser.

Le socket est lu sur l’entité qui l’a déclaré, qui n’est pas toujours le composant auquel l’arête est rattachée : une arête écrite dans le uses: d’un attachement de Feature se résout par rapport à l’usesSchema de la Feature attachée, et toute autre arête — écrite dans l’Aggregate, raccordée depuis la Release ou atteinte par un sous-aggregate — par rapport à celui du Component consommateur. Un socket hérité via extends est lu exactement comme un socket que l’entité a écrit elle-même.

Une arête qui n’impose rien n’est concernée par aucun des deux refus, quoi que déclare le socket : lire les valeurs d’une dépendance depuis .context.uses.<alias>.provides.<name> dans la Recipe consommatrice ne nécessite aucun bloc inject: et est toujours possible. Voir errors/fatal-halts.md pour les deux diagnostics.

Contrats de connexion par arête — valueSchema et infraSchema. Au-delà de déterminer quels Components peuvent être raccordés à un socket, un socket peut déclarer quelle configuration porte chaque connexion. Deux schémas facultatifs par socket valident la configuration propre à la connexion sur chaque arête raccordée par le socket :

  • valueSchema est le contrat du bloc values écrit par le développeur sur une arête uses — le réglage par connexion que le développeur exprime dans l’Aggregate (par exemple, la taille d’un pool de connexions ou un mode client).
  • infraSchema est le contrat du bloc infra écrit par l’opérateur sur une arête uses — le dimensionnement opérationnel par connexion que l’opérateur exprime dans la Release.

Tous deux acceptent JSON Schema 2020-12 sous les mêmes formes de contenu que le champ schema: — forme compacte en ligne, JSON Schema YAML en ligne, ou un $ref: inter-documents vers une entrée d’une SchemaLibrary. Ce sont des contrats par arête, validés indépendamment par rapport à la configuration de chaque arête ; ils ne sont pas composés dans le schéma values propre au Component consommateur. Un socket qui omet un schéma par arête pour un pilier n’y déclare aucun contrat, et toute configuration écrite pour ce pilier n’est pas validée. La configuration par arête est validée de manière fermée, et la validation tient compte des valeurs par défaut dans les deux piliers : une clé à laquelle le schéma donne un default: compte comme fournie même lorsque l’auteur l’omet.

Un default: déclaré se matérialise également, dans les deux piliers. Une clé que l’auteur omet atteint le contexte de rendu de la Recipe consommatrice avec sa valeur par défaut déclarée, exactement comme une clé value ou infra de composant omise — déclarer la valeur par défaut sur le socket suffit donc, et le template de la Recipe n’a besoin d’aucune expression de repli pour elle. Une valeur écrite l’emporte toujours sur la valeur par défaut déclarée, et elle ne remplit que la clé qu’elle fournit : une arête qui écrit une clé du contrat d’un socket reçoit tout de même les valeurs par défaut déclarées pour les autres clés de ce contrat. Les valeurs par défaut s’attachent aux arêtes, de sorte qu’un socket laissé non raccordé n’apporte rien.

spec:
usesSchema:
databases:
required: true
selector: "datastore.aggrega.ai/engine=relational"
inject: [env]
valueSchema: # developer per-edge values, authored in the Aggregate
pool_size: { type: integer, minimum: 1, maximum: 100, default: 10 }
tls_mode: { type: string, enum: [disable, require, verify-full], default: require }
infraSchema: # operator per-edge infra, authored in the Release
storage_class: { type: string, default: standard }

Avec ce socket déclaré, une arête dont l’Aggregate omet pool_size produit 10, et une arête dont la Release omet storage_class produit standard. Ce qui est écrit l’emporte clé par clé, au sein de son propre pilier : un Aggregate qui définit pool_size: 42 produit 42 tandis que tls_mode est toujours rempli avec require, et une Release qui définit storage_class: gp3 produit gp3 sans affecter aucune des deux clés du développeur.

Une Recipe pour le Component consommateur lit la configuration par arête résolue depuis le pipe de topologie enrichi, à .context.uses.<alias>.values.<key> et .context.uses.<alias>.infra.<key> — voir vocabulary/topology-triad.md.

Slots que remplit chaque connexion — le featuresSchema d’un socket. Un socket peut aussi déclarer des slots d’attachement, et chaque connexion raccordée par son intermédiaire peut alors porter son propre attachement dans chacun d’eux : une passerelle qui atteint plusieurs modèles détient un identifiant différent pour chacun, car l’identifiant se trouve sur la connexion et non sur la passerelle.

spec:
usesSchema:
models:
selector: "component.aggrega.ai/category=ai-model"
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: The credential the consumer presents to the component this connection reaches.

Une connexion remplit un slot en portant un attachement sous le nom du slot dans son propre features: — sur l’entrée de connexion de l’Aggregate (Aggregate) ou sur celle de la Release (Release) — et l’attachement devient l’un des attachements du composant consommateur, nommé <alias>.<slot>.

Ce que fait la déclaration, énoncé avec précision :

  • Les noms de slot forment un ensemble fermé. Contrairement au featuresSchema propre au Component, qui admet un attachement libre sous n’importe quel nom, les slots d’un socket sont les seuls noms qu’une connexion passant par lui peut porter : tout autre nom interrompt le build au chargement, et un socket qui ne déclare aucun featuresSchema n’admet aucun attachement sur ses connexions. Un socket ad hoc — un socket que cet usesSchema ne déclare pas — ne déclare aucun slot, de sorte que ses connexions n’en portent pas non plus. Chaque connexion remplit elle-même ses slots : un attachement à une portée plus large ne se propage jamais en cascade sur une connexion, et une clé de Release reprenant le nom composé de l’attachement d’une connexion interrompt le build.
  • Les autres clés soumettent chaque connexion au slot. Un slot accepte ici les mêmes clés qu’un slot au niveau du Component — required, selector, inject, sensitive, description — et chaque connexion y est soumise individuellement. selector est comparé aux labels de la Feature avec laquelle une connexion remplit le slot, et un remplissage qu’il n’admet pas interrompt le build, positionné sur l’entrée de cette connexion dans le document qui a écrit le remplissage. required: true s’impose à chaque connexion raccordée par le socket : une connexion qui laisse le slot vide interrompt le build, en nommant cette connexion, tandis qu’une connexion voisine qui remplit le slot passe. sensitive se lit exactement comme sur un slot au niveau du Component : l’attachement qui remplit le slot est marqué comme sensible dans le graphe de build et dans aggrega inspect. Sur une connexion, comme sur un composant, c’est le seul schéma propre de la Feature attachée qui décide quelles valeurs d’un attachement sont retenues comme sensibles. inject régit l’entrée de Workload qui livre le matériel du slot : l’attachement d’une connexion ne porte pas de bloc inject: propre — aucun des deux documents n’en admet sur une entrée de connexion — de sorte qu’un Workload le livre en nommant la connexion à côté du slot, et cette entrée est soumise à la liste d’autorisation du slot du socket exactement comme une entrée nommant un slot au niveau du Component est soumise à celle de ce slot.

L’usesSchema d’une Feature n’accepte pas featuresSchema : une connexion qu’établit une Feature ne porte aucun attachement, et une Feature qui déclare des slots sur un socket est refusée au chargement. Un identifiant dont une telle connexion a besoin est un slot dans le featuresSchema propre à la Feature.

Génération du schéma à partir de usesSchema. Le compilateur génère un fragment de base JSON Schema 2020-12 à partir des sockets déclarés et le compose avec la déclaration schema: de l’utilisateur — le même modèle que celui qu’utilise featuresSchema. Le schéma généré ne touche jamais le disque ; il n’existe qu’en mémoire pendant la passe de validation du Component. La map uses: du développeur dans l’Aggregate est validée par rapport au schéma fusionné ; le selector: de chaque socket est évalué par rapport aux labels de chaque Component candidat pendant l’analyse statique, en tant que vérification de sûreté de typage entre nœuds.

Sémantique des sélecteurs — le mécanisme du schéma scindé. usesSchema[].selector: est ce qui fait de la topologie d’Aggrega davantage qu’un simple passage de chaînes non typées. Un socket qui déclare selector: "datastore.aggrega.ai/engine=vector" n’accepte de raccordement qu’à des Components portant le label avec la paire clé-valeur correspondante ; un agent qui tente de raccorder son socket primary_datastore à un Component relational échoue au Static Analyzer avec un diagnostic clair de violation de sélecteur. Le sélecteur est une chaîne de sélecteur de labels de style Kubernetes — des exigences combinées en ET par des virgules, sous les formes =, !=, in (...), notin (...), clé seule et !key — la même grammaire qu’utilise appliesTo d’une Feature ; voir vocabulary/modifier-system.md pour la grammaire et architecture/13-catalog-and-registry.md §2 « Sélecteurs de style Kubernetes » pour la sémantique du moteur. Une exigence hors de ces formes est refusée plutôt que lue comme un autre sélecteur : une exigence vide (une virgule initiale, finale ou doublée), une clé contenant un espace ou l’un des caractères =, !, (, ) et la virgule, ou un ensemble sans parenthèse fermante interrompt chaque build qui raccorde une arête par le socket, en nommant l’exigence. Ainsi, un socket destiné à exclure les frontends s’écrit selector: "tier!=frontend" ; "!tier=frontend" est refusé, car ! nomme une clé de label et rien d’autre.

Sockets ad hoc — ce qu’apporte la déclaration d’un socket, et ce qu’un auteur peut faire sans elle. L’auteur d’un Aggregate peut écrire une entrée uses: sur son propre composant sous un nom de socket que cet usesSchema ne déclare pas, y compris sur un Component qui ne déclare aucun usesSchema. L’arête est construite. Le silence du catalogue sur un socket signifie que la connexion n’a pas été anticipée, non qu’elle est interdite, et la topologie de l’application appartient au développeur.

Ce à quoi renonce un tel socket ad hoc est précisément ce qu’apporte un socket déclaré, car tout cela réside dans l’entrée de l’usesSchema : pas de selector, donc rien ne contraint le composant que l’arête peut atteindre et la vérification de sûreté de typage entre nœuds n’a rien à évaluer ; pas de liste d’autorisation inject: ; pas de valueSchema par arête, donc les values: par arête n’ont aucun contrat par rapport auquel être vérifiées ni aucune valeur par défaut déclarée à hériter. Il renonce aussi à infraSchema, même si ce contrat n’est de toute façon jamais atteint sur un tel socket : l’infra par arête s’écrit sur une entrée d’arête de Release, et une entrée de Release ne peut nommer qu’un socket que le Component consommateur déclare. Ce qui ne change pas, c’est ce que l’arête peut porter : le from: de chaque entrée inject doit toujours nommer une clé que le schema.provides du Component cible déclare, et la cible doit toujours exister — les deux interrompent le build comme sur un socket déclaré.

Lisez « pas de liste d’autorisation inject: » comme l’absence d’une contrainte plutôt que comme une déclaration de boîte noire, car les deux se ressemblent et se comportent de façon opposée. Une arête passant par un socket ad hoc peut imposer librement la livraison : il n’existe aucune liste d’autorisation dont un mécanisme pourrait sortir, et aucune entité n’a promis de traiter les valeurs en interne. Le refus de boîte noire décrit ci-dessus s’applique à un socket que l’entité a bien déclaré et laissé sans liste d’autorisation inject: — cette omission est une déclaration sur une connexion que l’entité avait anticipée, et un socket ad hoc ne fait aucune déclaration de ce genre.

La livraison suit le même chemin, et l’artefact rendu n’enregistre aucune différence. Le bloc inject d’une arête ad hoc est résolu et livré exactement comme celui d’un socket déclaré : chaque clé from: est lue dans les provides évalués de la cible et arrive dans le contexte d’injection du nœud consommateur sous la clé de livraison choisie par l’auteur, atteignant de là l’artefact rendu. Il existe un seul chemin de livraison et rien sur ce chemin ne bifurque selon que le socket a été déclaré ou non. Ce qu’un socket déclaré peut ajouter, c’est du contenu — les valeurs par défaut par arête que remplit son valueSchema ou son infraSchema — de sorte que, là où un socket déclaré ne porte aucun contrat de ce type, la même arête produit un rendu identique avec l’un ou l’autre type de socket. La déclaration est un fait concernant la connexion, et non une entrée de ce qui est rendu.

Les values: par arête sur un socket ad hoc sont acceptées et atteignent la Recipe consommatrice à .context.uses.<alias>.values, sans validation : sans valueSchema auquel les comparer, aucune clé n’est vérifiée et aucune n’est rejetée. Ce n’est pas propre aux sockets ad hoc — un socket déclaré qui n’écrit aucun contrat pour le pilier traite sa configuration par arête de la même manière. Ce qu’un socket ad hoc change, c’est que le contrat ne peut pas être ajouté sans déclarer le socket. .context.uses.<alias>.infra est vide sur une telle arête, car la surface qui fournit l’infra par arête ne peut pas nommer un socket non déclaré.

Chaque arête du graphe émis enregistre lequel des deux elle est, de sorte qu’un consommateur n’a jamais à le déduire, et une organisation qui souhaite que chaque connexion passe par un socket déclaré peut l’exiger au moyen d’une politique de gouvernance. Déclarer le socket ici reste la meilleure voie et c’est ce que fait le catalogue de la bibliothèque standard : un socket déclaré porte un selector qui contraint les composants que l’arête peut atteindre, une liste d’autorisation inject:, un contrat par arête avec ses propres valeurs par défaut, et une description — une déclaration vérifiable d’une connexion anticipée, versionnée avec l’entité qui la fait. La forme ad hoc est une porte de sortie, pas un nouveau comportement par défaut. Deux surfaces ne sont délibérément pas ouvertes de cette façon — les uses d’un attachement de Feature ne peuvent nommer qu’un socket que déclare la Feature attachée, et les uses par arête d’une Release ne peuvent nommer qu’un socket que déclare le Component consommateur.

L’exemple détaillé examples/adhoc-uses-socket/ construit les deux types d’arête sur un même consommateur et montre côte à côte les deux valeurs livrées dans la sortie rendue, ainsi que l’arrêt que produit une clé from: non déclarée.

Les fautes de frappe dans les noms de socket apparaissent comme un avertissement, pas comme un arrêt. Comme un nom de socket non déclaré est légal, un nom de socket mal orthographié devient une connexion ad hoc à part entière au lieu de raccorder le socket que l’auteur visait — et le build reste vert alors que rien n’y transite. Le compilateur signale comme avertissement un nom de socket situé à une modification d’un nom que déclare cet usesSchema, en nommant les deux orthographes — voir errors/warnings.md « Uses-socket near-miss lint (Lint des quasi-correspondances de noms de socket uses) ». L’avertissement ne change jamais le verdict du build ; le compilateur ne contrôle pas la manière dont un auteur nomme un socket.

La relation entre usesSchema et featuresSchema. Tous deux sont des tables déclaratives et tous deux portent une liste d’autorisation inject: à la sémantique identique, mais un socket et un slot sont des choses différentes et ne sont pas interchangeables. usesSchema régit les arêtes entre composants — le graphe de topologie — en déclarant quels sockets portent un contrat. featuresSchema régit les slots d’attachement, et un slot est un point de liaison nommé, pas une énumération : un attachement sous un nom qu’aucun slot ne déclare est légal sur le bloc propre au composant. (Les slots qu’un socket déclare pour ses connexions sont le seul ensemble fermé, comme l’indique « Slots que remplit chaque connexion » ci-dessus.) Les deux surfaces ont convergé sur ce point — l’entrée uses: propre à un composant sous un nom de socket non déclaré est légale elle aussi — mais elles restent distinctes : un slot non déclaré est un attachement libre sur un Component dont les slots déclarés ne sont pas affectés, tandis qu’un socket non déclaré est une arête sans sélecteur et sans contrat par arête. De nombreux Components déclarent les deux ; les deux tables se composent indépendamment.

Slots de rattachement : featuresSchema

Un Component peut déclarer des slots de rattachement au moyen d’un bloc featuresSchema. Chaque slot nomme un point de liaison auquel le Component s’attend à ce qu’une Feature soit rattachée — un mot de passe root, une clé d’API, un jeton d’authentification, une liaison d’identité — et contraint quelle Feature peut l’occuper et comment le matériau du remplissage peut être livré.

Cette section porte sur les slots propres au Component. Les slots qu’un socket déclare pour chaque connexion forment au contraire un ensemble fermé — voir « Slots que remplit chaque connexion » sous Sockets de topologie.

Déclarer un slot ne ferme pas la surface de rattachement. Un auteur peut rattacher une Feature sous un nom qu’aucun slot ne déclare, et ce rattachement est un rattachement libre : parfaitement légal, simplement non lié à un slot déclaré. C’est cette ouverture qui permet à une même entité du catalogue de servir deux formes de déploiement différentes sans fork du catalogue :

  • Par consommateur. Chaque instance remplit le slot avec sa propre Feature, de sorte que chaque consommateur obtient son propre identifiant rendu.
  • Partagé. Aucune instance ne remplit le slot ; un identifiant est plutôt rattaché une seule fois à une portée plus large (un sous-système, ou une frontière de Release) et se propage en cascade à chaque composant situé en dessous, de sorte que chaque consommateur est rempli à partir de cette unique déclaration. Ce qui est rendu suit la réalisation : un Secret par consommateur, chacun portant le même matériau, avec une réalisation qui rend un Secret ; aucun avec une réalisation qui fait pointer chaque consommateur vers un Secret qui existe déjà.

L’auteur choisit entre les deux par ce qu’il rattache. L’entité du catalogue est la même dans les deux cas.

Sur cette surface ouverte, une seule forme provoque un arrêt : un remplissage écrit sur le composant sous un autre nom. Lorsqu’un rattachement écrit sur le composant lui-même — dans son propre bloc features: de l’Aggregate, ou dans l’entrée de la Release pour ce seul composant — porte un nom qu’aucun slot ne déclare, et que sa Feature satisfait le selector d’un slot que rien n’occupe sur ce composant une fois toutes les portées repliées, la build s’arrête. C’est la forme que prend un remplissage destiné au slot lorsqu’il est écrit sous le mauvais nom : laissé tel quel, ce serait un rattachement libre tandis que le slot reste vide, et un slot facultatif laissé vide produit une build verte et ne livre rien. Le message nomme le rattachement, le composant, la Feature et chaque slot vide auquel cette Feature correspond, et le remède consiste à la rattacher sous le nom du slot. Cela vaut pour toute Feature, pas seulement pour les identifiants. Tout le reste de la surface demeure libre : un rattachement dont la Feature ne correspond à aucun slot déclaré, un rattachement supplémentaire une fois occupé chaque slot auquel il correspond, et un rattachement que le composant hérite d’un sous-système ou d’une frontière de Release — la forme partagée décrite plus haut n’est donc pas affectée. Un slot qui ne déclare aucun selector ne dit rien de la Feature à laquelle il est destiné, si bien qu’aucun rattachement n’y est confronté de cette manière. L’arrêt est décrit dans errors/fatal-halts.md sous « An attachment written under another name fits a slot its component leaves empty (Un rattachement écrit sous un autre nom correspond à un slot que son composant laisse vide) ».

Les deux formes se combinent, et la plus proche l’emporte. Un auteur peut faire les deux à la fois : rattacher une Feature à une portée plus large pour qu’elle atteigne chaque composant de cette portée, et remplir le slot sur le seul composant qui a besoin d’autre chose. Le remplissage à la portée du composant l’emporte — champ par champ, si bien qu’il ne doit redéclarer que les champs qu’il modifie et que le reste provient toujours du rattachement plus large. Les composants frères qui n’ont pas rempli le slot conservent le rattachement plus large intact. La règle de précédence complète, y compris son interaction avec les rattachements pilotés par annotation et avec les Aggregates composés, se trouve dans vocabulary/labels-and-annotations.md « Précédence des rattachements ».

Définition du schéma sur le Component :

spec:
featuresSchema:
root_password:
inject: []
description: Root database password. Recipe controls delivery (Black-Box).
user_password:
inject: [env, file]
description: Application user password, auto-generated if omitted.
replication_password:
inject: []
description: Replication password for HA setups.

Sémantique des champs :

ChampTypePar défautSignification
requiredboolfalseDéclare que le slot doit finir occupé. La build s’arrête lorsque rien n’occupe le nom du slot sur une instance de ce Component, vérifié par rapport à l’ensemble de rattachements que l’instance détient après toute la cascade de rattachements — ainsi, un rattachement déclaré à une portée dont l’instance hérite satisfait le slot exactement comme un remplissage écrit sur l’instance elle-même. Le diagnostic nomme le composant et le slot.
injectstring[]—Liste d’autorisation des mécanismes de livraison inject permis. [] (vide) signifie boîte noire — la Recipe contrôle la livraison en interne et le matériau n’est jamais livré au workload. [env, file] signifie transparent — le matériau du remplissage peut être livré par les mécanismes listés. Même sémantique que usesSchema[].inject.
descriptionstring—Documentation destinée aux personnes, rendue par l’IDE et le hub.
selectorstring—Sélecteur de labels facultatif de style Kubernetes qui contraint quelle Feature peut remplir ce slot — l’équivalent, pour le slot, du selector d’un socket usesSchema, avec la même grammaire et le même moteur natif de correspondance de labels. Évalué par rapport aux labels propres de la Feature rattachée pendant l’analyse statique ; un remplissage dont les labels ne le satisfont pas provoque un arrêt, de même qu’un sélecteur que la grammaire refuse, en nommant l’exigence qu’elle n’a pas pu lire. Omettez-le pour n’imposer aucune contrainte au remplissage.
sensitiveboolfalseDéclare que tout ce qui occupe ce slot manipule du matériau secret. Une affirmation sur le point de liaison, et non sur un remplissage particulier ; voir « Déclarer un slot sensible » ci-dessous.

Un slot contraint quel remplissage peut l’occuper, et non ce que le remplissage configure. Il n’existe délibérément aucun contrat values ou infra au niveau du slot : le schema: propre de la Feature rattachée possède ces piliers, de sorte que chaque contrat a exactement un emplacement.

Le selector du slot est la manière dont un Component restreint quelle Feature peut remplir un slot — par exemple à une Feature d’identifiant propre à un provider (feature.aggrega.ai/kind=secret, provider=helm) — sans nommer de FeatureRecipe, exactement comme un sélecteur de socket usesSchema restreint la cible d’une arête de dépendance. Le compilateur évalue le sélecteur par rapport aux labels de la Feature rattachée et à rien d’autre : il lit les labels que porte le remplissage et indique si le sélecteur les admet. Quels labels il est pertinent d’exiger relève d’un choix de rédaction du catalogue, et non d’une règle que le compilateur impose.

Les fautes de frappe dans les noms de slot apparaissent comme un avis, et non comme un arrêt. Comme un nom de rattachement non déclaré est légal, un nom de slot mal orthographié devient un rattachement libre au lieu de remplir le slot que l’auteur visait. Le compilateur signale un nom de rattachement situé à une seule modification d’un nom de slot déclaré par un avertissement nommant les deux graphies — voir errors/warnings.md « Attachment-slot near-miss lint (Lint des quasi-correspondances de slots de rattachement) ». L’avertissement ne change jamais le verdict de la build ; le compilateur ne contrôle pas la façon dont un auteur nomme un rattachement. Un nom situé à une modification d’un slot dont la Feature du rattachement satisfait le selector ne déclenche aucun avertissement : là où ce slot reste vide, c’est l’arrêt décrit plus haut qui signale le rattachement, et là où autre chose occupe le slot, le rattachement est un rattachement supplémentaire ordinaire.

Déclarer un slot sensible

sensitive: true sur un slot énonce l’exigence propre du consommateur : tout ce qui occupe ce point manipule du matériau secret.

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: "Optional database password credential."

Il s’agit d’une information réellement différente du sensitive: true d’une feuille de schéma, et non d’un doublon de commodité, et le catalogue de la bibliothèque standard a besoin des deux. Un identifiant référençable publie provides.name et provides.key — le localisateur de la ressource et la clé de données qu’elle contient — et aucun des deux n’est sensible : le nom d’un Secret Kubernetes est public, tout comme la clé qu’il contient. Pourtant, le slot que remplit cet identifiant manipule sans conteste du matériau secret. Une feuille dit cette donnée est du matériau secret ; un slot dit ce point de liaison manipule du matériau secret ; les deux affirmations portent sur des choses différentes et peuvent valoir indépendamment.

La conséquence pratique est que l’exigence voyage avec le point de liaison plutôt qu’avec le remplissage. Une Feature qui ne déclare aucune feuille sensible — parce que le moteur cible possède l’identifiant et que l’auteur n’écrit rien — occupe tout de même un slot sensible en tant que rattachement sensible, parce que le slot l’a déclaré. L’inverse vaut aussi : un remplissage qui déclare une feuille sensible est un rattachement sensible même lorsqu’il occupe un slot qui n’a fait aucune déclaration de ce type, ou lorsqu’il s’agit d’un rattachement libre n’occupant aucun slot.

La déclaration suit la cascade de rattachements plutôt qu’un bloc écrit particulier. L’exigence d’un slot s’applique au remplissage qui finit par l’occuper une fois toutes les portées repliées, de sorte qu’un remplissage au niveau du composant qui en supplante un plus large hérite de l’exigence sans changement.

sensitive sur un slot porte le même plafond que le mot-clé au niveau des feuilles — il annote ; il ne chiffre pas, ne valide pas, ne rejette pas, n’impose pas de mécanisme de livraison et ne modifie aucun octet rendu. L’énoncé complet se trouve dans vocabulary/compact-form-authoring.md « Ce que le mot-clé ne fait pas ».

sensitive et compliance.aggrega.ai/data-class sont deux axes différents, documentés côte à côte et jamais confondus. sensitive est un booléen sur une feuille ou sur un slot : cette donnée, ou ce point de liaison, manipule du matériau secret. compliance.aggrega.ai/data-class est un label gradué sur un nœud entier — public, internal, restricted — qui donne aux données que détient un composant une identité de gouvernance. L’un est par donnée et binaire, l’autre par nœud et ordonné ; aucun ne remplace l’autre, et une entité peut porter les deux. Le label est traité dans vocabulary/labels-and-annotations.md et dans architecture/08-credential-model.md « Gouvernance des données autour des identifiants ».

Projection de schéma à partir de featuresSchema

Les slots déclarés sont projetés dans un fragment JSON Schema 2020-12 qui décrit la forme du bloc de rattachements. Deux sortes de remplissage sont validées par rapport à lui : le bloc de rattachements d’un composant qu’un module importé fournit, une fois construite la composition qui l’importe, et un rattachement déclaré à une portée plus large, par rapport au slot de chaque composant qu’il atteint. Le bloc de rattachements d’un composant que l’Aggregate déclare lui-même est mesuré à la place par le schéma de document de l’Aggregate et par la liste d’autorisation inject du slot (voir ci-dessous), et le fragment est conçu pour que les deux rendent le même verdict sur tout remplissage. La projection ne touche jamais le disque ; elle n’existe qu’en mémoire, et le schema: d’un Component n’a jamais à rédiger à la main le pilier des rattachements.

featuresSchema en entrée :

featuresSchema:
root_password:
inject: []
user_password:
inject: [env, file]

Fragment projeté (en mémoire ; représentation en forme compacte) :

# The OUTER object is open: an attachment under a name no slot declares is
# admitted, because a free attachment is legal authoring.
root_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
# inject admits only an empty block — inject: [] means the Recipe controls
# delivery, so a fill may name no mechanism
inject: {}
user_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
inject:
env: { type: array }
file: { type: array }
# arg is absent — not in the inject allowlist

Les deux profondeurs sont indépendantes. L’objet externe est ouvert, de sorte qu’un slot déclaré n’interdit jamais les rattachements que l’entité n’a pas énumérés. Le fragment propre à chaque slot déclaré est fermé, de sorte qu’un remplissage qui occupe effectivement un slot déclaré reste contraint à la forme de ce slot.

Le fragment décrit uniquement la FORME. Il ne contient aucune affirmation sur les slots qui doivent être occupés, car un slot marqué required peut être occupé par un rattachement arrivant en cascade depuis une portée plus large — ce qui laisse vide le bloc que décrit ce fragment. L’exigence est donc vérifiée par rapport à l’ensemble de rattachements dont un composant dispose au final plutôt que par rapport à ce que déclare un bloc particulier, et les deux questions ne se contredisent jamais, car une seule d’entre elles est jamais posée au bloc écrit.

Les clés permises reflètent les clés qu’un rattachement peut porter partout, de sorte qu’une clé légale sur un rattachement libre reste légale sur le remplissage d’un slot. Chaque mécanisme de livraison de la liste d’autorisation est une liste d’entrées de livraison — la même forme que inject: prend partout ; le slot restreint quels NOMS de mécanisme peuvent apparaître, et non l’aspect d’une entrée.

Où la liste d’autorisation inject est appliquée

La liste d’autorisation lie les deux côtés du slot, à deux étapes différentes.

Vis-à-vis du Workload de la Recipe, à l’étape de rendu : un Workload qui référence un slot par les entrées de rattachement de son conteneur doit nommer un slot que l’entité déclare, et doit sélectionner un mécanisme de livraison que la liste d’autorisation inject du slot permet ; une référence à un slot boîte noire (inject: []), à un mécanisme hors de la liste d’autorisation, ou à un slot que l’entité n’a jamais déclaré arrête la build. Le diagnostic nomme la Recipe, le chemin du conteneur et le slot fautif, et il est classé comme une faute du catalogue — c’est la Recipe qui s’est trompée.

Vis-à-vis du rattachement propre de l’Aggregate, lorsque ses rattachements sont résolus et avant tout rendu : un bloc inject: sur un remplissage qui occupe un slot déclaré ne peut nommer que des mécanismes que la liste d’autorisation du slot permet, et un slot boîte noire n’en permet aucun — sa liste d’autorisation vide dit « la Recipe livre ceci en interne ; n’imposez pas la livraison », et rédiger une livraison pour lui arrête la build. Le diagnostic est positionné sur le rattachement et nomme le slot et le mécanisme fautif, ainsi que les mécanismes que le slot permet lorsqu’il en permet ; il est classé comme une faute du développeur, car c’est l’Aggregate qui s’est trompé. Un bloc inject: {} vide ne nomme aucun mécanisme ; il n’impose donc aucune livraison et est accepté sur tout slot, un slot boîte noire compris — aussi bien sur un composant que l’Aggregate déclare que sur un composant qu’un module importé fournit et sur un rattachement déclaré à une portée plus large. Un rattachement libre — sous un nom qu’aucun slot ne déclare — n’est soumis à aucune contrainte de ce type, car la liste d’autorisation appartient au slot et non au bloc.

Le flux de bout en bout à travers le pipeline de compilation — comment un rattachement de l’Aggregate se connecte à une Feature d’identifiant (comme core/secret-value) puis à une FeatureRecipe propre au provider qui livre l’identifiant au workload en cours d’exécution — est détaillé dans examples/05-credential-features.

Une clé que l’appelant présente et une clé que le serveur vérifie

Lorsqu’un composant en appelle un autre qui vérifie une clé, chaque extrémité détient la clé de son propre côté, dans un slot qu’elle déclare elle-même. C’est une convention que suit le catalogue de la bibliothèque standard ; le compilateur n’en applique rien — il vérifie les slots de chaque composant par rapport aux rattachements propres de ce composant, transmet leurs chaînes et ne compare jamais ce que détient un composant avec ce que détient un autre.

  • La clé que présente un appelant appartient à l’appelant. Elle se trouve dans un slot que le socket de l’appelant déclare pour chaque connexion — voir « Slots que remplit chaque connexion » plus haut — de sorte qu’un appelant qui atteint plusieurs cibles détient une clé pour chacune. Le socket model de core/ai-agent/crewai déclare ce slot sous le nom credential, et ses Recipes livrent ce qui le remplit sous la forme OPENAI_API_KEY. Les sockets models de core/gateway/litellm, core/gateway/kong et core/gateway/apisix le déclarent aussi, et leurs Recipes livrent la clé de chaque connexion sous une variable qui lui est propre, nommée d’après l’alias de la connexion, de sorte que chaque modèle que sert la passerelle détient sa propre clé. Une clé qu’un Component déclare plutôt dans un slot qui lui est propre est une seule clé pour toutes les connexions qu’il établit.
  • La clé que vérifie un serveur est un slot propre au serveur. core/ai-model/vllm, core/ai-model/tei et core/ai-model/tgi déclarent chacun un api_key facultatif, et chacune de leurs Recipes livre ce qui le remplit sous la forme de la variable dans laquelle le serveur lit sa clé. Le modèle et la passerelle LiteLLM déclarent api_key pour la clé que LiteLLM appelle sa clé maîtresse.
  • Aucune extrémité ne voit les rattachements de l’autre. Un rattachement sur une connexion est l’un des rattachements de l’appelant et n’atteint que le rendu de l’appelant, et la sortie rendue d’un serveur est la même quoi que portent les connexions qui l’atteignent. Un slot marqué required est dû par le composant qui le déclare, jamais par les composants qui lui sont connectés, et remplir le slot d’une extrémité ne remplit rien sur l’autre — déclarer la clé aux deux extrémités est donc le minimum et non un doublon.
  • Les deux extrémités lisent un même paramètre, de sorte que la clé que présente l’appelant et la clé que vérifie le serveur ne peuvent pas être écrites différemment.
# Aggregate fragment — one parameter feeds both ends
spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
agent:
type: core/ai-agent/crewai
# values (role, goal, backstory, …) elided
uses:
model:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

Un serveur qui vérifie une seule clé ne peut pas distinguer ses appelants : vLLM, TEI et TGI vérifient chacun une seule clé, de sorte que chaque appelant présente la même, quel que soit le nombre de connexions qui atteignent le serveur. Que les deux extrémités référencent un même secret ou que chacune détienne le sien découle de l’endroit où chaque provider résout un secret par référence, et le Manifest choisit la réalisation de chaque extrémité — Modèle d’identifiants détaille les deux cas.

Un identifiant qu’un composant détient pour lui-même — une clé avec laquelle il signe ses propres sessions, par exemple — est un slot de son propre featuresSchema: comme un autre. Un mot de passe qu’il présente à un datastore qu’il atteint par l’un de ses sockets est la clé de l’appelant décrite plus haut ; il se trouve donc sur cette connexion sous le nom credential : le socket backend de core/gateway/kong le déclare, et ses Recipes de synthèse de workload le livrent sous la forme KONG_PG_PASSWORD, et le socket cache_store de core/gateway/litellm le déclare pour le mot de passe que son cache sémantique présente au store, livré sous la forme REDIS_PASSWORD. Lorsqu’une connexion présente une paire — un identifiant de clé d’accès et son secret — la moitié secrète est credential et la moitié identifiant credential_id, comme sur le socket store de core/ai-agent/agenta-api.

Auto-injection : spec.inject

Un Component peut déclarer un tableau de premier niveau spec.inject: qui liste les mécanismes de livraison autorisés pour l’auto-injection. Lorsqu’il est présent, les développeurs peuvent utiliser un bloc inject: au niveau du composant dans l’Aggregate pour injecter les clés values: ou provides: propres au Component directement dans son propre canal de livraison (les variables d’environnement de son conteneur, les fichiers montés ou les arguments du processus). Lorsque spec.inject: est absent ou vide, l’auto-injection au niveau du composant est interdite — la Recipe contrôle tout le câblage interne, conformément au modèle Black-Box que usesSchema[].inject: [] et featuresSchema[].inject: [] appliquent respectivement à la livraison entre composants et à la livraison des identifiants.

# Component declares its self-inject allowlist:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/web-server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
inject: [env, file]
schema:
values:
log_level: { type: string, default: info }
tls_enabled: { type: boolean, default: false }
provides:
health_endpoint: { type: string }
# Aggregate fragment — developer dictates self-inject delivery:
components:
api:
type: core/web-server
values:
log_level: debug
tls_enabled: true
inject:
env:
- in: LOG_LEVEL
value: '{{"{{"}} .values.log_level }}'
- in: TLS_ENABLED
value: '{{"{{"}} .values.tls_enabled }}'
file:
- in: /etc/web/health-probe
from: health_endpoint

Chaque template value: commence par {{"{{"}} plutôt que par {{. Le texte entier de l’Aggregate est lu une fois comme template, pour l’interpolation des paramètres, avant que la résolution de l’auto-injection ne s’exécute, et .values n’existe pas à ce stade ; l’échappement remet {{ en place pour que la résolution de l’auto-injection l’évalue. Voir Texte qui contient ses propres doubles accolades.

Sémantique du champ. spec.inject: est un tableau de noms de mécanismes. Trois valeurs sont définies :

  • env — variables d’environnement dans le conteneur.
  • file — chemins de fichiers montés.
  • arg — arguments de ligne de commande du processus.

La sémantique reproduit exactement celle de usesSchema[].inject et featuresSchema[].inject — même vocabulaire, même modèle Black-Box en cas d’omission, même forme de rédaction côté Aggregate. La différence est la source : usesSchema[].inject régit la manière dont les provides d’une dépendance entre composants s’écoulent dans le canal de livraison du consommateur ; featuresSchema[].inject régit la manière dont un identifiant atteint un conteneur ; spec.inject régit la manière dont les values et provides propres au Component atteignent le propre conteneur du Component.

Discipline de rédaction. Un Component core/web-server qui déclare spec.inject: [env, file] opte pour une livraison transparente — l’auteur de l’Aggregate dicte quels noms de variables d’environnement portent quelles valeurs. Un Component qui déclare spec.inject: [] (ou omet le champ) garde la livraison opaque — le valuesMapping: de la Recipe décide quels champs s’écoulent dans quelles variables du conteneur, et le développeur ne peut pas le remplacer dans l’Aggregate. Le modèle Black-Box convient aux Components à contrat stable (un Component core/postgres-db dont la Recipe sait câbler le mot de passe de la base de données dans une variable d’environnement POSTGRES_PASSWORD) ; le modèle transparent convient aux Components dont l’intention du développeur nomme légitimement des détails de livraison (un core/web-server dont l’application lit LOG_LEVEL depuis un nom de variable non standard que le développeur souhaite personnaliser).

Modes d’erreur. Un Aggregate de développeur qui utilise un bloc inject: sur un Component dont le spec.inject: est absent ou vide arrête le build au chargement de l’espace de travail (« Self-inject on a component without an allowlist » (Auto-injection sur un composant sans liste d’autorisation)). Un bloc inject: qui utilise un mécanisme absent de la liste d’autorisation s’arrête sur la même condition, en nommant le mécanisme et ceux que la liste autorise (« Self-inject mechanism not in the component’s allowlist » (Mécanisme d’auto-injection absent de la liste d’autorisation du composant)). Une collision de clés de livraison entre l’auto-injection, l’injection entre composants et l’injection d’identifiants arrête également le build (« Duplicate delivery key across inject sources » (Clé de livraison en double entre les sources d’injection)). Voir errors/fatal-halts.md pour la forme du message de chaque erreur.

Rédaction du catalogue : étendre des Components de base

Les Platform Architects utilisent le mot-clé extends pour superposer des interfaces spécialisées à des bases de référence d’entreprise ou communautaires. L’extension compose la structure et hérite des piliers de données en entier. Le compilateur parcourt la chaîne depuis la base vers le bas ; les deux moitiés se comportent différemment, et cette différence constitue tout le modèle de rédaction.

Ce que l’extension compose. Ces surfaces fusionnent le long de la chaîne, le Component qui étend l’emportant clé par clé et les listes se concaténant en commençant par la base, sans doublons :

SurfaceComment elle se compose
metadata.labelsfusion clé par clé ; la valeur du Component qui étend l’emporte sur une clé partagée
metadata.annotationsfusion clé par clé, même priorité — c’est pourquoi le mandat de présence d’une base atteint chaque Component qui l’étend
spec.featuresSchemaunion des emplacements d’attachement ; un emplacement que le Component qui étend redéclare remplace l’entrée de la base portant ce nom
spec.usesSchemaunion des sockets de topologie, même règle de remplacement par nom
spec.injectles deux listes d’autorisation d’auto-injection se concatènent, entrées de la base en premier, doublons supprimés
spec.assertionsles règles nommées s’accumulent, règles de la base en premier — et cette seule surface n’admet aucun remplacement par nom ; voir « L’héritage des assertions est additif » ci-dessous

Un socket ajouté par le Component qui étend peut porter ses propres valueSchema et infraSchema par arête ; ce sont des contrats sur les arêtes de ce socket, et non des ajouts aux piliers propres du Component.

Le reste de metadata: reste attaché au document qui le déclare. labels et annotations sont les seules métadonnées qui descendent le long de la chaîne. name, version, description, maintainers, license, repository, home et keywords appartiennent au Component qui étend et sont lus exactement tels qu’il les a rédigés — un Component qui omet description: n’en a aucune, au lieu d’emprunter celle de sa base. L’identité et la provenance appartiennent au document que vous lisez, de sorte qu’un wrapper n’est jamais confondu avec ce qu’il enveloppe.

Ce dont l’extension hérite en entier. Les trois piliers de données — values, infra, provides — ne sont pas composés. Un Component qui étend ne rédige aucun contenu de pilier : il écrit le marqueur littéral schema: inherited et reçoit le bloc schema: de sa base exactement tel que la base l’a rédigé. Le long d’une chaîne de toute profondeur, chaque Component qu’elle contient porte inchangé le bloc de la racine de la chaîne, de sorte que aggrega inspect --resolved sur une feuille affiche les mêmes piliers que sur la racine.

Le schéma Component publié établit lequel des trois résultats possibles est légal, et rejette les deux autres au chargement du document — avec un diagnostic différent pour chacun, car ce sont des erreurs différentes :

  • extends: avec du contenu de pilier sous schema: est rejeté. Le contrat du Component est celui de sa base ; un second contrat divergent n’a nulle part où exister.
  • extends: avec schema: entièrement omis est rejeté. Une omission empêcherait le lecteur de distinguer un bloc de piliers hérité d’un bloc oublié.
  • schema: inherited sans extends: est rejeté. Le marqueur indique d’où viennent les piliers, et ce Component n’a aucune base d’où les prendre.

Un Component qui étend ne peut pas remodeler l’ensemble des clés. Il ne déclare aucune clé de pilier : il ne peut donc ni masquer, ni supprimer, ni retyper une clé que sa base déclare, et il n’en ajoute aucune. Une nouvelle clé de pilier appartient au Component dont le contrat la possède. Tout ce que la base expose, tout ce qui l’étend l’expose à l’identique.

Une spécialisation se resserre au moyen de assertions:. Lorsqu’une spécialisation doit admettre moins que les piliers de sa base — une plage numérique plus étroite, un sous-ensemble d’un enum: hérité —, elle l’exprime dans son propre bloc assertions: : une règle y rejette une valeur que le schéma hérité accepte. C’est la surface où vit le resserrement ; voir « Le bloc assertions: » ci-dessous.

Ces deux derniers paragraphes forment une seule règle, et chaque moitié prise seule induit en erreur : restreindre l’ensemble des clés est impossible, resserrer les contraintes est possible. Si l’on ne retient que la première, on conclut qu’une spécialisation ne peut rien contraindre ; si l’on ne retient que la seconde, on conclut qu’elle peut remodeler le contrat. Ni l’un ni l’autre n’est vrai — l’ensemble des clés est fixé par la base, et les valeurs admises en son sein peuvent être restreintes par prédicat.

L’héritage des assertions est additif, et l’accumulation part de la racine. Une instance d’un Component qui étend est vérifiée par rapport à chaque règle que déclare sa chaîne ainsi qu’aux règles que le Component déclare lui-même, les règles héritées étant évaluées en premier. Le long d’une chaîne de toute profondeur, les règles s’accumulent depuis la racine de la chaîne vers le bas, de sorte que lorsqu’une instance enfreindrait plus d’une règle, c’est celle déclarée le plus haut dans la chaîne qui est signalée — le contrat le plus fondamental répond en premier.

Comme l’héritage ajoute plutôt qu’il ne remplace, un Component qui étend ne peut pas réutiliser le nom d’une règle héritée pour déclarer une règle différente : cela est rejeté lorsque la chaîne extends est résolue par rapport au catalogue, avec un diagnostic qui nomme les deux Components et le nom partagé. La vérification nécessite d’avoir le Component de base sous la main ; elle se signale donc lorsque le catalogue est validé ou qu’un build résout la chaîne — valider seul le document qui étend ne permet pas de la détecter. Le nom de la règle est un identifiant stable : ni supprimer la règle de la base ni la renommer silencieusement n’est donc une option, et la correction consiste à renommer dans le Component qui étend. Reformuler une règle héritée octet pour octet sous son propre nom est accepté comme l’opération sans effet qu’elle est.

aggrega pull récupère la base. Une base est une dépendance de chaque Release qui atteint un Component qui l’étend, que quoi que ce soit d’autre la nomme ou non. aggrega pull suit chaque extends: jusqu’au bout de la chaîne, récupère depuis le registre une base qu’aucun répertoire de catalogue ne contient, et enregistre chaque base dans le lockfile de la Release, référencée depuis le spec.extends du Component qui la nomme ; un build lit la base à partir de là. Ainsi, un Manifest ne mappe que le type propre d’un wrapper et rien de plus — la base n’a besoin de sa propre ligne de mappage que là où un Aggregate déclare aussi une instance de la base. Un aggrega validate sur l’ensemble du catalogue lit une base de la même manière, de sorte qu’une base publiée dans un registre y est refusée, en nommant aggrega pull, jusqu’à ce qu’un pull l’ait récupérée.

Voir architecture/13-catalog-and-registry.md §3 pour les formats de contenu des schémas.

Exemple A : le Component de base (la base de référence de l’entreprise) Le Platform Architect définit un serveur d’entreprise fondamental. Cette base définit le label obligatoire de primitive cloud opérationnelle et établit les contraintes de sécurité dans le schéma. Comme le bloc de piliers est hérité inchangé, chaque contrainte définie ici atteint chaque Component qui étend exactement telle qu’elle a été rédigée.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/base-enterprise-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
inject: [env]
schema:
values:
# The corporate baseline constraint. Every Component extending this base
# receives this leaf verbatim; none of them can restate or loosen it.
tls_enabled: { type: boolean, enum: [true], default: true }
# An open range at the baseline. A specialization that needs a tighter
# bound expresses it as an assertion, not as a redeclared schema leaf.
timeout_ms: { type: integer, default: 5000 }
assertions:
# A baseline invariant. It is evaluated for instances of this Component AND
# for instances of every Component extending it, under this same name.
audit-window-is-observable: |
{{- if lt (int .values.timeout_ms) 100 -}}
{{- fail "the corporate baseline needs timeout_ms of at least 100 so requests are observable" -}}
{{- end -}}

Exemple B : le Component qui étend (spécialiser la base de référence) Une passerelle est spécialisée à partir de cette base de référence. Elle reprend les piliers de la base en entier, ajoute sa propre structure — un label, un mécanisme d’auto-injection, un socket de topologie portant un emplacement d’attachement — et resserre le délai d’expiration hérité au moyen d’une assertion. Elle ne reformule pas la règle audit-window-is-observable de la base de référence : cette règle est héritée et évaluée en premier, de sorte qu’une instance de cette passerelle doit satisfaire les deux bornes — au moins 100 et au plus 2000.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/gateway/kong
version: 1.0.0
labels:
# Every Component declares the reserved base-ontology key, including one
# that extends: the envelope requires it on the document itself.
component.aggrega.ai/type: "server"
api.aggrega.ai/protocol: "http" # merged with the base's labels
spec:
extends: core/base-enterprise-server
schema: inherited # values, infra and provides are the base's, verbatim
inject: [file] # concatenates with the base's [env] -> [env, file]
usesSchema: # a socket of its own; the base declared none
backend:
required: true
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]
featuresSchema: # a slot each connection through it fills
credential:
sensitive: true
inject: [env]
description: Password the gateway presents to the configuration backend this connection reaches.
assertions:
# The tightening. The inherited schema admits any integer for timeout_ms;
# this gateway admits only 2000 or less, so the rule rejects a value the
# inherited pillar block would accept.
timeout-within-gateway-budget: |
{{- if gt (int .values.timeout_ms) 2000 -}}
{{- fail "the gateway must answer within 2000ms: set timeout_ms to 2000 or less" -}}
{{- end -}}

Pour la Recipe qui implémente cette interface core/gateway/kong sur un chart Helm physique, voir entities/recipe, exemple C (kong-gateway).

Le bloc assertions:

Component.spec.assertions: est une map facultative de règles nommées exprimant des invariants architecturaux du contrat du Component — des règles inter-champs que la rédaction du développeur doit satisfaire, quelle que soit la Recipe liée au Component. Chaque clé est un identifiant de règle qui apparaît dans le message d’échec ; chaque valeur est un corps de template Go. Le compilateur les évalue pour chaque instance après la validation du schéma et avant la liaison de la Recipe, dans l’ordre où elles sont écrites, et la première règle en échec arrête le build avec le message d’erreur propre à cette règle, conformément au contrat Loud Guardrails.

spec:
assertions:
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt (int .values.secondary.replicaCount) 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}

La règle ci-dessus est une propriété du contrat du Component — quelle que soit la Recipe liée (chart Bitnami, alternative écrite à la main, implémentation future), le mode de réplication exige au moins deux réplicas secondaires.

assertions: est l’endroit où un Component qui étend se resserre. Un Component qui étend une base via extends: hérite textuellement du bloc de piliers de la base et ne déclare aucun contenu de pilier propre ; une spécialisation qui doit admettre moins que le schéma hérité exprime donc ici la restriction sous forme de prédicat plutôt que de feuille de schéma restreinte — une règle qui rejette une valeur que les piliers hérités acceptent. La paire d’exemples et le comportement complet de l’héritage se trouvent dans « Rédaction du catalogue : étendre des Components de base » ci-dessus : les règles s’accumulent le long de la chaîne en partant de la racine, et réutiliser le nom d’une règle héritée pour une règle différente est rejeté plutôt qu’autorisé à la remplacer.

Le compilateur ne vérifie pas si deux règles peuvent être satisfaites ensemble. Une règle est un prédicat de template, pas une contrainte sur laquelle le compilateur raisonne ; une paire de règles qu’aucune valeur ne peut satisfaire à la fois — une base exigeant au moins 100 et une spécialisation exigeant au plus 50 — ne produit donc aucun avertissement au chargement du catalogue. Elle se manifeste de la manière ordinaire : une instance est rédigée, le build s’arrête sur celle des deux qui se déclenche en premier, et le message de cette règle est ce que lit l’auteur. Ne vous attendez pas à ce qu’une contradiction soit signalée d’emblée ; vérifiez le resserrement d’une spécialisation par rapport à ce que sa base exige déjà.

Utilisez assertions: pour de véritables règles inter-champs. Les contraintes par champ (plage, motif, enum) relèvent des mots-clés de schema: ; les prédicats personnalisés par champ relèvent de validate: de la forme compacte ; la forme conditionnelle (si les contraintes d’un sous-arbre s’appliquent) relève de when:. Pour la grammaire de rédaction complète — champs du contexte de template, convention de message {{ fail }}, phase d’évaluation et exemples détaillés couvrant les rôles Component et Recipe —, voir templates/assertions-block.md.