Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Wasm-Plugin-Vertrag

Die Kompilierungs-Pipeline von Aggrega enthält festgelegte Socket-Punkte, an denen WebAssembly-Plugins (Wasm) das Verhalten des Compilers erweitern: die vier Rollen des Governance-Sockets, darunter ein Mutation Gate bei der Topologiekonstruktion und ein Validation Gate bei der statischen Analyse; eine Post-Render-Plugin-Pipeline für Schritte von FeatureRecipe und Recipe; ein Provider-Rendering-Socket; ein Parser-Socket; ein Importer-Socket; und ein Out-of-Band-Linting-Socket. Diese Seite dokumentiert den öffentlichen Wasm-Plugin-Vertrag: welche Sockets es gibt, was jeder Socket konsumiert und erzeugt, wo jeder Socket in der Kompilierungs-Pipeline sitzt, und die Sandbox, in der jedes Plugin ausgeführt wird.

Diese Seite behandelt die Sockets — die Punkte der Pipeline und ihre Ein-/Ausgabeformen. Für das Plugin — die Entität Plugin, die Fähigkeitsansprüche pro Export, die Laufzeitgrenzen und den Lebenszyklus publish→pull→build — siehe den Entwicklerleitfaden für Wasm-Plugins.

Aggrega bettet eine Wasm-Host-Laufzeit ein — Extism auf Basis der Wazero-Engine —, die Plugins hinter einer AOT-Reinheits-Firewall lädt und ausführt: Der Host gewährt einem Guest keinerlei Ambient-Fähigkeit — kein Netzwerk, kein Dateisystem, keine Umgebung, verworfenes stdio, eine beobachtbare Wanduhrzeit, eingefroren auf einen Build-invarianten Zeitpunkt —, sodass ein Plugin die Ahead-of-Time-Garantien des Compilers nicht brechen kann. Die vollständige Fähigkeitsoberfläche — die Importmodulregel beim Laden, die Verweigerungen zur Instanziierungszeit und die kuratierten Host-Funktionen — ist der Sandbox-Vertrag weiter unten. Plugin-Autoren adressieren den Host über das PDK in drei Sprachen (Go, Rust, TypeScript). aggrega lint ruft über den Host den Linter-Socket auf — den standardmäßigen Veröffentlichungs-Linter. aggrega build ruft die Build-Zeit-Rollen des Governance-Sockets auf, wenn ein Workspace sie konfiguriert: die Rolle annotation-transform während der Auflösung und die Rolle label-transform bei der Topologiekonstruktion (beide formen die Ausgabe), dazu das IR-Verdikt bei der statischen Analyse und das Render-Verdikt über die gerenderten Artefakte. Jede ist ein No-op, wenn an dieser Rolle kein Plugin angebunden ist, sodass ein Build ohne Governance-Konfiguration unverändert bleibt. aggrega build ruft außerdem die pipeline: von FeatureRecipe und Recipe in der Plugin-Pipeline auf, die das Rendering abschließt — jeder deklarierte Schritt läuft über den Host gegen die Menge der gerenderten Dokumente, wendet die RFC-6902-Patches des Schritts an und erzeugt seine Nebeneffekte. Siehe Status der Sprache → Phasen der Kompilierungs-Pipeline.

Der Sandbox-Vertrag

Jeder Socket ruft sein Plugin über dieselbe Host-Sandbox auf. Die Sandbox hat zwei unabhängige Schichten — eine strukturelle Prüfung beim Laden und die Verweigerung von Fähigkeiten bei der Instanziierung —, und zusammen legen sie fest, was ein Plugin erreichen kann, was nicht und wofür es verantwortlich ist.

Die Importmodulregel (Ladezeit). Der Loader durchläuft den Importabschnitt der Plugin-Binärdatei und lässt Funktionsimporte nur unter drei Modul-Namespaces zu: wasi_snapshot_preview1 (die WASI-Preview-1-Laufzeit, gegen die die Laufzeit einer Guest-Sprache gelinkt wird), extism:host/env (die ABI der Extism-Laufzeit — die eigenen Speicher- und IO-Intrinsics des PDK) und extism:host/user (die kuratierten Host-Funktionen von Aggrega). Ein Guest darf unter einem zugelassenen Modul jeden Funktionsnamen importieren; ein Import unter einem anderen Modul benennt eine Oberfläche, die der Host nicht bereitstellt, und das Plugin wird beim Laden mit einer Diagnose abgelehnt, die das Modul und den Import nennt. Die Regel zensiert bewusst keine einzelnen WASI-Funktionsnamen: Eine statisch gelinkte Sprachlaufzeit importiert Dateisystem- und Socket-Funktionen, die ihre aktiven Codepfade nie aufrufen — transitiv über Abhängigkeiten hereingezogen —, und das Benennen eines Imports gewährt nichts. Die Verweigerung von Fähigkeiten bei der Instanziierung, nicht die Zensur von Importen, garantiert, dass kein I/O stattfindet.

Keinerlei Ambient-Fähigkeit (Instanziierung). Der Host instanziiert den Guest mit echtem WASI-Verhalten und keinerlei Ambient-Berechtigung:

  • kein Dateisystem — keine vorab geöffneten Verzeichnisse, sodass ein Dateisystemaufruf an der Aufrufgrenze fehlschlägt;
  • keine Netzwerk-Sockets;
  • eine leere Umgebung;
  • verworfenes stdio — nichts, was der Guest nach stdout oder stderr schreibt, erreicht die Streams des Hosts;
  • eine eingefrorene beobachtbare Wanduhr, festgelegt auf einen Build-invarianten Zeitpunkt, sodass ein Guest, der die Uhrzeit liest, die Build-Zeit nicht in seine Ausgabe durchsickern lassen kann;
  • eine echte, fortschreitende monotone Uhr — die Laufzeit einer Guest-Sprache braucht eine zum Starten, und monotone Zeit misst eine verstrichene Dauer, keinen Wanduhr-Zeitpunkt;
  • echte Entropie des Hosts — fixierte Entropie würde den internen Hash-Seed einer Sprachlaufzeit stabilisieren und Nichtdeterminismus des Guests verdecken, statt ihn als abweichende Ausgabe sichtbar werden zu lassen;
  • ein einzelner synthetischer Programmname als argv.

Ein I/O-Aufruf, den ein Guest tatsächlich ausführt — eine Datei öffnen, eine Verbindung zu einem Socket aufbauen —, schlägt an der Aufrufgrenze fehl. Das ist das eigene fähigkeitsbasierte Sicherheitsmodell von WASI: Die Sandbox verweigert die Fähigkeit, statt den Code zu überwachen.

Eingaben kommen nur über die Payload und die kuratierten Host-Funktionen an. Ein Plugin erhält alles, was es rendert oder auswertet, in der Payload, die sein Socket transportiert — Projektionen des Graphen und der Knoten, Werte und Render-Kontext. In welcher Kodierung eine Payload ankommt, ist pro Socket festgelegt und im eigenen Abschnitt dieses Sockets weiter unten genannt; jeder veröffentlichte Payload-Typ liefert einen Kodier- und einen Dekodier-Einstiegspunkt für die Kodierung seines Sockets, sodass ein Guest eine Funktion aufruft, statt einen Parser zu wählen. Bei einem Provider-Rendering mit Quelle transportiert die Payload eine Quellauflistung statt der Quellbytes: eine sortierte Menge von Einträgen {path, is_dir} unter der Quellwurzel des Knotens, ohne jede Interpretation des Provider-Layouts durch den Host. Der Guest wendet seine eigene Layout-Logik an — die einzige Compose-Datei auswählen, zu einer Chart-Wurzel hinabsteigen, eine Chart.yaml verlangen, ein Modul rekursiv vendoren — und liest genau den Ausschnitt, den er auswählt, über einen Host-Callback zurück. Über die Payload hinaus stellt der Host eine kuratierte Menge von Host-Funktionen nach dem Prinzip der geringsten Rechte bereit und gewährt einem Plugin genau diejenigen, die seine Binärdatei importiert:

  • aggrega_log — eine Logzeile am Log-Ziel des Hosts.
  • aggrega_emit_warning — eine strukturierte Warnung, die der Host nach dem Aufruf ausgibt.
  • aggrega_fetch_external_input — der Abrufkanal für externe Eingaben (siehe unten).
  • aggrega_pack_source — der Callback zur Quellauswahl: Der Guest benennt eine Auswahl {file | dir | tree, path} unter der Quellwurzel, und der Host liest und packt genau diese unter einer Sandbox, die Pfade unter der Wurzel auflöst und .. ablehnt.
  • aggrega_read_source_file — ein Lesen des Inhalts einer einzelnen Datei unter derselben Sandbox, für eine inhaltsabhängige Quellauswahl.
  • aggrega_parse_source — der Callback für den Konsum von Erzeugern: Der Guest benennt ein syntaktisches Format und übergibt die Quellbytes, und der Host ermittelt einen Parser für dieses Format, führt ihn aus und gibt den kanonischen Baum zurück, den dieser erzeugt hat. Auf diesem Weg erhält ein Konsument die Ausgabe eines Erzeugers über den Host, statt selbst einen Erzeuger-Guest aufzurufen, und der Host beschränkt ihn auf eine einzige Ebene — ein auf diesem Weg erreichter Erzeuger, der ihn erneut aufruft, wird abgewiesen —, sodass ein Konsument ihn einmal pro Quelle aufruft und viele Quellen nacheinander konsumieren kann.

Der Host leitet die Menge, die ein Plugin importiert, aus dessen Binärdatei .wasm ab, validiert sie gegen die kuratierte Allowlist und gleicht sie mit den Host-Funktionen ab, die describe() des Guests deklariert. aggrega plugin sync hält die Menge in spec.runtime.hostFunctions der Entität fest, und eine Veröffentlichung weist eine Entität zurück, deren Eintrag von der Binärdatei abweicht, sodass die Host-Oberfläche jedes Plugins im Katalog sichtbar ist und nicht von der Binärdatei abweichen kann.

Callback-Fehlschläge tragen einen maschinell abgleichbaren Code unter hostfunc_error_code. Die Host-Callbacks, die eine Antwort zurückgeben — aggrega_fetch_external_input, aggrega_pack_source, aggrega_read_source_file und der Callback für den Konsum von Erzeugern aggrega_parse_source —, melden einen Fehlschlag in-band: Der Antwort-Umschlag trägt eine für Menschen lesbare Meldung und daneben einen optionalen, maschinell abgleichbaren Code unter hostfunc_error_code, der aus einem geschlossenen Vokabular stammt. Die Meldung ist frei formulierte Prosa für einen Menschen; der Code ist die stabile Identität, nach der ein Guest verzweigt, ohne die Meldung zu parsen. Bei Erfolg fehlt der Code; bei einem Fehlschlag setzt der Host beides. Das PDK stellt das Paar als typisierten Fehler bereit, dessen Text die Meldung ist und dessen Code-Feld ein Guest mit den von der Sprache re-exportierten Code-Konstanten abgleicht. Ein Guest toleriert einen fehlenden Code und einen Code, den er nicht kennt, indem er auf die Meldung zurückgreift — der Abgleich über einen Code ist also eine Best-Effort-Verfeinerung über der stets vorhandenen Meldung, niemals ein Ersatz für sie. Die geschlossene Wertemenge ist das Schema der Fehlercodes für Host-Funktionen.

🔴 Zwei verschiedene Vokabulare benennen einen Fehlschlag an dieser Grenze, und der Schlüssel, den Sie lesen, sagt Ihnen, welches Sie vor sich haben. Sie zu verwechseln ist der eine Fehler, auf den es sich hier hinzuweisen lohnt, denn ein Wert aus beiden ist ein einfacher String, und weder der Host noch der Guest prüft, aus welcher Menge er stammt.

  • hostfunc_error_code, in einer Antwort, die der Host an einen Guest sendet. Sein Wert ist ein Element des oben verlinkten geschlossenen Katalogs — einer festen, sich langsam ändernden Liste der Arten, auf die ein Host-Callback fehlschlagen kann. Weil die Menge geschlossen ist, kann ein Guest einen Wert mit einer benannten Konstante abgleichen, die sein Kit re-exportiert, und anhand des Ergebnisses verzweigen.
  • condition_code neben condition_short_code, in einer Socket-Ausgabe, die ein Guest an den Host zurückgibt. Das sind die beiden Bezeichner einer abbrechenden Bedingung, die der Guest selbst ausgelöst hat, und sie stammen aus der offenen, wachsenden Menge von Bedingungen, die der Compiler registriert, nicht aus dem Katalog. condition_code ist der beschreibende Code, unter dem die Bedingung registriert ist; condition_short_code ist die kompakte Form — der Buchstabe E und vier Ziffern —, die ein Leser zitiert, sucht und in einen Bericht einfügt. Der Host gibt den Kurzcode im eckig geklammerten Kopf der Diagnose aus, die er rendert, sodass eine von einem Guest ausgelöste Bedingung genauso zitierbar ist wie eine vom Compiler ausgelöste. Er leitet keinen der beiden Werte ab, prüft sie aber: Ein Kurzcode, der zu keiner von diesem Compiler deklarierten Bedingung auflöst oder zu einer, deren Nummer stillgelegt wurde, bricht den Build ab, statt einen Leser als Bezeichner zu erreichen, der zu nichts auflöst.

Die beiden Bezeichner auf der Guest-Seite werden gemeinsam gemeldet: Ein Guest, der den einen setzt und den anderen nicht, hat eine Bedingung benannt, die der Host nicht auflösen kann, und der Host meldet dann stattdessen seine eigene generische Bedingung für einen Plugin-Fehlschlag, wobei die Meldung weiterhin den gesamten Fehlschlag trägt. Und ein condition_code ist nie ein Element des Katalogs der Host-Funktionen, sodass der Vergleich mit einer re-exportierten Konstante nie übereinstimmt — weshalb jeder Schlüssel sein eigenes Vokabular benennt statt Fehlschläge im Allgemeinen.

Die Slots jedes Callbacks tragen eine festgelegte Kodierung, und jeder Slot, der ein Payload-Dokument enthält, enthält es binär. Jedes Argument, das ein Host-Callback entgegennimmt, ist ein Zeiger in den Speicher des Guests, abgesehen von der numerischen Stufe von aggrega_log; ein Callback, der eine Antwort zurückgibt, antwortet ebenfalls mit einem Zeiger. Was jeder dieser Slots enthält, ist pro Callback festgelegt:

CallbackArgument-SlotsAntwort-Slot
aggrega_log, aggrega_emit_warningUTF-8-Text — kein Payload-Dokumentkeine Antwort
aggrega_fetch_external_inputeine bloße UTF-8-URL — kein Payload-Dokumentkanonisches CBOR
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_sourcekanonisches CBOR (RFC 8949 §4.2.1)kanonisches CBOR

Die Tabelle unterscheidet danach, was jeder Slot enthält, nicht nach der Identität des Callbacks: Ein Slot mit einem Payload-Dokument trägt kanonisches CBOR, und ein Slot mit einem bloßen String — einer Logzeile, einem Diagnosefeld, einer URL — trägt UTF-8-Text. aggrega_fetch_external_input ist der eine, dessen zwei Slots sich unterscheiden: Sein Argument ist eine bloße URL, gelesen als UTF-8-Text, und seine Antwort ist ein Payload-Dokument in kanonischem CBOR.

Was ein Guest an einem Slot mit Payload tut und was er nicht tun darf. 🔴 Ein Slot, der ein Payload-Dokument enthält, enthält eine opake Bytefolge, keinen UTF-8-Text — das ist also die Form, die ein Guest deklariert, nicht nur die Bytes, die er dort ablegt. Ein Guest, der eine solche Anfrage als String allokiert oder eine solche Antwort als String liest, ist nicht interoperabel: Eine Textkonvertierung in beide Richtungen beschädigt binäre Bytes. Der Fehlschlag ist laut statt partiell — eine Anfrage, die der Host nicht dekodieren kann, kommt als Antwort-Umschlag mit dem Code request_undecodable zurück, in derselben In-Band-Form wie jeder andere Callback-Fehlschlag, sodass der Guest ihn meldet, statt mit einer halb gelesenen Payload weiterzumachen. Die Payload-Typen sind SourcePackRequest und SourcePackResponse für aggrega_pack_source, SourceFileRequest und SourceFileResponse für aggrega_read_source_file, ParseInput und ParseSourceResponse für aggrega_parse_source und allein der Antworttyp FetchExternalInputResponse für aggrega_fetch_external_input, dessen URL als Text allokiert wird. Konkret, pro Kit:

  • Go — erstellen Sie die Anfrage mit EncodeCBOR() des Anfragetyps, allokieren Sie sie mit pdk.AllocateBytes (nicht pdk.AllocateString) und lesen Sie die Antwort mit ReadBytes() aus dem Speicher, auf den der Antwortzeiger auflöst, in DecodeCBOR des Antworttyps. Die Abruf-URL ist auf der Anfrageseite die Ausnahme und wird mit pdk.AllocateString allokiert; ihre Antwort wird wie jede andere gelesen. Die Deklaration //go:wasmimport ist in beiden Fällen ein Zeiger, sodass nichts in der Signatur die Form zeigt — sie steckt in der Allokation und im Lesen.
  • Rust — die Deklaration #[host_fn] gibt die Form direkt an: Jeder der drei Payload-Callbacks lautet fn <callback>(request: Vec<u8>) -> Vec<u8>;, und der Abruf-Callback lautet fn aggrega_fetch_external_input(url: String) -> Vec<u8>;. Erstellen Sie die Anfrage mit encode_cbor() des Anfragetyps und lesen Sie die Antwort mit decode_cbor(&raw) des Antworttyps.
  • TypeScript — erstellen Sie die Anfrage mit der Funktion encodeCBOR… des Anfragetyps, allokieren Sie sie mit Memory.fromBuffer (nicht Memory.fromString) und lesen Sie die Antwort mit readBytes() in die Funktion decodeCBOR… des Antworttyps. Die Abruf-URL wird mit Memory.fromString allokiert; ihre Antwort wird wie die anderen mit readBytes() gelesen. Wie in Go ist der Eintrag declare module in beiden Fällen ein Zeiger.

