Kompilierungspipeline (Überblick)
Dieses Kapitel beschreibt im Detail die interne Physik des Go-Compilers und legt fest, wie abstraktes YAML über die Kompilierungspipeline, den Graphen der Zwischendarstellung (Intermediate Representation, IR) und die WebAssembly-(Wasm-)Ausführungssockets in physische Konfigurationen übersetzt wird.
Die Kompilierungspipeline & der Ausführungsablauf
Aggrega führt statt fest codierter Orchestrierungslogik eine strikte Ahead-of-Time-Compiler-Pipeline (AOT) mit fester Reihenfolge aus. Ausgelöst durch aggrega build reicht der Compiler den flachen Graphen zwischen isolierten WebAssembly-(Wasm-)Sockets weiter, um die Architektur auszuwerten, bevor physische Artefakte gerendert werden.
Die Wasm-Sockets laufen auf einem eingebetteten Host — dem Extism-Toolkit auf Basis der Wazero-Engine — hinter einer AOT-Reinheits-Firewall, die einem Plugin jede Fähigkeit zum Laufzeitzugriff verweigert (Netzwerk, Dateisystem, Systemuhr, Umgebung, Standard-E/A), sodass ein Plugin die deterministische Ahead-of-Time-Garantie nicht brechen kann. Der Host führt den Publishing-Linter out of band über aggrega lint aus. Die unten beschriebenen In-Band-Gates — die Label-Transform-Rolle des Governance-Sockets bei der Topologiekonstruktion und seine IR-Verdict-Rolle bei der statischen Analyse sowie die Plugin-Pipeline, die das Rendering abschließt — laufen in jedem Build: eine Governance-Rolle überall dort, wo der Workspace ihr ein Plugin anhängt, und die Plugin-Pipeline für jedes Recipe, das Schritte deklariert. Status der Sprache verfolgt den Status jeder Pipeline-Phase.
Die Pipeline läuft vollständig im Arbeitsspeicher in einer strikten, festen Reihenfolge ab:
Auflösung — Der Resolver & Syntax-Validator
- Mechanismus: Vererbungs-Merge, Go-Template-Interpolation und Validierung nach JSON Schema 2020-12.
- Aktion: Die CLI ruft alle angeforderten Entitäten ab (Components, Features, Releases). Zuerst prüft sie diese Definitionen auf das Schlüsselwort
extends. Für die Katalog-Entitäten führt sie einen Deep-Merge der YAML-Metadaten durch, und bei den Datensäulen gehen die beiden Arten getrennte Wege: Dasschema:eines Feature wird nach der Komposition von JSON Schema 2020-12 mit dem seiner Basis komponiert, während eine erweiternde Component nur Struktur komponiert — ihre Attachment-Slots, Topologie-Sockets, Self-Inject-Allowlist und benannten Assertions — und denschema:-Block ihrer Basis genau so erhält, wie die Basis ihn verfasst hat. Ein erweiterndesReleasewird nach derselben Regel gefaltet: Der Wert des Kindes gewinnt Schlüssel für Schlüssel, bis hinunter zum ersten unteilbaren Wert — einem Skalar, einer Liste, einem Template —, der als Ganzes ersetzt wird, und ein Schlüssel, den das Kind alsnullschreibt, wird entfernt. So wandert seine gesamte Authoring-Oberfläche mit — der Boundary-Baum mit seinen komponentenspezifischeninfra- und Feature-Anhängen, derparameters-Block, die Annotationen und der Verweis auf das Manifest —, während keinmetadata-Feld mitwandert, da Identität und Provenienz pro Release gelten. Anschließend führt sie in drei Teilschritten eine Interpolation im Arbeitsspeicher durch: Validierung des Parametervertrags gegen die typisiertenparameters:-Deklarationen des Aggregate; Interpolation der aufgelösten Werte in die umgebendenvalues:-Strings; Entzug der.parameters-Map aus jedem Wert-Template-Kontext, sodass sie nur noch für vom Betreiber verfasste Pfad-Templates lesbar bleibt. Schließlich injiziert sie die aufgelösteninfra-Blöcke in die Payloads der Zielkomponenten. Sobald der Bauplan vollständig konkret ist, verwendet der Compiler die vereinheitlichteschema:-Deklaration aus dem Katalog (Kompaktform oder vollständiges JSON Schema 2020-12), um dievalues- undinfra-Konfigurationen des Entwicklers lokal strikt zu validieren.- Schema-Validierung der Features im Release: Über das Release angehängte Features (sowohl Boundary-weite als auch komponentenspezifische) werden in diesem Schritt gegen ihre Katalog-Entitäten aufgelöst. Der Compiler validiert die vom Release bereitgestellten
infra-Blöcke unmittelbar nach der Katalogauflösung gegen dieschema:-Deklaration jedes Feature und stellt so Typsicherheit her, bevor die Topologie aufgebaut wird. - Teilphase der annotationsgesteuerten Feature-Expansion: Nach der Auflösung des Manifest, der Recipe/Provider-Bindung und der Validierung der Bindungsziele des Manifest (unter
mappings.features.annotations.<key>.mapsdeklarierte Pfade existieren imspec.schemades referenzierten Feature) führt der Compiler vor dem Topologie-Builder eine Teilphase zur Annotationsexpansion aus. Die Teilphase durchläuft Release-Boundaries von außen nach innen und Aggregate-Subsysteme von außen nach innen und berechnet die effektive Annotationsmenge pro Komponente durch einen Merge aus Kaskade + Überschreibung + Null-Opt-out; parst jeden Annotationswert als YAML in einen Skalar, einen strukturierten Wert oder null; leitet jeden Wert (skalar oder strukturiert pro Unterschlüssel) über diemaps-Deklaration der Manifest-Bindung an die Ziel-Schemasäule des Feature weiter, mit Durchsetzung von Seite gegenüber Säule (die Aggregate-Seite löstmaps.valuesaus; die Release-Seite löstmaps.infraaus); validiert Typen pro Blatt gegen dasspec.schemades Feature; und injiziert synthetische Feature-Anhänge, die der IR-Graph mitorigin: annotationmarkiert. Schemas werden einmal pro Build kompiliert und über Kaskadendurchläufe hinweg wiederverwendet. Die Expansion läuft nach der Validierung der Bindungsziele und vor der Topologiekonstruktion, sodass nachgelagerte Stufen synthetische Anhänge strukturell identisch mit expliziten behandeln (außer bei Inspektion der Provenienz). Siehe 13-catalog-and-registry.md §„Annotationsgesteuerte Feature-Expansion“ undlanguage-reference/providers/well-known-annotations.mdfür die Form der Bindung, die Kaskadensemantik und die seitenübergreifenden Kompositionsregeln.
- Schema-Validierung der Features im Release: Über das Release angehängte Features (sowohl Boundary-weite als auch komponentenspezifische) werden in diesem Schritt gegen ihre Katalog-Entitäten aufgelöst. Der Compiler validiert die vom Release bereitgestellten
Topologiekonstruktion — Der Topologie-Builder & das Mutations-Gate
- Mechanismus: AST-Expansion + die
label-transform-Rolle des Governance-Sockets. - Aktion: Der Compiler liest nativ die explizit deklarierten
uses-Blöcke aus den validierten Komponenten, um deterministisch topologische Kanten zwischen Knoten im Graphen zu ziehen, und lässt denvalues-Block vollständig opak. Anschließend wertet er das Mutations-Gate aus, indem er eine Projektion des Graphen — die Labels jedes Knotens und dievalues, die seine Instanz deklariert und die der Compiler ungelesen weitergibt — zusammen mit dem Namen und der Umgebung des Release an ein Governance-Plugin übergibt, das an derlabel-transform-Rolle angehängt ist. Das Plugin wertet den Kontext aus und gibt JSONPatches zurück, um den Graphen dynamisch automatisch zu taggen (z. B. durch Injektion des Labelscompliance.aggrega.ai/data-class: restrictedauf Basis der Umgebung des Release oderdatastore.aggrega.ai/engine: vectorauf Basis der deklarierten Erweiterungen einer Datenbank); die Patches erreichen nur Labels.
Finalisierung des Graphen
- Mechanismus: Normalisierung.
- Aktion: Der Compiler finalisiert den flachen Graphen der Zwischendarstellung (Intermediate Representation, IR) und bewahrt dabei die expliziten topologischen Kanten, die der Topologie-Builder gezogen hat. Anschließend normalisiert er die angehängten Features und ihre
values-Payloads in ein flaches, nach Knoten-ID abgebildetes Dictionary und bereitet so den Capability-agnostischen Graphen auf die Validierung vor.- Normalisierung der IR-Payload: Die strukturelle Form der IR erzwingt eine Single Source of Truth für die Konfiguration: Die Topologieschicht trägt nur die Graphstruktur (Knotenidentität, Kanten, Metadaten-Labels), und der normalisierte Konfigurationszustand liegt in einem separaten In-Memory-Dictionary, das der Compiler an nachgelagerte Plugins übergibt. Mutatoren, die die Konfiguration ändern, ändern sie an einer Stelle; der Provider liest den normalisierten Zustand ohne das Risiko einer Abweichung durch redundante Speicherung.
Statische Analyse — Der statische Analysator & das Validierungs-Gate
- Mechanismus: Prüfungen der topologischen Reinheit + die
ir-verdict-Rolle des Governance-Sockets. - Aktion: Der Compiler führt eine abstrakte statische Analyse über den IR-Graphen aus. Zuerst extrahiert er die
selector-Strings aus denusesSchema-Definitionen und wertet sie mit einer nativen Go-Label-Matching-Engine (mit Unterstützung für Kubernetes-artige Semantik vonAND,ORüberin()undNOTüber!=) über die explizit definierten Kanten des Graphen aus, um knotenübergreifende Typsicherheit über deklarierte Sockets zu garantieren. Eine Kante auf einem Ad-hoc-Socket — einem, den ein Aggregate-Autor benannt und der Katalog nicht deklariert hat — hat keinen Katalogeintrag und damit keinen Selektor, sodass es für diese Prüfung nichts auszuwerten gibt und nichts fehlt; jede Kante hält fest, welche der beiden Arten sie ist, und was eine Ad-hoc-Kante tragen darf, wird stattdessen durch die deklariertenprovidesdes Ziels begrenzt. Außerdem wertet er die SelektorenappliesToundappliesToAnyOfvon Features aus, um zu prüfen, ob angehängte Features mit den Labels ihrer Zielkomponente kompatibel sind, sowie den eigenenselectorjedes gefüllten Attachment-Slots gegen die Labels des Feature, das ihn füllt. Zweitens wertet er jedes Präsenzmandat, das die Component eines Knotens deklariert — jedefeatures.aggrega.ai/requiredType.<label>-Annotation —, gegen die endgültige Anhangsmenge dieses Knotens aus. Der Analysator ist der richtige Ort für diese Prüfung, weil er die erste Stufe ist, die beide Hälften der Regel besitzt: die Annotationen der aufgelösten Component-Entität und die Anhangsmenge, die die 5-Tier-Kaskade erzeugt hat, wobei an das Aggregate, an Subsysteme und an das Release angehängte sowie durch Annotationen expandierte Anhänge gleichermaßen zählen. Ein Mandat, das kein Anhang erfüllt, hält den Build an; ein Mandat mit fehlerhafter Deklaration hält mit einer eigenen Diagnose an, sodass eine defekte Deklaration nie als erfüllte Anforderung gelesen wird. Drittens führt er das Validierungs-Gate aus, indem er die vollständige Graphstruktur (einschließlich aller Knoten, Kanten, angehängten Features und vorberechneten DFS-Pfade) an ein Governance-Plugin übergibt, das an derir-verdict-Rolle angehängt ist. Die benutzerdefinierte Wasm-Richtlinie des Unternehmens wertet die Topologie aus. Gibt das Wasm-Plugin ein Fehler-Array zurück (z. B. weil es einen durchgehenden Pfad von einempublic-Knoten zu einemrestricted-Knoten ohne ein bestimmtes Proxy-Feature erkennt), hält der Build an.
Rendering
- Mechanismus: Pre-Render-Interception (
injectMapping), Late Binding (valuesMapping) und Wasm-Rendering-Sockets (pipeline). - Aktion: Die abschließende Phase der Artefakterzeugung ist in strikte zeitliche Teilphasen aufgeteilt, die in fester Reihenfolge laufen, was die Ausführung deterministisch hält:
- Inject-Mapping (Pre-Render-Interception): Der Go-Compiler löst den abstrakten
.context.inject-Vertrag des Entwicklers auf. Anschließend führt er dieinjectMapping-Go-Templates aller angehängtenFeatureRecipesin der strikten Ausführungsreihenfolge des 5-Tier-Onion-Modells aus (Sub-Aggregate — die eigenen Anhänge einer Modulkomponente, dann die, die die Subsysteme ihres Moduls deklarieren, von außen nach innen → Komponente des Root-Aggregate → Subsystem des Root-Aggregate → Release-Boundary von außen nach innen → komponentenspezifisch im Release). Der Compiler führt die resultierenden Dictionaries nativ per Deep-Merge über die.context.inject-Speicherpipe des Aufrufers zusammen. Dadurch werden Umgebungsvariablen und Verbindungsstrings für den Aufrufer sicher umgeschrieben, bevor das Basis-Recipe sie überhaupt sieht. Ein Mapping darf umschreiben, was der eigeneinject:-Block des Aufrufers oder eine seiner Verbindungen geliefert hat; ein Schlüssel, den bereits ein anderes angehängtes Feature geliefert hat — über sein eigenes Mapping oder seinen eigeneninject:-Block —, hält den Build an und nennt beide Anhänge, sodass die Ausführungsreihenfolge nie zwischen den Werten zweier Anhänge entscheidet. - Locals-Präambel: Bevor ein
provides-Template ausgeführt wird, wertet der Compiler die.locals-Einträge des Recipe in der Reihenfolge aus, in der sie geschrieben sind, jeweils gegen einen in sich geschlossenen knotenlokalen Kontext —.context.instance_id,.values,.infraund die bis dahin aufgelösten Einträge desselben Blocks, nicht jedoch.context.injectoder.context.uses. Ein Eintrag kann daher einen darüber definierten Geschwistereintrag lesen und erhält dessen aufgelösten Wert; die Reihenfolge des Autors ist überall dort Teil des Vertrags, wo ein Eintrag einen anderen liest, und der Block wird nie umsortiert, damit eine Referenz aufgelöst werden kann. Dass Locals zuerst aufgelöst werden, ermöglicht es einemprovides-Template,.localszu lesen. Das.source-Template des Recipe wird gegen denselben Kontext ausgewertet, sobald diese Locals aufgelöst sind; dadurch bleibt.localsals Kurzschreibweise über die Templates eines Recipe hinweg wiederverwendbar, und Autoren können.source(Chart-Version, Pfad, Registry) pro Boundary parametrisieren. - Basis-Rendering (
valuesMappingdes Basis-Recipe): Der Compiler wertet dasvaluesMapping-Template des Basis-Recipe aus. Das Template liest die abgefangenen Strings aus der.context.inject-Pipe (während des Inject-Mappings umgeschrieben), und das resultierende Werte-Dictionary wird an den Provider übergeben, den diecapabilitydes Recipe benennt — die Provider helm und helm-chart rendern beide über Helm —, um die Basis-Infrastrukturartefakte zu rendern. - Workload-Parsing und -Validierung: Bei einem Recipe, das
workload:deklariert — Inline-Blockinhalt oderworkload: { $import: <path> }mit Verweis auf eine Datei —, wird dieses Dokument als Template gegen den Render-Kontext des Knotens ausgewertet, dann als YAML in die Workload-Form geparst und geprüft: Die gerenderten Bytes werden gegen das Workload-Schema validiert, der dekodierte Wert ebenfalls (die Bytes tragen Schlüssel, die die Dekodierung verwirft, und die Dekodierung lässt ein leer geliefertes Feld weg, sodass jede Prüfung zurückweist, was die andere nicht sehen kann), jederattachments-Eintrag wird gegen die Slots geprüft, die dasfeaturesSchemader gebundenen Component deklariert, und jede Ressourcenreferenz wird gegen die aufgelöstenprovidesdes Slots geprüft, den sie benennt. Ein Fehler an dieser Stelle hält den Build an. Die geparste Workload wird als.workloadin den Template-Kontext gelegt, sodass ein später auf demselben Knoten ausgewertetes Template sie lesen kann. - Auswertung der Artefakte: Jeder Eintrag, den ein Recipe unter
artifacts:deklariert — Inline-Inhalt oder eine durch den eigenen$import:des Eintrags benannte Datei —, wird gelesen, als Template geparst, gegen den vollständigen Template-Kontext ausgewertet und trägt die Provenienz des Builds. Die resultierende Projektion wird an den Provider übergeben, der über das Ausgabeformat, den Ort der Provenienz, den Ausgabepfad und die endgültigen Bytes entscheidet. Jede ausgegebene Datei hält fest, aus welcher verfassten Form sie stammt, sodass eine Kollision von Dateinamen jeden Beitragenden benennen kann. - Workload-Synthese: Die geparste Workload wird an den Provider übergeben, den die
capabilitydes Recipe benennt, und dieser übersetzt sie in seine nativen Ressourcen. Ein Recipe, das keinworkload:deklariert, hat hier nichts zu synthetisieren; seine Dateien stammen stattdessen aus dem Source-Rendering. - Feature-Rendering (Ressourcenerzeugung per FeatureRecipe): Jeder Anhang am Knoten, dessen gebundene FeatureRecipe eine eigene
source,workload,artifactsund/odervaluesMappingträgt — das Muster der Ressourcenerzeugung, verwendet für Hilfsmanifeste wie einen ServiceMonitor, eine NetworkPolicy, eine Sidecar-ConfigMap oder eine Ressource zur Bereitstellung von Anmeldedaten —, wird in einem Durchgang ausgewertet, in derselben Reihenfolge des 5-Tier-Onion-Modells, der das Inject-Mapping folgt. Es gibt eine Sequenz über eine Anhangsmenge: Ein operatives Feature und ein Anmeldedaten-Feature durchlaufen denselben Pfad, und was sie unterscheidet, ist das, was ihre FeatureRecipe ausgibt. Für jeden Anhang werden.valuesund.infraauf seinen eigenen Geltungsbereich umgeschaltet; er erbt die ausgewerteten.localsdes Basis-Recipe;.attachment_namebenennt die gerenderte Instanz, und.providesträgt die eigenen aufgelösten Provides des Anhangs, dieselbe Sammlung, die der Konsument liest. Das resultierende Werte-Dictionary wird an den Provider übergeben, den die eigene Capability der FeatureRecipe benennt, und die gerenderten Dateien werden an die Ausgabe der Boundary angehängt und tragen zwei Koordinaten — die Komponente, an die das Feature angehängt ist, dann den Namen, unter dem es angehängt ist —, sodass ein an mehrere Komponenten angehängter Feature-Name jede getrennt hält. Welche Form diese Koordinaten annehmen, ergibt sich aus dem Layout, das der Host-Provider selbst verwendet: ein Verzeichnis<component>--<instance>/neben dem eigenen der Komponente, wo das Ziel jedem Beitragenden eine eigene Position gibt, und ein Dateinamenpräfix<component>--<instance>--, wo es nur die Dateien liest, die direkt in einem Verzeichnis liegen. Reine Inject-FeatureRecipes — solche, die nurinjectMappingtragen und bereits während des Inject-Mappings behandelt wurden — werden hier übersprungen. Wie die Teilphasen davor läuft das Feature-Rendering jeweils für eine Komponente, sodass ein Anhang normalerweise direkt nach der Komponente ausgewertet wird, an die er angehängt ist. Ein Anhang, dessen FeatureRecipereadsCallerRenderFacts: trueoderreadsTargetRenderFacts: truedeklariert, wird stattdessen erst ausgewertet, wenn jede Komponente und jeder Anhang, der keines von beiden deklariert, gerendert hat — sodass bis dahin jede Komponente, die sich mit seinem Host verbindet, und jede, mit der sein Host verdrahtet ist, gerendert hat —, und seine Ausgabe landet dort, wo sie sonst gelandet wäre. - Die Plugin-Pipeline (Ausführung der Wasm-Schritte): Der Compiler liest das
pipeline-Array des Recipe und führt seine Schritte in der deklarierten Reihenfolge aus. Er ruft das benannte Wasm-Plugin jedes Schritts für die gerenderten Dokumente des Knotens auf, wendet die vom Schritt zurückgegebenen JSON-Patch-Operationen nach RFC 6902 auf die Dokumente an, die diese Operationen adressieren, und gibt die Seiteneffekte des Schritts neben ihnen aus — die Oberfläche hinter chirurgischen Mutationen wie dem Injizieren eines Envoy-Sidecars oder dem Einhängen eines Secret-VolumeMount. Ein Schritt, dessenwhen:-Gate falsy rendert, wird als Durchreichung übersprungen und lässt die Dokumentmenge für den nächsten Schritt unverändert. Dieplugin-URI jedes Schritts wird vor der Ausführung zu den verifizierten Artefakt-Bytes aufgelöst, die die Lockfile per Digest festschreibt. Diepipeline-Schritte einer FeatureRecipe werden auf dieselbe Weise ausgeführt, über die eigenen gerenderten Dokumente des Anhangs und, bei einem Anhang im Komponenten-Scope, zusätzlich über die der Host-Komponente.
- Inject-Mapping (Pre-Render-Interception): Der Go-Compiler löst den abstrakten
Alle drei Recipe-Eingabearten erreichen den Compiler: source: + valuesMapping: über das Basis-Rendering, workload: über das Workload-Parsing und die Workload-Synthese und artifacts: über die Auswertung der Artefakte. Welche davon ein bestimmter Provider erhalten darf, wird nicht Teilstufe für Teilstufe entschieden — es wird einmal pro Knoten vor jedem Render-Dispatch anhand des vom Provider selbst deklarierten Vertrags festgelegt, sodass ein Recipe, dessen Eingabeart der gebundene Provider nicht akzeptiert, dort abgewiesen wird statt mitten im Rendering. Siehe 16-recipe-input-composition.md für das Kompositionsmodell der drei Eingabearten, die Workload-Art und den Artifacts-Mechanismus sowie Status der Sprache dafür, welcher Provider welche Art akzeptiert.
GitOps-native Ausgabe
Um strikt meinungslos darüber zu bleiben, wie ihre Ausgabe angewendet wird, geben die Rendering-Plugins die generierten Artefakte in eine saubere, nach Boundaries isolierte Verzeichnisstruktur aus (z. B. dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/). So können externe GitOps-Controller (wie ArgoCD oder Flux) die Infrastruktur synchronisieren und anwenden, ohne dass der Aggrega-Compiler jemals Anmeldedaten für die API eines laufenden Clusters benötigt.
graph TD
subgraph CLI_Orchestrator ["The Aggrega Compiler Pipeline"]
direction TB
A["Resolution — The Resolver & Syntax Validator<br/>(Inheritance Merge + Parameter Interpolation + JSON Schema 2020-12 Validation)"] --> B["Topology construction — The Topology Builder<br/>(AST Expansion + governance label-transform)"]
B -->|"Emits IR Graph"| C["Graph finalization<br/>(Normalization)"]
C -->|"Flat IR Graph"| D["Static analysis — The Static Analyzer<br/>(Selectors + governance ir-verdict Gate)"]
D -->|"Validated Topology"| E["Rendering<br/>Inject mapping: Pre-Render Interception (injectMapping)<br/>Base rendering (valuesMapping)<br/>The plugin pipeline: Wasm Mutation (pipeline)"]
end
graph LR
E["Rendering"]
E -->|"Stringified Artifacts"| F["Helm Charts"]
E -->|"Stringified Artifacts"| G["Docker Compose"]
E -->|"Stringified Artifacts"| H["Kubernetes Manifests"]
E -->|"Stringified Artifacts"| I["Terraform Configuration"]
E -->|"Stringified Artifacts"| J["CloudFormation Templates"]
Infrastruktur-Source-Map
Aggrega kompiliert eine ~30 Zeilen lange Aggregate.yaml in Tausende Zeilen physischer JSON- oder YAML-Konfiguration. Ohne eine Möglichkeit, eine laufende Ressource zu ihrer Quelle zurückzuverfolgen, zwingt das Debuggen eines Fehlers bei „main.tf.json Zeile 4.032“ Entwickler dazu, die Zuordnung manuell zu rekonstruieren. Die Rendering-Plugins von Aggrega begegnen dem, indem sie Trace-Kennungen in die native Metadatenoberfläche des Providers mergen — metadata.labels und metadata.annotations für Kubernetes, ein Provenienzkommentar für Terraform und entsprechende Konventionen je Provider —, sodass jedes gerenderte Objekt einen Verweis auf die Quelle trägt, aus der es stammt. Das Label aggrega.ai/compiler-version (dokumentiert in Governance und Compliance §5) ist ein Trace-Schlüssel dieser Familie; daneben trägt der Stempel aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri und aggrega.ai/environment, und die Provider helm, helm-chart, compose, terraform und cloudformation geben ihn jeweils aus — der Provider helm-chart auf den Template-Dateien, die ein Recipe einem Chart hinzufügt, da er die eigenen Templates des Charts unverändert kopiert.
Der Stempel trägt keinen Schlüssel, der die Herkunft des Features oder den Katalogtyp identifiziert.
Mit dem Compiler werden zwei weitere Debug-Oberflächen ausgeliefert. aggrega build --trace schreibt den Zwischenzustand jedes Knotens, Durchlauf für Durchlauf, nach .trace/ neben dist/, für einen Recipe-Autor, der prüft, was jede Stufe empfangen und erzeugt hat; und eine abbrechende Diagnose trägt die Kategorie der Authoring-Oberfläche, zu der sie gehört — DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR und die übrigen —, wo immer der Fehler eine hat, sodass sie auf den richtigen Autor verweist. Fehler, die ein fehlerhaftes Feld eines generierten Manifests auf die Template-Zeile zurückführen, die es erzeugt hat, sind nicht Teil des Compilers.
Die Validator-Pipeline
Die Schemavalidierungsphase der Auflösung beruht auf einer Validator-Pipeline, die Inhalte von Entitätsspezifikationen (kompakte Form, JSON-Schema-YAML oder gemischt) in ein einheitliches JSON-Schema-2020-12-Dokument mit Provenienz pro Blatt umwandelt und anschließend von Entwicklern verfasste Instanzinhalte dagegen validiert. Fünf Stufen laufen der Reihe nach als reine Transformationen; jede ist eine deterministische Funktion ihrer deklarierten Eingaben.
Stufe 1 — Kompilierung der kompakten Form. Der Compiler durchläuft den YAML-Baum von schema:, parameters: und SchemaLibrary-Inhalten; verzweigt pro Knoten (Blatt in kompakter Form vs. JSON-Schema-YAML vs. $ref:-Referenz vs. Komposition); gibt aufgelöstes JSON Schema 2020-12 aus. Kompakte Form und JSON-Schema-YAML können an jeder Knotengrenze über das Escape $jsonschema: gemischt werden; den gemischten Fall behandelt der Compiler, indem er den Baum durchläuft und pro Knoten verzweigt. Die Transformation ist eine reine Funktion: Dieselbe Eingabe in kompakter Form erzeugt immer dieselbe JSON-Schema-Ausgabe. Das Schlüsselwortvokabular finden Sie unter language-reference/vocabulary/compact-form-authoring.md.
Stufe 2 — Auflösung von spec.templates und $instantiate:. Für SchemaLibrary-Einträge, die als Template-Referenzen verfasst sind, durchläuft der Compiler jeden Bibliothekseintrag, der $instantiate: mit $args: aufruft, setzt die Parameterwerte als literale Skalarersetzung ein und erzeugt konkrete Schemaeinträge. Die Ersetzung läuft einmal pro Laden der Bibliothek; aufgelöste Einträge werden zwischengespeichert. Die Authoring-Form der Bibliotheksentität finden Sie unter language-reference/entities/schemalibrary.md.
Stufe 3 — Dokumentübergreifende $ref:-Expansion. Für SchemaLibrary-Referenzen über $ref: (die Identitätsform <Library>#/schemas/<entry>) durchläuft der Compiler die Referenzkette zur Kompilierzeit, indem er einen Auflösungsstapel mitführt; der referenzierte Inhalt wird in das Schema des Konsumenten eingebettet. Die Expansion bewahrt die Zykluserkennung (Zyklen halten den Build mit einem Fehler an, der die Kette benennt), die Schutzregel „Identität statt Ort“ (eine Referenz mit einem Registry-Host hält den Build an und verweist auf die Identitätsform — Referenzen adressieren Bibliotheken über ihre Identität, nicht über ihren physischen Ort) und die Komposition aus einer einzigen Quelle ($ref:-Blöcke akzeptieren nur die bloße Referenz; konsumentenseitige Überschreibungen werden über allOf: von JSON Schema komponiert). Die Auflösungssemantik finden Sie unter language-reference/vocabulary/cross-document-ref.md.
Stufe 4 — Brückensynthese für featuresSchema:. Der Compiler durchläuft den featuresSchema:-Inhalt jeder Entität in der Reihenfolge des Autors und gibt ein JSON-Schema-Fragment aus, das die Form einer Belegung beschreibt, die jeden Attachment-Slot binden darf, mit einem Erweiterungsschlüsselwort x-aggrega-inject: an einem Slot, der eine inject-Allowlist deklariert. Dieses Fragment wird für sich kompiliert und gegen den verfassten Attachment-Block geprüft, statt in den entwicklerseitigen schema:-Inhalt eingefaltet zu werden; das Erweiterungsschlüsselwort ist Metadaten, die die JSON-Schema-Validierung ignoriert, und keine spätere Stufe liest es aus dem Fragment zurück — eine Prüfung, die die Allowlist eines Slots benötigt, liest den Slot. Die Socket-Tabelle usesSchema: wird in überhaupt kein Fragment projiziert: selector: und inject: eines Sockets werden als das typisierte YAML gelesen, das der Architekt geschrieben hat, und das kantenbezogene valueSchema: / infraSchema: eines Sockets wird für sich kompiliert. Die Synthese ist eine reine Funktion ihrer Eingaben.
Stufe 5 — Eigener Merger mit Provenienz. Für Entitäten, die extends: deklarieren, durchläuft der Compiler die Elternkette; das aufgelöste JSON Schema des Elternteils wird zur Basis; die Überschreibungen des Kindes werden darüber angewendet. Jedes Blatt im aufgelösten Schema trägt ein Provenienz-Tag pro Blatt (Dateipfad, Zeilennummer, Herkunft aus Eltern oder Kind). Die Ausgabe des Mergers ist das, was die Validator-Engine verarbeitet; die Validator-Engine ist eine unveränderte, JSON-Schema-2020-12-konforme Drittanbieterimplementierung mit einem deterministischen Walker darum für die geordnete Ausgabe der Befunde.
Die fünf Stufen laufen, bevor die Validator-Engine das Schema sieht. Die Engine erhält ein einziges aufgelöstes JSON-Schema-2020-12-Dokument sowie die Instanzinhalte des Entwicklers; sie erzeugt einen Validierungsbericht. Der Fehlerformatierer zieht die Provenienz-Tags heran, um benutzerseitige Diagnosen auszugeben, die Quellpositionen klar benennen — einschließlich der Ursprungsdatei für eine Einschränkung, die ein Feature von seiner Basis geerbt statt selbst verfasst hat.
Die Validator-Pipeline läuft dort, wo jeder Payload erstmals vollständig ist — values und infra einer Komponente während der Auflösung, die Komponenten eines Sub-Aggregats, sobald die Topologiekonstruktion sie hereinholt, und der Payload eines Anhangs bei der Graphfinalisierung —, sodass ein Schemabefund den Build abbricht, bevor die statische Analyse irgendeinen Selektor auswertet, und vor der Auswertung der Assertions, wodurch sich die Assertion-Templates auf validierte Payloads verlassen können.
Wahrung des Determinismus über die gesamte Pipeline
Jede Stufe der Kompilierungspipeline wahrt die Invariante der deterministischen Ausgabe: Bei denselben Quelldateien, derselben Lockfile und derselben Compiler-Version erzeugt der Build eine byteidentische Ausgabe. Die Invariante ist grundlegend — Content-Addressing in der Lockfile erfordert stabile Artefakt-Digests; reproduzierbare Builds erfordern, dass ein auf dem Laptop von Entwickler A verfasstes Release auf dem Laptop von Entwickler B und in der CI zur selben Ausgabe kompiliert; die Prüfbarkeit von Diffs erfordert, dass Quelländerungen als einzige Änderungen in der kompilierten Ausgabe erscheinen.
Der Determinismus wird durch eine kleine Zahl von Disziplinen gewahrt, die jede Transformation einhält:
- Feste Iterationsreihenfolge. Jeder Durchlauf über map-förmiges YAML iteriert in einer festen Reihenfolge, weil die native Map-Iteration von Go randomisiert ist. In den meisten Stufen sortiert der Compiler vor dem Iterieren (Compiler der kompakten Form, Merger,
spec.templates-Resolver, Fehlerformatierer, YAML-Serialisierer); die Projektion der Attachment-Slots übernimmt dagegen die Reihenfolge des Autors, sodass die Eigenschaftsreihenfolge einer Slot-Tabelle die Reihenfolge ist, in der sie geschrieben wurde. - Keine eingebetteten Zeitangaben. Die Kompilierung bettet keine Zeitstempel in die Ausgabe ein. Ein Build um 14:00 Uhr erzeugt dasselbe Artefakt wie ein Build um 2:00 Uhr. Die Provenienzmetadaten des Mergers verwenden Datei:Zeile, nicht Datei:Zeitstempel.
- Workspace-relative Pfade. Alle Pfade in der aufgelösten Ausgabe sind relativ zum Workspace; die Pfadauflösungsschicht normalisiert Pfade, bevor sie in eine Ausgabe gelangen.
- Keine Zufallsquellen, kein externer Zustand. Transformationen sind reine Funktionen ihrer deklarierten Eingaben (Entitätsinhalt, Elternkette, Lockfile). Externer Zustand wird nur während der Auflösung herangezogen (Abruf von OCI-Artefakten), und aufgelöste Inhalte werden über ihren Digest inhaltsadressiert.
- Kanonische YAML-Serialisierung. Die Ausgabe wird für eine Eingabe in einer einzigen festen Form geschrieben: dieselbe Schlüsselreihenfolge auf jeder Ebene bei jedem Lauf, wobei Arrays und
enum:-Arrays die Eingabereihenfolge behalten; Einrückung mit 2 Leerzeichen; Unix-LF-Zeilenenden; Strings ohne Anführungszeichen, wo YAML es erlaubt; boolesche Formtrue/false; null wird für fehlende Felder weggelassen. - Alphabetische Reihenfolge von
$defs:. Die$defs:-Einträge eines Schemas werden im aufgelösten JSON Schema in alphabetischer Schlüsselreihenfolge ausgegeben.$defs:ist konzeptionell ein Wörterbuch, keine geordnete Liste; die alphabetische Reihenfolge macht Diffs über Umstrukturierungen der Quelle hinweg vorhersagbar. - Parallelität dringt nicht bis zur Ausgabe durch. Der Compiler kann unabhängige Einheiten parallelisieren (verschiedene Entitäten können nebenläufig kompiliert werden). Parallele Ergebnisse werden vor der Serialisierung in einer deterministischen Struktur gesammelt (z. B. nach Entitätsname sortiert).
Die End-to-End-Tests des Compilers kompilieren jedes Fixture innerhalb eines Tests mehrmals und prüfen, dass jeder Lauf dieselben Dateien mit byteidentischem Inhalt ausgibt. Erst die wiederholte Kompilierung deckt ein Durchsickern der Map-Iterationsreihenfolge oder eine Iteration über eine unsortierte Menge auf, die in den meisten Läufen eine stabile Ausgabe liefert und gelegentlich abweicht. Die Tests laufen mit der übrigen Testsuite des Compilers.
Die Invariante der deterministischen Ausgabe gilt zur Build-Zeit: dieselben Quelldateien + dieselbe Lockfile + dieselbe Compiler-Version ergeben byteidentische Ausgabe. Die begleitende Eigenschaft zur Lock-Zeit (dieselben Quelldateien + derselbe Registry-Zustand ergeben dieselbe Lockfile) ist schwächer — Registries sind veränderlich (neue Versionen können veröffentlicht, Sidecars hinzugefügt werden, komponentenbezogene Metadaten können sich weiterentwickeln), sodass zwei Lock-Aufrufe für dieselben Quelldateien zu unterschiedlichen Zeitpunkten unterschiedliche Lockfiles erzeugen können. Genau das ist der Zweck der Lockfile, entsprechend den Konventionen in npm, Cargo und Go. Aus einer frischen Lockfile erzeugt der Build deterministische Ausgabe. Die Trennung der zwei Zeitpunkte macht die registryseitige Veränderlichkeit tragbar: Ein zum Zeitpunkt T2 veröffentlichter Sidecar ändert den nächsten Lock-Aufruf; er ändert keine Builds gegen die zum Zeitpunkt T1 erzeugte Lockfile.