Résolution des dépendances
Résolution des dépendances dans Aggrega & le pilier de la topologie structurelle
Dans l’architecture Aggrega, les dépendances topologiques sont cartographiées explicitement via le pilier de schéma uses afin de conserver une charge utile values entièrement opaque. Déterminer « qui parle à qui » pose un défi spécifique : des topologies applicatives complexes à plusieurs nœuds doivent être cartographiées sans obliger le développeur à écrire un routage réseau explicite, des ordres d’exécution au niveau de l’orchestrateur ou des dépendances d’infrastructure.
1. La philosophie de base : pourquoi uses ?
Le bloc uses déclare les dépendances entre composants comme de la pure topologie : le Component A dépend du contrat public provides du Component B, et non de l’adresse physique ou des détails de connexion du Component B. La topologie vit dans uses ; la configuration vit dans values. Cette séparation permet au compilateur de voir explicitement toutes les arêtes entre composants sans les déduire du contenu de values.
Aggrega résout ce problème en élevant la topologie au rang de pilier de schéma de premier ordre appelé uses.
- L’argument du proxy sémantique : le mot-clé
usesreprésente une intention sémantique L7. Si un agentusesune base de données, cela reste sémantiquement vrai même si Platform Ops insère entre eux des maillages de proxys Wasm transparents. - Neutralité mathématique : le compilateur Go analyse nativement la structure
usespour tracer le graphe de la représentation intermédiaire (IR). Il ne tente jamais d’analyser ni d’interroger la logique applicative du développeur (values). - Atomicité de la Feature : le pilier
usess’applique de manière identique aux Components et aux Features (y compris les Features d’identifiants). Cela permet à un proxy sidecar (une Feature) ou à un récupérateur d’identifiants de déclarer de manière autonome ses propres dépendances réseau sans polluer la configuration de son Component parent.
2. La mécanique du contrat de schéma unifié
Pour extraire des instructions opérationnelles sans analyser la charge utile de l’application, le système s’appuie sur des déclarations JSON Schema 2020-12 strictes régissant des structures YAML explicitement séparées.
Domaine 2 : le schéma scindé (usesSchema & schema) Pour éviter que le catalogue de la plateforme ne se fragmente en fichiers de schéma ingérables, Aggrega utilise un moteur de schéma scindé. Le usesSchema en YAML natif définit et valide strictement la topologie, tandis que schema: (JSON Schema 2020-12 — généralement écrit au moyen de la notation abrégée compacte) valide le contenu des piliers values et infra et déclare la forme du pilier provides. Les values qu’écrit un développeur et l’infra que définit un opérateur sont vérifiées par rapport à leurs types déclarés ; le sous-schéma provides déclare les noms de clés et les types du contrat en aval que produit une Recipe, et le compilateur vérifie que chaque référence inject nomme une clé provides déclarée — mais les valeurs provides produites circulent elles-mêmes en aval comme des chaînes opaques que le compilateur achemine sans interprétation, et non comme des valeurs dont il vérifie le type, car le cœur n’interprète pas ce que signifie une valeur acheminée. C’est dans le usesSchema qu’un socket est déclaré, et c’est sa déclaration qui lui donne un contrat. Un socket que l’entité de catalogue déclare porte les contraintes de cette entité : un sélecteur indiquant quelles cibles il peut atteindre, une liste d’autorisation inject et des valueSchema / infraSchema par arête. Dans le usesSchema, les architectes de la plateforme utilisent le champ selector: — lu comme la chaîne que l’architecte a écrite, et non copié dans un schéma généré — et le moteur de sélecteurs Go natif l’évalue pour imposer la sûreté de typage entre nœuds sur les sockets déclarés. Il garantit que, si un socket requiert une base de données, le développeur ne peut pas y brancher un serveur web.
Le sélecteur est tenu à sa grammaire au moment où il est évalué, c’est-à-dire une fois pour chaque arête câblée à travers le socket. Un sélecteur que le moteur ne peut pas lire comme l’une de ses six formes d’exigence — une exigence vide laissée par une virgule superflue, une clé contenant des espaces ou l’un des caractères qu’utilise la grammaire pour distinguer ses formes (=, !, (, ) et la virgule), ou un ensemble sans sa parenthèse fermante — arrête la compilation sur cette arête, en nommant l’exigence, au lieu d’être lu comme un autre sélecteur. C’est cette rigueur qui garde la vérification honnête : lu avec indulgence, !tier=frontend, écrit pour exclure les frontends, demanderait seulement qu’aucune étiquette ne soit nommée tier=frontend, et toutes les cibles — frontends compris — passeraient. La même grammaire régit les sélecteurs des emplacements d’attachement et l’appliesTo d’une Feature ; la grammaire des sélecteurs énumère chaque forme et chaque refus. Une compilation n’évalue jamais un socket à travers lequel aucune arête n’est câblée ; c’est pourquoi aggrega validate — sur l’ensemble du catalogue, ou sur le Component ou la Feature qui déclare le socket — lit le sélecteur de chaque socket déclaré et refuse dès ce stade un sélecteur mal formé, sous le code et dans les termes qu’emploie une compilation qui câble ce socket.
Déclarer le socket n’est toutefois pas la seule façon de tracer une arête. L’auteur d’un Aggregate peut nommer sur son propre composant un socket que l’entité de catalogue ne déclare pas — y compris sur un type de composant qui ne déclare aucun usesSchema — et l’arête est construite. Un catalogue qui ne déclare aucune entrée pour un socket n’a pas anticipé la connexion, ce qui n’équivaut pas à l’interdire, et la topologie de l’application appartient au développeur. Un tel socket est dit ad hoc, et ce qu’il coûte est exactement ce que la déclaration apporte : il n’y a pas d’entrée de catalogue, donc ni sélecteur ni contrat par arête, et la sûreté de typage entre nœuds n’a rien à évaluer. Ce que l’arête peut transporter reste inchangé — chaque clé qu’elle injecte doit toujours nommer une clé que déclare le provides de la cible, et la cible doit toujours exister. Chaque arête du graphe émis enregistre lequel des deux cas elle représente, de sorte qu’un consommateur n’a jamais à deviner ; voir governance-and-compliance pour savoir comment un opérateur interdit purement et simplement les sockets ad hoc.
Deux surfaces ne sont délibérément pas ouvertes de cette manière, car elles n’écrivent pas la topologie de l’application. Le uses d’un attachement de Feature ne peut nommer qu’un socket que déclare la Feature attachée, et le uses par arête d’une Release ne peut nommer qu’un socket que l’entité de catalogue du composant consommateur déclare dans son usesSchema, jamais un socket que l’Aggregate a écrit ad hoc — un opérateur configure et câble au sein d’une architecture, et une Feature participe à la topologie que déclare sa propre entité de catalogue. Déclarer le socket dans le catalogue reste par ailleurs la meilleure voie et c’est ce que fait le catalogue de la bibliothèque standard : un socket ad hoc est une porte de sortie, pas un nouveau comportement par défaut.
Domaine 1 : l’expérience développeur (polymorphisme) Les développeurs écrivent uses: au même niveau que values: et features:. Pour garantir une UX sans friction, le schéma prend en charge nativement le polymorphisme :
- Tableaux de chaînes : utilisés pour de simples références logiques à des composants (par ex.
tools: ["search-api"]) lorsque le routage standard suffit. - Maps d’objets : utilisées lorsque des contrats de livraison stricts sont requis (par ex.
databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } }). - Pas de jokers : il n’existe pas de forme joker, ce qui empêche les « dépendances fantômes » et le câblage automatique non autorisé : chaque entrée nomme un seul composant, de sorte que
["*"]arrête la build comme cible inexistante — aucun nom de composant ne peut contenir*.
Domaine 3 : la réalité d’Ops (normalisation) Pour que les templates Go restent prévisibles, le compilateur Go normalise les entrées polymorphes de uses. Les tableaux de références logiques à des composants sont convertis en objets standard avant d’être transmis au dictionnaire plat et strict appelé .context.uses.
3. Exemples de bout en bout
Les deux exemples suivants démontrent les deux propriétés distinctes du pilier explicite de la topologie : l’exemple A prouve si une connexion est autorisée (sûreté de typage entre nœuds), et l’exemple B prouve comment les données de connexion sont physiquement livrées (polymorphisme & normalisation).
Exemple A : validation topologique et sûreté de typage entre nœuds
Ce scénario montre comment le sélecteur d’un socket déclaré détecte qu’un agent IA s’apprête à se connecter à une base de données dépourvue des étiquettes de conformité requises, et arrête le build. Le compilateur évalue le sélecteur d’étiquettes écrit par l’architecte par rapport aux étiquettes de la cible, en tant que chaînes ; il n’interprète pas ce que signifie une étiquette, et aucun plugin de politique n’intervient.
1. La bibliothèque standard (le schema: unifié dans le catalogue) Le Platform Architect définit la structure du schéma, en séparant nativement la logique cognitive des cibles topologiques.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/enterprise-agent version: 1.0.0 labels: component.aggrega.ai/type: "worker"spec: usesSchema: datastores: selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
schema: # 1. The Cognitive Intent values: system_prompt: { type: string, required: true }2. L’intention du développeur (l’Aggregate) Le développeur sépare proprement ce que fait l’agent (values) de ce à quoi l’agent se connecte (uses).
components: my_secure_vector_db: type: core/qdrant-secure:1.0.0 values: collection_name: finance_data
auditing_agent: type: core/enterprise-agent:1.0.0 values: system_prompt: "You are a financial auditing AI..." uses: datastores: finance_memory: { target: "my_secure_vector_db" }3. Exécution du compilateur et validation topologique
- Validation locale : le compilateur Go évalue l’objet entier par rapport au JSON Schema résolu lors de la résolution. Il vérifie les étiquettes de catalogue sous-jacentes de
my_secure_vector_db. Si la base de données n’avait pas l’étiquetterestricted, le compilateur arrêterait immédiatement le build avec une violation de sûreté de typage. - Tracé du graphe : lors de la construction de la topologie, le compilateur Go ignore entièrement le contenu validé par le schéma. Il lit
uses.datastores.finance_memory.targetnativement depuis le YAML et trace l’arête explicite dans le graphe IR.
Exemple B : polymorphisme et .context.uses normalisé
Ce scénario montre comment le compilateur gère à la fois un outil d’IA boîte noire (passé sous forme de tableau) et une base de données relationnelle héritée (qui exige une map avec un contrat inject).
1. Le catalogue (domaine 2) : la déclaration schema: L’Architect autorise des tableaux polymorphes pour les outils, mais exige des objets stricts pour les bases de données.
spec: usesSchema: # Polymorphic Array Socket (No injection needed) tools: selector: "tool.aggrega.ai/impact=read-only"
# Strict Map Socket (Requires delivery contract) databases: selector: "component.aggrega.ai/type=stateful-server" inject: ["env", "file"]
schema: values: system_prompt: { type: string, required: true }2. L’intention du développeur (domaine 1) : l’Aggregate Le développeur utilise un tableau simple pour l’outil et une map explicite pour la base de données.
components: my-agent: type: core/python-worker:1.0.0 values: system_prompt: "You are an HR bot."
uses: # 1. Polymorphic Array: Simple logical component reference tools: - "corporate-search-api"
# 2. Strict Map: Dictating the environment variable delivery databases: hr_db: target: corporate-hr-db inject: env: - in: HR_DATABASE_URI # Local env var from: "host" # Target provides key3. La réalité d’Ops (domaine 3) : la Recipe Le compilateur Go normalise le polymorphisme. Ops reçoit un dictionnaire .context.uses plat et prévisible. Il suffit de parcourir le pipe .context.inject dans les sections pertinentes du template.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: generic-worker version: 1.0.0spec: capability: helm implements: core/python-worker:1.0.0 source: "./charts/internal/python-runner"
locals: primary_compute: worker-container
valuesMapping: | env: # Ops uses the pre-resolved inject map, kept apart from values and topology loops {{- range $key, $value := .context.inject.env }} - name: {{ $key }} value: "{{ $value }}" {{- end }}