Ein Guest, der einen PDK-Wrapper aufruft, braucht nichts davon. Die Wrapper — FetchExternalInput, PackSource, ReadSourceFile und ParseSource, in der jeweiligen Schreibweise jeder Sprache — übernehmen die Allokation und die Kodierung, und keine ihrer Signaturen nennt einen Übertragungstyp, sodass ein Guest, der diese Callbacks über sein Kit erreicht, selbst nichts allokiert und nichts dekodiert; ein Guest, der die Host-Funktionen selbst deklariert und aufruft, allokiert und liest seinen Speicher wie oben beschrieben. Eine als Text allokierte Anfrage wird abgelehnt statt halb bedient, und eine als Text gelesene Antwort lässt sich nicht dekodieren, sodass eine Unstimmigkeit zwischen beiden Seiten laut statt still ist.

Zwei Eigenschaften, auf die man sich verlassen kann. Die Antwort hat dieselbe Kodierung, ob sie erfolgreich ist oder fehlschlägt: Ein Guest liest einen Slot und kann vor dem Dekodieren nicht wissen, welches von beiden er enthält, sodass ein Dekodier-Einstiegspunkt beides liest und der oben beschriebene Fehlercode und die Meldung über ihn ankommen. Und ein Guest befüllt ein bytewertiges Feld im eigenen Feldtyp seines Kits — einem Byte-Slice in Go, einem Base64-String in Rust und TypeScript —, denn die Umwandlung in die rohe Bytefolge, die die binäre Kodierung transportiert, ist Aufgabe des generierten Encoders, auf dem Weg hinaus erledigt und auf dem Weg herein umgekehrt. Das betrifft die Quellbytes von ParseInput, den Dateiinhalt, den aggrega_read_source_file zurückgibt, den Inhalt, den aggrega_fetch_external_input abgerufen hat, und den Inhalt jeder gepackten Datei in einer Pack-Source-Antwort: Diese Bytes überqueren die Grenze einmal, statt doppelt kodiert zu werden, und kein Guest kodiert etwas in Base64, das der Encoder gleich wieder aus Base64 dekodiert. Das Feld content der Read-Source-File- und Fetch-Antworten wird weggelassen, wenn es leer ist, sodass die Antwort für eine leere Datei oder eine abgerufene Payload der Länge null gar keinen Inhalt trägt; eine solche Antwort ist dennoch ein Erfolg, denn ein Fehlschlag trägt immer seine Meldung und seinen Code, und der Wrapper jedes Kits gibt dafür leere Bytes zurück. Der Baum, den aggrega_parse_source zurückgibt, wird als Bytefolge übertragen, die ihr eigenes JSON-Dokument unverändert enthält; der Host liest ihn weder, noch formt er ihn um. Ein Parser liest dasselbe ParseInput in derselben Kodierung über seinen eigenen Export parse — siehe den Parser-Socket.

Kanonisch bedeutet, dass identische Eingaben auf jeder Seite identische Bytes erzeugen; das ermöglicht es, eine Payload über die drei Plugin-Kits hinweg zu vergleichen, statt sie nur im Round-Trip zu übertragen, und deshalb bleibt die Ausgabe eines Builds byteidentisch. In einem Guest ist keine CBOR-Bibliothek nötig, und nichts parst Bytes von Hand: Jeder veröffentlichte Payload-Typ liefert die Kodier- und Dekodier-Einstiegspunkte, die die Kodierung seines Slots braucht.

Determinismus liegt in der Verantwortung des Plugin-Autors. Der Host übernimmt die Ausgabebytes eines Guests unverändert und lässt keinen Serialisierer darüber laufen, sodass der Vertrag, den jedes Plugin einhalten muss, lautet: Identische Eingaben erzeugen identische Ausgabebytes. Die Sandbox entfernt die Ambient-Quellen von Nichtdeterminismus — Wanduhrzeit, Umgebung, Dateisystemzustand —, verdeckt aber bewusst nicht den Rest: Ein Guest, der Entropie oder verstrichene monotone Zeit in seine Ausgabe kodiert, erzeugt über Läufe hinweg sichtbar abweichende Bytes statt eines stabil verborgenen Defekts.

Der Abrufkanal für externe Eingaben. aggrega_fetch_external_input ist der eine sanktionierte Kanal für entfernte Inhalte, und er wird vom Host vermittelt und ist kein Netzwerkzugriff des Guests: Der Guest benennt eine URL, und der Host liefert Bytes gemäß der Fixierungsdisziplin für externe Eingaben. Eine in der Lockfile des Release fixierte URL wird aus dem lokalen inhaltsadressierten Speicher geliefert und gegen ihren aufgezeichneten Digest geprüft; eine nicht fixierte URL wird mit einer Diagnose abgelehnt, die die URL und den Schritt nennt, der sie fixiert, denn ein Rendering konsumiert die Hülle, die seine Lockfile aufzeichnet, und erweitert sie nie. Die Fixierungen werden geschrieben, wenn die Abhängigkeiten des Release aufgelöst werden, und das ist der eine Moment, in dem überhaupt etwas fixiert wird. Der Entwicklerleitfaden enthält die Anleitung zum Erstellen und die Fixierungsdisziplin vollständig.

Maps, die ihre Reihenfolge beibehalten

Manche Maps, die eine Payload transportiert, sind im Schema ihres Sockets als reihenfolgeerhaltend markiert, weil die Reihenfolge ihrer Einträge Teil dessen ist, was sie transportieren: die Knoten eines Builds, die Labels eines Knotens, die Anbindungen an einem Knoten, die Ein- und Ausgaben eines Pipeline-Schritts, die Schlüsselräume, die ein Provider deklariert. Die veröffentlichten Payload-Typen halten jede solche Map in einem Container, der ihre Einträge in der Reihenfolge behält, in der sie gesetzt wurden:

KitContainer
Goaggrega.OrderedMap[V] — der Name des Kits für abi.OrderedMap[V] aus dem ABI-Paket
RustOrderedMap<V> aus dem Crate aggrega-abi, vom Kit re-exportiert
TypeScriptdie spracheigene Map<string, V>

Die Container für Go und Rust bieten die Operationen einer Map — einen Schlüssel nachschlagen, ihn setzen, ihn löschen, die Schlüssel lesen, die Einträge der Reihe nach durchlaufen, sie zählen. Das Setzen eines Schlüssels, den der Container bereits enthält, ersetzt seinen Wert und behält seine Position bei; ein neuer Schlüssel kommt nach allen vorhandenen.

Die Reihenfolge übersteht beide Kodierungen. In der binären Kodierung wird eine markierte Map als geordnete Liste von Einträgen geschrieben — jeder Eintrag eine Liste aus zwei Elementen, zuerst der Schlüssel, dann der Wert — in der Reihenfolge des Containers, wo die kanonische Kodierung eine Map sonst mit sortierten Schlüsseln schreiben würde. In der Textkodierung ist sie ein JSON-Objekt, dessen Member in der Reihenfolge des Containers geschrieben werden. Ein Decoder weist in beiden Kodierungen eine Map zurück, die einen Schlüssel wiederholt, und nennt dabei den Schlüssel. Eine Map, die das Schema nicht markiert, behält in der binären Kodierung die sortierte Map-Form und in den veröffentlichten Typen den gewöhnlichen Map-Typ einer Sprache.

Drei Konsequenzen für einen Guest:

  • Die Reihenfolge ist Ausgabe. Weil eine markierte Map in der Reihenfolge geschrieben wird, in der sie gefüllt wurde, schreibt ein Guest, der eine solche Map aus einer Quelle ohne feste Reihenfolge füllt — etwa beim Iterieren über eine eingebaute Go-Map —, Bytes, die sich zwischen Läufen mit identischer Eingabe unterscheiden. Füllen Sie sie in einer festen Reihenfolge.
  • Die Reihenfolge gilt nur, solange die Map in ihrem Container bleibt. Ein Guest, der eine Payload in einen generischen Werttyp seiner eigenen Sprache umwandelt, erhält stattdessen die Reihenfolge dieses Typs: Ein map[string]any in Go hat keine, und serde_json::Value in Rust hält Objektschlüssel sortiert, sofern das Crate nicht mit seiner Option preserve_order gebaut wird.
  • Lesen und schreiben Sie in TypeScript über die generierten Funktionen. Ein Typ, der eine markierte Map enthält, dekodiert sein JSON Member für Member, sodass ein Schlüssel, der sich als Array-Index liest, etwa "8080", seine Position behält, wo JSON.parse ihn an den Anfang des Objekts verschieben würde; und sein Encoder schreibt jede Map als Objekt, wo JSON.stringify eine Map als {} schreibt. Auch Object.keys einer Map ist leer: Lesen Sie die Schlüssel einer Map mit ihrem eigenen keys().

Werte, die eine Eingabe als sensibel markiert

Ein Plugin zitiert in einer Ablehnung oder einer Warnung, die es zurückgibt, niemals einen Wert, den seine Eingabe als sensibel markiert — weder über seinen Schlüssel noch als Teil einer insgesamt markierten Payload. Eine Ablehnung ist der error, den eine Ausgabe trägt; eine Warnung ist eine Diagnostic, die die Ausgabe trägt, gleich welchen Schweregrads, oder eine, die über aggrega_emit_warning ausgelöst wird. Der Host gibt diesen Text überall, wo er ihn meldet, unverändert weiter — auf der Kommandozeile, im Language Server und in der Problemliste des Editors, in den Assistenz-Tools — und liest keinen Wert daraus, sodass das Plugin die einzige Stelle ist, die den Wert heraushalten kann. Nennen Sie stattdessen den Schlüssel, die Einstellung oder die Position: Von dort findet ein Leser den Wert.

Die Regel gilt für Text, den eine Bibliothek für das Plugin schreibt, ebenso wie für Text, den das Plugin selbst schreibt. Eine Template-Engine meldet die Daten, die sie gerade ausgewertet hat, ein Schema-Validator zitiert einen Wert, der an einem pattern scheitert, ein Parser zitiert das Token, das er nicht lesen konnte. Wo ein solcher Fehler über einen Wert lief, den die Eingabe markiert, melden Sie ihn ohne den Wert — führen Sie zum Beispiel denselben Schritt erneut aus, wobei jeder markierte Wert durch einen Platzhalter ersetzt ist, melden Sie den Fehler dieses Laufs, wenn er an derselben Stelle scheitert, und sagen Sie andernfalls, dass der Fehlertext zurückgehalten wird. Unter einer insgesamt markierten Payload ist jeder Wert in dieser Payload ein markierter Wert, während ihre Schlüssel — die Form des Dokuments — lesbar bleiben.

Wo eine Eingabe einen Schlüssel oder eine Payload als sensibel markiert, so geschrieben, wie die übertragenen Daten sie benennen:

Socket und ExportWo die Markierung gelesen wird
Provider render_node und validate_node_input (RenderNodeInput)node.sensitive_rendered_keys: Jeder Schlüssel benennt einen Eintrag von node.values, wenn diese Werte die eigenen der Component sind, geschlüsselt nach den Blättern, die sie deklariert — das valuesMapping eines Recipe schreibt Schlüssel, die keine Deklaration benennt, daher ist hier keiner davon markiert — oder einen Eintrag der Map attachments des Containers einer Arbeitslast, der einen als sensibel deklarierten Slot liest. node.sensitive_values markiert node.values insgesamt: Es ist true, wenn ein valuesMapping — das des Recipe oder das des FeatureRecipe einer Anbindung — diese Werte erzeugt hat und einen Wert liest, den ein Autor als sensibel deklariert hat. workload_projection.sensitive_workload markiert auf dieselbe Weise jeden Wert der Arbeitslast, wenn das Template der Arbeitslast einen solchen liest, und jeder Eintrag von artifacts_projection.entries trägt sensitive_content für seinen eigenen Inhalt, einschließlich der Meldung eines Parsers über diesen Inhalt. Jeder Eintrag von omits trägt sensitive, wenn das Template, das sein Kind, seinen Namen oder seinen Namespace erzeugt, einen solchen liest, und dann ist jedes Feld dieses Eintrags ein markierter Wert. Jeder Eintrag von node.features trägt die Markierung seiner eigenen Anbindung: sensitive_payload_leaves (die Blätter values.<path> und infra.<path>, die sein Feature als sensibel deklariert), sensitive_inject (die inject-Auslieferungsschlüssel, die einen provides-Schlüssel lesen, den sein Feature als sensibel deklariert) und sensitive (ob die Anbindung überhaupt als sensibel deklariertes Material verarbeitet).
Governance ir-verdict (PolicyInput)graph: die sensitive_payload_leaves jedes Knotens sowie die sensitive_payload_leaves, sensitive_inject und sensitive jeder Anbindung. Jeder Wert, den diese Markierungen benennen, kommt bereits als Zurückhaltungsmarker {"aggrega_withheld": "declared"} an, sodass der Wert selbst das Plugin nie erreicht.

Keine andere Socket-Eingabe und keine Eingabe eines anderen Provider-Exports trägt eine Markierung. Eine Schlüsselmarkierung benennt nur, was sie exakt mit einer Deklaration verknüpft, sodass ein fehlender Schlüssel nie bedeutet, dass ein Wert gefahrlos zitiert werden kann: Er bedeutet, dass keine Deklaration mit diesem Schlüssel verknüpft werden konnte. Eine Payload-Markierung wird aus den Referenzen des Templates gelesen, das die Payload erzeugt hat — eine Referenz, die einen deklarierten Wert erreicht, das Template, das seine Daten vollständig weiterreicht, oder ein Template, das sich nicht parsen lässt — und nie aus einem Wert, sodass ihr Fehlen bedeutet, dass dieses Template, soweit seine Referenzen zeigen, keinen deklarierten Wert gelesen hat, oder dass kein Template die Payload erzeugt hat; es ist keine Aussage darüber, dass die Payload nichts Sensibles trägt.

Pipeline-Platzierung der Wasm-Sockets

Die Kompilierungs-Pipeline reserviert die folgenden Socket-Punkte. Die Form-Labels folgen der Taxonomie mit vier Labels von der Status-Seite.

SocketPlatzierung in der PipelineStatus heute
Governance-Socket, Rolle annotation-transformAuflösung (vor der Annotationsexpansion)verfügbar — aufgerufen, wenn ein Workspace ein annotation-transform-Plugin anbindet; injiziert Annotationen, die die Expansion in Feature-Anbindungen umwandelt
Governance-Socket, Rolle label-transformTopologiekonstruktion (der Topologie-Builder)verfügbar — aufgerufen, wenn ein Workspace ein label-transform-Plugin anbindet; taggt Knoten-Labels automatisch über JSON Patch
Governance-Socket, Rolle ir-verdictStatische Analyse (der statische Analysator, über dem IR-Graphen)verfügbar — aufgerufen, wenn ein Workspace ein ir-verdict-Plugin anbindet; ein Verdikt halt stoppt den Build
Governance-Socket, Rolle render-verdictRendering (über die gerenderten Artefakte)verfügbar — aufgerufen, wenn ein Workspace ein render-verdict-Plugin anbindet; ein Verdikt halt stoppt den Build
Plugins der pipeline: von FeatureRecipe und RecipeDie Plugin-Pipeline (Mutation nach dem Rendering)verfügbar — jeder deklarierte Schritt läuft gegen die Menge der gerenderten Dokumente, wendet RFC-6902-Patches an und erzeugt Nebeneffekte
Provider-Rendering-Plugins (helm, helm-chart, compose, terraform, cloudformation)Basis-Rendering (die Provider)verfügbar — jeder Provider rendert über seinen Wasm-Guest; das Rendering erfolgt ausschließlich über Wasm, ohne Fallback auf einen Renderer im Host
Parser-Plugins (parse:<format>)Rendering, für eine render-verdict-Richtlinie; und Out-of-Band, für einen Importverfügbar — aufgerufen für ein Artefakt in einem Format, das eine render-verdict-Richtlinie nicht nativ liest, für einen Importer über aggrega_parse_source und zum Erkennen des Formats eines Imports, der keines nennt
Importer-Plugins (import:<format>)Out-of-Band (aggrega import)verfügbar — aufgerufen von aggrega import, der Editor-Sitzung und dem Tool für den Assistenten
Linter-Plugins (linter/publishing)Out-of-Band (aggrega lint)verfügbar — der Veröffentlichungs-Linter wird mitgeliefert und läuft über den Host mittels aggrega lint

