Architektonische Invarianten
Diese acht Invarianten sind die Gründungsregeln von Aggrega. Sie gelten über alle Releases hinweg, im Compiler-Kern, in der Schemaschicht, im Katalog und in der Wasm-Plugin-Oberfläche. Jede Designentscheidung, jede Funktion und jede verfasste Entität hält sie ein.
Andere Architekturkapitel verweisen auf die Invarianten über ihre Nummer. Wenn ein späteres Kapitel „gemäß Invariante 2“ oder „nach der String-Pipe-Regel (Invariante 3)“ sagt, verweist es hierher.
1. Der Compiler ist inhaltsneutral, meinungslos und agnostisch gegenüber der Absicht des Benutzers
Der Aggrega-Compiler ist ein Ahead-Of-Time-Textrouter (AOT). Er parst YAML, durchläuft Graphen, wertet Label-Schnittmengen aus und leitet Strings von Quellen zu Senken. Er überwacht nicht, was Autoren in values, parameters, infra, provides oder locals eintragen. Er erzwingt weder Namenskonventionen noch Port-Konventionen noch die semantischen Labels, die ein Architect erfindet.
Viele Regeln, die wie Compiler-Regeln klingen — der Zero-Port-Vertrag, der Katalogstil Naked-Base / Flavored-Edges, die Wahl, welches operative Primitiv zu einer bestimmten Komponente passt —, sind Gesellschaftsverträge: Best Practices mit Auswegen, getragen von den Plattformarchitekten, die den Katalog der Standardbibliothek verfassen. Der Compiler interpretiert sie nicht.
Diese Invariante betrifft, was der Compiler aus von Ihnen verfassten Inhalten ableitet, und dieser Geltungsbereich ist ihr ganzer Inhalt. Eine Handvoll Schlüssel gehört Aggrega selbst — reserviert, mit den akzeptierten Werten im veröffentlichten Schema festgeschrieben —, und das Schema prüft diese so, wie es jedes andere deklarierte Feld prüft. component.aggrega.ai/type ist einer davon: Seine Wertemenge ist geschlossen, und ein Dokument mit einem Wert außerhalb davon wird beim Laden abgelehnt. Das ist die Plattform, die festlegt, was ihr eigener Schlüssel bedeutet, nicht der Compiler, der einem von Ihnen geschriebenen String eine Bedeutung beimisst, und es lässt jeden Ihrer eigenen Schlüssel genau so unüberwacht, wie diese Invariante sagt. Ein Katalog, der Komponenten entlang einer Achse klassifiziert, die Aggrega nicht definiert, verfasst seinen eigenen Label-Schlüssel, den das Schema mit jedem String-Wert akzeptiert und den jede Selektor-Oberfläche gleich liest.
Was der Compiler tatsächlich durchsetzt, ist eng begrenzt: Schemavalidierung, YAML-Parsing, Graphaufbau, Template-Auswertung und das reine Text-Routing des Injection-Vertrags. Alles andere ist Konvention, durchgesetzt beim Verfassen des Katalogs oder im optionalen Wasm-Governance-Socket.
Unternehmen, die ihre eigenen internen Kataloge verfassen, steht es ausdrücklich frei, Konventionen der Standardbibliothek zu brechen. Der Compiler akzeptiert alles, was sie schreiben, sofern es die Schemavalidierung besteht. Die Architektur fördert Best Practices; sie baut keine Gefängnisse.
2. AOT-Reinheit: Der Compiler hat keinen Zugriff auf Laufzeitinformationen
Aggrega ist ein Ahead-Of-Time-Compiler. Zur Kompilierzeit:
- Er authentifiziert sich nicht bei Cloud-APIs.
- Er ruft keine aktuellen IP-Adressen, DNS-Namen oder von der Cloud generierten URLs ab.
- Er löst Secrets nicht in Klartext auf — Secrets bleiben in der gesamten Zwischendarstellung (Intermediate Representation) Metadaten-Zeiger.
- Er kennt den Laufzeitzustand der Ziel-Cluster oder -Dienste nicht.
- Er kann keine Daten abrufen, die noch nicht existieren (Endpunkte nach der Bereitstellung, dynamisch zugewiesene Ports, automatisch generierte Ressourcennamen).
Alles, was vom Laufzeitzustand abhängt, wird als deterministischer Zeiger-String ausgedrückt — ein stabiler DNS-Name, ein Terraform-Interpolations-String, eine CloudFormation-Ressourcenreferenz —, den das Ops Recipe liefert. Der Compiler leitet den Zeiger durch, ohne ihn aufzulösen. Die Laufzeitumgebung (der Cluster, der IaC-Zustandsmanager) löst die endgültigen physischen Daten auf.
Das ist echte Kontrollumkehr (True Control Inversion): Entwickler legen im Aggregate einen Injection Contract fest, der Compiler verdrahtet deterministische Zeiger im Voraus, und die Laufzeitumgebung löst die endgültigen physischen Daten auf. Anforderungen, die tatsächlich eine Auflösung zur Laufzeit benötigen, gehören in die Wasm-Pipeline eines Ops Recipe, nicht in den Compiler-Kern.
3. Die String Pipe: Der Compiler kann keine Bedeutung ableiten
Der Compiler interpretiert nicht, was durchgeleitete Werte bedeuten. Wenn Component A Component B verwendet, nimmt der Compiler den Skalar, den die Recipe von Component B über provides erzeugt — eine Zeichenkette, eine Zahl oder einen Booleschen Wert —, und leitet ihn in den Recipe-Kontext von Component A, an der Injektionsgrenze deterministisch in eine Zeichenkette umgewandelt. Ob dieser Wert ein FQDN, ein lokaler Hostname, ein IP-Literal, eine Portnummer oder ein Wasm-formatierter DSN ist, macht keinen Unterschied: Der Compiler validiert weder Routbarkeit noch Protokollkorrektheit noch semantische Angemessenheit.
Daraus ergeben sich zwei Konsequenzen:
- Der Compiler errät den Zweck einer Komponente nicht aus ihrem Namen. Eine Komponente namens
database-productionwird nicht als Datenbank erkannt. Semantische Typ-Labels wiecomponent.aggrega.ai/type(sofern vorhanden) sind opake Metadaten, die für das Label-Matching verwendet werden, keine Verzweigungslogik des Compilers. - Der Compiler unterscheidet einen Hostnamen nicht von einem Datenbanknamen, einer Portnummer oder einem beliebigen opaken Wert. Sie alle sind skalare Einträge im Injektionskontext und werden als Strings übergeben.
Die Topologie-Triade — provides am erzeugenden Recipe, uses am konsumierenden Aggregate, inject an der Kante — ist der Injection Contract. Der Compiler wertet Labels aus und reicht Strings weiter; die Interpretation ist der Autorenvertrag zwischen Recipe und Component.
4. Keine Geisterinfrastruktur: Der Compiler erfindet niemals Rechenressourcen oder Funktionen
Der Compiler fügt niemals stillschweigend Rechenressourcen, Features, Annotationen, Routing-Proxys oder andere Ressourcen ein, die der Autor nicht ausdrücklich deklariert hat. Richtlinienverstöße erzeugen laute Leitplanken (Loud Guardrails) — der Build bricht mit einem spezifischen Fehler ab, der dem Autor sagt, was in dem von ihm geschriebenen Dokument zu korrigieren ist —, keine stillen Mutationen, die beim Debuggen zu rätselhafter Infrastruktur führen.
Ressourcen gelangen durch explizite Deklarationen beim Verfassen in den Graphen:
- Das Aggregate des Entwicklers (Komponenten,
uses-Kanten, Feature-Anbindungen). - Die Feature-Anbindungen des Release (Ergänzungen auf Operator-Ebene).
- Annotationsgesteuerte Erweiterung (das Manifest deklariert Bindungen von Annotation → Feature; die Annotation an einer Component oder Grenze ist eine explizite Deklaration).
- Ressourcenerzeugung auf Recipe-Ebene: Das Rendern von
sourceim Recipe erzeugt das primäre Artefakt; die Synthese vonworkloadgibt die providerspezifische Deployment-Form aus (Pod-Spezifikation, Compose-Dienst usw.); Einträge inartifacts:(inline oder per$import:geladen) geben Recipe-eigene Hilfsmanifeste aus; die Ressourcengenerierung des FeatureRecipe gibt Hilfsressourcen pro Feature aus, ausgelöst durch eine explizite Feature-Anbindung.
Pfade auf Recipe-Ebene sind Deklarationen beim Verfassen, nur einen Schritt entfernt: Der Recipe-Autor schreibt source / workload / artifacts / valuesMapping gegen einen Component-Vertrag, und das Aggregate des Entwicklers wählt aus, welche Components beteiligt sind. Eine Ressource in der gerenderten Ausgabe lässt sich entweder auf eine Deklaration im Aggregate, im Release oder in einer Annotationsbindung zurückführen oder auf das Verfassen des Recipe, das die Komponententypen des Aggregate ausgewählt haben.
Die Synthese wandelt vom Autor deklarierte Formen in providerspezifische Ausgabeformate um. Eine als Map von Containern verfasste Workload-Spezifikation kann als Kubernetes-Pod-Spezifikation, als Compose-Dienstblock oder als Terraform-Modul gerendert werden — die Umwandlung ist providergesteuert, doch die Ressourcen lassen sich auf die Workload-Deklaration des Autors zurückführen.
Der Governance-Socket trägt pro Anbindung eine Rolle, und die Rolle — nicht die Art des Plugins — legt fest, was eine Anbindung mit einem Build tun darf. Ein in einer Urteilsrolle angebundenes Governance-Plugin — das den IR-Graphen (ir-verdict) oder die gerenderten Artefakte (render-verdict) prüft — darf einen Build ablehnen, ihn aber nicht ändern. Will ein solches Urteil eine Ressource hinzugefügt haben, lässt es den Build mit einem Hinweis zur Behebung fehlschlagen, sodass der Autor die Ressource selbst hinzufügt; der Host liest die Ausgabe eines Urteils nur als Annahme oder Ablehnung und wendet sie niemals als Änderung an, sodass ein ungebetenes Umschreiben des Graphen in einen konformen Zustand — genau die Geisterinfrastruktur, die diese Invariante verbietet — nicht aus einer Urteilsrolle kommen kann. Ein in einer Transformationsrolle (label-transform oder annotation-transform) angebundenes Governance-Plugin ist die enge, explizite Ausnahme: Ein Operator, der eines anbindet — optional, über die Konfiguration plugins.governance des Workspace —, hat diese Transformation deklariert, sodass die Änderungen, die sie vornimmt, eine explizite Deklaration sind, mit demselben Status wie die annotationsgesteuerte Erweiterung, keine stillschweigende Einfügung. Der Unterschied liegt in der Einladung: Ein nicht angefordertes Urteil darf den Build nicht umschreiben, eine explizit angebundene Transformation darf es, weil der Operator sie angefordert hat. Da eine Transformation die gerenderte Ausgabe formt, wird sie wie jedes ausgabeformende Plugin in der Lockfile fixiert — die angewandte Transformation steht zum Zeitpunkt des Pulls fest, sodass eine Änderung ein erneutes Pullen bedeutet statt einer stillen Verschiebung zwischen Builds; ein Urteil formt keine Ausgabe und wird nicht fixiert.
5. Das Aggregate ist die Autorenoberfläche; ein Release kann keine values: deklarieren
Das Release-Schema verbietet mechanisch einen values:-Block. Operatoren können aus einem Release heraus keine values an einer Component oder einem Feature schreiben. Das ist Schemadurchsetzung auf Ebene von JSON Schema — kein Gesellschaftsvertrag, keine Konvention —, und sie ist laut: Jedes Entitätsdokument wird beim Laden gegen das Schema seiner Art validiert, sodass ein Release mit values: den Build mit einer Diagnose abbricht, die die Datei und den beanstandeten Schlüssel nennt, statt stillschweigend ignoriert zu werden.
Das bedeutet nicht, dass Werte in allen Umgebungen identisch sind. Der unterstützte Weg für umgebungsspezifische Variation ist das Hochziehen von Parametern (Parameter Hoisting):
- Der Entwickler stellt im Aggregate ein typisiertes Feld
parameters.*bereit. - Das
values-Template der Component referenziert es:storage_size: "{{ .parameters.db_size }}". - Das Release erfüllt den Parameter:
parameters: { db_size: "100Gi" }. - Die gerenderte Ausgabe spiegelt den umgebungsspezifischen Wert wider.
Das Aggregate bleibt die einzige Quelle der Wahrheit dafür, welche Werte für umgebungsspezifische Variation bereitgestellt werden (die parameters-Deklaration) und wie sie in die Komponentenwerte einfließen (die Template-Referenz). Das Release erfüllt; es überschreibt nicht.
Zwei weitere Einschränkungen schützen dieselbe Invariante:
- Wenn ein Release
extendsverwendet, ist die Deklaration einesaggregate:-Zeigers durch das Schema verboten. Das Kind-Release muss dieselbe Entwicklerabsicht (Developer Intent) bereitstellen wie sein übergeordnetes Release. - Das Release kann keine Rechenressourcen einführen, die das Aggregate nicht deklariert hat, und keine vom Entwickler deklarierte Kante umleiten. Innerhalb der Sockets, die der Architect deklariert hat, darf das Release Kanten zwischen bestehenden Komponenten verdrahten und konfigurieren: Es setzt kantenbezogenes
infraauf einer Kante, die der Entwickler verdrahtet hat, oder verdrahtet eine Kante in einen deklarierten, aber ungebundenen Socket zu einer bestehenden Komponente. Es kann keine kantenbezogenenvaluesdeklarieren (diese bleiben im Aggregate), keinen Socket binden, den dasusesSchemader Component nicht deklariert, und keine Kante auf eine nicht existierende Komponente richten — jedes davon bricht den Build ab. Beachten Sie, welche Deklaration der mittlere Teilsatz meint: Der Socket muss imusesSchemader Katalog-Component erscheinen. Ein Aggregate-Autor darf einen Socket benennen, den sein Komponententyp nicht deklariert, und die Release-Oberfläche wird bewusst nicht auf dieselbe Weise geöffnet — ein Operator verdrahtet und konfiguriert innerhalb einer Architektur, statt eine zu erfinden.
Die kantenbezogene Verbindungskonfiguration ist auf den Konsumenten beschränkt: Die auf einer Kante getragenen values und infra erscheinen nur im Render-Kontext des Knotens, der die Kante verfasst hat, niemals im Kontext des Ziels. Die gerenderte Ausgabe einer Komponente ist daher invariant gegenüber den Verbindungen, die andere Komponenten zu ihr herstellen — das Verdrahten oder Konfigurieren einer Kante zu einem Ziel verändert niemals, was das Recipe des Ziels rendert. Der einzige Ort, an dem diese Verbindungen sichtbar sind, ist ein an das Ziel angebundenes Feature: Sein FeatureRecipe kann lesen, welche Komponenten das Ziel verwenden, sodass die Ressourcen, die es ausgibt — etwa eine Richtlinie, die genau die deklarierten Aufrufer zulässt —, der Verdrahtung folgen, während die eigene Ausgabe des Ziels das nicht tut. Selbst dort bleiben die kantenbezogenen values und infra beim Konsumenten.
6. Die WebAssembly-ABI-Grenze: Domänenspezifische Intelligenz lebt in Wasm
Das Go-Host-Binary enthält keinerlei cloud- oder infrastrukturspezifische Logik. Sämtliche domänenspezifische Intelligenz, das Template-Rendering und die Formatierung leben strikt in WebAssembly-Plugins, die von der eingebetteten Wazero-Laufzeit ausgeführt werden. Der Go-Host orchestriert die Pipeline und übergibt Payloads über die ABI als Speicherzeiger an Wasm-Gäste, in der Kodierung, die der jeweilige Socket trägt.
Daraus ergeben sich zwei Folgerungen:
- Provider-spezifische Logik (Helm-spezifisches Rendering, Terraform-spezifische Formatierung, Compose-spezifisches Zusammenführen) lebt niemals im Go-Compiler-Kern. Der Compiler löst den Provider-Namen, den ein Recipe in
spec.capabilitydeklariert, zu dem Provider-Rendering-Plugin auf, das ihn bedient, und leitet den Knoten an dieses Plugin weiter; die Übersetzung selbst läuft vollständig im Wasm-Gast. Der Host enthält für einen Standard-Provider keinen providerspezifischen Go-Code, sodass es im Prozess nichts gibt, auf das zurückgegriffen werden könnte — ein Provider-Name, der sich zu keinem bedienenden Plugin auflösen lässt, bricht den Build ab, statt irgendeinen eingebauten Standard zu rendern. - Richtlinienlogik (Sicherheitsregeln, Compliance-Prüfungen, FinOps-Berechnungen) lebt niemals im Go-Compiler-Kern. Richtlinien gehören in den Wasm-Governance-Socket, für den sich Unternehmen entscheiden — ein Plugin, das in einer Urteilsrolle (
ir-verdict/render-verdict) angebunden ist, um einen Build anzunehmen oder abzulehnen, oder in einer Transformationsrolle (label-transform/annotation-transform), um Labels oder Annotationen zu formen.
Die ABI-Grenze hält den Go-Kern kompakt, prüfbar und cloud-agnostisch. Das Austauschen der Rendering-Logik eines Providers ist ein Austausch eines Wasm-Artefakts, keine Neukompilierung von Aggrega selbst.
7. Trennung der Zuständigkeiten (Vier-Domänen-Aufteilung) — Orientierung, kein Gefängnis
Die Designrichtlinien von Aggrega teilen das Verfassen in vier Domänen auf:
- Developer Intent — Aggregate.
- Platform Architect — Katalogentitäten Component und Feature.
- Platform Ops — Recipe, FeatureRecipe, Plugin (einschließlich des Provider-Rendering-Plugin).
- Platform Operator — Manifest, Release.
Das typische, gut funktionierende Deployment folgt dieser Aufteilung: Entwickler schreiben die Anwendungsabsicht, nicht die physische Infrastruktur; Ops schreiben die physische Infrastruktur, nicht die Anwendungslogik. Aggrega ist dafür entworfen, so verwendet zu werden, und die offizielle Dokumentation, die Beispiele und der Katalog der Standardbibliothek sind auf diese Aufteilung hin verfasst.
Die Vier-Domänen-Aufteilung ist Orientierung und Designrahmen, keine Durchsetzung durch den Compiler. Der Compiler ist (gemäß Invariante 1) meinungslos. Benutzern steht es frei:
- Rollen zusammenzulegen (eine Person schreibt sowohl Aggregates als auch Recipes).
- Zuständigkeiten zu vermischen (Architects schreiben Compliance-Labels fest direkt auf
core/*-Components, wenn Unternehmenskataloge es verlangen). - Domänengrenzen zu überschreiten (Entwickler nutzen das Hochziehen von Parametern, um Infrastrukturbelange in das Aggregate einzubringen, wenn Legacy-Code es verlangt).
Der Compiler akzeptiert jedes Autorenmuster, das die Schemavalidierung besteht. Die Architektur fördert Best Practices; Einschränkungen auf Schemaebene (etwa das Verbot von values: im Release aus Invariante 5) sind die einzigen Domänenüberschreitungen, die der Compiler tatsächlich ablehnt. Jede andere Trennung ist ein Gesellschaftsvertrag, den Katalogautoren aufrechterhalten und, wo Unternehmen sich dafür entscheiden, der Wasm-Governance-Socket.
8. Deterministische Ausgabe
Bei identischer Eingabe erzeugt der Compiler eine byteidentische Ausgabe. Zwei Kompilierungen desselben Aggregate + Release + Manifest gegen denselben Katalog ergeben gerenderte Artefakte, die Byte für Byte übereinstimmen.
Das ist der Vertrag, auf den sich GitOps-Werkzeuge und diff-basierte Review-Abläufe verlassen. Ein Pull Request, der die Eingabe nicht geändert hat, sollte keinen Diff in der gerenderten Ausgabe erzeugen. Ein Pull Request, der die Eingabe geändert hat, sollte nur den Diff zeigen, den diese Änderung impliziert — keine unechte Umsortierung, keine Zeitstempel-Fluktuation, keine Artefakte der Map-Iteration.
Deterministische Ausgabe wird durch drei Disziplinen gewährleistet:
- Vom Autor geordnete Maps: Jede Map, deren Iterationsreihenfolge die gerenderte Ausgabe beeinflussen könnte, verwendet einen geordneten Map-Container, sodass die Iteration der Deklarationsreihenfolge des Autors folgt statt der Hash-Reihenfolge.
- Keine Uhrzeit- oder Zufallsinhalte in gerenderten Artefakten, es sei denn, der Autor hat sie ausdrücklich über die Template-Eingabe eingefügt.
- Das Rendering ist rein: Derselbe Aufruf eines Wasm-Gasts mit derselben Eingabe erzeugt dieselbe Ausgabe.
Das Flag --trace des Compilers (siehe language-reference/cli/aggrega-build.md) gibt Autoren und Operatoren eine Verifikationsoberfläche für diese Invariante. Zwei Kompilierungen derselben Eingabe mit aktiviertem --trace erzeugen byteidentische Trace-Dumps; jeder Diff in einem Durchlauf lokalisiert eine Regression. Determinismus ist nicht nur eine Eigenschaft zum Zeitpunkt der Veröffentlichung — er ist in jedem Zwischenzustand des Compilers über das knotenbezogene Trace-Layout beobachtbar.
Deterministische Ausgabe ist der Vertrag, der Aggrega sicher als Quelle der Wahrheit in einer GitOps-Schleife nutzbar macht.
Geltungsbereich der Invarianz über die Auflösungsstufen hinweg
Die Garantie byteidentischer Ausgabe gilt für Artefakte, die in der Lockfile fixiert sind — Entitäten, die über Registry-Artefakte aufgelöst werden, deren Digests die Lockfile festhält (die Registry-Stufe des dreistufigen Modells der Entitätsauflösung). Wenn ein Build die Dateien liest, die ein Release über einen Pfad benennt (lokale Pfade, die mit ./ oder ../ beginnen), oder Entitäten in Katalogverzeichnissen des Workspace (catalog_dirs:, in der Workspace- und Cache-Stufe), hängt die Invarianz davon ab, dass diese Dateien zwischen Builds unverändert bleiben. Die Lockfile hält eine Entität in einem Katalogverzeichnis des Workspace über den Digest ihres Dokuments und der von ihr deklarierten Dateien fest, sodass ein Build bei einer Entität, die sich seit dem Pull geändert hat, abbricht, statt sie zu rendern — mit einer Ausnahme: Ein Recipe oder FeatureRecipe, das das Manifest über eine Referenz benennt, die zugleich der Name einer Component oder eines Feature ist, wird unter dieser Referenz als Component oder Feature festgehalten, sodass seine Eingaben nur durch die Pins in der Lock-Datei daneben gehalten werden und eine Änderung an seinem eigenen Dokument nicht erkannt wird. Die Dateien unverändert zu halten, liegt in der Verantwortung des Versionskontrollsystems (typischerweise Git).
Eine Referenz auf einen lokalen Pfad, deren zugrunde liegende Datei sich zwischen zwei Kompilierungen ändert, erzeugt einen legitimen Diff in der gerenderten Ausgabe, obwohl die Form der Compiler-Eingabe unverändert ist — die Garantie deterministischer Ausgabe bleibt gewahrt (gleiche Byte-Eingabe → gleiche Byte-Ausgabe), aber die Eingaben unterscheiden sich, weil sich die lokale Datei geändert hat. Kataloge, die für jede Quelle Invarianz über Builds hinweg benötigen, ziehen Artefakte aus einer Registry in den in der Lockfile fixierten Cache, statt sie aus einem lokalen Pfad oder einem Workspace-Verzeichnis zu lesen; die Lockfile ist der Anker der Byte-Identität.