Abhängigkeitsauflösung
Abhängigkeitsauflösung in Aggrega & die Säule der strukturellen Topologie
In der Aggrega-Architektur werden topologische Abhängigkeiten explizit über die Schemasäule uses abgebildet, um eine vollständig opake values-Nutzlast zu bewahren. Die Frage „wer spricht mit wem“ zu beantworten, stellt eine spezifische Herausforderung dar: Komplexe Anwendungstopologien mit mehreren Knoten müssen abgebildet werden, ohne den Entwickler zu zwingen, explizites Netzwerkrouting, Ausführungsreihenfolgen auf Orchestratorebene oder Infrastrukturabhängigkeiten zu schreiben.
1. Die Grundphilosophie: Warum uses?
Der uses-Block deklariert komponentenübergreifende Abhängigkeiten als reine Topologie: Component A hängt vom öffentlichen provides-Vertrag von Component B ab, nicht von der physischen Adresse oder den Verbindungsdetails von Component B. Die Topologie lebt in uses, die Konfiguration in values. Die Trennung erlaubt dem Compiler, alle komponentenübergreifenden Kanten explizit zu sehen, ohne sie aus dem Inhalt von values ableiten zu müssen.
Aggrega löst dies, indem es die Topologie zu einer vollwertigen Schemasäule namens uses erhebt.
- Das Argument des semantischen Proxys: Das Schlüsselwort
usessteht für semantische L7-Absicht. Wenn ein Agent eine Datenbankuses, bleibt dies semantisch wahr, selbst wenn Platform Ops transparente Wasm-Proxy-Meshes dazwischenschaltet. - Mathematische Neutralität: Der Go-Compiler parst die
uses-Struktur nativ, um den Graphen der Zwischendarstellung (IR) zu zeichnen. Er versucht nie, die Anwendungslogik des Entwicklers (values) zu parsen oder abzufragen. - Feature-Atomarität: Die
uses-Säule gilt für Components und Features gleichermaßen (einschließlich Credential-Features). So kann ein Sidecar-Proxy (ein Feature) oder ein Abrufer von Zugangsdaten seine eigenen Netzwerkabhängigkeiten selbstständig deklarieren, ohne die Konfiguration seiner übergeordneten Component zu verunreinigen.
2. Die Mechanik des einheitlichen Schemavertrags
Um operative Anweisungen zu extrahieren, ohne die Anwendungsnutzlast zu parsen, stützt sich das System auf strenge JSON Schema 2020-12-Deklarationen, die ausdrücklich getrennte YAML-Strukturen regeln.
Domäne 2: Das geteilte Schema (usesSchema & schema) Um zu verhindern, dass der Plattformkatalog in unüberschaubare Schemadateien zerfällt, nutzt Aggrega eine Split-Schema-Engine. Das native YAML-usesSchema definiert und validiert streng die Topologie, während schema: (JSON Schema 2020-12 — typischerweise über die kompakte Kurzform verfasst) den Inhalt der Säulen values und infra validiert und die Form der Säule provides deklariert. Die values, die ein Entwickler verfasst, und die infra, die ein Operator setzt, werden gegen ihre deklarierten Typen geprüft; das provides-Teilschema deklariert die Schlüsselnamen und Typen des nachgelagerten Vertrags, den ein Recipe erzeugt, und der Compiler prüft, dass jede inject-Referenz einen deklarierten provides-Schlüssel benennt — die erzeugten provides-Werte selbst reisen jedoch als opake Strings nachgelagert, die der Compiler ohne Interpretation durchleitet, nicht als Werte, deren Typ er prüft, denn der Kern interpretiert nicht, was ein durchgeleiteter Wert bedeutet. Im usesSchema wird ein Socket deklariert, und erst die Deklaration gibt ihm einen Vertrag. Ein Socket, den die Katalogentität deklariert, trägt die Einschränkungen dieser Entität: einen Selektor, der angibt, welche Ziele er erreichen darf, eine inject-Allowlist sowie valueSchema / infraSchema pro Kante. Innerhalb des usesSchema verwenden Plattformarchitekten das Feld selector: — gelesen als der String, den der Architekt geschrieben hat, und in kein generiertes Schema kopiert —, und die native Go-Selektor-Engine wertet es aus, um über deklarierte Sockets knotenübergreifende Typsicherheit durchzusetzen. Sie stellt sicher, dass ein Entwickler keinen Webserver anschließen kann, wenn ein Socket eine Datenbank verlangt.
Der Selektor wird in dem Moment an seine Grammatik gebunden, in dem er ausgewertet wird, also einmal für jede über den Socket verdrahtete Kante. Ein Selektor, den die Engine nicht als eine ihrer sechs Anforderungsformen lesen kann — eine leere Anforderung durch ein überzähliges Komma, ein Schlüssel mit Leerraum oder mit einem der Zeichen, mit denen die Grammatik ihre Formen unterscheidet (=, !, (, ) und das Komma), oder eine Menge ohne schließende Klammer —, bricht den Build an dieser Kante ab und benennt die Anforderung, statt als ein anderer Selektor gelesen zu werden. Diese Strenge hält die Prüfung ehrlich: Großzügig gelesen würde !tier=frontend, geschrieben, um Frontends auszuschließen, nur verlangen, dass kein Label tier=frontend heißt, und jedes Ziel — Frontends eingeschlossen — würde passieren. Dieselbe Grammatik gilt für Selektoren von Anhangs-Slots und für das appliesTo eines Feature; die Selektorgrammatik führt jede Form und jede Ablehnung auf. Ein Build wertet nie einen Socket aus, über den keine Kante verdrahtet ist; daher liest aggrega validate — über den gesamten Katalog oder über die Component oder das Feature mit der Deklaration des Sockets — den Selektor jedes deklarierten Sockets und lehnt einen fehlerhaften bereits dort ab, unter demselben Code und mit denselben Worten, die ein Build verwendet, der den Socket verdrahtet.
Die Deklaration des Sockets ist jedoch nicht der einzige Weg, eine Kante zu ziehen. Der Autor eines Aggregate kann an seiner eigenen Komponente einen Socket benennen, den die Katalogentität nicht deklariert — auch bei einem Komponententyp, der überhaupt kein usesSchema deklariert —, und die Kante wird gebaut. Ein Katalog, der für einen Socket keinen Eintrag deklariert, hat die Verbindung nicht vorhergesehen, was nicht dasselbe ist, wie sie zu verbieten, und die Topologie der Anwendung gehört dem Entwickler. Ein solcher Socket heißt ad hoc, und was er kostet, ist genau das, was die Deklaration einbringt: Es gibt keinen Katalogeintrag, also keinen Selektor und keinen Vertrag pro Kante, und die knotenübergreifende Typsicherheit hat nichts auszuwerten. Was die Kante transportieren darf, bleibt unverändert — jeder Schlüssel, den sie injiziert, muss weiterhin einen Schlüssel benennen, den das provides des Ziels deklariert, und das Ziel muss weiterhin existieren. Jede Kante im ausgegebenen Graphen hält fest, welcher der beiden Fälle vorliegt, sodass ein Konsument nie raten muss; siehe governance-and-compliance, wie ein Operator Ad-hoc-Sockets vollständig verbietet.
Zwei Oberflächen sind bewusst nicht auf diese Weise offen, weil sie die Topologie der Anwendung nicht verfassen. Das uses eines Feature-Anhangs darf nur einen Socket benennen, den das angehängte Feature deklariert, und das kantenbezogene uses eines Release darf nur einen Socket benennen, den die Katalogentität der konsumierenden Komponente in ihrem usesSchema deklariert, niemals einen, den das Aggregate ad hoc verfasst hat — ein Operator konfiguriert und verdrahtet innerhalb einer Architektur, und ein Feature nimmt an der Topologie teil, die seine eigene Katalogentität deklariert. Den Socket im Katalog zu deklarieren bleibt zudem der bessere Weg und ist das, was der Katalog der Standardbibliothek tut: Ein Ad-hoc-Socket ist ein Ausweg, kein neuer Standard.
Domäne 1: Die Entwicklererfahrung (Polymorphie) Entwickler schreiben uses: auf derselben Ebene wie values: und features:. Um eine reibungslose UX zu gewährleisten, unterstützt das Schema nativ Polymorphie:
- Arrays von Strings: Werden für einfache logische Komponentenreferenzen verwendet (z. B.
tools: ["search-api"]), wenn Standard-Routing ausreicht. - Maps von Objekten: Werden verwendet, wenn strenge Zustellverträge erforderlich sind (z. B.
databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } }). - Keine Wildcards: Es gibt keine Wildcard-Form, was „Geisterabhängigkeiten“ und unautorisiertes automatisches Verdrahten verhindert: Jeder Eintrag benennt genau eine Komponente, sodass
["*"]den Build als nicht existierendes Ziel anhält — kein Komponentenname kann*enthalten.
Domäne 3: Die Ops-Realität (Normalisierung) Damit Go-Templates vorhersehbar bleiben, normalisiert der Go-Compiler die polymorphen uses-Eingaben. Arrays logischer Komponentenreferenzen werden in Standardobjekte umgewandelt, bevor sie an das strenge, flache Dictionary namens .context.uses übergeben werden.
3. End-to-End-Beispiele
Die folgenden zwei Beispiele zeigen die zwei unterschiedlichen Eigenschaften der expliziten Topologiesäule: Beispiel A belegt, ob eine Verbindung autorisiert ist (knotenübergreifende Typsicherheit), und Beispiel B belegt, wie die Verbindungsdaten physisch zugestellt werden (Polymorphie & Normalisierung).
Beispiel A: Topologische Validierung und knotenübergreifende Typsicherheit
Dieses Szenario zeigt, wie der Selektor an einem deklarierten Socket erkennt, dass sich ein KI-Agent mit einer Datenbank verbinden will, der erforderliche Compliance-Labels fehlen, und den Build anhält. Der Compiler wertet den vom Architekten geschriebenen Label-Selektor als Zeichenketten gegen die Labels des Ziels aus; er interpretiert nicht, was ein Label bedeutet, und es ist kein Policy-Plugin beteiligt.
1. Die Standardbibliothek (das vereinheitlichte schema: im Katalog) Der Platform Architect definiert die Schemastruktur und trennt dabei kognitive Logik nativ von topologischen Zielen.
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. Die Absicht des Entwicklers (das Aggregate) Der Entwickler trennt sauber, was der Agent tut (values), von dem, womit sich der Agent verbindet (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. Compiler-Ausführung und topologische Validierung
- Lokale Validierung: Der Go-Compiler prüft bei der Auflösung das gesamte Objekt gegen das aufgelöste JSON Schema. Er prüft die zugrunde liegenden Katalog-Labels von
my_secure_vector_db. Fehlte der Datenbank das Labelrestricted, würde der Compiler den Build sofort mit einer Typsicherheitsverletzung anhalten. - Graphzeichnung: Beim Aufbau der Topologie ignoriert der Go-Compiler schemavalidierte Inhalte vollständig. Er liest
uses.datastores.finance_memory.targetnativ aus dem YAML und zeichnet die explizite Kante im IR-Graphen.
Beispiel B: Polymorphie und das normalisierte .context.uses
Dieses Szenario zeigt, wie der Compiler sowohl ein Blackbox-KI-Werkzeug (als Array übergeben) als auch eine relationale Legacy-Datenbank (die eine Map mit einem inject-Vertrag erfordert) verarbeitet.
1. Der Katalog (Domäne 2): Die schema:-Deklaration Der Architect erlaubt polymorphe Arrays für Werkzeuge, verlangt aber strikte Objekte für Datenbanken.
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. Die Absicht des Entwicklers (Domäne 1): Das Aggregate Der Entwickler verwendet ein schlichtes Array für das Werkzeug und eine explizite Map für die Datenbank.
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. Die Ops-Realität (Domäne 3): Das Recipe Der Go-Compiler normalisiert die Polymorphie. Ops erhält ein flaches, vorhersehbares .context.uses-Dictionary. Es genügt, in den relevanten Abschnitten des Templates über die .context.inject-Pipe zu iterieren.
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 }}