Die annotationsgesteuerte Unterphase der Feature-Expansion, Teil der Auflösung, ist ein nativer Go-Durchlauf der Pipeline, kein Wasm-Socket. Sie validiert Annotationswerte gegen das spec.schema des Ziel-Feature und injiziert synthetische Feature-Anbindungen zur Build-Zeit der IR. Siehe vocabulary/labels-and-annotations.md für die sechs Oberflächen, die Annotationen und Labels tragen, und providers/well-known-annotations.md für die Binding-Form und die Anleitung zum Verfassen.

Vertrag der Ausgabeform — was es heute gibt

Der Governance-Socket trägt an jeder seiner vier Rollen eine typisierte Vertragsoberfläche, und die Rolle legt fest, welche. Plugin-Autoren implementieren Guest-seitigen Code, der die dokumentierten Formen erzeugt; der Host liest sie zur Build-Zeit, einmal pro konfiguriertem Plugin, wenn ein Workspace ein Plugin an dieser Rolle anbindet. Die folgenden Unterabschnitte folgen der Reihenfolge, in der die Pipeline sie aufruft.

Die Rolle annotation-transform — Ausgabe der Annotationsinjektion

Pipeline-Platzierung. Auflösung, nachdem die Komponenten aufgelöst sind und bevor die annotationsgesteuerte Feature-Expansion läuft.

Eingabeform (Host → Guest). Ein Dokument vom Typ AnnotationTransformInput mit:

  • targets — die Injektionsziele: die aufgelösten Komponenten, die der Guest annotieren darf — die, die eine Boundary direkt benennt, und jede Komponente, die ein Routing-Eintrag unter den aggregates: einer Boundary hineinroutet, ob der Eintrag sie benennt oder nicht —, jede mit ihrem boundary_path, ihrem component_name (für eine geroutete Komponente ihre gepunktete ID im Build-Graphen, etwa metrics.query) und den annotations, die das Release auf sie schreibt, sodass ein Guest entscheiden kann, was er hinzufügt, ohne einen vom Autor geschriebenen Wert zu verdrängen. Jeder Annotationswert kommt so an, wie er geschrieben wurde — als String, als Objekt aus Unterschlüsseln oder als null, wo die Komponente eine Annotation abwählt, die sie erben würde —, und jeder Schlüssel, den die Komponente trägt, ist vorhanden, gleich welchen Wert er hat. Vom Host deterministisch geordnet.
  • binding_keys — die Annotationsschlüssel, für die das Manifest ein Binding registriert, in Autorenreihenfolge. Eine Injektion unter einem registrierten Schlüssel wird anschließend zu einer Feature-Anbindung expandiert, daher liest ein Guest diese Liste, um Schlüssel zu injizieren, die wirksam werden. Der Host verlangt nicht, dass eine Injektion einen registrierten Schlüssel benennt: Eine nicht registrierte injizierte Annotation verhält sich genau wie eine vom Autor geschriebene Annotation ohne Binding.
  • sources — die Definitionsdateien, die die Anbindung unter with.sources deklariert hat, jede mit ihrem Basisnamen-Pfad und ihrem Inhalt, nach Pfad sortiert.
  • settings — das frei geformte Einstellungsobjekt, das die Anbindung unter with.settings deklariert hat, unverändert an den Guest übergeben.

settings und sources sind derselbe Kanal with, agnostisch gegenüber der Engine, den jede andere Rolle liest, und beide fehlen, wenn die Anbindung keine deklariert. Weil die Ausgabe dieser Rolle den Build formt, werden die Einstellungen und der Quellinhalt der Anbindung beim Pull in der Release-Lockfile fixiert und beim Build daraus rekonstruiert.

Ausgabeform (Guest → Host). Ein Dokument vom Typ AnnotationTransformOutput mit:

  • injections — die hinzuzufügenden Annotationen, der Reihe nach. Jede benennt eine vorhandene Zielkoordinate (boundary_path und component_name) sowie den annotation_key und seinen annotation_value: einen String oder ein Objekt aus Unterschlüsseln, das ein Binding speist, das mehrere Unterschlüssel auf einmal routet.

Der Host wendet nur Hinzufügungen von Annotationen an, und zwar auf Koordinaten, die er selbst geliefert hat, jede mit einem Wert, den ein Autor auf diese Annotation schreiben könnte. Er liest einen injizierten Wert genau so, wie er denselben im Release geschriebenen Wert liest — die Unterschlüssel eines Objekts in der Reihenfolge, in der der Guest sie geschrieben hat —, sodass die Expansion ihm so begegnet wie einem vom Autor geschriebenen. Eine Injektion, die eine Koordinate benennt, die die Payload nicht trägt, oder die null, eine Liste, eine Zahl, einen booleschen Wert oder ein Objekt ohne Unterschlüssel trägt, hält den Build mit einer Meldung an, die die Koordinate und die Annotation nennt, statt stillschweigend verworfen oder angewendet zu werden; die gesamte Ausgabe wird geprüft, bevor irgendein Teil davon angewendet wird. Diese Beschränkung ist es, die die Rolle begrenzt: Ein Betreiber, der hier ein Plugin anbindet, hat Annotationsinjektion deklariert und nichts darüber hinaus. Wo der Build eine injizierte Annotation später ablehnt — wegen der Art, wie sie routet, wegen eines Unterschlüsselwerts, den das Schema des gebundenen Feature nicht zulässt, oder wegen einer Säule, die eine Release-seitige Annotation nicht verwenden darf —, nennt seine Meldung das Plugin, das sie injiziert hat, und die Rolle, an der es angebunden ist.

Übertragungskodierung. Payload und Ergebnis dieser Rolle werden in beide Richtungen als kanonisches CBOR (RFC 8949 §4.2.1) übertragen. Ein Guest liest und schreibt sie über die Einstiegspunkte, die die Payload-Typen tragen — DecodeCBOR und EncodeCBOR in Go, decode_cbor und encode_cbor in Rust, decodeCBORAnnotationTransformInput und encodeCBORAnnotationTransformOutput in TypeScript —, sodass keine CBOR-Bibliothek nötig ist und nichts Bytes von Hand parst. In Rust nimmt der Export Vec<u8> entgegen und gibt es zurück; in TypeScript liest er Host.inputBytes() und schreibt Host.outputBytes(...). Die annotations jedes Ziels sind eine Map, die das Schema als reihenfolgeerhaltend markiert, daher werden sie als geordnete Liste von Einträgen in der Reihenfolge übertragen, in der das Ziel sie hält, und ein Guest liest sie über den reihenfolgeerhaltenden Container seines Kits; jeder Wert wird als die Bytes seines JSON übertragen, so wie der annotation_value einer Injektion in der Gegenrichtung. settings wird als die Bytes seines JSON-Dokuments übertragen, das ein Guest als JSON parst, um hineinzusehen. Eine Antwort, die kein AnnotationTransformOutput in dieser Kodierung ist — eine als JSON geschriebene oder eine, die ein Feld auf oberster Ebene trägt, das die Form nicht deklariert —, hält den Build an und nennt dabei das Plugin und seinen Export, statt als leere Liste von Injektionen gelesen zu werden. Direkt mit aggrega plugin run-local --export transform_annotations aufgerufen, erhält ein Guest die vom Autor geschriebene JSON-Payload, in diese Kodierung umgewandelt, und seine Antwort wird als Ausgabeform des Exports gelesen und als JSON ausgegeben — eine Antwort, die diese Form nicht hat, wird unter Nennung des Exports abgelehnt, so wie ein Build sie ablehnt.

Typdefinitionen. Die Übertragungstypen von annotation-transform — AnnotationTransformInput, AnnotationTransformOutput, AnnotationTarget, AnnotationInjection, AnnotationSource — sind in allen drei ABI-Paketen veröffentlicht, generiert aus einem einzigen Codec, sodass die drei im Gleichschritt bleiben.

Die Rolle label-transform — JSONPatch-Ausgabe

Pipeline-Platzierung. Topologiekonstruktion, nachdem der Graph abgeflacht ist und bevor der IR-Graph aufgebaut wird, sodass die Socket- und Feature-Selektoren, die der Analysator auswertet, die Labels lesen, die die Rolle hinterlässt.

Eingabeform (Host → Guest). Ein Dokument vom Typ MutatorInput mit:

  • compilation_context — die Release-Identität (release_name, environment).
  • graph — eine Projektion vom Typ MutatorGraph der Topologieknoten: für jeden Knoten seine Component, die aufgelöste Version, die Labels und die values, die seine Instanz deklariert.
  • settings — das frei geformte Einstellungsobjekt, das die Anbindung unter with.settings deklariert hat, unverändert an den Guest übergeben.
  • sources — die Definitionsdateien, die die Anbindung unter with.sources deklariert hat, jede mit ihrem Basisnamen-Pfad und ihrem Inhalt, sodass ein Mutator von einer eingecheckten Regel- oder Zuordnungsdatei statt von Inline-Einstellungen gesteuert werden kann.

Der Graph ist eine Projektion und nicht der IR-Graph: Jeder Knoten trägt seine aufgelöste Label-Menge und die Werte, die seine Instanz im Aggregate deklariert, während Kanten und Funktions-Payloads im Compiler bleiben. Die Werte sind die des Aggregate selbst, mit seinen bereits gegen seine Parameter ausgewerteten Templates, sodass ein in einen Parameter ausgelagerter Wert als der Wert ankommt, den das Release geliefert hat; ein Standardwert, den das Schema der Component deklariert, und alles, was ein Recipe oder ein Feature beiträgt, gehören nicht dazu, und ein Knoten, der keine Werte deklariert, trägt keinen Schlüssel values. Ein Wert, den die Component des Knotens als sensibel deklariert, wird genau so zurückgehalten, wie ihn das Verdikt über den Graphen zurückhält — er liest sich als {"aggrega_withheld": "declared"} —, während jeder Geschwisterwert, den keine Deklaration erreicht, so ankommt, wie er geschrieben wurde. Genau das erlaubt es, dass eine vom Entwickler deklarierte Konfiguration über ein Label entscheidet — etwa eine Datenbank, deren Werte eine Vektor-Erweiterung aktivieren, hochgestuft zu datastore.aggrega.ai/engine: vector. settings und sources sind derselbe Kanal with, agnostisch gegenüber der Engine, den die Verdikt-Rollen lesen; der Host reicht sie durch und interpretiert ihren Inhalt nie. Weil die Ausgabe eines Mutators den Build formt, werden die Einstellungen und der Quellinhalt der Anbindung beim Pull in der Release-Lockfile fixiert und beim Build daraus rekonstruiert, sodass die Eingabe des Mutators gegenüber einer Änderung an einem der beiden nach dem Pull invariant bleibt, bis zum nächsten Pull.

Ausgabeform (Guest → Host). Ein Dokument vom Typ MutatorOutput mit:

  • patches — ein Array opaker JSONPatch-Dokumente (RFC 6902), die der Host ausschließlich auf die Knoten-Labels anwendet; die Werte, die die Eingabe trug, sind schreibgeschützt.

Jeder Patch adressiert die Labels eines bestimmten Knotens über JSON Pointer (RFC 6901); der Host wendet die Patches in Array-Reihenfolge an und übernimmt die veränderte Label-Menge wieder in den IR-Graphen. Die Aufgabe der label-transform-Rolle ist unternehmensweites automatisches Tagging — das Hinzufügen von Compliance- / Observability- / Kostenzuordnungs-Labels, die von Unternehmensrichtlinien deklariert werden, ohne Katalog-Inhalte zu verändern. Die Label-Oberfläche ist das einzige zulässige Ziel dieser Rolle: Ein Patch, der ein anderes Knotenfeld als seine Labels berührt, einen Knoten hinzufügt oder entfernt oder einen Label-Wert setzt, der kein String ist, hält den Build an, statt stillschweigend übernommen zu werden. RFC 6901 ist die Grundlage der Pfadgrammatik für jede Dokumentpfad-Oberfläche in Aggrega — den Wasm-Plugin-Vertrag hier, dazu die Exporte *_path von .locals und die Schemafelder *Path an anderer Stelle im Korpus. Siehe 02-naming-conventions.md „Disziplin der Benennungssuffixe für Dokumentpfade“ für die kanonische Deklaration dieser Grundlage und die Suffixdisziplin *Path / *_path, die die beiden Autorenseiten unterscheidet.

Übertragungskodierung. Payload und Ergebnis dieser Rolle werden in beide Richtungen als kanonisches CBOR (RFC 8949 §4.2.1) übertragen. Kanonisch bedeutet, dass identische Eingaben auf jeder Seite identische Bytes erzeugen; das ist es, was erlaubt, eine Payload über die drei Plugin-Kits hinweg zu vergleichen, statt sie nur zu kodieren und wieder zu dekodieren, und es ist der Grund, warum die Ausgabe eines Builds byte-identisch bleibt. Ein Guest liest und schreibt sie über die Einstiegspunkte, die der Payload-Typ seines Kits bereits trägt — DecodeCBOR und EncodeCBOR in Go, decode_cbor und encode_cbor in Rust, decodeCBORMutatorInput und encodeCBORMutatorOutput in TypeScript —, sodass keine CBOR-Bibliothek nötig ist und nichts Bytes von Hand parst. In Rust nimmt der Export Vec<u8> entgegen und gibt es zurück; in TypeScript liest er Host.inputBytes() und schreibt Host.outputBytes(...). Die nodes des Graphen, die labels jedes Knotens und die values jedes Knotens sind Maps, die das Schema als reihenfolgeerhaltend markiert, daher werden sie als geordnete Listen von Einträgen übertragen — die Knoten in der Reihenfolge, in der der Build sie hält, also in Autorenreihenfolge, die Labels jedes Knotens in der Reihenfolge, in der der Knoten sie trägt, und die Werte jedes Knotens in der Reihenfolge, in der das Aggregate sie schreibt —, und ein Guest liest alle drei über den reihenfolgeerhaltenden Container seines Kits. Jeder Wert wird als die Bytes seines JSON-Dokuments übertragen: Die Go- und Rust-Kits übergeben ihn dem Guest als dieses JSON, das so weit geparst wird, wie eine Regel es braucht, und das TypeScript-Kit als den geparsten Wert.

Zwei Dinge ändert dies nicht. Das Array patches bleibt JSON: Der Socket trägt jedes Patch-Dokument unverändert als opaken Inhalt, und keine der beiden Seiten liest hinein, sodass die eigene Form eines Patch-Dokuments unabhängig von der Kodierung ist, die sein Socket trägt. Und settings und sources werden weiterhin unverändert durchgereicht — settings kommt als die Bytes an, die die Anbindung geschrieben hat, und ein Guest parst sie als JSON, wenn er hineinsehen muss.

Jede andere Governance-Rolle trägt dieselbe Kodierung — die Rolle annotation-transform und die beiden Verdikt-Rollen sagen das jeweils in ihrem eigenen Abschnitt —, sodass ein Guest, der mehr als eine Rolle bedient, an jeder Rolle, die er bedient, kanonisches CBOR spricht und jede Payload über den Dekodier-Einstiegspunkt ihres eigenen Typs liest.

Typdefinitionen. Die Übertragungstypen des Mutators — MutatorInput, MutatorOutput, CompilationContext, MutatorGraph, MutatorNode — sind in allen drei ABI-Paketen veröffentlicht (github.com/aggrega-ai/aggrega-abi/go, dem Crate aggrega-abi und @aggrega-ai/aggrega-abi), generiert aus einem einzigen Codec, sodass die drei im Gleichschritt bleiben. Der Host stellt die Eingabe zusammen und wendet die Patches an, die der Guest zurückgibt.

Die Verdikt-Rollen — Ausgabe des Verdikt-Arrays

Ein Richtlinien-Guest prüft einen Build und gibt eine Liste von Verdikten zurück; der Host handelt nach dem Schweregrad jedes Verdikts und interpretiert die Richtlinie selbst nie. Die vollständige Behandlung — die vier Rollen, die Schweregrade, der vom Betreiber bereitgestellte Eingabekanal, das Schreiben einer Richtlinie für eine der beiden Engines, die im Compiler mitgeliefert werden, das Einbinden einer fremden Richtlinien-Engine, die Referenz-Guests und wie ein Betreiber eine Richtlinie anbindet — steht auf der Seite zum Governance-Socket. Dieser Abschnitt hält die Pipeline-Platzierung und die typisierten Übertragungsformen fest.

Pipeline-Platzierung. Eine Richtlinie wird an genau einer Verdikt-Rolle angebunden, die festlegt, wo sie ausgewertet wird:

  • ir-verdict — ausgewertet bei der statischen Analyse, vor dem Basis-Rendering. Der Analysator stellt die Payload bei jedem Build zusammen.
  • render-verdict — ausgewertet nach dem Rendering, über die ausgegebenen Artefakte.

Wenn ein Workspace ein Plugin einer Verdikt-Rolle anbindet, serialisiert die Pipeline die Payload dieser Rolle an das Plugin und liest dessen Verdikte zurück.

Eingabeform (Host → Guest). Die Rolle wählt die Payload:

  • Die Eingabe PolicyInput der Rolle ir-verdict trägt graph — den vollständigen IR-Graphen, agnostisch gegenüber Fähigkeiten (dieselbe Form, die der Topologie-Builder ausgibt), mit jedem Detail zu Knoten, Kanten und Anbindungen, das der Compiler hält, außer dass ein Wert, den ein Autor als sensibel deklariert hat, zurückgehalten ankommt (siehe Werte, die eine Eingabe als sensibel markiert) — und precalculated_paths, die Routing-Pfade, die der Analysator daneben aufzählt, sodass eine Richtlinie über Erreichbarkeit schlussfolgern kann, ohne den Graphen erneut zu durchlaufen. Der Graph ist der versionierte IR-Graph, mit einziger Quelle im Schema ir-v1beta1; die IR-Form ist nicht geheim (es ist derselbe Graph, den aggrega inspect ausgibt), und Geheimnisse darin sind Zeiger, nie Klartext.
  • Die Eingabe RenderPolicyInput der Rolle render-verdict trägt artifacts — die gerenderten Ausgabedateien, nach Pfad sortiert, sodass die übertragenen Daten über Läufe mit identischer Eingabe hinweg byte-identisch sind. Jeder Eintrag trägt den Ausgabepfad path des Artefakts und seinen gerenderten Inhalt content; er trägt außerdem das format, in dem es gerendert wurde, wenn der erzeugende Provider eines deklariert hat, und einen tree, die geparste kanonische Ansicht eines Formats, das der Guest nicht nativ liest, die der Host über den aufgelösten Parser parst und opak durchreicht. Beide fehlen, wenn sie nicht zutreffen — ein Format, das der Guest nativ liest (JSON, YAML), bleibt ungeparst, damit der Guest es aus content liest.

Beide Rollen tragen zusätzlich die sources der Anbindung (Richtliniendefinitionsdateien, die der Host zur Build-Zeit liest und dem Guest unverändert übergibt, Pfade als Basisnamen, Inhalt opak) und settings (ein frei geformtes Objekt, das unangetastet durchgereicht wird). Beide fehlen, wenn die Anbindung keine deklariert.

Ausgabeform (Guest → Host). Ein Dokument vom Typ PolicyOutput mit:

  • results — ein Array von Einträgen vom Typ Diagnostic, jeder mit einer severity (halt, warn oder info) und einem String message. Ein Verdikt kann im selben Eintrag außerdem code, rule_id, classification, source_ref, location und suggest setzen; der Host hängt diejenigen davon, die das Verdikt trug, an das ausgegebene Verdikt an, auf jedem Schweregrad-Pfad.

Nur ausgelöste Verdikte erscheinen; eine zulassende Auswertung gibt ein leeres Array zurück. Der Host durchläuft die Verdikte und ordnet jedem Schweregrad eine Aktion zu: halt stoppt den Build (und zeigt die Meldung jedes halt an), warn markiert das Verdikt und lässt den Build fortfahren, info hält es fest, ohne das Ergebnis zu beeinflussen. Ein halt stoppt über denselben Prüfpunkt, den eine Verletzung eines Selektors oder von appliesTo verwendet.

Übertragungskodierung. Die Payloads beider Rollen und der PolicyOutput, den ein Guest an einer der beiden zurückgibt, werden als kanonisches CBOR (RFC 8949 §4.2.1) übertragen. Ein Guest liest und schreibt sie über die Einstiegspunkte, die die Payload-Typen tragen — DecodeCBOR und EncodeCBOR in Go, decode_cbor und encode_cbor in Rust, decodeCBORPolicyInput, decodeCBORRenderPolicyInput und encodeCBORPolicyOutput in TypeScript —, sodass keine CBOR-Bibliothek nötig ist und nichts Bytes von Hand parst. In Rust nimmt jeder Export Vec<u8> entgegen und gibt es zurück; in TypeScript liest er Host.inputBytes() und schreibt Host.outputBytes(...). Die reihenfolgeerhaltenden Maps des Graphen, darunter seine nodes und die labels jedes Knotens, werden als geordnete Listen von Einträgen in der Reihenfolge übertragen, in der der Build sie hält, und ein Guest liest sie über den reihenfolgeerhaltenden Container seines Kits; in welcher Reihenfolge eine Richtlinie ihnen unter jeder Richtlinien-Engine begegnet, steht auf der Seite zum Governance-Socket. settings und der geparste tree eines Artefakts werden als die Bytes ihrer JSON-Dokumente übertragen, die ein Guest als JSON parst, um hineinzusehen. Eine Antwort, die kein PolicyOutput in dieser Kodierung ist — eine als JSON geschriebene oder eine, die ein Feld auf oberster Ebene trägt, das die Form nicht deklariert —, hält den Build an und nennt dabei das Plugin und seinen Export, statt als leere Verdiktliste gelesen zu werden. Direkt mit aggrega plugin run-local --export verdict_ir oder --export verdict_render aufgerufen, erhält ein Guest die vom Autor geschriebene JSON-Payload, in diese Kodierung umgewandelt, und seine Antwort wird als Ausgabeform des Exports gelesen und als JSON ausgegeben — eine Antwort, die diese Form nicht hat, wird unter Nennung des Exports abgelehnt, so wie ein Build sie ablehnt.

Typdefinitionen. Die Übertragungstypen der Richtlinien sind in denselben drei ABI-Paketen veröffentlicht: PolicyInput (Rolle ir-verdict), RenderPolicyInput (Rolle render-verdict), das gemeinsame PolicySource und PolicyOutput, dessen Einträge in results Werte vom Typ Diagnostic sind. Der Schweregrad einer Diagnose ist einer von drei Werten, die jeder Socket teilt — halt, warn oder info —, und die drei sind als Konstanten neben den Übertragungstypen in jedem der drei Pakete veröffentlicht, sodass ein Guest aus derselben geschlossenen Menge meldet, nach der der Host routet. Ein Guest, der einen anderen Wert zurückgibt, hält den Build an, wobei die Meldung das Plugin und den zurückgegebenen Wert nennt: Ein nicht routbarer Schweregrad ist ein Defekt des Plugins, den der Host meldet, statt einer Diagnose, die er verwirft.

Vertrag der Ausgabeform — die FeatureRecipe-Pipeline und die Provider-Sockets

Die folgenden Sockets tragen typisierte Vertragsoberflächen, die der Compiler beim Build aufruft. Die Schritte der pipeline: von FeatureRecipe und Recipe laufen in der Plugin-Pipeline gegen die Menge der gerenderten Dokumente; der Provider-Rendering-Socket läuft beim Basis-Rendering; der Veröffentlichungs-Linter läuft Out-of-Band.

RFC-6902-Patches (die Plugin-Pipeline)

Schritte der pipeline: von FeatureRecipe und Recipe, die in der Plugin-Pipeline laufen, erzeugen RFC-6902-JSON-Patch-Operationen gegen die Menge der gerenderten Dokumente. Der Host übergibt jedem Schritt die nach Schlüsseln adressierte Dokumentmenge vollständig; der Schritt wählt die Dokumente, auf die er zielt, nach ihrem Inhalt aus und gibt schlüsseladressierte Patches zurück, die die Apply-Engine auf die adressierten Dokumente anwendet — typischerweise, indem sie einen Sidecar-Container anhängt, ein Secret-Volume einhängt oder eine Umgebungsvariable umschreibt. Ein Schritt gibt außerdem side_effects (unten), diagnostics — jeder Eintrag in derselben gemeinsamen Form Diagnostic, in der jeder Socket Probleme meldet — und outputs (unten) zurück. Beschrieben in examples/04-secrets.md.

Status heute: verfügbar. Jeder deklarierte Schritt läuft während aggrega build.

Übertragungskodierung. Die Eingabe eines Schritts (FRPStepInput) und seine Antwort (FRPStepOutput) werden in beide Richtungen als kanonisches CBOR (RFC 8949 §4.2.1) übertragen. Ein Guest dekodiert seine Eingabe und kodiert seine Antwort über die Einstiegspunkte, die die Payload-Typen tragen — DecodeCBOR und EncodeCBOR in Go, decode_cbor und encode_cbor in Rust (auf den Typen, die das Crate aggrega-abi veröffentlicht), decodeCBORFRPStepInput und encodeCBORFRPStepOutput in TypeScript —, wobei er Bytes liest und schreibt (Vec<u8> in Rust, Host.inputBytes() und Host.outputBytes(...) in TypeScript). Es ist keine CBOR-Bibliothek nötig, und nichts parst Bytes von Hand. Die Eingabe with des Schritts (step_input), die outputs, die er zurückgibt, und die Dokumentmengen own und host sind Maps, die das Schema als reihenfolgeerhaltend markiert, daher werden sie als geordnete Listen von Einträgen in der Reihenfolge übertragen, in der die Pipeline sie hält, und ein Guest liest und schreibt sie über den reihenfolgeerhaltenden Container seines Kits — was es den Ausgaben eines Schritts ermöglicht, .steps.<id>.outputs in der Reihenfolge zu erreichen, in der der Schritt sie zurückgegeben hat. Der tree jeder Einheit, jeder Wert von step_input und outputs, der value eines Patches, das crd eines Nebeneffekts und der context des Renderings werden als die Bytes ihrer JSON-Dokumente übertragen, die ein Guest als JSON parst, um hineinzusehen; die bytes einer Einheit werden als rohe Bytefolge übertragen, die der generierte Decoder in den eigenen Feldtyp des Kits füllt — ein Byte-Slice in Go, ein Base64-String in Rust und TypeScript. Jede Diagnose wird in der gemeinsamen Form Diagnostic übertragen. Eine Antwort, die kein FRPStepOutput in dieser Kodierung ist — eine als JSON geschriebene oder eine, die ein Feld auf oberster Ebene trägt, das die Form nicht deklariert —, lässt den Schritt fehlschlagen und nennt dabei die Funktion, die er ausführt, was den Build anhält, sofern der Schritt nicht optional ist. Direkt mit aggrega plugin run-local --export step aufgerufen, erhält ein Schritt die vom Autor geschriebene JSON-Payload, in diese Kodierung umgewandelt, und seine Antwort wird als Ausgabeform des Exports gelesen und als JSON ausgegeben — eine Antwort, die diese Form nicht hat, wird unter Nennung des Exports abgelehnt, so wie ein Build sie ablehnt.

Nebeneffekte — Erzeugen von Ressourcen (Plugins für Anmeldedaten in der Plugin-Pipeline)

FeatureRecipe-Pipelines für Anmeldedaten (Prinzip des zweiteiligen Plugin: Fetcher + Injector) erzeugen über die side_effects eines Schritts vollständige Ressourcen neben einem Patch, von denen jede eine der zwei Arten deklariert, die der Vertrag definiert: emit_crd, ein Custom-Resource-Dokument wie eine CRD ExternalSecret oder VaultSecret, die der Cluster zur Laufzeit abruft, oder emit_file, eine geschriebene Datei. Ein Schritt, der eine andere Art zurückgibt, hält den Build an und nennt dabei den Knoten, den Index des Nebeneffekts und die Art, die er deklariert hat. Der Schritt des Fetcher erzeugt die vollständige Ressource; der Schritt des Injector gibt einen Patch zurück, der das resultierende Kubernetes-Secret einhängt. Beschrieben in examples/04-secrets.md.

Status heute: verfügbar.

Schrittausgabe (Map outputs eines Schritts der pipeline:)

Ein Schritt der Plugin-Pipeline veröffentlicht benannte Ausgaben, die nachfolgende Schritte über {{ .steps.<id>.outputs.<key> }} konsumieren. Die Ausgabeform wird pro Plugin vom Provider definiert; Schrittausgaben sind auf dieselbe Pipeline beschränkt und nur für nachfolgende Schritte in Deklarationsreihenfolge sichtbar. Dokumentiert in templates/expansion-matrix.md, Zeile 10.

Status heute: verfügbar.

Provider-Rendering — der Guest-gesteuerte Socket

Ein Provider ist ein Wasm-Guest. Rendering erfolgt ausschließlich über Wasm: Der Name in capability: eines Recipe wird zu dem Provider-Rendering-Plugin (pluginType: provider) aufgelöst, das den Namen in seinen spec.provider.capabilities aufführt und einen Export render_node anbietet, und der Guest, den dieses Plugin mitbringt, rendert den Knoten. Es gibt keinen Renderer im Host, auf den zurückgegriffen werden könnte; ein Provider-Name, der sich zu keinem bedienenden Plugin auflöst, hält den Build zur Routing-Zeit an. Einen Standard-Provider hinzuzufügen bedeutet, einen Guest .wasm und eine Katalog-Entität Plugin auszuliefern — der Host enthält keinen Provider-spezifischen Code.

Eine Fähigkeit, die ein Provider bedient, enthält keinen Doppelpunkt, und ebenso wenig eine, mit der sich ein Pipeline-Schritt als kompatibel erklärt. Das capability: eines Recipe wird als die Fähigkeit bis zu ihrem letzten Doppelpunkt und eine Versionsfixierung danach gelesen — helm:1.0.0 fragt helm in Version 1.0.0 an —, sodass ein Name mit einem Doppelpunkt einer ist, den kein Recipe anfragen kann. Der Host lehnt einen solchen Namen in den capabilities von describe() für einen Guest vom Typ provider oder pipeline-step ab, wenn der Guest geladen wird und wenn seine Entität für die Veröffentlichung generiert wird, und nennt dabei den Guest und den Namen. Das parse:<format> eines Parsers und das import:<format> eines Importers behalten ihren Doppelpunkt: Diese werden nach Format nachgeschlagen, nie über das capability: eines Recipe.

Der Host ist ein generischer Router. Er liest die Selbstauskunft describe() des Guest — einschließlich seines Render-Verhaltensvertrags — und verteilt die Exporte des Guest, ohne irgendein Provider-Format zu verstehen. Dieser Vertrag steuert die Verteilung als Daten:

  • input_kinds (sourced, synthesized, artifacts_standalone) — welche Recipe-Eingabearten der Guest rendert; der Host prüft die Eingabeart eines Knotens gegen diese Menge.
  • boundary_assembly (none | merge | nest) — wie der Guest die Ausgabe einer Verteilungsgruppe kombiniert: merge klassifiziert die Ausgabe pro Knoten als Fragmente, die der Assembler zu einem Artefakt zusammenführt, nest verschachtelt die Dateien pro Knoten unter einem assemblierten Wrapper, none schreibt die Ausgabe jedes Knotens direkt.
  • nest_segment (optional) — für eine Assemblierung vom Typ nest das Verzeichnis, unter dem das eigene Unterverzeichnis jedes Beitragenden abgelegt wird, geschrieben als ein einzelner Verzeichnisname; fehlt es, liegt das Unterverzeichnis jedes Beitragenden direkt an der Verteilungsposition.
  • assembly_name_annotation (optional) — eine Boundary-Annotation, deren aufgelöster Wert das Artefakt benennt, das der Guest aus einer Verteilungsgruppe assembliert; fehlt sie, benennt der Guest seine Assemblierung allein nach dem Verteilungspfad.
  • cross_boundary_linking (optional) — ob der Guest eine Boundary-übergreifende Kante uses über seine Exporte link_publish und link_resolve verdrahtet; ein Guest deklariert es genau dann als wahr, wenn er beide exportiert, und das Laden lehnt einen Guest ab, dessen Flag und Exporte nicht übereinstimmen.
  • artifact_delimiters (optional) — das Begrenzerpaar für Go-Templates, das der Guest auf Artefaktinhalte anwendet.
  • reusable_instance (optional) — ob eine einzige geladene Instanz jeden Übergang des Builds bedienen darf (siehe Determinismus und Wiederverwendung von Instanzen weiter unten).
  • omits (optional) — ob der Guest die Auslassungseinträge berücksichtigt, die ein Quell-Rendering trägt (siehe Gerenderte Einheiten auslassen weiter unten).
  • boundary_artifacts (optional) — ob das Ziel des Guest die Dateien annimmt, die ein Recipe zur gemeinsamen Ausgabe seiner Boundary beiträgt (siehe Dateien annehmen, die ein Recipe zur Boundary beiträgt weiter unten).
  • source_ignore (optional) — die Dateien, die das Ökosystem des Guest nie neben einer Quelle ausliefert, die er rendert (siehe Deklarieren, was das Ökosystem einer Quelle nie ausliefert weiter unten).

Der Socket ist eine feste Menge von Exporten — einer verpflichtend, die übrigen optional und in describe() angekündigt:

  • render_node (verpflichtend) — rendert einen IR-Knoten in Provider-native Dateien.
  • assemble_boundary (optional) — führt die Ausgabe pro Knoten einer Verteilungsgruppe zu einem Artefakt pro Pfad zusammen (vorhanden, wenn boundary_assembly den Wert merge oder nest hat).
  • validate_node_input (optional) — strukturelle Validierung der Eingabe eines Knotens vor dem Rendering; eine Diagnose halt hält den Build an, eine warn erscheint im Build-Ergebnis.
  • carve / reassemble (optional, gepaart) — der eigene bytegetreue Patch-Codec des Guest für Pipeline-Schritte nach dem Rendering, nur verwendet, wenn beide angekündigt sind.
  • name_bound (optional) — der Guest beurteilt, ob ein Name, den der Host als Identität einer Komponente vorschlägt, Namen ergibt, die sein Ziel akzeptiert, und antwortet mit einer Einschränkung statt mit einem eigenen Namen.
  • rendered_name (optional) — der Guest meldet den Namen, den sein Ziel den Ressourcen gibt, die er für einen Knoten rendert.
  • link_publish / link_resolve (optional, gepaart) — der Guest verdrahtet eine Boundary-übergreifende Kante uses: Der konsumierte Endpunkt veröffentlicht ein Handle, und der konsumierende Endpunkt löst es in seine eigene assemblierte Ausgabe auf.

Die artifacts: eines Recipe fließen über eine Artefaktprojektion in der Eingabe in render_node ein: Der Host übernimmt das Lesen von $import, die Auswertung der Go-Templates und die Berechnung der Herkunfts-Schlüssel/Werte und übergibt dem Guest jeden Eintrag bereits gelesen und ausgewertet; der Guest verantwortet Platzierung und Ausgabe in dem Format, das nur er kennt. Dokumentiert in architecture/13-catalog-and-registry.md.

Die Eingabe eines Quell-Renderings trägt die Werte des Knotens in node.values, und node.values_mapped gibt an, woher sie stammen: Es ist true, wenn sie die Ausgabe des valuesMapping des Recipe sind — oder, beim eigenen Rendering einer Anbindung, die ihres FeatureRecipe —, und fehlt, wenn es die eigenen Werte der Komponente sind, so weitergereicht, wie sie geschrieben wurden. Ob ein Guest es liest, ist Teil des eigenen Vertrags dieses Guest. Der Provider cloudformation bindet die Parameters eines quellbasierten Templates nur an Werte, die ein Mapping erzeugt hat, weil die eigenen Werte einer Komponente für die anderen Eingaben des Recipe geschrieben worden sein können; der Provider terraform schreibt die Argumente eines quellbasierten Moduls aus den Werten, die seine Assemblierung erhält, und liest das Flag nicht. Diese Werte werden auf jedem gerenderten Knoten einer Eingabe von assemble_boundary für einen aus einer Quelle gerenderten Knoten übertragen — die einer Komponente, ob ein Mapping sie erzeugt hat oder nicht, die eines angebundenen Feature nur dort, wo das valuesMapping seines FeatureRecipe sie erzeugt hat —, und dasselbe Flag wird neben ihnen übertragen, und nur dort, wo sie übertragen werden, sodass ein Assembler dieselbe Antwort liest wie das eigene Rendering des Knotens; der Provider cloudformation liest es dort, um zu erfahren, welche Parameter das Binding eines Knotens befüllt hat, und lehnt einen Verweis auf einen davon von jeder anderen Stelle im Stack ab, die Host-Komponente eines angebundenen Feature eingeschlossen. Das Flag hält fest, wie die Werte erzeugt wurden, und wird nie aus einem Schlüssel oder einem Wert abgeleitet.

Übertragungskodierung. Jeder Export dieses Sockets erhält seine Eingabe und liefert seine Ausgabe als kanonisches CBOR (RFC 8949 §4.2.1), in beide Richtungen. Ein Guest dekodiert seine Eingabe und kodiert seine Ausgabe über die Einstiegspunkte, die die Payload-Typen bereits tragen — DecodeCBOR und EncodeCBOR in Go, decode_cbor und encode_cbor in Rust und in TypeScript die Funktionen decodeCBOR und encodeCBOR jedes Typs, etwa decodeCBORRenderNodeInput und encodeCBORRenderNodeOutput —, wobei er Bytes liest und schreibt (Vec<u8> in Rust, Host.inputBytes() und Host.outputBytes(...) in TypeScript). Es ist keine CBOR-Bibliothek nötig, und nichts parst Bytes von Hand. Der content einer gerenderten Datei und jedes andere Byte-Feld werden als rohe Bytefolge übertragen, die der generierte Decoder in den eigenen Feldtyp des Kits füllt: ein Byte-Slice in Go, ein Base64-String in Rust und TypeScript. Die Maps, die das Schema als reihenfolgeerhaltend markiert — darunter die values, features und uses eines Knotens, die derived_keys einer Antwort und die values eines Beitragenden einer Assemblierung —, werden als geordnete Listen von Einträgen in der Reihenfolge übertragen, in der der Build sie hält, und ein Guest liest sie über den reihenfolgeerhaltenden Container seines Kits. Jeder Wert der values eines Knotens wird als die Bytes seines eigenen JSON-Dokuments übertragen, sodass die Schlüssel innerhalb eines Werts die Reihenfolge behalten, in der sie geschrieben wurden; ebenso jeder Anbindungseintrag von features, der Render-Kontext, die geparste Arbeitslast, jede angereicherte Kante, jede herausgeschnittene Einheit und jede Patch-Operation, und ein Guest parst sie als JSON, um hineinzusehen. Jede Diagnose wird in der gemeinsamen Form Diagnostic übertragen. Eine Antwort, die in dieser Kodierung nicht die Ausgabeform ihres Exports hat — eine als JSON geschriebene oder eine, die ein Feld auf oberster Ebene trägt, das die Form nicht deklariert —, hält den Build an und nennt dabei den Export, den er aufgerufen hat. Die Payload-Beispiele auf dieser Seite sind zur besseren Lesbarkeit als JSON geschrieben. Direkt mit aggrega plugin run-local --export render_node oder mit einem anderen Export des Sockets aufgerufen, erhält ein Guest die vom Autor geschriebene JSON-Payload, in diese Kodierung umgewandelt, und seine Antwort wird als Ausgabeform des Exports gelesen und als JSON ausgegeben — eine Antwort, die diese Form nicht hat, wird unter Nennung des Exports abgelehnt, so wie ein Build sie ablehnt.

Status heute: verfügbar für alle fünf Provider. Der Guest helm rendert quellbasierte Charts (unter Auflösung des Chart-Stammverzeichnisses), synthetisierte Arbeitslasten und eigenständige Artefakte als flache Kubernetes-Manifeste. Der Guest helm-chart assembliert ein Umbrella-Chart, wobei er das quellbasierte Chart jedes Knotens als Sub-Chart verschachtelt, und bringt einen bytegetreuen Patch-Codec sowie Artefakt-Begrenzer in eckigen Klammern ([[ ]]) mit. Der Guest compose rendert quellbasierte Compose-Dateien und synthetisierte Arbeitslasten und führt eine Verteilungsgruppe zu einer einzigen docker-compose.yaml zusammen, wobei er einen Dienst mit den Netzwerken der Komponenten verbindet, die sein x-aggrega-networks-of benennt. Der Guest terraform erzeugt Terraform-Konfiguration unverändert (HCL oder JSON) oder übernimmt ein quellbasiertes Modul per Vendoring und liefert dessen Eingaben als Argumente des Modulblocks dieser Komponente, validiert das HCL eines quellbasierten Moduls vor dem Rendering strukturell und setzt eine Boundary zu einer einzigen Root-Konfiguration zusammen, die jede Komponente als Modulblock deklariert, dessen Quelle das eigene Unterverzeichnis dieser Komponente ist. Der Guest cloudformation rendert quellbasierte Templates und eigenständige Stack-Fragmente, führt eine Verteilungsgruppe zu einem einzigen Stack-Template zusammen und verdrahtet eine Boundary-übergreifende Kante uses über link_publish und link_resolve. Jeder rendert offline und deterministisch.

Die Namen deklarieren, die ein Guest ableitet

Ein Provider-Guest leitet üblicherweise Namen, die seine Ausgabe benötigt, die aber niemand geschrieben hat — den Bezeichner, über den ein Ziel eine Ressource adressiert, den Namen, unter dem eine Ausgabe veröffentlicht wird, damit eine andere darauf verweisen kann —, aus der Identität des Knotens und der Ressource ab, die er gerade ausgibt. Zwei Knoten können bei demselben Namen ankommen, wann immer die Teile, aus denen sie abgeleitet werden, übereinstimmen, und weil der Name in den Dateibytes steht, die der Host unverändert schreibt, kann der Host den Konflikt nicht sehen: Er müsste das Format des Providers parsen, um ihn zu finden, und das ist genau das Wissen, das im Guest bleibt.

render_node liefert deshalb in seiner Ausgabe optionale derived_keys, und die Richtung ist umgekehrt — statt dass der Host die Ausgabe untersucht, deklariert der Guest, und der Host prüft:

{
"files": [ { "path": "stack.yaml", "content": "..." } ],
"derived_keys": {
"logical-ids": ["paymentsapiQueue", "paymentsapiTopic"],
"export-names": ["aggrega--prod--api--orders-db--host"]
}
}

Jeder Schlüssel von derived_keys ist ein Schlüsselraum, den der Guest benennt, und jeder Raum trägt die Namen, die der Guest in ihn abgeleitet hat, in Ableitungsreihenfolge. Sowohl die Namen der Räume als auch die Namen darin sind Ihr Vokabular: Der Host liest sie nur als Strings, die innerhalb eines Raums auf Gleichheit verglichen werden. Er parst keinen Namen, erfährt nicht, was ein Raum oder ein Name bedeutet, und leitet nie selbst einen ab — so deckt eine einzige Prüfung jede Art von Namen ab, die irgendein Provider ableitet, und ein neuer Provider braucht keinen neuen Host-Code. In den veröffentlichten Typen ist derived_keys eine reihenfolgeerhaltende Map, sodass die Räume in der Reihenfolge übertragen werden, in der Ihr Guest sie setzt.

Was der Host damit tut, ist eine einzige Frage: Ist innerhalb eines Raums jeder deklarierte Name über die Beitragenden hinweg eindeutig, deren Ausgabe in eine Assemblierung zusammengeführt wird? Zwei Beitragende, die denselben Namen im selben Raum deklarieren, halten den Build an, und der Abbruch nennt den Raum, den Namen und beide Beitragenden, sodass ein Autor handeln kann, ohne den Provider zu lesen. Eindeutige Namen und Namen, die zufällig über zwei verschiedene Räume hinweg übereinstimmen, bestehen die Prüfung.

Drei Eigenschaften sollten Sie kennen, wenn Sie entscheiden, was Sie deklarieren:

  • Der Geltungsbereich ist eine assemblierte Ausgabe — die Menge der Beitragenden, deren Dateien zusammengeführt werden. Ein Guest, der Eindeutigkeit in einem engeren oder weiteren Geltungsbereich als diesem wünscht, drückt den Geltungsbereich im Namen des Raums aus, den er deklariert, wodurch die Wahl bei Ihnen bleibt statt beim Host.
  • Ein Beitragender darf einen Namen beliebig wiederholen. Ein Knoten kann über mehrere Übergänge rendern — ein Quell-Rendering, eine Arbeitslast-Synthese, eine Artefaktplatzierung —, und die Deklarationen werden zusammengeführt. Derselbe Name, zweimal von einem Beitragenden deklariert, bedeutet, dass dieser Beitragende eine Ressource zweimal beschreibt, nicht einen Konflikt.
  • Deklarieren ändert keine Bytes. Das Feld ist eine Aussage darüber, was der Guest abgeleitet hat, nie eine Änderung dessen, was er ausgegeben hat, sodass die gerenderte Ausgabe eines Guest identisch ist, ob er deklariert oder nicht. derived_keys wegzulassen ist gültig und lässt die Prüfung für diesen Guest wirkungslos.

Fakten darüber melden, was ein Guest ausgegeben hat

Manche Dinge am Rendering eines Knotens sind nur für den Provider sichtbar, der es erzeugt hat — was die von ihm geschriebenen Dokumente enthalten, welche Namen sie definieren, wie viele von etwas er ausgegeben hat —, weil sie aus den Dateibytes herauszulesen bedeutet, das Format des Providers zu verstehen. render_node kann solche Dinge selbst melden, in einer optionalen Liste render_facts neben seinen Dateien:

{
"files": [ { "path": "stack.yaml", "content": "..." } ],
"render_facts": [
{ "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] },
{ "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] }
]
}

Jeder Fakt besteht aus einem name und einem value, und beide gehören Ihrem Provider: Welche Fakten er meldet, was jeder Name bedeutet und was jeder Eintrag enthält, ist Teil des eigenen dokumentierten Vertrags Ihres Providers, also dokumentieren Sie sie für die Autoren, die sie lesen werden.

Melden Sie den Wert jedes Fakts als Liste — ein JSON-Array —, auch wenn sie einen einzigen Eintrag enthält. Ein Name kann von mehr als einem Rendering einer Komponente gemeldet werden: Ihr eigenes Rendering kann mehrere Aufrufe umfassen — etwa ein Chart-Rendering und eine Artefaktplatzierung —, und jedes an die Komponente angebundene Feature rendert über einen eigenen Provider-Aufruf. Kein Provider kann beim Rendern wissen, ob seine Meldung die einzige unter einem Namen sein wird, daher ist jede Meldung eine Liste, und der Compiler fügt die Listen, die ein Name erhält, zu einer Liste zusammen. Ein Fakt, dessen Wert etwas anderes ist — ein Objekt, ein String, eine Zahl, ein Boolean, null —, wird abgelehnt, wenn Ihr Guest ihn zurückgibt: Der Build hält mit dem Kurzcode E0325 an, nennt den Fakt, den Knoten und Ihren Guest und gibt an, welcher Wert vorlag. Die Einträge innerhalb einer Liste sind beliebige JSON-Werte in der Form, die Sie dokumentieren.

Dass ein Wert eine Liste ist, ist das Einzige, was der Compiler über ihn erfährt. Er schlüsselt die Fakten nach Namen auf und übergibt jede Liste an die Templates, die sie lesen — die Fakten der Host-Komponente an jedes an sie angebundene Feature, die Fakten jedes Aufrufers an ein Feature, das deklariert, dass es die Render-Fakten seiner Aufrufer liest, und die Fakten jedes Ziels an ein Feature, das deklariert, dass es die Render-Fakten der Komponenten liest, mit denen seine Host-Komponente verdrahtet ist, wie der Template-Kontext beschreibt —, wobei er jede Liste in einen Wert dekodiert, über den ein Template iterieren kann. Er erfährt nie, was ein Name oder ein Eintrag bedeutet, und leitet nie selbst einen Fakt ab, sodass ein neuer Provider neue Fakten melden kann, ohne dass sich auf der Seite des Compilers etwas ändert. Die Fakten, die ein an den Knoten angebundenes Feature aus seinem eigenen Rendering meldet, werden getrennt von denen gehalten, die das eigene Rendering des Knotens gemeldet hat.

Vier Eigenschaften sollten Sie kennen, wenn Sie entscheiden, was Sie melden:

  • Die Reihenfolge liegt bei Ihnen. Die Fakten behalten die Reihenfolge, in der Ihr Guest sie auflistet, und jeder Wert behält seine eigenen Bytes — die Reihenfolge der Einträge einer Liste und der Schlüssel jedes Objekts ist die Reihenfolge, die Ihr Guest geschrieben hat. Listen Sie die Fakten in einer festen Reihenfolge auf und schreiben Sie jeden Eintrag mit einer festen Schlüsselreihenfolge, sodass identische Eingaben identische Bytes erzeugen; eine Liste von Fakten statt einer Map gibt es gerade deshalb, damit diese Reihenfolge im eigenen Sequenztyp jedes Kits erhalten bleibt, ohne dass etwas zu markieren ist, während eine Map die von einem Guest geschriebene Reihenfolge nur dann behält, wenn ihr Schema sie als reihenfolgeerhaltend markiert und der Guest den reihenfolgeerhaltenden Container seines Kits befüllt.
  • Melden ändert keine Bytes. Die Dateien, die der Compiler schreibt, sind die Dateien, die Ihr Guest zurückgegeben hat, ob Fakten sie begleiten oder nicht.
  • Ein Knoten kann über mehrere Übergänge melden. Ein Knoten kann als Quell-Rendering, als Arbeitslast-Synthese und als Artefaktplatzierung rendern; die Fakten, die jeder davon meldet, werden in der Reihenfolge gehalten, in der die Übergänge liefen, und ein Name, der von mehr als einem davon gemeldet wird, liest sich als eine Liste, die sie in dieser Reihenfolge zusammenfügt.
  • Nichts zu melden ist vollständig. render_facts wegzulassen ist gültig, und ein Provider, der nichts meldet, rendert genau so, wie er es ohne das Feld täte.

Der Typ RenderFact wird in den drei ABI-Paketen veröffentlicht und vom Plugin-Entwicklungskit jeder Sprache re-exportiert, und die Render-Beispiele der Kits melden zwei Fakten neben ihren Dateien. In Go ist ein Wert das JSON, das Ihr Guest schreibt; ein Slice von Structs statt von Maps zu marshallen ist das, was die Schlüssel jedes Eintrags in der Reihenfolge hält, in der Sie sie deklariert haben:

type stackFact struct {
Name string `json:"name"`
Resources int `json:"resources"`
}
stacks, err := json.Marshal([]stackFact{{Name: "payments-api", Resources: 2}})
if err != nil {
pdk.SetError(err)
return 1
}
out := aggrega.RenderNodeOutput{
Files: files,
RenderFacts: []aggrega.RenderFact{{Name: "stacks", Value: stacks}},
}

Gerenderte Einheiten auslassen

Ein Quell-Rendering kann Einheiten benennen, die der Provider aus dem, was er rendert, auslassen muss — etwa ein Secret, das ein abgerufenes Chart bei jedem Rendering neu erzeugt. Welche gerenderte Einheit ein Eintrag benennt, ist Wissen, das nur Ihr Provider hat, daher gelangen die Einträge zu Ihrem Guest, und Ihr Guest übernimmt das Auslassen. Sie kommen in der Eingabe von render_node als optionale Liste omits neben dem source_listing an:

{
"node": { "id": "payments-api" },
"context": { },
"source_listing": { "root": "/acquired/payments-chart", "root_is_dir": true, "entries": [] },
"omits": [
{ "kind": "Secret", "name": "payments-api-token", "namespace": "payments" },
{ "kind": "ConfigMap", "name": "payments-api-dashboards" }
]
}

Jeder Eintrag besteht aus einem kind, einem name und einem optionalen namespace, bereits zu einfachen Strings aufgelöst und in der Reihenfolge aufgeführt, in der der Autor sie deklariert hat; ein Eintrag, der für den Build nicht gilt, wird nicht übertragen. Was die drei Felder auswählen, ist der eigene Vertrag Ihres Providers — Art, Name und Namespace einer Ressource im Format Ihres Ziels —, also dokumentieren Sie ihn für die Autoren, die die Einträge schreiben.

Ein Autor kann die Felder eines Eintrags aus einem Wert bilden, den er als sensibel deklariert hat — etwa eine Ressource, die nach einer sensiblen Einstellung benannt ist. Ein solcher Eintrag kommt mit "sensitive": true an, und Ihr Guest behandelt ihn so, wie er jeden anderen markierten Wert behandelt, den die Render-Eingabe trägt (siehe Werte, die eine Eingabe als sensibel markiert): Er gleicht den Eintrag weiterhin anhand seiner Felder ab und zählt ihn, wofür der Eintrag da ist, und hält jedes seiner Felder aus einer Ablehnung, einer Warnung oder einer Logzeile heraus. Die Markierung umfasst den gesamten Eintrag, weil der Compiler nicht angibt, welches Feld der Wert erzeugt hat. Sie fehlt, wenn kein Feld aus einem solchen Wert gebildet wurde.

Ein Guest, der die Einträge berücksichtigt, tut drei Dinge:

  • Er gleicht jeden Eintrag mit dem ab, was er gerendert hat, in den Begriffen Ihres Formats.
  • Er lässt jede abgeglichene Einheit aus allem aus, was er zurückgibt — aus seinen files, den Namen, die er in derived_keys deklariert, und den Fakten, die er in render_facts meldet —, sodass nichts, was der Compiler erhält, sie noch beschreibt.
  • Er meldet einen Zählwert pro Eintrag in einer optionalen Liste omitted in seiner Ausgabe, in der Reihenfolge, in der die Einträge ankamen, jeweils die Anzahl der Einheiten, auf die dieser Eintrag zutraf, gezählt unabhängig davon, ob auch ein anderer Eintrag auf sie zutraf:
{
"files": [ { "path": "templates/deployment.yaml", "content": "..." } ],
"omitted": [1, 0]
}

Eine Null ist eine vollständige Antwort: Dieser Eintrag traf auf nichts zu, was Ihr Guest gerendert hat. Die Zählwerte sind alles, was über das Ausgelassene zurückkommt; die Einheiten selbst fehlen einfach in dem, was Ihr Guest zurückgegeben hat.

Ein Provider, der alle drei Dinge tut, deklariert dies mit omits: true in seinem Vertrag. Die Entität Plugin hält denselben Anspruch als spec.provider.contract.omits fest; wo die Entität einen Render-Verhaltensvertrag trägt, lehnt das Laden einen Guest ab, dessen describe() einen anderen Wert meldet. Die Einträge begleiten eine Quellauflistung und nichts sonst: Ein Rendering einer synthetisierten Arbeitslast oder einer Artefaktmenge trägt sie nie.

Ein Rendering, das keine Einträge trägt, bleibt von den Feldern unverändert. Beide Felder sind optional und fehlen, wenn sie leer sind, sodass ein Rendering ohne Einträge den Socket Byte für Byte so durchquert, als gäbe es die Felder nicht, und ein Guest, der sie nie liest, von ihnen unberührt bleibt. Der Typ OmitEntry wird in den drei ABI-Paketen veröffentlicht und vom Plugin-Entwicklungskit jeder Sprache re-exportiert.

Was der Compiler mit Ihrer Antwort tut. Die Einträge stammen aus dem Schlüssel omits:, den ein Autor in ein Recipe oder ein FeatureRecipe schreibt (Recipe → Das Feld omits:); der Compiler wertet die Templates jedes Eintrags aus und übergibt Ihrem Guest diejenigen, die gelten. Dann liest er Ihre Zählwerte, und nur Ihre Zählwerte — er schaut nie in eine zurückgegebene Datei, um sie zu prüfen:

Status heute: verfügbar. Die mit dem Compiler ausgelieferten Guests helm, compose und cloudformation deklarieren den Anspruch und berücksichtigen die Einträge. Der Guest helm schreibt kein Feld irgendeines Eintrags in einen Text, den er zurückgibt. Die Guests compose und cloudformation nennen Art, Name und Namespace eines Eintrags, wenn sie den Eintrag ablehnen, und die Einheiten, die ein Eintrag ausgelassen hat, wenn sie eine Datei oder ein Template ablehnen, das sie noch nennt, und zeigen dort jedes Feld eines markierten Eintrags als <redacted>. Die Guests helm-chart und terraform deklarieren den Anspruch nicht, sodass ein Dokument, das omits: deklariert und von einem von ihnen gerendert wird, abgelehnt wird.

Dateien annehmen, die ein Recipe zur Boundary beiträgt

Manche Dateien gehören zu einer Boundary als Ganzes statt zu einer ihrer Komponenten — etwa eine Provider-Konfiguration, die ein Ziel einmal für alles liest, was die Boundary bereitstellt. Ein Recipe schreibt sie unter spec.boundary.artifacts, und der Compiler, nicht Ihr Guest, erledigt die Arbeit: Er wertet jede Datei in dem Kontext aus, in dem ein Eintrag artifacts: ausgewertet wird, führt die Dateien, die jeder Beitragende der Verteilungsgruppe deklariert hat, nach Namen zusammen und schreibt jede einmal in das Verzeichnis, das die assemblierte Ausgabe der Gruppe enthält, neben das, was Ihr assemble_boundary zurückgibt. Ihr Guest erhält keine dieser Dateien über irgendeinen Export und wird nie nach einer davon gefragt, sodass es nichts zu implementieren gibt — nur eine Aussage über Ihr Ziel zu treffen:

"contract": {
"input_kinds": { "sourced": true, "artifacts_standalone": true },
"boundary_assembly": "nest",
"boundary_artifacts": true
}

Deklarieren Sie boundary_artifacts: true nur, wenn Ihr Ziel eine in diesem Verzeichnis abgelegte Datei als Teil der Ausgabe der Boundary liest. Die Entität Plugin hält denselben Anspruch als spec.provider.contract.boundaryArtifacts fest; wo die Entität einen Render-Verhaltensvertrag trägt, lehnt das Laden einen Guest ab, dessen describe() einen anderen Wert meldet. Ein Recipe, das den Block deklariert und dessen Provider ihn nicht beansprucht, wird abgelehnt, bevor irgendetwas rendert, unter Nennung des Providers und der Komponente; siehe The provider does not support boundary artifacts (Der Provider unterstützt keine Boundary-Artefakte). Eine Datei, die eine dieser Zusammenführungen unter einem Namen ablegt, den auch Ihre Assemblierung schreibt, hält den Build als zwei Beitragende, die einen Ausgabepfad schreiben an, sodass die Namen, die Ihre Assemblierung schreibt, Teil dessen sind, was Sie für Autoren dokumentieren.

Status heute: verfügbar. Der mit dem Compiler ausgelieferte Guest terraform deklariert den Anspruch, und Terraform liest jede Datei neben der Root-Konfiguration der Boundary; die Guests helm, compose, helm-chart und cloudformation deklarieren ihn nicht.

Deklarieren, was das Ökosystem einer Quelle nie ausliefert

Das lokale Quellverzeichnis eines Recipe — ein am selben Ort abgelegtes Chart, ein Modul — wird mit dem Recipe veröffentlicht, und nicht jede Datei darin gehört dazu. Ein Provider-Guest gibt über source_ignore in seinem Vertrag an, was sein eigenes Ökosystem nie ausliefert, als Ignorierregeln in der Syntax, die .gitignore verwendet:

"contract": {
"input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false },
"boundary_assembly": "none",
"source_ignore": {
"patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"],
"files": [".helmignore"]
}
}
  • patterns sind Regeln, die vom Stamm des Quellverzeichnisses aus gelesen und der Reihe nach angewendet werden, wobei ein späterer Treffer einen früheren überschreibt.
  • files benennt die Ignorierdateien, die Ihr Ökosystem innerhalb einer Quelle berücksichtigt. Wo immer der Durchlauf durch eine Quelle auf eine solche trifft, werden ihre Zeilen als weitere Regeln für das Verzeichnis gelesen, das sie enthält, nach Ihren Mustern.

Die Deklaration wird gelesen, wenn eine Entität fixiert wird, nicht wenn sie gerendert wird. Der Fixierungsschritt des Autors löst in seinem Workspace das Plugin auf, das die Fähigkeit der Entität bedient, setzt Ihre Regeln mit seiner eigenen .aggregaignore zusammen — deren Zeilen zuletzt kommen und daher bei jedem Pfad gewinnen, den sie nennen — und zeichnet den Namen Ihres Plugins ohne Version zusammen mit den exakt zusammengesetzten Regeln in der entity.lock der Entität auf. Jede spätere Veröffentlichung, jeder Vergleich und jedes Rendering dieser Entität wendet die aufgezeichneten Regeln an; der Host gleicht sie ab und hat keine eigene Meinung zu irgendeinem Ökosystem. Die Dateien, die Ihr Guest beim Rendering erhält — die Auflistung und jede Datei, die er den Host packen oder lesen lässt —, sind also genau die Dateien, die eine Veröffentlichung der Entität enthält, und auf eine Datei, die die Regeln auslassen, wird unter Nennung ihres Namens geantwortet, sie sei nicht vorhanden. Ein symbolischer Link unter einer Quelle wird abgelehnt, bevor Ihr Guest aufgerufen wird.

Kompatibilität folgt aus dem, was aufgezeichnet wurde. Ein Guest kann ein für seine Fähigkeit veröffentlichtes Recipe rendern, wenn er dieselbe ABI-Version spricht, sein Vertrag der Angabe seiner Entität entspricht und er keine Datei außerhalb der veröffentlichten Menge benötigt. Ein Guest, der eine Datei benötigt, die die Menge ausgelassen hat, muss seinen Build deutlich sichtbar fehlschlagen lassen und die Datei nennen — die Ablehnung eines Packens oder Lesens durch den Host nennt sie, und ein Guest übernimmt das in seinen eigenen Fehlschlag. Wo das Plugin, das der Workspace eines Konsumenten für eine Fähigkeit bindet, andere Regeln deklariert als die, die die Lockfile einer Entität aufzeichnet, gibt der Pull des Konsumenten eine Warnung aus, die beide Plugins und den Unterschied nennt; er hält deswegen nie an.

Das Weglassen von source_ignore deklariert keine Regeln, und eine Quelle, die Sie rendern, behält dann jede Datei, die die eigenen Regeln des Autors behalten. Das Feld ist optional und benötigt keine eigene ABI-Version: Ein Guest, der es weglässt, wird als einer geladen, der nichts deklariert. Die Entität Plugin zeichnet dieselbe Deklaration als spec.provider.contract.sourceIgnore auf; wo sie das tut, lehnt das Laden einen Guest ab, dessen describe() etwas anderes meldet.

Determinismus und Wiederverwendung von Instanzen

Der Host übernimmt die Ausgabebytes eines Guest unverändert, daher muss ein Guest aus identischer Eingabe identische Ausgabe erzeugen. Standardmäßig wird ein Guest für jeden Knoten neu geladen — konstruktionsbedingt wird kein Zustand von Knoten zu Knoten übertragen. Ein Guest, der selbst reusable_instance deklariert, wird stattdessen einmal pro Build geladen, und seine einzige Instanz bedient jeden Übergang, was die dominierenden Instanziierungskosten pro Knoten einspart. Da Wiederverwendung nur für einen zustandslosen Guest sicher ist, rendert aggrega build --verify-determinism jeden Knoten zweimal über dieselbe Instanz und hält den Build an, wenn sich die beiden Renderings irgendeines Knotens unterscheiden; der Standard-Build rendert einmal und vertraut der Deklaration. Der Wasm-Kompilierungscache liegt auf der Festplatte und gilt prozessweit, sodass ein Guest einmal kompiliert wird und warme Builds die Neukompilierung überspringen.

Der Linter-Socket — der Veröffentlichungs-Linter

Der Linter-Socket wird als der standardmäßige publishing-linter ausgeliefert, ein Out-of-Band-Prüfpunkt, der über aggrega lint statt zur Kompilierzeit läuft. Er konsumiert eine Katalog-Entität (und im Modus --pre-publish die aktuell veröffentlichte Version der Entität) und gibt eine Liste von Befunden zurück, jeder mit einem Schweregrad und einer Meldung; im Modus --pre-publish gibt er zusätzlich eine Klassifizierung der Versionserhöhung zurück. Der Host verteilt ihn über die eingebettete Wasm-Runtime, hinter derselben AOT-Reinheits-Firewall wie jeden anderen Socket. Der vollständige Regelsatz, die Schweregrade und die Opt-outs pro Regel sind unter cli/aggrega-lint.md dokumentiert.

Der Linter ist eine Katalogdisziplin auf Opt-in-Basis: Der Compiler führt ihn während aggrega build nicht aus (mit der einzigen Ausnahme des Hinweises, der von x-aggrega-* abrät und der während des Builds mit dem Schweregrad warn und unter aggrega lint --pre-publish mit dem Schweregrad halt erscheint). Da die Regeln in einem Plugin liegen, kann ein Unternehmen aggrega lint auf ein anderes Linter-Plugin richten, um seine eigene Disziplin durchzusetzen.

Kein Parameterwert erreicht ein Linter-Plugin, in keinem Geltungsbereich, in dem aggrega lint läuft. Bevor ein Dokument übergeben wird, hält der Host die Parameter-Standardwerte eines Aggregate, die Werte, die es an jedes importierte Modul übergibt, und die Parameter eines Release zurück und behält dabei den Vertrag jeder Parameterdeklaration — nur die Schlüssel, mit denen eine Deklaration geschrieben ist, auf jeder Ebene ihrer Verschachtelung — und jeden Template-Text bei, der einen Parameter liest: Der Wert eines Parameters kann selbst eine Anmeldeinformation sein, und das hier angebundene Plugin kann Code sein, den der Workspace nicht geschrieben hat. Was jedes Dokument enthält, ist unter Was ein Linter-Plugin übergeben bekommt beschrieben.

Übertragungskodierung. Die Eingabe und die Ausgabe werden beide als kanonisches CBOR (RFC 8949 §4.2.1) übertragen. Ein Guest dekodiert seine Eingabe und kodiert seine Ausgabe über die Einstiegspunkte, die LinterInput und LinterOutput seines Kits bereits tragen — DecodeCBOR und EncodeCBOR in Go, decode_cbor und encode_cbor in Rust, decodeCBORLinterInput und encodeCBORLinterOutput in TypeScript —, wobei er Bytes liest und schreibt (Vec<u8> in Rust, Host.inputBytes() und Host.outputBytes(...) in TypeScript). Es ist keine CBOR-Bibliothek nötig, und nichts parst Bytes von Hand. Die Entitätsdokumente — proposed, previous, implemented_component und release — und jeder Wert von components werden als die Bytes ihrer JSON-Dokumente übertragen, sodass ein Guest sie als JSON parst, um hineinzusehen. components ist eine Map, die das Schema als reihenfolgeerhaltend markiert, daher wird sie in der Eingabe einer Regel, die ein ganzes Release liest, als geordnete Liste von Einträgen in der Reihenfolge übertragen, in der das Aggregate seine Komponenteninstanzen deklariert, und ein Guest liest sie über den reihenfolgeerhaltenden Container seines Kits. policies wird als Map übertragen, die nur die gesetzten Flags enthält, sodass ein Flag, das sie nicht enthält, als falsch gelesen wird, und jeder Befund wird in der gemeinsamen Form Diagnostic übertragen. Eine Antwort, die in dieser Kodierung kein LinterOutput ist — eine als JSON geschriebene oder eine, die ein Feld auf oberster Ebene trägt, das die Form nicht deklariert —, lässt den Lint fehlschlagen und nennt dabei den aufgerufenen Export, statt als Lauf gelesen zu werden, der nichts gefunden hat. Direkt mit aggrega plugin run-local --export lint_rules aufgerufen, erhält ein Linter die vom Autor geschriebene JSON-Payload, in diese Kodierung umgewandelt, und seine Antwort wird als Ausgabeform des Exports gelesen und als JSON ausgegeben — eine Antwort, die diese Form nicht hat, wird unter Nennung des Exports abgelehnt, so wie ein Build sie ablehnt.

Status heute: verfügbar. Der publishing-linter wird ausgeliefert und läuft über den Host per aggrega lint.

Der Parser-Socket — kanonische Baumausgabe

Ein Parser wandelt eine Quelle, die in einem Format geschrieben ist, das der Compiler nicht nativ liest, in einen kanonischen strukturierten Baum um, sodass ein Konsument den Baum liest, statt einen eigenen Parser mitzubringen. Der Host löst den Parser auf, der das angeforderte Format als parse:<format> anbietet, und ruft dessen Export parse an drei Stellen auf: wenn einer Richtlinie der Rolle render-verdict ein gerendertes Artefakt in einem Format übergeben wird, das sie nicht nativ liest, wenn ein Importer den Host über aggrega_parse_source um einen Baum bittet, und wenn ein Import erkannt wird, der kein Format nennt (siehe den Importer-Socket weiter unten). Ein Guest ruft nie selbst einen Parser auf.

Eingabeform (Host → Guest). Ein Dokument vom Typ ParseInput mit:

  • format — das angeforderte Format, eine der Fähigkeiten parse:<format> des Parsers ohne ihr Präfix.
  • bytes — die Quellbytes.
  • options — ein Optionsdokument, das der Konsument für parserspezifisches Verhalten liefert, unverändert weitergereicht. Fehlt, wenn der Konsument keines liefert.

Ausgabeform (Guest → Host). Ein Dokument vom Typ ParseOutput mit dem tree — der geparsten Quelle als JSON-Dokument, dessen oberste Ebene ein Objekt, ein Array oder ein Skalar sein kann — allen Diagnosen in der gemeinsamen Form Diagnostic, optionalen Quellbereichen, die Baumknoten in den ursprünglichen Bytes verorten, und einem Fehlschlag in error, wenn das Parsen nicht abgeschlossen werden konnte. Jedes Feld und seine Einschränkungen stehen in der generierten Schemareferenz des Parser-Sockets.

Übertragungskodierung. Die Eingabe und die Ausgabe werden beide als kanonisches CBOR (RFC 8949 §4.2.1) übertragen, die Kodierung, in der dasselbe ParseInput übertragen wird, wenn ein Guest es an aggrega_parse_source übergibt. Ein Guest dekodiert seine Eingabe und kodiert seine Ausgabe über die Einstiegspunkte, die ParseInput und ParseOutput seines Kits bereits tragen — DecodeCBOR und EncodeCBOR in Go, decode_cbor und encode_cbor in Rust, decodeCBORParseInput und encodeCBORParseOutput in TypeScript —, wobei er Bytes liest und schreibt (Vec<u8> in Rust, Host.inputBytes() und Host.outputBytes(...) in TypeScript). Es ist keine CBOR-Bibliothek nötig, und nichts parst Bytes von Hand. Die Quellbytes werden als rohe Bytefolge übertragen, und der generierte Decoder füllt sie in den eigenen Feldtyp des Kits: ein Byte-Slice in Go, ein Base64-String in Rust und TypeScript. options und tree werden als die Bytes ihrer JSON-Dokumente übertragen, sodass der Baum, den ein Parser schreibt, seinen Konsumenten unverändert erreicht. Ein Parser, der nicht abschließen kann, sagt im error der Ausgabe, warum, und das Parsen schlägt unter Nennung des Parsers und dieser Meldung fehl; eine Antwort, die in dieser Kodierung kein ParseOutput ist — eine als JSON geschriebene oder eine, die ein Feld auf oberster Ebene trägt, das die Form nicht deklariert —, lässt das Parsen ebenfalls fehlschlagen und nennt dabei den Parser und seinen Export parse. Ein fehlgeschlagenes Parsen hält einen Build in der Rolle render-verdict an und erreicht einen Importer als der Fehlschlag, mit dem aggrega_parse_source antwortet. Ebenso eine Quelle, die der Parser ablehnt — eine, auf die er mit einer Diagnose halt neben seinem Baum antwortet: Der Aufruf des Importers schlägt mit der Meldung jeder solchen Diagnose fehl, in der Reihenfolge des Parsers, und erhält den Baum nie. Direkt mit aggrega plugin run-local --export parse aufgerufen, erhält ein Parser die vom Autor geschriebene JSON-Payload, in diese Kodierung umgewandelt — die Quelle in dieser Payload als Base64 geschrieben, so wie JSON jedes Byte-Feld schreibt —, und seine Antwort wird als Ausgabeform des Exports gelesen und als JSON ausgegeben — eine Antwort, die diese Form nicht hat, wird unter Nennung des Exports abgelehnt, so wie ein Build sie ablehnt.

Typdefinitionen. Die Übertragungstypen des Parsers — ParseInput, ParseOutput, NodeSpan und SourceSpan — sind in allen drei ABI-Paketen veröffentlicht und werden vom Plugin-Entwicklungskit jeder Sprache re-exportiert, generiert aus einem einzigen Codec, sodass die drei im Gleichschritt bleiben. Das Beispiel parse jedes Kits liest seine Eingabe und schreibt seine Ausgabe auf diese Weise, ebenso die Parser für HCL, TOML, YAML, JSON und JSON mit Kommentaren, die in der Binärdatei mitgeliefert werden.

Status heute: verfügbar — verteilt in der Rolle render-verdict für ein Artefakt in einem Format, das die Richtlinie nicht nativ liest, über aggrega_parse_source für einen Importer und zum Erkennen des Formats eines Imports, der keines nennt.

Der Importer-Socket — Ausgabe von Authoring-Entwürfen

Ein Importer wandelt eine Quelle, die für ein anderes Werkzeug geschrieben wurde — etwa einen aus einem Agent-Builder exportierten Flow —, in Aggrega-Authoring-Dateien als Entwurf um. Er läuft Out-of-Band: aggrega import, die Methode aggrega/import der Editor-Sitzung und das für den Assistenten bestimmte Werkzeug import lösen den Importer auf, der das angeforderte Format als import:<format> anbietet, und rufen dessen Export import einmal pro Import auf. Ein Build verteilt ihn nie. Welcher Importer läuft und was ein Operator ihm übergibt, ist unter Welcher Importer eine Quelle in Entwürfe umwandelt beschrieben. Die eigenen Importer des Compilers, einer für jedes Format, das er liest, sind unter Core-Importer beschrieben: welche Formate das sind, was jeder liest, was er entwirft, welche Einstellungen er annimmt, ihre Veröffentlichung mit jedem Compiler-Release und wie ein Import einen abruft und verifiziert, den der Rechner noch nicht enthält.

Eingabeform (Host → Guest). Ein Dokument vom Typ ImportInput mit:

  • format — das Format, das der Import angefordert hat, eine der Fähigkeiten import:<format> des Importers ohne ihr Präfix.
  • bytes — die Quellbytes: die ganze Datei bei einem Import einer Datei und leer bei einem Import eines Verzeichnisses, dessen Dateien unter sources ankommen.
  • name — der Name der Quelle, ohne vorangestelltes Verzeichnis, damit der Importer die Quelle in dem, was er meldet, und in dem, was er entwirft, benennen kann: bei einem Import einer Datei der Basisname der Datei, aus der bytes gelesen wurde; bei einem Import eines Verzeichnisses der eigene Basisname des Verzeichnisses, aus seinem vollständigen Pfad gelesen, sodass aggrega import . den Namen des Verzeichnisses übergibt, in dem es läuft, während die Dateien des Verzeichnisses weiterhin jeweils unter ihrem eigenen Namen ankommen. Fehlt, wo die Quelle keinen Namen zu geben hat.
  • sources — die benannten Quellen, jede mit ihrem Namen und ihren Bytes, in einer einzigen nach Namen sortierten Liste: bei einem Import eines Verzeichnisses jede seiner Dateien, die die deklarierten Dateimuster des Importers auswählen, ohne den Build-Ausgabeordner des Workspace, benannt nach ihrem durch Schrägstriche getrennten Pfad innerhalb des Verzeichnisses; und die Dateien, die der Eintrag plugins.importer, der diesen Importer anbindet, unter with.sources deklariert, jede unter ihrem Basisnamen. Eine Verzeichnisdatei und eine Datei aus with.sources mit demselben Namen führen zur Zurückweisung des Imports, statt dass die eine die andere verdeckt. Fehlt, wo es keine gibt.
  • settings — das Einstellungsobjekt, das dieser Eintrag unter with.settings deklariert, als JSON-Dokument mit sortierten Schlüsseln, unverändert weitergereicht. Fehlt, wenn kein Eintrag den Importer anbindet oder der Eintrag keines deklariert.
  • catalog — eine Sicht auf die Components, die der eigene Katalog des Workspace enthält: den Katalog, aus dem der Importer selbst ausgewählt wurde — die Katalogordner des Workspace oder, wo er keinen nennt, den Katalog-Snapshot, den seine Standard-Registry veröffentlicht, auf diesem Rechner gehalten —, ohne dass für die Sicht selbst etwas abgerufen wird. Ihre Liste components enthält einen Eintrag pro Component-Name, nach Namen sortiert; wo der Katalog mehrere Versionen einer Component enthält, beschreibt der Eintrag die Version, zu der sich ein Verweis auflöst, der sie ohne Version nennt. Jeder Eintrag trägt name und version der Component, ihre labels, die Schlüsselnamen der obersten Ebene, die ihre values und provides deklarieren (values und provides, jeweils sortiert), und ihre sockets — jeder mit dem name des Sockets und dem selector aus Labels, den eine über ihn verbundene Abhängigkeit erfüllen muss — in der Reihenfolge, in der die Component sie deklariert. Eine Component, die eine andere erweitert, trägt das, was sie erbt, ebenso wie das, was sie deklariert, und die Sockets, die sie erbt, kommen zuerst. Die Sicht enthält nur Namen, Versionen, Labels und Selektoren — nie einen Wert, einen Standardwert oder ein Secret — und ihre Reihenfolge ist fest, sodass ein Katalog eine einzige Bytefolge ergibt. Fehlt, wenn der Katalog keine Component enthält.

Ausgabeform (Guest → Host). Ein Dokument vom Typ ImportOutput mit den Entitäten, die der Import erzeugt hat — jede ein Verweis auf eine bestehende Katalog-Entität oder ein entworfener Inhalt —, den Zuordnungsentscheidungen dahinter, allen Diagnosen in der gemeinsamen Form Diagnostic, den zu schreibenden Scaffold-Dateien und einem Fehlschlag in error, wenn der Import nicht abgeschlossen werden konnte. Jedes Feld und seine Einschränkungen stehen in der generierten Schemareferenz des Importer-Sockets.

Übertragungskodierung. Die Eingabe und die Ausgabe werden beide als kanonisches CBOR (RFC 8949 §4.2.1) übertragen. Ein Guest dekodiert seine Eingabe und kodiert seine Ausgabe über die Einstiegspunkte, die ImportInput und ImportOutput seines Kits bereits tragen — DecodeCBOR und EncodeCBOR in Go, decode_cbor und encode_cbor in Rust, decodeCBORImportInput und encodeCBORImportOutput in TypeScript —, wobei er Bytes liest und schreibt (Vec<u8> in Rust, Host.inputBytes() und Host.outputBytes(...) in TypeScript). Es ist keine CBOR-Bibliothek nötig, und nichts parst Bytes von Hand. settings wird innerhalb des binären Dokuments als die Bytes seines JSON-Dokuments übertragen, sodass ein Guest es als JSON parst, um hineinzusehen, wie bei jedem anderen Socket. Ein Importer, der nicht abschließen kann, sagt im error der Ausgabe, warum, und der Import hält unter Nennung des Importers und dieser Meldung an; eine Antwort, die in dieser Kodierung kein ImportOutput ist — eine als JSON geschriebene oder eine, die ein Feld auf oberster Ebene trägt, das die Form nicht deklariert —, hält den Import ebenfalls an und nennt dabei den Importer und seinen Export import. Direkt mit aggrega plugin run-local --export import aufgerufen, erhält ein Importer die vom Autor geschriebene JSON-Payload, in diese Kodierung umgewandelt, und seine Antwort wird als Ausgabeform des Exports gelesen und als JSON ausgegeben — eine Antwort, die diese Form nicht hat, wird unter Nennung des Exports abgelehnt, so wie ein Build sie ablehnt.

Wie eine Quelle Ihres Formats erkannt wird. Ein Import muss kein Format nennen, und der Host erkennt dann eines anhand dessen, was die Importer deklarieren, ohne selbst ein Format zu kennen. Ein Importer deklariert in seiner Selbstauskunft describe() unter importer (einem ImporterContract) eine Liste detect der Signaturen, an denen eine Quelle seiner Formate erkannt wird. Jede DetectSignature nennt:

  • syntax — das syntaktische Format, als das die Quelle geparst wird, ein Format, das ein Parser-Plugin als parse:<syntax> anbietet, etwa json oder yaml;
  • files — optionale Dateinamenmuster, die mit dem Ende des Namens der Quelle verglichen werden: ein Segment mit dem eigenen Namen der Datei, mehrere durch Schrägstriche getrennte Segmente mit ebenso vielen abschließenden Segmenten ihres Pfads, wobei *, ? und [...] innerhalb eines Segments abgleichen. Eine Signatur, die keine deklariert, gilt für eine Quelle, die eine einzelne Datei ist, wie auch immer sie heißt, und für keine Datei eines Verzeichnisses;
  • match — die Prädikate, die der geparste Baum alle erfüllen muss, jedes ein PathMatch mit einem path aus durch Punkte verbundenen Schlüsseln von der Spitze des Baums aus (ein ganzzahliges Segment wählt eine Array-Position aus), einem is aus present, absent, object, array, string, number oder boolean und optional einem String equals oder einem String prefix — höchstens einem der beiden.

Wenn ein Import kein Format nennt, gleicht der Host die Signaturen aller Importer ab, unter denen der Import auswählt — derjenigen im Katalog des Workspace und der Core-Importer des Compilers —, in der Reihenfolge ihrer Identität und Version: Er parst die Quelle über den Parser, den der Katalog für eine Syntax bereitstellt — oder, für eine Syntax, für die der Katalog keinen Parser bereitstellt, über den, den der Compiler selbst mitbringt —, höchstens einmal pro Syntax, wertet die Prädikate über dem Baum aus und liest die Quelle als das Format des einen Importers, dessen Signatur zutrifft. Das ist auch der Parser, über den der Aufruf aggrega_parse_source eines Importers beantwortet wird, sodass ein Importer seine Quelle über den Parser liest, über den sie erkannt wurde. Eine Quelle, die sich in einer Syntax nicht parsen lässt, trifft auf keine Signatur zu, die diese Syntax nennt; eine Syntax, für die weder der Katalog noch der Compiler einen Parser bereitstellt, stoppt die Erkennung unter Nennung des fehlenden Parsers. Eine Quelle, auf die keine Signatur zutrifft, wird mit der Aufforderung zurückgewiesen, das Format zu nennen, und eine, die als mehr als ein Format erkannt wird, wird unter Nennung dieser Formate zurückgewiesen. Eine Signatur erkennt eine Quelle als jedes Format, das ihr Importer anbietet, daher bedient ein Importer, dessen Quellen erkannt werden sollen, ein einziges Format, und einer, der keine Signatur deklariert, wird nur durch Nennung seines Formats erreicht.

Die Plugin-Entität des Importers zeichnet dieselbe Liste als spec.importer.detect auf, abgeleitet aus describe(), wenn die Entität aus dem Guest generiert wird; die Erkennung liest diese Aufzeichnung, sodass der Guest erst geladen wird, wenn sein Format feststeht. Das Laden und das Veröffentlichen des Guest lehnen einen ab, dessen Selbstauskunft von der Aufzeichnung seiner Entität abweicht, unter Nennung von importer.detect, und eine Entität, die keine aufzeichnet, erhebt keinen Anspruch. Der Deskriptor wird beim Laden abgelehnt, wo der Vertrag auf einem Plugin deklariert ist, das kein Importer ist, wo eine Signatur keine Syntax oder ein fehlerhaftes Dateimuster nennt und wo ein Prädikat keinen Pfad, ein is außerhalb der sieben oder sowohl equals als auch prefix nennt.

Die Core-Importer des Compilers und das Beispiel import des Go-Kits deklarieren ihre Signaturen auf diese Weise. Der Langflow-Importer liest eine Quelle als JSON und verlangt ein Array unter data.nodes; der Flowise-Importer verlangt Arrays unter nodes und edges und nichts unter data.nodes; der n8n-Importer verlangt ein Array unter nodes, ein Objekt unter connections und nichts unter edges oder data.nodes; der MCP-Importer deklariert eine Signatur pro Client-Konfiguration, die deren Datei nennt — .mcp.json, claude_desktop_config.json und .cursor/mcp.json, als JSON gelesen mit einem Objekt unter mcpServers, und .vscode/mcp.json, als JSON mit Kommentaren gelesen, wie Visual Studio Code es liest, mit einem Objekt unter servers — und eine, die keine Datei nennt und einen String $schema verlangt, der mit https://static.modelcontextprotocol.io/schemas/ beginnt; der Compose-Importer liest eine Quelle als YAML, nennt die Dateien, die Compose standardmäßig liest — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml und ihre vier Überschreibungsdateien — und verlangt ein Objekt unter services; der Dify-Importer liest eine Quelle als YAML, nennt keine Datei und verlangt den String app unter kind sowie etwas unter app.mode und unter version; der CrewAI-Importer nennt config/agents.yaml und config/tasks.yaml, als YAML gelesen, ohne etwas vom Baum zu verlangen, crew.jsonc und crew.json, als JSON mit Kommentaren gelesen mit einer Liste unter agents, und agents/*.jsonc und agents/*.json, als JSON mit Kommentaren gelesen mit etwas unter role, sodass keine zwei davon auf dieselbe Quelle zutreffen, und eine einzeln importierte Datei ohne genanntes Format wird sowohl als YAML als auch als JSON gelesen; der LangGraph-Importer nennt langgraph.json, als JSON gelesen mit einem Objekt unter graphs, deklariert eine Signatur, die keine Datei nennt und ein Objekt unter graphs sowie den String https://langgra.ph/schema.json unter $schema verlangt, und nennt keine Umgebungsdatei, da die Erkennung jede Datei liest, die die Muster irgendeines Importers auswählen, sodass ein Muster, das eine solche nennt, die Umgebungsdateien jedes ohne Formatangabe importierten Verzeichnisses öffnen würde; der Google-ADK-Importer nennt root_agent.yaml, als YAML gelesen mit etwas unter name und unter instruction oder einem String unter agent_class und etwas unter name, und nennt keine andere Datei, da die Konfiguration eines Sub-Agenten beliebig heißen kann und ein Muster, das jede YAML-Datei nennt, jede einzelne davon in jedem ohne Formatangabe importierten Verzeichnis öffnen würde; der Agent-Framework-Importer liest eine Quelle als YAML, nennt keine Datei und verlangt den String Prompt unter kind und ein Objekt unter model; das Beispiel import des Go-Kits liest eine Quelle als YAML und verlangt den String DemoSource unter kind. In Go:

Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{
Syntax: "json",
Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},
}}},

Was ein Import eines Verzeichnisses liest. Eine Quelle kann ein Verzeichnis sein, und die deklarierten Dateimuster des Importers entscheiden, was er liest: Der Host liest genau die Dateien des Verzeichnisses, in beliebiger Tiefe, die eines der Muster files der Signaturen des Importers auswählt — jedes mit dem Ende des durch Schrägstriche getrennten Pfads der Datei innerhalb des Verzeichnisses verglichen — und übergibt sie als sources in Namensreihenfolge, mit leerem bytes und dem eigenen Namen des Verzeichnisses als name. Keine andere Datei des Verzeichnisses wird geöffnet. Der Ordner, in den ein Build des Arbeitsbereichs seine gerenderten Dateien schreibt — dist/ unterhalb des Stammverzeichnisses des Arbeitsbereichs —, wird nicht als Teil eines Verzeichnisses gelesen, das ihn enthält: Keine seiner Dateien wird übergeben oder erkannt, und ein Link, der zu ihm führt, wird übergangen, sodass ein Verzeichnis, das gebaut wurde, als das Projekt gelesen wird, das es enthält, während ein Verzeichnis, das dieser Ordner ist oder in ihm liegt, so gelesen wird, wie es angegeben ist. Eine Signatur, die keine Muster files deklariert, wählt keine Datei eines Verzeichnisses aus, daher liest ein Importer, der keine deklariert, eine einzelne Datei und weist ein Verzeichnis zurück, und auch ein Verzeichnis, das keine Datei enthält, die seine Muster auswählen, wird zurückgewiesen. Das Verzeichnis bleibt auf sich selbst beschränkt: Ein Link unter den Dateien, die er lesen würde, oder auf ein Verzeichnis, der aus dem Verzeichnis hinausführt, wird zurückgewiesen, bevor irgendetwas gelesen wird, ein Link auf ein Verzeichnis wird nie betreten, und ein Link auf eine Datei, die kein Muster auswählt, wird ungelesen übergangen. Das Erkennen des Formats eines Verzeichnisses folgt derselben Regel — jede Signatur wird gegen die Dateien probiert, die ihre Muster auswählen, in Namensreihenfolge, jede Datei höchstens einmal pro Syntax gelesen und geparst, und eine Signatur, die kein Muster deklariert, gilt für keine davon. Der Host begrenzt nichts: Ein Verzeichnis, das für den Importer zu groß ist, wird durch die eigenen Laufzeitgrenzen des Importers zurückgewiesen. Keiner der Importer des Compilers für Langflow, Flowise, n8n, Dify und Agent Framework deklariert Muster files, daher liest jeder eine einzelne Datei; sein MCP-Importer deklariert die Namen der vier Client-Konfigurationen, daher liest er jede davon, die ein Verzeichnis enthält; sein Compose-Importer deklariert die acht Compose-Dateinamen, daher erhält er jede Compose-Datei, die ein Verzeichnis enthält, und führt diejenigen zusammen, die Compose lesen würde; und sein CrewAI-Importer deklariert die sechs Namen, unter denen die Deklarationen eines CrewAI-Projekts geschrieben werden, daher erhält er die Deklarationen eines Projekts und nichts von seinem Programm; und sein LangGraph-Importer deklariert langgraph.json, daher erhält er die Konfiguration einer Anwendung und nichts von ihrem Code oder ihren Umgebungsdateien, wobei eine Umgebungsdatei ihn nur unter dem with.sources seiner Anbindung erreicht; und sein Google-ADK-Importer deklariert root_agent.yaml, daher erhält er die Konfiguration des Wurzelagenten einer Anwendung und nichts von ihrem Code oder ihrer Umgebungsdatei, wobei die Konfigurationen, die ihre Sub-Agenten nennen, ihn nur unter dem with.sources seiner Anbindung erreichen.

Typdefinitionen. Die Übertragungstypen des Importers — ImportInput, ImportSource, CatalogProjection, CatalogComponent, CatalogSocket, ImportOutput und die Entitäts-, Entscheidungs- und Scaffold-Formen, die es trägt — sind in allen drei ABI-Paketen veröffentlicht und werden vom Plugin-Entwicklungskit jeder Sprache re-exportiert, generiert aus einem einzigen Codec, sodass die drei im Gleichschritt bleiben, und ebenso die Erkennungstypen ImporterContract, DetectSignature und PathMatch, die die describe-Selbstauskunft trägt. Das Importer-Paket des Go-Kits, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer, trägt alles, was ein Importer unabhängig von seinem Format tut, und die Core-Importer des Compilers, die alle darauf aufbauen, lesen ihre Eingabe und schreiben ihre Ausgabe auf diese Weise.

Wogegen ein auf dem Go-Kit aufbauender Importer bewertet. Der Bewerter des Kits gewichtet jeden Quellknoten gegen die Components der Sicht catalog und gegen nichts anderes: Die Kandidaten sind der eigene Katalog des Workspace — die Components eines Unternehmenskatalogs genauso wie die der Standardbibliothek —, und das Kit trägt keinen eigenen Kandidaten. Von jeder Component liest er den Namen, die Kategorie, die ihr Label component.aggrega.ai/category trägt, ihre Labels und die Schlüsselnamen, die ihre values deklarieren; ihre Schlüssel unter provides und ihre Sockets werden nicht gewichtet. Eine dem Katalog hinzugefügte Component ist beim nächsten Import ein Kandidat, ohne dass ein Importer neu gebaut wird. Wo die Sicht fehlt, weil der Katalog keine Component enthält, hat kein Knoten einen Kandidaten: Auf keinen wird verwiesen und keiner wird vorgeschlagen, und jeder Knoten, dem der Entwurf eine eigene Component gibt, wird entworfen. Jeder Importer, der über das Kit bewertet, bewertet auf diese Weise — darunter die Importer des Compilers für Langflow, Flowise, n8n und Compose, während sein MCP-Importer keinen Kandidaten gewichtet; ein Importer, der das Kit nicht verwendet, liest die Sicht, wie er will.

Wofür ein auf dem Go-Kit aufbauender Importer die Sockets einer Plattform liest. Sockets haben in einer Bewertung kein Gewicht, aber das Kit liest sie, um einen Entwurf anzuordnen. Ein Format, dessen Flows eine Plattform so ausführt, wie sie geschrieben sind — wie es die von Langflow, Flowise und n8n tun —, wird standardmäßig als eine Instanz der Component dieser Plattform entworfen, die den Flow trägt, und jeder Bestandteil des Flows wird mit dem ersten Socket verbunden, in der Reihenfolge, in der der Eintrag catalog der Plattform ihre sockets aufführt, dessen selector die Labels der Component des Bestandteils erfüllen, so wie die Sicht diese Labels trägt. Nur der Selektor und die Labels werden gelesen, und der Selektor wird von einer Funktion abgeglichen, die der Importer bereitstellt, da das Kit keine eigene Selektorgrammatik trägt; wo die Sicht keine Component mit dem Namen der Plattform enthält, wird kein Bestandteil verbunden. Core-Importer beschreibt den Entwurf, den die Importer des Compilers für Langflow, Flowise und n8n auf diese Weise erstellen, und die Einstellung layout, die stattdessen jeden Knoten als eigene Component entwirft.

Status heute: verfügbar — verteilt durch aggrega import und durch dieselbe Operation in der Editor-Sitzung und im für den Assistenten bestimmten Werkzeug.

Platzierungskriterium: der Linter-Socket gegenüber den Verdikt-Rollen der Governance

Zwei der dokumentierten Sockets haben eine ähnliche Oberfläche — beide geben Ergebnisse pro Regel aus —, unterscheiden sich aber in der Platzierung in der Pipeline und in der Blockiersemantik. Das Kriterium für die Entscheidung, welcher Socket eine bestimmte Prüfung trägt:

  • Die Verdikt-Rollen der Governance (in-band, build-abbrechend). Vorbehalten für build-abbrechende Richtlinien: Ein Verdikt halt stoppt die Kompilierungs-Pipeline, und der Build erzeugt keine Artefakte. Anwendungsfälle sind Richtlinien, deren Verletzung die Anwendung der Ausgabe unsicher macht: Compliance-Prüfpunkte (Platzierung der Boundaries für PCI / SOC2), Topologie-Invarianten (Zero-Trust-Ingress, Authentifizierung über Boundaries hinweg), Form des Anmeldedatenflusses (keine Secrets im Klartext in der IR) usw. Eine Richtlinie wertet den IR-Graphen (ir-verdict, vor dem Rendering) oder die gerenderten Artefakte (render-verdict, nach dem Rendering) aus.
  • Der Linter-Socket (out-of-band, CI / IDE, beratend). Vorbehalten für Best-Practice- und Auffindbarkeitsprüfungen: Regeln, deren Verletzung verdächtig, aber nicht unsicher ist — verwaiste Secrets, ungenutzte Parameter, veraltetes Label-Vokabular, Vollständigkeit der Tags für die Kostenzuordnung, Abweichung von Benennungskonventionen. Ein Fehlschlag erzeugt eine beratende Ausgabe; der Build erzeugt trotzdem Artefakte.

Das Platzierungskriterium als eine einzige Regel formuliert: Wenn die Prüfung den Build abbrechen soll, gehört sie zu einer Verdikt-Rolle der Governance; wenn die Prüfung einen Autor oder einen Reviewer warnen soll, ohne die Pipeline zu blockieren, gehört sie in den Linter-Socket.

Beide sind heute nutzbar. Der Linter-Socket führt den publishing-linter über aggrega lint aus; die Verdikt-Rollen der Governance werden während aggrega build in-band aufgerufen, wenn ein Workspace ein Plugin mit Verdikt-Rolle anbindet. Beachten Sie, dass eine Verdikt-Rolle eigene Schweregrade hat — eine Richtlinie kann selbst Verdikte warn und info ausgeben, die beraten, ohne abzubrechen —, sodass die obige Linie zwischen Abbrechen und Beraten die Platzierungsempfehlung für ganze Prüfungen ist und keine Aussage, dass eine Richtlinie nur abbrechen könne. Das Schweregradmodell beschreibt die Seite zum Governance-Socket.

Querverweise

  • policy-socket.md — die umfassende Behandlung des Governance-Sockets: die vier Rollen, die Schweregrade von Verdikten, der Eingabekanal des Operators, das Schreiben einer Richtlinie für eine der beiden im Compiler mitgelieferten Engines, das Kapseln einer fremden Richtlinien-Engine und die Referenz-Guests.
  • core-importers.md — die eigenen Importer des Compilers, einer für jedes Format, das er liest: was jeder liest, ihre Einstellungen und ihre Veröffentlichung mit jeder Compiler-Version.
  • 10-status.md#compilation-pipeline-phases — Klassifizierung der Plugin-Pipeline auf der Statusseite (Laufzeitbereitschaft der Wasm-Plugin-Pipeline).
  • architecture/04-entity-taxonomy.md §„Domain 3: Infrastructure Base (Domäne 3: Infrastrukturbasis)“ — Prinzip des zweiteiligen Plugin für FeatureRecipes für Anmeldedaten (Muster Fetcher + Injector).
  • architecture/13-catalog-and-registry.md — die OCI-Taxonomie, die mit dem Provider-Segment beginnt.
  • entities/featurerecipe.md — die Authoring-Oberfläche pipeline: des FeatureRecipe.
  • when-to-use-a-pipeline-step.md — Entscheidungshilfe: ein Pipeline-Schritt oder ein FeatureRecipe mit Templates.
  • templates/expansion-matrix.md — die Regeln der Template-Auswertung für den Block pipeline: with: der Plugin-Pipeline und die Zugriffssemantik von .steps.
  • examples/04-secrets.md — die Pipeline-Form Fetcher + Injector, die ein FeatureRecipe für Anmeldedaten annehmen kann.
  • errors/error-translation.md — die Disziplin der Fehlerübersetzung, an der Plugin-Guests teilnehmen.