Component
Die konzeptionelle Rolle der Entität Component (die abstrakte Schnittstelle eines Rechenknotens in Domäne 2) ist in architecture/04-entity-taxonomy.md beschrieben. Diese Seite behandelt die Authoring-Oberfläche der Component: die semantische Label-Taxonomie, mit der Architekten kognitive Identität über die operative Basisontologie legen, die Deklaration schema: für die Datensäulen, die deklarativen Tabellen usesSchema und featuresSchema für Topologie-Sockets und Anbindungs-Slots, Präsenzvorgaben, den Vererbungsmechanismus extends: und den Block assertions: für feldübergreifende Regeln.
Die Taxonomie Semantischer Labels (Die Konvention der Standardbibliothek)
Wenn die Basistypen rein cloud-nativ sind, wird die operative und kognitive Intelligenz der Architektur vollständig über semantisches Duck-Typing geschichtet.
Der zentrale Go-Compiler interpretiert diese Labels nicht. Der Compiler baut den flachen Graphen der Zwischenrepräsentation (IR) auf, ohne die Semantik der Labels zu interpretieren. Diese Labels stellen die Konvention der Standardbibliothek dar—unveränderliche „genetische Marker“, die der Platform Architect in Domäne 2 verfasst. Sie liefern die expliziten semantischen Hooks, mit denen die Wasm-Policy-Validatoren und die physischen Ops-Recipes die Architektur steuern.
(A) Die generische Cloud-Schicht Diese Labels beschreiben universelle Verhaltensweisen und ermöglichen es Policy-Engines und generierten L7-Proxys, Standard-Unternehmensarchitekturen zu steuern, ohne KI-Frameworks nativ verstehen zu müssen.
| Label-Präfix | Zulässige Werte (Konvention) | Warum Platform Ops es braucht (Der Policy-Hook) |
|---|---|---|
tool.aggrega.ai/impact | read-only, mutating | Ermöglicht Policy-Engines, eine Autorisierung nach dem Prinzip der geringsten Rechte (Least-Privilege AuthZ) zu bewerten. Verändernde Tools können automatisch Policies auslösen, die das Anhängen strenger Sidecars mit Freigabeschranke verlangen. |
datastore.aggrega.ai/engine | relational, document, kv, vector, graph, semantic-memory, search (Wertemenge stabilisiert sich anhand des befüllten Katalogs) | Ermöglicht Policy-Engines, knotenübergreifende Typsicherheit durchzusetzen (z. B. indem verhindert wird, dass ein Agent versucht, SQL-Payloads an eine Vektordatenbank zu senden). |
gateway.aggrega.ai/intelligence | semantic, l4-mesh | Legt fest, welche Funktionen ein Router physisch unterstützen kann (z. B. indem verhindert wird, dass ein Feature, das anhand des in einer Anfrage genannten Modells routet, etwa eine Fallback-Kette, an ein Standard-TCP-Mesh angehängt wird). |
dataplane.aggrega.ai/request-mirroring | full-rate, sampled | Ermöglicht einem Feature, das Live-Traffic an ein zweites Ziel kopiert, einen Proxy auszuwählen, der überhaupt kopieren kann, und einen, der jede passende Anfrage kopiert, von einem zu unterscheiden, dessen Anteil kopierter Anfragen einstellbar ist. |
dataplane.aggrega.ai/caller-identity | client-certificate, injected-header | Ermöglicht einem Feature, das den ursprünglichen Aufrufer gegenüber dem Dienst hinter dem Proxy identifiziert haben muss, eine Komponente auszuwählen, die diese Identität übermitteln kann, und zu lesen, welcher Mechanismus sie übermittelt — die weitergeleiteten Details des eigenen TLS-Zertifikats des Clients oder ein Header, den der Proxy nach der Authentifizierung des Aufrufers selbst zusammensetzt. |
dataplane.aggrega.ai/content-masking | entity-recognition, pattern-list | Ermöglicht einem Feature, das sensiblen Text maskiert, eine Komponente auszuwählen, die ihn in der Chat- und Completion-Payload, die sie routet, durch einen Platzhalter ersetzen kann, bevor der Text weiterläuft. Der Wert benennt die Genauigkeit: Mit entity-recognition ersetzt die Komponente Treffer von Mustern, die in ihrer Konfiguration angegeben sind, und zusätzlich Entitätstypen, die ein von ihr aufgerufener Erkennungsdienst erkennt; mit pattern-list ersetzt sie nur Treffer von Mustern aus ihrer Konfiguration und ruft keinen Erkennungsdienst auf. |
dataplane.aggrega.ai/prompt-guard | pattern-list, classifier | Ermöglicht einem Feature, das Modell-Prompts prüft, eine Komponente auszuwählen, die die Chat- und Completion-Payload, die sie routet, untersuchen und eine Anfrage aufgrund ihres Inhalts ablehnen kann. Der Wert benennt die Genauigkeit: Mit pattern-list erfolgt der Abgleich gegen Muster aus ihrer Konfiguration, über die Modell-Payload und nicht über einen beliebigen HTTP-Body; mit classifier stammt das Urteil von einem trainierten Textklassifikator, erreicht über einen Erkennungsdienst, den die Komponente aufruft, gemessen an einem Schwellenwert aus ihrer Konfiguration. |
dataplane.aggrega.ai/upstream-tls | trust-anchor | Ermöglicht einem Feature, das vom Proxy verlangt zu prüfen, mit wem er kommuniziert, eine Komponente auszuwählen, die das Zertifikat eines Upstreams gegen einen Vertrauensanker prüfen kann, den das Release bereitstellt. |
dataplane.aggrega.ai/upstream-pinning | public-key | Ermöglicht einem Feature, das festlegt, welchen Schlüssel ein Upstream vorlegen darf, eine Komponente auszuwählen, die einen Upstream ablehnen kann, sofern nicht ein von ihm vorgelegtes Zertifikat einen der öffentlichen Schlüssel enthält, die das Release bereitstellt. Eine andere Zusicherung als upstream-tls: Ein Pin sagt, welcher Schlüssel ein Zertifikat sein muss, ein Anker, was es aussagen muss. |
dataplane.aggrega.ai/period-budget | cost, tokens | Ermöglicht einem Feature, das begrenzt, was Traffic über einen Zeitraum verbrauchen darf, eine Komponente auszuwählen, die Modellanfragen ablehnen kann, sobald das, was sie über den Zeitraum gezählt hat, ein in ihrer Konfiguration festgelegtes Limit überschreitet. Der Wert benennt, was sie zählt: cost, was der Traffic gekostet hat, bepreist anhand einer Tabelle, die die Komponente pro Modell führt; tokens, die Tokens, die die Antwort jedes Modells als gelesen, geschrieben oder beides meldet, welche die Komponente zählt, ohne etwas zu bepreisen. |
dataplane.aggrega.ai/concurrency-cap | total, per-target | Ermöglicht einem Feature, das begrenzt, wie viele Anfragen eine Komponente gleichzeitig verarbeitet, eine Komponente auszuwählen, die eine Anfrage jenseits eines in ihrer Konfiguration festgelegten Limits zurückhalten oder ablehnen kann. Der Wert benennt, was ein Limit zählt: total, jede Anfrage, die die Komponente weiterleitet, gegen ein einziges Limit; per-target, die laufenden Anfragen an jedes Upstream-Ziel, an das sie sendet, mit einem Limit für jedes und keinem für ihre Summe. |
Die dataplane.aggrega.ai/-Schlüssel benennen eine Position auf dem Traffic-Pfad statt einer Art von Komponente, sodass sich ein Proxy, ein Ingress-Gateway und ein Service Mesh alle in einem einzigen Vokabular beschreiben, statt dass jedes ein eigenes braucht. Zwei Eigenschaften dieser Familie verdienen eine sorgfältige Lektüre, weil sich beide leicht umkehren lassen:
- Der Wert trägt die Genauigkeit, nicht nur das Vorhandensein der Fähigkeit. Zwei Komponenten können beide Anfragen spiegeln und sich dennoch auf eine Weise unterscheiden, die für ein Feature relevant ist; deshalb steckt die Unterscheidung im Wert, und ein Feature wählt die Genauigkeit, die es braucht. Eine Komponente mit höherer Genauigkeit trägt den stärkeren Wert und keinen anderen.
- Ein Wert sagt aus, was das Produkt leisten kann, niemals, was ein Deployment eingeschaltet hat. Beides liest sich ähnlich, doch nur das Erste ist eine Eigenschaft der Komponente. Ein Proxy, der ein Upstream-Zertifikat prüfen kann, trägt
upstream-tls: trust-anchor, unabhängig davon, ob ein bestimmtes Deployment die Prüfung aktiviert, denn das Label ist das, worauf ein Feature auswählt, bevor irgendetwas konfiguriert ist.
Eine Komponente, die auf einer dieser Achsen nichts zu beschreiben hat, trägt dort keinen Wert statt eines schwächsten, genau wie an anderer Stelle der Taxonomie: Fehlen bedeutet, dass die Achse auf dieser Komponente keinen Gegenstand hat, sodass ein Feature, das dort irgendeinen Wert verlangt, korrekterweise nicht angehängt wird.
(B) Die spezialisierte KI-Schicht (Die kognitive Identität) Diese Labels beschreiben die kognitive Identität der Arbeitslast und ermöglichen es der Architektur, moderne KI-Frameworks abzusichern.
| Label-Präfix | Zulässige Werte (Konvention) | Warum Platform Ops es braucht (Der Policy-Hook) |
|---|---|---|
model.aggrega.ai/capability | generative, embedding, transcription | Wird von den Selektor-Strings in usesSchema verwendet (die der Go-Compiler während der statischen Analyse nativ auswertet), um sicherzustellen, dass ein Entwickler nicht versehentlich eine generative Text-Payload an einen Embedding-Endpunkt routet. |
model.aggrega.ai/api | openai, anthropic, gemini, native | Benennt, welche Modell-API unter der Adresse antwortet, die eine Komponente veröffentlicht: openai, wenn es die OpenAI-API ist, die des Anbieters selbst oder die Implementierung eines Servers, anthropic, wenn es die Messages API von Anthropic ist, die des Anbieters selbst oder die Implementierung eines Servers, gemini, wenn es die Gemini API von Google ist, und native, wenn es die eigene API des Produkts und keine davon ist. Jede Modellkomponente trägt es, ebenso ein Gateway, das eine Modell-API bereitstellen kann, sodass ein Socket, der component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api auswählt, ein Modell oder ein solches Gateway annimmt und ein Gateway ablehnt, das keine bereitstellen kann, während ein Socket, der einen einzigen Wert nennt, etwa model.aggrega.ai/api=anthropic, nur annimmt, was diese API bereitstellt. Es benennt, was das Produkt bereitstellt, nicht, was ein einzelnes Release verdrahtet: Ein Gateway, dessen Modelle an einen eigenen Socket verdrahtet werden, trägt es auch, wenn nichts verdrahtet ist. Das Label ist ein String, gegen den der Selektor abgleicht; nichts prüft, was tatsächlich unter der Adresse antwortet. |
agent.aggrega.ai/autonomy | autonomous, copilot | Kennzeichnet das Ausführungsrisiko der kognitiven Schleife und ermöglicht es Policies, für vollständig autonome Agenten Funktionen zur menschlichen Freigabe vorzuschreiben. |
(C) Die Querschnittsthemen (Governance, Zustand und Hardware) Sie stellen die grundlegenden Unternehmens-Tags dar, die die Zero-Trust-Validierung und das Hardware-Routing steuern.
| Label-Präfix | Zulässige Werte (Konvention) | Warum Platform Ops es braucht (Der Policy-Hook) |
|---|---|---|
component.aggrega.ai/hosting | self-hosted, managed, external, mixed | Hält fest, wer die zugrunde liegende Ressource einer Komponente betreibt — die Achse der Vertrauensgrenze. Policy-Engines lesen es, um das Risiko einer Datenexfiltration zu berechnen (z. B. verlassen interne Daten, die an eine managed Drittanbieter-API geroutet werden, die Grenze des Betreibers). Querschnittlich: Dieselben Werte beschreiben gleichermaßen eine verwaltete Datenbank, eine verwaltete Modell-API und einen selbst betriebenen Inferenzserver. mixed kennzeichnet eine Komponente, deren Recipes mehr als eine Betriebsform abdecken — ein Datenspeicher, der von seinen Helm- und Compose-Recipes selbst gehostet und von seinen RDS-Recipes verwaltet wird —, sodass die Betriebsform eines Release dem Recipe folgt, das sein Manifest auswählt. |
compliance.aggrega.ai/data-class | public, internal, restricted | Die Klasse der Daten, die eine Komponente enthält. Der Compiler überträgt sie als String in den Build-Graphen und stuft nichts ein; eine Policy, die ein Betreiber in der Rolle ir-verdict anhängt, gibt den Klassen in ihren eigenen Einstellungen ihre Reihenfolge und liest das Label entlang der Routen, die der Compiler aufzählt — und hält zum Beispiel einen Build an, in dem eine restricted Komponente eine Komponente einer anderen Klasse erreicht, ohne dass auf der Route ein deklassifizierendes Feature angehängt ist (policy-data-class-route). Keine Component der Standardbibliothek trägt es: Die Klasse ist eine Aussage darüber, wie eine IT-Landschaft eine Komponente nutzt, getragen von der eigenen Component dieser Landschaft — etwa einer Spezialisierung über extends. |
compliance.aggrega.ai/contains-pii | true, false | Kennzeichnet Arbeitslasten ausdrücklich als im Geltungsbereich von DSGVO/CCPA. Eine Policy, die ein Betreiber anhängt, kann es lesen, um bestimmte Features auf den Routen zu verlangen, die der Traffic einer solchen Arbeitslast nimmt — core/data-masking auf einem KI-Gateway, über das sie Modell-Traffic sendet, zum Beispiel; die Form, die policy-data-class-route für eine Datenklasse prüft. Keine Component der Standardbibliothek trägt es; wie die Datenklasse ist es eine Aussage einer IT-Landschaft über ihre eigenen Komponenten. |
hardware.aggrega.ai/accelerator | gpu, tpu, npu | Wird von DevOps in der Release-Datei verwendet. Dort werden diese Komponenten über die Map components: {} explizit in physische Hardware-Pool-Grenzen geroutet (z. B. ein GPU-fähiger Cluster), während eine Governance-Verdict-Rolle durchsetzen kann, dass mit GPU gekennzeichnete Komponenten niemals in Grenzen ohne GPU platziert werden. |
state.aggrega.ai/retention | retain, delete | Schließt die AOT-Löschlücke. Wenn ein Entwickler eine Datenbank aus seinem Aggregate löscht, entfernt ein GitOps-Orchestrator physisch die Festplatte. Ein pipeline:-Schritt eines Recipe kann das Label retain lesen und den gerenderten Artefakten einen orchestratoreigenen Schutz hinzufügen (z. B. helm.sh/resource-policy: keep). |
state.aggrega.ai/backup-tier | mission-critical, standard, ephemeral | SOC2-Verfügbarkeits-Hook. Teilt dem Ops-FeatureRecipe mit, ob für die Ressource physisch automatisierte Snapshot-/Volume-Backup-Konfigurationen erzeugt werden sollen. |
(D) Der dynamische Geschäftskontext (kaskadierende Annotationen) Während labels die unveränderliche Katalog-DNA definieren, ändern sich dynamische Geschäftskontexte (wie die Abgrenzung von SOC2-Audits oder die FinOps-Kostenverfolgung) je nachdem, wer die Anwendung bereitstellt und wo sie läuft. Sie werden durch Annotationen gesteuert, die dynamisch von den subsystems des Entwicklers, den Release-Grenzen von Ops oder einem in der Rolle annotation-transform angehängten Governance-Plugin eingefügt werden.
| Annotations-Präfix | Zulässige Werte (Konvention) | Warum Platform Ops es braucht (Der Policy-Hook) |
|---|---|---|
business.aggrega.ai/cost-center | z. B. finance, ai-research | Von Wasm-Rendering-Plugins benötigt, um physisches Tagging (z. B. AWS-Tags oder K8s-Labels) für Cloud-Abrechnungs-Dashboards in die endgültig generierten Artefakte einzufügen. |
business.aggrega.ai/owner | z. B. team-alpha@corp.com | Routing der Incident Response. Stellt sicher, dass die Infrastruktur einem menschlichen Team zugeordnet ist. |
compliance.aggrega.ai/frameworks | z. B. soc2, hipaa | Auslöser für den SOC2-Geltungsbereich. Wird über das Umgebungs-Release eingefügt. Wasm-Plugins lesen diesen String, um automatisch strikte Audit-Logging-Sidecars zu erzeugen und Debug-Ports zu deaktivieren, wenn eine Anwendung eine Compliance-Grenze der Produktion betritt. |
Die Taxonomie ist eine Katalogkonvention, keine Compiler-Regel. Unternehmen können sie ignorieren, löschen oder ihr eigenes Label-Vokabular erfinden (mycompany.com/custom-trait). Wasm-Plugins werten alle Label-Schlüssel aus, die das Unternehmen verfasst.
Schema-Authoring
Das Component-Schema (und sein Feature-Gegenstück, einschließlich Credential-Features mit dem Label feature.aggrega.ai/kind: secret) deklariert den Validierungsvertrag für vom Entwickler verfasste values über einen spec.schema:-Block. Der Block akzeptiert JSON Schema 2020-12, ausgedrückt entweder in der kompakten YAML-Kurzschreibweise (der Standard; etwa 15 Schlüsselwörter, die zur Kompilierzeit mechanisch in JSON Schema umgewandelt werden) oder in vollständigem JSON-Schema-YAML (die ausführliche Form), mit dokumentübergreifenden Referenzen über $ref: für SchemaLibrary-Einträge, die von mehreren Components gemeinsam genutzt werden.
- Inline-Kompaktform (Standard-Authoring-Oberfläche): ein eingebetteter YAML-Block, der Blätter in Kompaktform direkt im Component-YAML enthält. Deckt den Großteil der Schemainhalte des Katalogs mit einem Bruchteil der Zeilenzahl eines vollständigen JSON Schema ab. Das Schlüsselwort-Vokabular und die Authoring-Konventionen finden Sie unter
vocabulary/compact-form-authoring.md. - Inline-JSON-Schema-YAML: die ausführliche Form, geeignet, wenn das Schema Schlüsselwörter von JSON Schema 2020-12 benötigt, die die Kompaktform nicht direkt abbildet (
$dynamicRef, tiefeunevaluatedProperties, komplexenot:-Kompositionen). Kompaktform und JSON Schema lassen sich an jeder Knotengrenze innerhalb eines einzigenschema:-Blocks über den Ausweg$jsonschema:mischen. - Dokumentübergreifende Referenz (
$ref:auf einen SchemaLibrary-Eintrag): ein JSON-Schema-natives$ref:, das per Identität auf einen SchemaLibrary-Eintrag zeigt (Datastores#/schemas/MariaDBValuesoder Ähnliches). Unternehmensschemas, die Hunderte von Zeilen umfassen und in mehreren Components wiederverwendet werden, liegen in SchemaLibrary-Entitäten; die konsumierende Component referenziert den Eintrag, ohne den Inhalt einzubetten. Die Bibliotheksentität und die Auflösungssemantik finden Sie unterentities/schemalibrary.mdundvocabulary/cross-document-ref.md.
Die drei obigen Formen verfassen Pillar-Inhalte und stehen einer Component zur Verfügung, die nichts erweitert. Eine Component, die extends: deklariert, verfasst überhaupt keine Pillar-Inhalte: Sie schreibt den literalen Marker schema: inherited und erhält den Pillar-Block ihrer Basis genau so, wie die Basis ihn verfasst hat. Dieser Marker ist der einzige Wert, den schema: bei einer solchen Component annimmt. Siehe „Katalog-Authoring: Basis-Components erweitern“ weiter unten.
Der Compiler löst den schema:-Block auf — er expandiert die Kompaktform, dereferenziert $ref:-URLs, wendet SchemaLibrary-Ketten von Bibliothek zu Bibliothek an — und vereinigt das resultierende JSON Schema während des Validierungsdurchlaufs der Component mit den automatisch generierten Basen, die aus usesSchema und featuresSchema abgeleitet werden (siehe den Abschnitt unten). Die Validierung läuft gegen das aufgelöste Schema; der Authoring-Pfad ist für nachgelagerte Pipeline-Stufen nicht sichtbar.
Verfasste Instanzen werden zur Build-Zeit gegen dieses aufgelöste Schema validiert: Die vom Entwickler verfassten values einer Komponenteninstanz und die aufgelöste infra des Operators sowie die values/infra an jeder Feature-Anbindung müssen den deklarierten Pillars entsprechen — ein Wert mit falschem Typ, eine Zahl außerhalb des Bereichs, ein String ohne sein deklariertes format, ein fehlendes Pflichtfeld oder (bei values, geschlossen validiert) eine nicht deklarierte Eigenschaft hält den Build an seiner verfassten Quelle an, statt zur Deploy-Zeit ein fehlerhaftes Manifest zu erzeugen. Ein Pillar, dessen Schema ein format nennt, das der Compiler nicht prüft — alles außerhalb von email, uri, hostname, ipv4, ipv6, uuid, date-time und date, password eingeschlossen —, wird beim Laden des Katalogs abgelehnt, mit einer Liste der unterstützten Namen; was jeder Name prüft, finden Sie unter vocabulary/compact-form-authoring.md. Eine Instanz einer Component, die eine Basis per extends: erweitert, wird gegen den Pillar-Block der Basis validiert, den die erweiternde Component unverändert erbt — sodass eine Instanz der Basis und eine Instanz von allem, was sie erweitert, demselben Pillar-Vertrag unterliegen. Die Diagnosen und die Regeln pro Pillar (einschließlich der Validierung von infra gegen die Schlüsselvereinigung aus Component und Provider) finden Sie unter errors/fatal-halts.md §„Authored values or infra do not conform to the declared schema (Verfasste values oder infra entsprechen nicht dem deklarierten Schema)“.
Deklarierte Standardwerte materialisieren sich in den gerenderten Pillars. Über die Validierung hinaus wird ein default:, das auf einem values-Feld (oder einem infra-Feld) deklariert ist, zur Build-Zeit für jeden Schlüssel, den der Autor weglässt, in den gerenderten Pillar eingetragen — sodass ein Recipe-Template, das {{ .values.charset }} liest, das im Schema deklarierte utf8mb4 statt eines leeren Werts erhält. Vom Autor angegebene Werte haben immer Vorrang; verschachtelte Objekte werden pro ausgelassenem Kind aufgefüllt. Da die Materialisierung dieselbe Schemaauflösung wie die Validierung verwendet, materialisieren sich auch Standardwerte, die über ein dokumentübergreifendes $ref: in eine SchemaLibrary erreicht werden — sowohl eine Referenz auf den ganzen Pillar (values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}) als auch die Form Basis plus Variante (ein Basis-$ref: neben benachbarten properties, jede mit eigenen Standardwerten). Standardwerte, die nur innerhalb einer lokalen dokumentinternen #/$defs/-Referenz oder unter einem allOf- / oneOf- / anyOf-Zweig deklariert sind, werden nicht materialisiert; die Standardbibliothek setzt Pillars über dokumentübergreifendes $ref: zusammen, das materialisiert wird.
Die Säule values
Das Component-Schema trennt drei Säulen nach Zuständigkeit: values wird vom Entwickler im Aggregate befüllt (kognitive Absicht — Datenbankname, Version, Zeichensatz), infra wird vom Operator im Release befüllt (operative Dimensionierung — Rechenleistung, Speicher, HA), und provides wird vom Recipe gesetzt (der öffentliche API-Vertrag — Host, Port, Protokoll). Der Entwickler sieht infra nie; der Operator sieht values nie. Recipes verarbeiten beide Säulen beim Basis-Rendering und bilden die abstrakten Säulen auf die konkrete Form ab, die ihr Ziel-Provider erwartet. Dieser Abschnitt behandelt die Authoring-Oberfläche der Säule values. Unter vocabulary/data-pillars.md finden Sie die umfassendere Säulen-Taxonomie und die Disziplin der säulenübergreifenden Kaskade.
values trägt die kognitive Absicht des Entwicklers — die Entscheidungen, die beschreiben, was die Anwendung ist oder tut, nicht wie sie dimensioniert oder betrieben wird. Datenbankname, Zeichensatz, Engine-Version, Log-Level, Funktionsschalter sowie anwendungsseitige Stellschrauben, die sich zwischen Anwendungsversionen ändern, aber über Umgebungen hinweg stabil bleiben, sind typischer Inhalt von values. Der Operator überschreibt values: nie (das Release-Schema lehnt einen values:-Block gemäß architecture/06-data-taxonomy-and-composition.md §8 Einschränkung 4 mechanisch ab); umgebungsspezifische Variation fließt über Parameter Hoisting — das Aggregate stellt typisierte parameters.* bereit, das values-Template der Component referenziert sie, und das Release erfüllt die Parameter.
# Component schema declares the values shape:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-serverspec: schema: values: database_name: { type: string, required: true } charset: { type: string, default: utf8mb4, enum: [utf8mb4, latin1, ascii] } engine_version: { type: string, default: "10.11" } log_level: { type: string, default: info, enum: [debug, info, warn, error] }# Aggregate fragment — the developer fills values:components: customer-db: type: core/datastore/mariadb values: database_name: customers charset: utf8mb4 engine_version: "{{ .parameters.mariadb_version }}" # Parameter Hoisting log_level: infoVerwendung auf Recipe-Seite. Recipes lesen die aufgelösten Werte über .values.<field> in valuesMapping:, provides:, assertions: und den anderen Template-Oberflächen — die Verfügbarkeitsmatrix pro Template finden Sie unter entities/recipe.md. Der Compiler vereinigt das values-Schema der Component mit allen values:-Schemas von Feature-Attachments am selben Component-Knoten, sodass der aufgelöste Template-Kontext jedes zutreffende Feld enthält.
Säulenübergreifende Disziplin. values ist die einzige Säule, die der Entwickler im Aggregate verfasst. Rein entwicklerseitige Felder gehören hierher; operative Stellschrauben (Replikatanzahl, CPU-/Speichergrenzen) gehören in die Säule infra der Component, damit sie im Release liegen; öffentliche Ausgaben (Host, Port) gehören in provides des Recipe. Wer diese vermischt, bricht die Zuständigkeitsinvariante; unter vocabulary/data-pillars.md „Säulenübergreifende Mechanik“ finden Sie die seltenen Fälle, in denen eine bewusste säulenübergreifende Weiterleitung gerechtfertigt ist.
Die Säule infra
Das Component-Schema trennt drei Säulen nach Zuständigkeit: values wird vom Entwickler im Aggregate befüllt (kognitive Absicht — Datenbankname, Version, Zeichensatz), infra wird vom Operator im Release befüllt (operative Dimensionierung — Rechenleistung, Speicher, HA; das Backup eines Datenspeichers wird nicht hier dimensioniert, sondern ist das Feature core/backup, das der Operator im Release anhängt), und provides wird vom Recipe gesetzt (der öffentliche API-Vertrag — Host, Port, Protokoll). Der Entwickler sieht infra nie; der Operator sieht values nie. Recipes verarbeiten beide beim Basis-Rendering und bilden die abstrakten Säulen auf die konkrete Form ab, die ihr Ziel-Provider erwartet.
Drei Konventionen für infra sind bei jeder gegenüber Fähigkeiten agnostischen Component der Standardbibliothek von Bedeutung: ein Ausweg in Form einer offenen Struktur für providerspezifische Stellschrauben, eine optionale Überschreibung der Upstream-Artefaktversion und ein absichtsbasiertes Vokabular für Hochverfügbarkeitsfelder. Die kanonische Referenz-Component ist core/datastore/mariadb im Katalog der Standardbibliothek — umsetzbar durch Helm-Recipes, die das offizielle Image mariadb ausführen oder eine MariaDB-Custom-Resource an den Controller mariadb-operator übergeben, durch Terraform-Recipes für AWS RDS, durch CloudFormation-Recipes für dieselbe RDS-Oberfläche und durch Compose-Recipes für einen lokalen Container — und ihr infra-Block veranschaulicht die erste und die dritte.
infra.overrides
Universelle infra-Felder — compute, storage, ha — decken den Großteil der operativen Dimensionierung über Provider hinweg ab. Der verbleibende Teil ist unvermeidlich providerspezifisch: Ein Kubernetes-Recipe benötigt einen nodeSelector, ein RDS-Terraform-Recipe benötigt eine instance_class, ein CloudFormation-RDS-Recipe benötigt eine DBInstanceClass, ein Compose-Recipe benötigt eine Überschreibung von image. Das Component-Schema stellt eine tatsächlich offene Map als Ausweg bereit, damit diese Stellschrauben durchgereicht werden, ohne das Schema aufzublähen:
infra: # ... universal fields ...
# Provider-specific overrides. Accepts any nested structure. # Each Recipe documents which keys it reads. overrides: type: object additionalProperties: true # genuinely open map: arbitrary nested structure permittedDas explizite type: object mit additionalProperties: true aktiviert die Semantik einer offenen Map. Der Compiler reicht die Struktur unverändert durch; der Template-Body des Recipe liest die Schlüssel, die er kennt, und ignoriert den Rest. Jedes Recipe dokumentiert die Ontologie seiner Override-Schlüssel in seinem Kopfkommentar, sodass ein Operator, der ein Release für eine bestimmte Kombination aus Component × Recipe verfasst, weiß, welche Stellschrauben das Recipe bereitstellt.
Ein Release-Fragment mit Overrides:
components: main-db: infra: compute: { cpu: "2", memory: 8Gi } storage: { size: 40Gi, type: balanced-csi } overrides: nodeSelector: kubernetes.io/hostname: cluster1-worker1 service_type: LoadBalancer metrics: enabled: true image: repository: bitnamilegacy/mysqld-exporterDer Entwickler sieht overrides nie — es liegt im Release, das die Domäne des Operators ist.
infra.source_version
Das Feld source eines Recipe referenziert ein Upstream-Artefakt in einer bestimmten Version (Helm-Chart 25.0.8, Terraform-Modul 4.2.0, OCI-Image-Tag). Die Version fest im Recipe zu codieren, zwingt den Katalog-Maintainer, bei jedem kompatiblen Upstream-Versionssprung ein neues Recipe zu veröffentlichen. Das Component-Schema stellt eine optionale Überschreibung bereit:
infra: source_version: type: string description: | Source artifact version. A Recipe versions its artifact from this key where its source resolution reads it, and is unaffected where it does not. Changing from the version a Recipe was authored against does not guarantee value mapping compatibility.Das Recipe liest dies über den Helper optional in seinem source-Block, sodass ein fehlender Pin auf die Version zurückfällt, für die das Recipe verfasst wurde:
source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "{{ optional .infra `source_version` `25.0.8` }}"source-Strings eines Recipe (und stringwertige Unterfelder einer strukturierten source:-Map) werden als Go-Templates ausgewertet. Eine entfernte Koordinate — etwa die version oben — wird ausgewertet, wenn aggrega pull das Artefakt pinnt, und zwar gegen .values, .infra und .locals ohne .context-Wurzel; eine Source, die einen Pfad im Workspace benennt, wird beim Rendern der Entität ausgewertet, gegen denselben in sich geschlossenen Kontext wie die locals eines Recipe — .context.instance_id, .values, .infra und die gesamten aufgelösten .locals des Knotens. .context.inject, .context.uses und .provides sind in beiden Fällen verboten. Dass .infra in diesem Kontext liegt, ist das, was die obige Überschreibung funktionieren lässt, und .locals ermöglicht es einem Recipe, ein Source-Fragment einmal zu berechnen und hier wieder zu lesen. Ein Source-Template liest nie die provides seines eigenen Knotens: Diese Säule ist nicht Teil des Kontexts, und ein Template, das danach greift, hält den Build an — eine feste Eigenschaft der Oberfläche und keine Lücke, die auf spätere Arbeit wartet. Die vollständigen Verfügbarkeitsregeln finden Sie in Zeile Nr. 5 der Template-Expansionsmatrix. Wird infra.source_version vom Standardwert des Recipe weg geändert, ist nicht garantiert, dass das valuesMapping des Recipe mit der neuen Upstream-Version auf Wire-Ebene kompatibel ist; die description der Deklaration source_version im Component-Schema enthält diese Warnung.
infra.ha.*
Hochverfügbarkeitsfelder verwenden Absichtsvokabular, kein Mechanismusvokabular:
infra: ha: enabled: { type: boolean, default: false } read_replicas: { type: integer, min: 0, default: 0 }infra.ha.enabled sagt „mache diese Component hochverfügbar“, und infra.ha.read_replicas sagt „ich möchte N schreibgeschützte Kopien“. Jedes Recipe entscheidet, was aus der Absicht auf seinem Provider wird. Die Recipes der Standardbibliothek für core/datastore/mariadb, so benannt, wie ein Manifest sie abbildet:
| Recipe | ha.enabled: true entspricht | ha.read_replicas: N entspricht |
|---|---|---|
helm/mariadb (ein StatefulSet auf dem offiziellen Image mariadb) | betreibt einen einzigen Server, daher hält der Build an und nennt den Schlüssel | betreibt einen einzigen Server, daher hält N größer als 0 den Build an |
helm/mariadb-cluster (eine MariaDB-Custom-Resource, die der Controller mariadb-operator abgleicht) | aktiviert automatisches Failover (replication.primary.autoFailover: true); das Failover erfolgt auf ein Lesereplikat, daher hält N gleich 0 den Build an | setzt spec.replicas auf N + 1 und aktiviert die Replikation; provides.host wird zum Service <name>-primary |
terraform/mariadb-rds (AWS RDS) | setzt multi_az = true auf der primären aws_db_instance | erstellt N separate aws_db_instance-Lesereplikat-Ressourcen |
terraform/mariadb-rds-module, terraform/mariadb-rds-terraform-aws-modules (AWS RDS über ein Modul) | übergibt multi_az = true an das Modul | stellt eine einzige Instanz bereit, daher hält N größer als 0 den Build an |
cloudformation/mariadb-rds (AWS RDS) | setzt MultiAZ: true auf der AWS::RDS::DBInstance | stellt eine einzige Instanz bereit, daher hält N größer als 0 den Build an |
compose/mariadb (lokaler Entwicklungscontainer) | betreibt einen einzigen Server, daher hält der Build an und nennt den Schlüssel | betreibt einen einzigen Server, daher hält N größer als 0 den Build an |
Mechanismusvokabular (infra.primary.replicas) liest sich für einen Provider natürlich (Kubernetes-Pods sind Replikate eines StatefulSet) und anderswo als Kategorienfehler — RDS kennt kein Konzept von „Replikaten“ auf dem Primary, CloudFormation spiegelt RDS, Compose hat überhaupt keine Abstraktion für horizontale Replikate. Absichtsvokabular lässt sich übertragen: Jeder Provider hat irgendein Konzept von „mache diese Datenbank hochverfügbar“ und irgendein Konzept von „ich möchte N schreibgeschützte Kopien“, und das Recipe übernimmt die providerspezifische Übersetzung. Wo eine Realisierung keinen solchen Mechanismus hat, kann ihr Recipe den Build anhalten und den Schlüssel nennen, wie es helm/mariadb und compose/mariadb für beide Schlüssel und die RDS-Recipes mit einer einzigen Instanz für Lesereplikate tun.
infra.ha.read_replicas: 0 ist der Standardwert; wenn beide Schlüssel auf ihren Standardwerten stehen, rendert helm/mariadb-cluster ein MariaDB mit einer einzigen Instanz ohne replication-Block statt einer Replikation über eine Instanz. compose/mariadb betreibt einen einzigen Server auf dem lokalen Docker-Host, daher hält infra.ha.enabled: true oder ein von null verschiedenes infra.ha.read_replicas den Build an und nennt den Schlüssel, und die Meldung verweist auf helm/mariadb-cluster, das Failover und Lesereplikate bietet.
Die Säule provides
provides ist die vom Recipe verfasste öffentliche API — die Werte, die das aufgelöste Recipe einer Component nachgelagerten Aufrufern über deren Oberfläche .context.uses.<alias>.provides.<provided-name> bereitstellt (oder, wenn der Aufrufer auf der Kante eine inject:-Allowlist deklariert, über dessen Pipe .context.inject). Das Component-Schema deklariert die Form (Schlüsselnamen plus Typen); der provides:-Block des gebundenen Recipe liefert die Werte. Der Entwickler, der ein Aggregate verfasst, sieht die provides-Form auf der Component-Seite als den Vertrag, auf den sich Aufrufer verlassen können; der Recipe-Autor erfüllt den Vertrag für die konkrete Implementierung, die er kapselt.
Die Erfüllung wird als Loud Guardrail durchgesetzt: Ein gebundenes Recipe muss jeden provides-Schlüssel erzeugen, den seine Component deklariert. Lässt das gebundene Recipe einen deklarierten Schlüssel aus, hält der Build an und nennt den fehlenden Schlüssel, statt den Aufrufern, die ihn referenzieren, stillschweigend nichts zu liefern. Zusätzliche Schlüssel über die deklarierte Menge hinaus zu erzeugen, ist erlaubt. Geprüft wird nur das Vorhandensein der Schlüssel — die erzeugten Werte sind opake Strings, die der Compiler durchreicht, daher bleiben ihre deklarierten Typen ein Vertrag, den Aufrufer lesen, und kein Wert, den der Compiler validiert.
# Component schema declares the provides contract:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-serverspec: schema: values: database_name: { type: string, required: true } provides: host: { type: string } port: { type: integer } database: { type: string }# Recipe fulfills the contract:apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-bitnami version: 1.0.0spec: capability: helm implements: core/datastore/mariadb:1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "25.0.8" provides: # The chart's primary Service, named by the fullnameOverride pinned below host: "{{ .context.rendered_name }}" port: "3306" database: "{{ .values.database_name }}" valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}"Die Aufteilung der Auswertung in provides und inject. Der Compiler wertet provides:-Templates bei der provides-Auswertung gegen den in sich geschlossenen Template-Kontext aus (.context.instance_id, .context.rendered_name, sofern der Provider des Knotens einen meldet, .values, .infra und die aufgelösten locals: des Recipe auf demselben Knoten) — kein Zustand von Aufrufern ist sichtbar. Die locals des Knotens werden in der Präambel dieser Phase aufgelöst, vor seinen provides, und genau das erlaubt einem provides:-Template, .locals zu lesen. Bei der inject-Hydrierung, die als Nächstes läuft, durchläuft der Compiler uses:-Kanten und löst das .context.uses.<alias>.provides.<provided-name> jedes Aufrufers gegen die aufgelösten provides-Werte auf. Die Trennung der beiden garantiert eine azyklische Auflösung: provides: kann keinen Aufrufer referenzieren, und das inject: eines Aufrufers kann die Ausgabe eines noch nicht aufgelösten Provider erst referenzieren, wenn die inject-Hydrierung läuft.
Vertragsentwicklung. Das Umbenennen oder Entfernen eines provides-Felds ist eine Breaking Change für jeden Aufrufer, der sich auf den alten Namen verlässt. Die metadata.version der Component (und die implements:-Deklaration des Recipe) trägt das Signal der Vertragsentwicklung; nachgelagerte Aufrufer, die auf eine bestimmte Major-Version festgelegt sind, sehen eine stabile provides-Form.
Lehrinhalte auf Recipe-Seite. Die Authoring-Grammatik für provides:-Templates, die Verfügbarkeitsmatrix pro Template und ausgearbeitete Beispiele für namespace- und regionsübergreifendes Routing finden Sie unter entities/recipe.md „Der Block provides:“ und architecture/06-data-taxonomy-and-composition.md §3.
Präsenzpflichten: features.aggrega.ai/requiredType.<label>
Eine Component kann deklarieren, dass jede ihrer Instanzen ein Attachment eines bestimmten Feature-Typs tragen muss. Dies ist eine Präsenzpflicht, und sie wird als wiederholbare Annotation in den eigenen Metadaten der Component verfasst:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/payment-processor version: 1.0.0 labels: component.aggrega.ai/type: server annotations: features.aggrega.ai/requiredType.audit: core/audit-logging features.aggrega.ai/requiredType.compliance: core/pci-compliancespec: schema: values: processor_endpoint: { type: string, required: true }Der Schlüssel ist das Präfix features.aggrega.ai/requiredType. gefolgt von einem Label Ihrer Wahl; der Wert ist der URI des Feature-Typs, den mindestens ein Attachment tragen muss. Das Label benennt die Anforderung in der Diagnose, die eine unerfüllte Pflicht erzeugt — oben audit und compliance —, und das ist seine ganze Aufgabe. Mit Label versehene Schlüssel sind der Weg, auf dem eine Component mehrere Pflichten gleichzeitig deklariert: Annotationen sind eine flache String-Map und können keinen doppelten Schlüssel enthalten.
Der Compiler wertet jede Pflicht gegen die endgültige Attachment-Menge der Instanz aus, nachdem die Kaskade des 5-Tier Onion Model jeden Geltungsbereich eingefaltet hat: die features:-Blöcke des Aggregate auf Komponenten- und Subsystemebene, die features:-Blöcke des Release auf Grenz- und Komponentenebene sowie Attachments, die durch annotationsgesteuerte Expansion entstehen. Jedes davon erfüllt die Pflicht — die Regel prüft, was vorhanden ist, nie, wie es dorthin gelangt ist. Eine Component, deren Pflicht nur erfüllt ist, weil ein Operator im Release eine Monitoring-Annotation gesetzt hat, besteht also genauso wie eine, an die der Entwickler das Feature von Hand angehängt hat.
Eine Pflicht, die kein Attachment erfüllt, hält den Build mit einer Diagnose an, die die Komponenteninstanz, das Label der Anforderung und den erforderlichen Typ nennt. Ein Annotationswert ist ein opaker String, daher validiert nichts seine Form, bevor der Compiler ihn liest; ein Wert, der kein Feature-Typ-URI ist, oder ein Schlüssel ohne Label nach dem Präfix hält den Build daher mit einer separaten Diagnose an, die besagt, dass die Deklaration fehlerhaft ist. Die beiden sind bewusst verschieden: Eine fehlerhafte Deklaration wird in der Katalogentität korrigiert, während eine unerfüllte Anforderung durch Anhängen des Feature behoben wird — und ein Tippfehler darf nie als erfüllte Anforderung gelesen werden.
Beide Diagnosen sind unter errors/fatal-halts.md „Required feature not attached (Erforderliche Funktion nicht angehängt)“ dokumentiert.
Eine Pflicht ist kein Slot. Die beiden Oberflächen beantworten unterschiedliche Fragen, und der Unterschied ist nicht kosmetisch:
featuresSchema-Slot | Präsenzpflicht | |
|---|---|---|
| Deklariert | einen benannten Bindungspunkt | eine Einschränkung dessen, was vorhanden sein muss |
| Name ist dereferenzierbar | ja — from: <slot> und .features.<slot>.provides.* | nein — das Label benennt die Anforderung, sonst nichts |
| Kardinalität | genau eine Befüllung pro Slot | mindestens ein Attachment des Typs |
| Schränkt die Befüllung ein | selector, inject, sensitive | nichts über den Typ hinaus |
| Durch ein freies Attachment erfüllt | nein — ein Slot wird über den Namen befüllt | ja — in jedem Geltungsbereich, unter jedem Namen |
| Wenn die Anforderung unerfüllt ist | hält an, wenn required: true gilt und nichts den Namen des Slots bindet | hält an, wenn kein Attachment den Typ trägt |
Beide Anforderungen werden gegen dieselbe Eingabe geprüft — die endgültige Attachment-Menge der Instanz — und beide halten mit ihrer eigenen Diagnose an, weil sie ihr unterschiedliche Fragen stellen: ob ein benannter Bindungspunkt gebunden ist, oder ob irgendein Attachment einen benannten Typ trägt. Keine beantwortet die Frage der anderen.
Greifen Sie zu einem Slot, wenn das Recipe lesen muss, was angehängt wurde. Greifen Sie zu einer Pflicht, wenn der Vertrag der Component verlangt, dass eine Fähigkeit vorhanden ist, und es keine Rolle spielt, welche Instanz sie liefert. Eine Component für Zahlungsverarbeitung, die core/audit-logging vorschreibt, erhält in jedem Deployment Audit-Logging, ob der Entwickler daran gedacht hat, es anzuhängen, oder nicht; eine PCI-konforme Component, die core/pci-compliance vorschreibt, kann nicht ausgeliefert werden, ohne dass das Compliance-Feature irgendwo im Deployment angehängt ist.
Vererbung. Eine auf einer Basis-Component deklarierte Pflicht wird von jeder Component geerbt, die sie per extends: erweitert, weil Metadaten-Annotationen entlang der extends-Kette zusammengeführt werden, wobei pro Schlüssel das Kind gewinnt. Ein Kind kann eine geerbte Pflicht daher umlenken, indem es dasselbe Label mit einem anderen Typ erneut deklariert, oder eigene Pflichten unter neuen Labels hinzufügen; es kann keine Pflicht entfernen, die die Basis deklariert hat.
Topologie-Sockets: usesSchema
Eine Component kann über einen Block usesSchema: topologische Sockets deklarieren — eine deklarative YAML-Map parallel zu featuresSchema. Jeder Eintrag benennt einen Socket, über den die Component komponentenübergreifende Abhängigkeiten annimmt, und legt fest, welche Component-Formen der Entwickler mit dem Socket verbinden darf. Der Compiler generiert aus den deklarierten Sockets automatisch Validierungsregeln in JSON Schema 2020-12 und vereinigt sie während der Component-Auflösung mit dem schema: der Component; Entwickler schreiben keine Säule uses: von Hand in schema:, weil die Struktur aus usesSchema stammt.
# Component declares the sockets it accepts:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/ai-agent/orchestrator version: 1.0.0 labels: component.aggrega.ai/type: serverspec: usesSchema: primary_datastore: required: true selector: "datastore.aggrega.ai/engine=vector" inject: [env] cache: required: false selector: "datastore.aggrega.ai/engine=kv" inject: [env, file] log_destination: required: false selector: "component.aggrega.ai/category=messaging" inject: []# Aggregate fragment — developer wires the sockets:components: agent: type: core/ai-agent/orchestrator uses: primary_datastore: main: { target: vector-db-instance } log_destination: audit: { target: audit-sink }Verbindungsformen — ein Socket akzeptiert ein oder mehrere Ziele. Die obigen Beispiele verbinden jeden Socket mit einem einzelnen Ziel, aber ein Socket kann sich auf mehrere Ziele verzweigen. Ein Socket-Wert wird in einer von zwei Formen geschrieben:
uses: # Compact form — a list of target names. Each entry produces an edge # whose alias equals its target. Use it for the single-target case, and # when one socket connects to several peers of the same shape. shards: [orders-db, customers-db, inventory-db]
# Verbose form — an alias-keyed map. Each alias maps to an entry object # carrying its own `target:`, and may carry its own inject directives. # Use when the connections need distinct names or per-edge inject. databases: primary: { target: orders-db, inject: { env: [{ in: DB_URL, from: url }] } } replica: { target: orders-db-ro, inject: { env: [{ in: DB_REPLICA_URL, from: url }] } }Ein Alias verweist immer auf ein Eintragsobjekt, nie auf einen bloßen Zielnamen: databases: { primary: orders-db } wird beim Laden abgelehnt, ebenso ein Eintragsobjekt, das target: weglässt. Um ein einzelnes Ziel zu verbinden, ohne einen Alias erfinden zu müssen, verwenden Sie die kompakte Form — primary_datastore: [vector-db-instance] —, die das Ziel einmal benennt und den Alias daraus ableitet.
Jeder Eintrag — Listenelement oder Map-Alias — wird zu einer Kante, die in der Reihenfolge des Schreibens erhalten bleibt. Der selector: des Sockets gilt für jedes darüber verbundene Ziel (jede Kante wird während der statischen Analyse unabhängig typgeprüft), und required: true bedeutet, dass mindestens ein Ziel verbunden sein muss.
Feldsemantik:
| Feld | Typ | Standard | Bedeutung |
|---|---|---|---|
required | bool | false | Bei true muss der Entwickler mindestens eine Abhängigkeit mit diesem Socket verbinden. Bei false ist der Socket optional. |
selector | string | — | Ein Label-Selektor in der Grammatik, die appliesTo bei einem Feature verwendet, den das Ziel jeder über diesen Socket verbundenen Kante erfüllen muss. Er wird als die hier geschriebene Zeichenfolge gelesen und während der statischen Analyse gegen die Labels des Ziels ausgewertet: Ein Ziel, dessen Labels ihn nicht erfüllen, bricht den Build ab, ebenso ein Selektor, den die Grammatik ablehnt, unter Nennung der Anforderung, die nicht gelesen werden konnte. Ein leerer Selektor schränkt das Ziel nicht ein. |
inject | string[] | — | Allowlist der erlaubten inject-Zustellmechanismen (parallel zu featuresSchema[].inject). Fehlend oder [] (leer) bedeutet Blackbox — kein inject:-Block im uses:-Eintrag des Entwicklers erlaubt; die Recipe steuert die Zustellung. [env, file, arg] (nicht leer) bedeutet transparent — der Entwickler darf vorgeben, welcher Mechanismus die provides-Werte der Abhängigkeit zustellt. Durchgesetzt: siehe „Wo die inject-Allowlist eines Sockets durchgesetzt wird“ unten. |
valueSchema | object | — | Optionaler Vertrag pro Kante für vom Entwickler geschriebene values auf einer über diesen Socket verbundenen Kante (geschrieben im Aggregate). JSON Schema 2020-12 in denselben Schreibformen wie schema:. Fehlt er, deklariert der Socket keinen values-Vertrag. |
infraSchema | object | — | Optionaler Vertrag pro Kante für vom Operator geschriebenes infra auf einer über diesen Socket verbundenen Kante (geschrieben im Release). Dieselben Schreibformen wie valueSchema. Fehlt er, deklariert der Socket keinen infra-Vertrag. |
featuresSchema | map | — | Die Attachment-Slots, die jede über diesen Socket verbundene Verbindung füllen darf, nach Slot-Name geschlüsselt; jeder Slot nimmt die Schlüssel an, die ein Slot auf Component-Ebene annimmt. Fehlt die Angabe, trägt eine Verbindung über diesen Socket kein Attachment. Siehe „Slots, die jede Verbindung füllt“ unten. |
Wo die inject-Allowlist eines Sockets durchgesetzt wird. Die Allowlist ist die Aussage des Sockets darüber, ob ein Konsument die Zustellform überhaupt wählen darf und, wenn ja, welche Formen — daher wird sie gegen jede über den Socket verbundene uses:-Kante geprüft, sobald sowohl die Kante als auch die Deklaration des Sockets vorliegen. Aus einer Regel folgen zwei Ablehnungen, und beide brechen den Build ab:
- Eine Kante, die einen Mechanismus vorgibt, den die Allowlist nicht aufführt, bricht den Build ab und nennt den Socket, den beanstandeten Mechanismus und das, was der Socket erlaubt. Alle beanstandeten Mechanismen der Kante werden gemeinsam gemeldet.
- Eine Kante, die irgendeine Zustellung über einen Socket vorgibt, dessen Allowlist fehlt oder leer ist, bricht ebenfalls ab. Das ist die Blackbox-Deklaration, die ihre Aufgabe erfüllt: Sie besagt „die Recipe stellt dies intern zu; geben Sie die Zustellung nicht vor“, und eine leere Allowlist erlaubt nichts, statt alles zu erlauben.
Der Socket wird an derjenigen Entität gelesen, die ihn deklariert hat, und das ist nicht immer die Komponente, an der die Kante hängt: Eine im uses: eines Feature-Attachments geschriebene Kante wird gegen das usesSchema des angehängten Feature aufgelöst, und jede andere Kante — im Aggregate geschrieben, aus dem Release verbunden oder über ein Sub-Aggregate erreicht — gegen das der konsumierenden Component. Ein über extends geerbter Socket wird genau so gelesen wie einer, den die Entität selbst geschrieben hat.
Eine Kante, die nichts vorgibt, ist von keiner der beiden Ablehnungen betroffen, unabhängig davon, was der Socket deklariert: Das Lesen der Werte einer Abhängigkeit aus .context.uses.<alias>.provides.<name> in der konsumierenden Recipe benötigt keinen inject:-Block und ist immer verfügbar. Beide Diagnosen finden Sie unter errors/fatal-halts.md.
Verbindungsverträge pro Kante — valueSchema und infraSchema. Über die Frage hinaus, welche Components mit einem Socket verbunden werden dürfen, kann ein Socket deklarieren, welche Konfiguration jede Verbindung trägt. Zwei optionale Schemas pro Socket validieren die verbindungsbezogene Konfiguration auf jeder über den Socket verbundenen Kante:
valueSchemaist der Vertrag für den vom Entwickler geschriebenenvalues-Block auf eineruses-Kante — die verbindungsbezogene Feinabstimmung, die der Entwickler im Aggregate ausdrückt (zum Beispiel die Größe eines Verbindungspools oder einen Client-Modus).infraSchemaist der Vertrag für den vom Operator geschriebeneninfra-Block auf eineruses-Kante — die verbindungsbezogene betriebliche Dimensionierung, die der Operator im Release ausdrückt.
Beide akzeptieren JSON Schema 2020-12 in denselben Inhaltsformen wie das Feld schema: — kompakte Inline-Form, Inline-JSON-Schema-YAML oder ein dokumentübergreifendes $ref: auf einen Eintrag einer SchemaLibrary. Es sind Verträge pro Kante, die unabhängig gegen die Konfiguration jeder Kante validiert werden; sie werden nicht in das eigene values-Schema der konsumierenden Component eingefügt. Ein Socket, der für eine Säule kein Schema pro Kante angibt, deklariert dort keinen Vertrag, und jede für diese Säule geschriebene Konfiguration bleibt unvalidiert. Die Konfiguration pro Kante wird geschlossen validiert, und die Validierung berücksichtigt in beiden Säulen Standardwerte: Ein Schlüssel, dem das Schema einen default: gibt, gilt als angegeben, auch wenn der Autor ihn weglässt.
Ein deklarierter default: wird zudem in beiden Säulen materialisiert. Ein Schlüssel, den der Autor weglässt, erreicht den Render-Kontext der konsumierenden Recipe mit seinem deklarierten Standardwert, genau wie ein weggelassener value- oder infra-Schlüssel einer Komponente — es genügt also, den Standardwert am Socket zu deklarieren, und das Recipe-Template braucht dafür keinen Fallback-Ausdruck. Ein geschriebener Wert hat immer Vorrang vor dem deklarierten Standardwert und füllt nur den Schlüssel, den er angibt: Eine Kante, die einen Schlüssel des Vertrags eines Sockets schreibt, erhält für die übrigen Schlüssel dieses Vertrags dennoch die deklarierten Standardwerte. Standardwerte hängen an Kanten, daher trägt ein nicht verbundener Socket nichts bei.
spec: usesSchema: databases: required: true selector: "datastore.aggrega.ai/engine=relational" inject: [env] valueSchema: # developer per-edge values, authored in the Aggregate pool_size: { type: integer, minimum: 1, maximum: 100, default: 10 } tls_mode: { type: string, enum: [disable, require, verify-full], default: require } infraSchema: # operator per-edge infra, authored in the Release storage_class: { type: string, default: standard }Mit diesem deklarierten Socket rendert eine Kante, deren Aggregate pool_size weglässt, 10, und eine Kante, deren Release storage_class weglässt, rendert standard. Das Geschriebene hat pro Schlüssel Vorrang, innerhalb seiner eigenen Säule: Ein Aggregate, das pool_size: 42 setzt, rendert 42, während tls_mode weiterhin mit require gefüllt wird, und ein Release, das storage_class: gp3 setzt, rendert gp3, ohne einen der beiden Entwicklerschlüssel zu berühren.
Eine Recipe für die konsumierende Component liest die aufgelöste Konfiguration pro Kante aus der angereicherten Topologie-Pipe unter .context.uses.<alias>.values.<key> und .context.uses.<alias>.infra.<key> — siehe vocabulary/topology-triad.md.
Slots, die jede Verbindung füllt — das featuresSchema eines Sockets. Ein Socket kann auch Attachment-Slots deklarieren, und dann darf jede darüber verbundene Verbindung in jedem davon ihr eigenes Attachment tragen: Ein Gateway, das mehrere Modelle erreicht, hält für jedes eine andere Anmeldeinformation, weil die Anmeldeinformation an der Verbindung und nicht am Gateway liegt.
spec: usesSchema: models: selector: "component.aggrega.ai/category=ai-model" featuresSchema: credential: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env] description: The credential the consumer presents to the component this connection reaches.Eine Verbindung füllt einen Slot, indem sie unter dem Namen des Slots ein Attachment in ihrem eigenen features: trägt — im Verbindungseintrag des Aggregate (Aggregate) oder in dem des Release (Release) —, und das Attachment wird zu einem der Attachments der konsumierenden Komponente, mit dem Namen <alias>.<slot>.
Was die Deklaration tut, genau formuliert:
- Die Slot-Namen sind eine geschlossene Menge. Anders als das eigene
featuresSchemader Component, das ein freies Attachment unter jedem Namen zulässt, sind die Slots eines Sockets die einzigen Namen, die eine Verbindung darüber tragen darf: Jeder andere Name bricht beim Laden des Builds ab, und ein Socket, der keinfeaturesSchemadeklariert, lässt auf seinen Verbindungen kein Attachment zu. Ein Ad-hoc-Socket — einer, den diesesusesSchemanicht deklariert — deklariert keine Slots, daher tragen auch seine Verbindungen keine. Jede Verbindung füllt ihre Slots selbst: Ein Attachment auf einer breiteren Ebene kaskadiert nie auf eine Verbindung, und ein Release-Schlüssel, der den zusammengesetzten Namen eines Verbindungs-Attachments schreibt, bricht ab. - Die übrigen Schlüssel binden jede Verbindung an den Slot. Ein Slot nimmt hier dieselben Schlüssel an wie ein Slot auf Component-Ebene —
required,selector,inject,sensitive,description— und jede Verbindung wird einzeln daran gemessen.selectorwird mit den Labels des Feature abgeglichen, mit dem eine Verbindung den Slot füllt, und eine Füllung, die er nicht zulässt, bricht ab, positioniert am Eintrag dieser Verbindung in dem Dokument, das die Füllung geschrieben hat.required: truegilt für jede über den Socket verbundene Verbindung: Eine Verbindung, die den Slot leer lässt, bricht ab und wird dabei genannt, während eine Verbindung daneben, die den Slot füllt, besteht.sensitivewird genau wie bei einem Slot auf Component-Ebene gelesen: Das Attachment, das den Slot füllt, wird im Build-Graphen und inaggrega inspectals sensibel markiert. Bei einer Verbindung wie bei einer Komponente entscheidet allein das eigene Schema des angehängten Feature, welche Werte eines Attachments als sensibel zurückgehalten werden.injectbindet den Workload-Eintrag, der das Material des Slots zustellt: Das Attachment einer Verbindung trägt keinen eigeneninject:-Block — keines der beiden Dokumente lässt einen auf einem Verbindungseintrag zu —, daher stellt ein Workload es zu, indem er die Verbindung neben dem Slot benennt, und dieser Eintrag wird genau so an die Allowlist des Socket-Slots gebunden, wie ein Eintrag, der einen Slot auf Component-Ebene benennt, an die Allowlist dieses Slots gebunden ist.
Das usesSchema eines Feature nimmt kein featuresSchema an: Eine Verbindung, die ein Feature zieht, trägt keine Attachments, und ein Feature, das Slots an einem Socket deklariert, wird beim Laden abgelehnt. Eine Anmeldeinformation, die eine solche Verbindung braucht, ist ein Slot im eigenen featuresSchema des Feature.
Schemagenerierung aus usesSchema. Der Compiler generiert aus den deklarierten Sockets ein Basisfragment in JSON Schema 2020-12 und setzt es mit der schema:-Deklaration des Benutzers zusammen — dasselbe Muster, das featuresSchema verwendet. Das generierte Schema berührt nie die Festplatte; es existiert nur im Speicher während des Component-Validierungsdurchlaufs. Die uses:-Map des Entwicklers im Aggregate wird gegen das zusammengeführte Schema validiert; der selector: jedes Sockets wird während der statischen Analyse als knotenübergreifende Typsicherheitsprüfung gegen die Labels jeder Kandidaten-Component ausgewertet.
Selektorsemantik — der Split-Schema-Mechanismus. usesSchema[].selector: ist das, was die Topologie von Aggrega zu mehr als untypisierter Zeichenfolgenübergabe macht. Ein Socket, der selector: "datastore.aggrega.ai/engine=vector" deklariert, akzeptiert nur Verbindungen zu Components, die mit dem passenden Schlüssel-Wert-Paar gelabelt sind; ein Agent, der versucht, seinen Socket primary_datastore mit einer relational-Component zu verbinden, scheitert am Static Analyzer mit einer klaren Diagnose zur Selektorverletzung. Der Selektor ist eine Label-Selektor-Zeichenfolge im Kubernetes-Stil — durch Kommas UND-verknüpfte Anforderungen in den Formen =, !=, in (...), notin (...), bloßer Schlüssel und !key —, dieselbe Grammatik, die appliesTo bei einem Feature verwendet; siehe vocabulary/modifier-system.md für die Grammatik und architecture/13-catalog-and-registry.md §2 „Selektoren im Kubernetes-Stil“ für die Semantik der Engine. Eine Anforderung außerhalb dieser Formen wird abgelehnt, statt als ein anderer Selektor gelesen zu werden: Eine leere Anforderung (ein führendes, abschließendes oder doppeltes Komma), ein Schlüssel mit Leerraum oder einem der Zeichen =, !, (, ) und dem Komma oder eine Menge ohne schließende Klammer bricht jeden Build ab, der eine Kante über den Socket verbindet, und nennt die Anforderung. Ein Socket, der Frontends ausschließen soll, wird daher selector: "tier!=frontend" geschrieben; "!tier=frontend" wird abgelehnt, weil ! einen Label-Schlüssel benennt und sonst nichts.
Ad-hoc-Sockets — was das Deklarieren eines Sockets bringt und was ein Autor ohne Deklaration tun darf. Der Autor eines Aggregate darf an seiner eigenen Komponente einen uses:-Eintrag unter einem Socket-Namen schreiben, den dieses usesSchema nicht deklariert, auch an einer Component, die überhaupt kein usesSchema deklariert. Die Kante wird aufgebaut. Schweigt der Katalog zu einem Socket, bedeutet das, dass die Verbindung nicht vorgesehen war, nicht dass sie verboten ist, und die Topologie der Anwendung gehört dem Entwickler.
Worauf ein Ad-hoc-Socket verzichtet, ist genau das, was ein deklarierter bietet, denn all das steckt im Eintrag in usesSchema: kein selector, sodass nichts einschränkt, welche Komponente die Kante erreichen darf, und die knotenübergreifende Typsicherheitsprüfung nichts auszuwerten hat; keine inject:-Allowlist; kein valueSchema pro Kante, sodass values: pro Kante keinen Vertrag hat, gegen den es geprüft werden könnte, und keine deklarierten Standardwerte, die es erben könnte. Er verzichtet auch auf infraSchema, obwohl dieser Vertrag bei einem solchen Socket ohnehin nie erreicht wird: infra pro Kante wird in einem Kanteneintrag eines Release geschrieben, und ein Release-Eintrag darf nur einen Socket benennen, den die konsumierende Component deklariert. Unverändert bleibt, was die Kante tragen darf: Das from: jedes inject-Eintrags muss weiterhin einen Schlüssel benennen, den das schema.provides der Ziel-Component deklariert, und das Ziel muss weiterhin existieren — beides bricht den Build ab wie bei einem deklarierten Socket.
Lesen Sie „keine inject:-Allowlist“ als das Fehlen einer Einschränkung und nicht als Blackbox-Deklaration, denn beide sehen gleich aus und verhalten sich gegensätzlich. Eine Kante über einen Ad-hoc-Socket darf die Zustellung frei vorgeben: Es gibt keine Allowlist, außerhalb derer ein Mechanismus liegen könnte, und keine Entität hat zugesagt, die Werte intern zu behandeln. Die obige Blackbox-Ablehnung gilt für einen Socket, den die Entität sehr wohl deklariert und ohne inject:-Allowlist gelassen hat — diese Auslassung ist eine Aussage über eine Verbindung, die die Entität vorgesehen hat, und ein Ad-hoc-Socket trifft keine solche Aussage.
Die Zustellung nimmt denselben Weg, und das gerenderte Artefakt verzeichnet keinen Unterschied. Der inject-Block einer Ad-hoc-Kante wird genau wie der eines deklarierten Sockets aufgelöst und zugestellt: Jeder from:-Schlüssel wird aus den ausgewerteten provides des Ziels gelesen und landet im Injektionskontext des konsumierenden Knotens unter dem vom Autor gewählten Zustellschlüssel, von wo aus er das gerenderte Artefakt erreicht. Es gibt einen einzigen Zustellweg, und nichts darauf verzweigt danach, ob der Socket deklariert wurde. Was ein deklarierter Socket hinzufügen kann, ist Inhalt — Standardwerte pro Kante, die sein valueSchema oder infraSchema einsetzt —, daher rendert dieselbe Kante dort, wo ein deklarierter Socket keinen solchen Vertrag trägt, unter beiden Arten von Sockets identisch. Die Deklaration ist eine Tatsache über die Verbindung, keine Eingabe für das, was gerendert wird.
values: pro Kante auf einem Ad-hoc-Socket wird akzeptiert und erreicht die konsumierende Recipe unter .context.uses.<alias>.values, unvalidiert: Ohne ein valueSchema, an dem es gemessen werden könnte, wird kein Schlüssel geprüft und keiner abgelehnt. Das ist keine Besonderheit von Ad-hoc-Sockets — ein deklarierter Socket, der für die Säule keinen Vertrag schreibt, behandelt seine Konfiguration pro Kante genauso. Was ein Ad-hoc-Socket ändert, ist, dass der Vertrag nicht hinzugefügt werden kann, ohne den Socket zu deklarieren. .context.uses.<alias>.infra ist bei einer solchen Kante leer, weil die Oberfläche, die infra pro Kante liefert, keinen nicht deklarierten Socket benennen kann.
Jede Kante im ausgegebenen Graphen verzeichnet, welche der beiden sie ist, sodass ein Konsument dies nie ableiten muss, und eine Organisation, die will, dass jede Verbindung über einen deklarierten Socket läuft, kann dies als Governance-Richtlinie verlangen. Den Socket hier zu deklarieren bleibt der bessere Weg und ist das, was der Katalog der Standardbibliothek tut: Ein deklarierter Socket trägt einen selector, der einschränkt, welche Komponenten die Kante erreichen darf, eine inject:-Allowlist, einen Vertrag pro Kante mit eigenen Standardwerten und eine Beschreibung — eine überprüfbare Aussage über eine vorgesehene Verbindung, versioniert mit der Entität, die sie trifft. Die Ad-hoc-Form ist ein Ausweg, kein neuer Standard. Zwei Oberflächen sind bewusst nicht auf diese Weise offen — die uses eines Feature-Attachments dürfen nur einen Socket benennen, den das angehängte Feature deklariert, und die uses pro Kante eines Release dürfen nur einen Socket benennen, den die konsumierende Component deklariert.
Das ausgearbeitete Beispiel examples/adhoc-uses-socket/ baut beide Arten von Kanten an einem einzigen Konsumenten auf und zeigt die beiden zugestellten Werte nebeneinander in der gerenderten Ausgabe, zusammen mit dem Abbruch, den ein nicht deklarierter from:-Schlüssel erzeugt.
Tippfehler in Socket-Namen erscheinen als Hinweis, nicht als Abbruch. Da ein nicht deklarierter Socket-Name zulässig ist, wird ein falsch geschriebener Socket-Name zu einer eigenen Ad-hoc-Verbindung, statt den vom Autor gemeinten Socket zu verbinden — und der Build bleibt grün, während nichts darüber fließt. Der Compiler meldet einen Socket-Namen, der eine Bearbeitung von einem von diesem usesSchema deklarierten Namen entfernt ist, als Warnung, die beide Schreibweisen nennt — siehe errors/warnings.md „Uses-socket near-miss lint (Lint für Beinahe-Treffer bei uses-Socket-Namen)“. Die Warnung ändert nie das Urteil des Builds; der Compiler überwacht nicht, wie ein Autor einen Socket benennt.
Das Verhältnis von usesSchema und featuresSchema. Beide sind deklarative Tabellen und beide tragen eine inject:-Allowlist mit identischer Semantik, aber ein Socket und ein Slot sind verschiedene Dinge und nicht austauschbar. usesSchema regelt komponentenübergreifende Kanten — den Topologiegraphen — und deklariert, welche Sockets einen Vertrag tragen. featuresSchema regelt Attachment-Slots, und ein Slot ist ein benannter Bindungspunkt, keine Aufzählung: Ein Attachment unter einem Namen, den kein Slot deklariert, ist im eigenen Block der Komponente zulässig. (Die Slots, die ein Socket für seine Verbindungen deklariert, sind die eine geschlossene Menge, wie oben unter „Slots, die jede Verbindung füllt“ beschrieben.) Die beiden Oberflächen sind in diesem Punkt zusammengewachsen — auch der eigene uses:-Eintrag einer Komponente unter einem nicht deklarierten Socket-Namen ist zulässig —, bleiben aber getrennt: Ein nicht deklarierter Slot ist ein freies Attachment an einer Component, deren deklarierte Slots davon unberührt bleiben, während ein nicht deklarierter Socket eine Kante ohne Selektor und ohne Vertrag pro Kante ist. Viele Components deklarieren beides; die beiden Tabellen setzen sich unabhängig voneinander zusammen.
Anbindungs-Slots: featuresSchema
Eine Component kann über einen featuresSchema-Block Anbindungs-Slots deklarieren. Jeder Slot benennt einen Bindungspunkt, an dem die Component erwartet, dass ein Feature angebunden wird — ein Root-Passwort, ein API-Schlüssel, ein Auth-Token, eine Identitätsbindung — und schränkt ein, welches Feature ihn belegen darf und wie das Material der Füllung zugestellt werden darf.
Dieser Abschnitt behandelt die eigenen Slots der Component. Die Slots, die ein Socket für jede Verbindung deklariert, sind dagegen eine geschlossene Menge — siehe „Slots, die jede Verbindung füllt“ unter Topologie-Sockets.
Das Deklarieren eines Slots schließt die Anbindungsoberfläche nicht. Ein Autor kann ein Feature unter einem Namen anbinden, den kein Slot deklariert, und diese Anbindung ist eine freie Anbindung: vollkommen zulässig, nur eben nicht an einen deklarierten Slot gebunden. Diese Offenheit ermöglicht es, dass eine Katalogentität zwei unterschiedliche Deployment-Formen bedient, ohne den Katalog zu forken:
- Pro Konsument. Jede Instanz füllt den Slot mit ihrem eigenen Feature, sodass jeder Konsument seine eigene gerenderte Credential erhält.
- Gemeinsam. Keine Instanz füllt den Slot; stattdessen wird eine Credential einmal in einem breiteren Geltungsbereich angebunden (einem Subsystem oder einer Release-Grenze) und kaskadiert auf jede Komponente darunter, sodass jeder Konsument aus dieser einen Deklaration gefüllt wird. Was gerendert wird, folgt der Realisierung: ein Secret pro Konsument, jedes mit demselben Material, bei einer Realisierung, die ein Secret rendert; keines bei einer, die jeden Konsumenten auf ein bereits existierendes Secret verweist.
Der Autor wählt zwischen beiden durch das, was er anbindet. Die Katalogentität ist in beiden Fällen dieselbe.
Eine Form führt auf dieser offenen Oberfläche zum Abbruch: eine Füllung, die auf der Komponente unter einem anderen Namen geschrieben ist. Wenn eine Anbindung, die auf der Komponente selbst geschrieben ist — in ihrem eigenen features:-Block im Aggregate oder im Eintrag des Release für genau diese Komponente —, einen Namen trägt, den kein Slot deklariert, und ihr Feature den selector eines Slots erfüllt, den auf dieser Komponente nichts belegt, nachdem alle Geltungsbereiche zusammengeführt sind, bricht der Build ab. Das ist die Form, die eine für den Slot gedachte Füllung annimmt, wenn sie unter dem falschen Namen geschrieben wird: Unverändert wäre sie eine freie Anbindung, während der Slot leer bleibt, und ein leer gelassener optionaler Slot baut grün und stellt nichts zu. Die Meldung nennt die Anbindung, die Komponente, das Feature und jeden leeren Slot, zu dem dieses Feature passt, und die Abhilfe ist, es unter dem Namen des Slots anzubinden. Das gilt für jedes Feature, nicht nur für Credentials. Alles andere auf der Oberfläche bleibt frei: eine Anbindung, deren Feature zu keinem deklarierten Slot passt, eine zusätzliche Anbindung, sobald jeder passende Slot belegt ist, und eine Anbindung, die die Komponente von einem Subsystem oder einer Release-Grenze erbt — die oben beschriebene gemeinsame Form bleibt also unberührt. Ein Slot, der keinen selector deklariert, sagt nichts darüber aus, für welches Feature er gedacht ist, daher wird keine Anbindung auf diese Weise an ihm gemessen. Der Abbruch ist in errors/fatal-halts.md unter „An attachment written under another name fits a slot its component leaves empty (Eine unter einem anderen Namen geschriebene Anbindung passt zu einem Slot, den ihre Komponente leer lässt)“ beschrieben.
Die beiden Formen lassen sich kombinieren, und die nähere gewinnt. Ein Autor kann beides zugleich tun: ein Feature in einem breiteren Geltungsbereich anbinden, sodass es jede Komponente in diesem Bereich erreicht, und den Slot auf der einen Komponente füllen, die etwas anderes benötigt. Die Füllung im Geltungsbereich der Komponente gewinnt — Feld für Feld, sodass sie nur die Felder neu angeben muss, die sie ändert, und der Rest weiterhin aus der breiteren Anbindung stammt. Die Geschwisterkomponenten, die den Slot nicht gefüllt haben, behalten die breitere Anbindung unverändert. Die vollständige Vorrangregel, einschließlich ihres Zusammenspiels mit annotationsgesteuerten Anbindungen und mit zusammengesetzten Aggregates, findet sich unter vocabulary/labels-and-annotations.md „Vorrang von Anbindungen“.
Schemadefinition auf der Component:
spec: featuresSchema: root_password: inject: [] description: Root database password. Recipe controls delivery (Black-Box). user_password: inject: [env, file] description: Application user password, auto-generated if omitted. replication_password: inject: [] description: Replication password for HA setups.Feldsemantik:
| Feld | Typ | Standard | Bedeutung |
|---|---|---|---|
required | bool | false | Deklariert, dass der Slot am Ende belegt sein muss. Der Build bricht ab, wenn auf einer Instanz dieser Component nichts den Namen des Slots belegt, geprüft gegen die Anbindungsmenge, die die Instanz nach der gesamten Anbindungskaskade hält — eine Anbindung, die in einem Geltungsbereich deklariert ist, von dem die Instanz erbt, erfüllt den Slot also genauso wie eine direkt auf der Instanz geschriebene Füllung. Die Diagnose nennt die Komponente und den Slot. |
inject | string[] | — | Allowlist der zulässigen Inject-Zustellmechanismen. [] (leer) bedeutet Blackbox — das Recipe steuert die Zustellung intern, und das Material wird nie an den Workload zugestellt. [env, file] bedeutet transparent — das Material der Füllung darf über die aufgeführten Mechanismen zugestellt werden. Dieselbe Semantik wie usesSchema[].inject. |
description | string | — | Dokumentation für Menschen, gerendert von IDE und Hub. |
selector | string | — | Optionaler Label-Selektor im Kubernetes-Stil, der einschränkt, welches Feature diesen Slot füllen darf — das Slot-Gegenstück zum selector eines usesSchema-Sockets, mit derselben Grammatik und derselben nativen Label-Matching-Engine. Wird während der statischen Analyse gegen die eigenen Labels des angebundenen Features ausgewertet; eine Füllung, deren Labels ihn nicht erfüllen, führt zum Abbruch, ebenso ein Selektor, den die Grammatik ablehnt, unter Nennung der Anforderung, die sie nicht lesen konnte. Weglassen, um der Füllung keine Einschränkung aufzuerlegen. |
sensitive | bool | false | Deklariert, dass alles, was diesen Slot belegt, geheimes Material verarbeitet. Eine Aussage über den Bindungspunkt, nicht über eine bestimmte Füllung; siehe „Einen Slot als sensibel deklarieren“ weiter unten. |
Ein Slot schränkt ein, welche Füllung ihn belegen darf, nicht, was die Füllung konfiguriert. Es gibt bewusst keinen values- oder infra-Vertrag auf Slot-Ebene: Das eigene schema: des angebundenen Features besitzt diese Säulen, sodass jeder Vertrag genau einen Ort hat.
Mit dem selector des Slots grenzt eine Component ein, welches Feature einen Slot füllen darf — zum Beispiel auf ein Provider-spezifisches Credential-Feature (feature.aggrega.ai/kind=secret, provider=helm) —, ohne ein FeatureRecipe zu nennen, genau so, wie ein usesSchema-Socket-Selektor das Ziel einer Abhängigkeitskante eingrenzt. Der Compiler wertet den Selektor gegen die Labels des angebundenen Features aus und gegen nichts anderes: Er liest die Labels, die die Füllung trägt, und meldet, ob der Selektor sie zulässt. Welche Labels sinnvoll zu verlangen sind, ist eine Entscheidung beim Verfassen des Katalogs, keine Regel, die der Compiler auferlegt.
Tippfehler in Slot-Namen erscheinen als Hinweis, nicht als Abbruch. Da ein nicht deklarierter Anbindungsname zulässig ist, wird ein falsch geschriebener Slot-Name zu einer freien Anbindung, statt den vom Autor gemeinten Slot zu füllen. Der Compiler meldet einen Anbindungsnamen, der eine Bearbeitung von einem deklarierten Slot-Namen entfernt ist, als Warnung, die beide Schreibweisen nennt — siehe errors/warnings.md „Attachment-slot near-miss lint (Lint für Beinahe-Treffer bei Anbindungs-Slots)“. Die Warnung ändert nie das Urteil des Builds; der Compiler überwacht nicht, wie ein Autor eine Anbindung benennt. Ein Name, der eine Bearbeitung von einem Slot entfernt ist, dessen selector das Feature der Anbindung erfüllt, löst keine Warnung aus: Wo dieser Slot leer bleibt, meldet stattdessen der oben beschriebene Abbruch die Anbindung, und wo etwas anderes den Slot belegt, ist die Anbindung eine gewöhnliche zusätzliche.
Einen Slot als sensibel deklarieren
sensitive: true auf einem Slot drückt die eigene Anforderung des Konsumenten aus: Alles, was diesen Punkt belegt, verarbeitet geheimes Material.
spec: featuresSchema: password: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env] description: "Optional database password credential."Das ist tatsächlich eine andere Information als das sensitive: true eines Schema-Blatts, kein bequemes Duplikat davon, und der Katalog der Standardbibliothek braucht beides. Eine referenzierbare Credential veröffentlicht provides.name und provides.key — den Locator der Ressource und den Datenschlüssel darin — und keines von beiden ist sensibel: Der Name eines Kubernetes-Secret ist öffentlich, ebenso der Schlüssel darin. Dennoch verarbeitet der Slot, den diese Credential füllt, zweifellos geheimes Material. Ein Blatt sagt dieses Datum ist geheimes Material; ein Slot sagt dieser Bindungspunkt verarbeitet geheimes Material; die beiden Aussagen betreffen verschiedene Dinge und können unabhängig voneinander gelten.
Die praktische Folge ist, dass die Anforderung mit dem Bindungspunkt wandert und nicht mit der Füllung. Ein Feature, das überhaupt kein sensibles Blatt deklariert — weil die Ziel-Engine die Credential besitzt und der Autor nichts schreibt —, belegt einen sensiblen Slot dennoch als sensible Anbindung, weil der Slot es so festgelegt hat. Auch das Umgekehrte gilt: Eine Füllung, die ein sensibles Blatt deklariert, ist eine sensible Anbindung, auch wenn sie einen Slot belegt, der keine solche Deklaration getroffen hat, oder wenn sie eine freie Anbindung ist, die keinen Slot belegt.
Die Deklaration folgt der Anbindungskaskade und nicht einem einzelnen geschriebenen Block. Die Anforderung eines Slots gilt für die Füllung, die nach dem Zusammenführen aller Geltungsbereiche am Ende gebunden ist, sodass eine Füllung auf Komponentenebene, die eine breitere verdrängt, die Anforderung unverändert erbt.
sensitive auf einem Slot hat dieselbe Obergrenze wie das Schlüsselwort auf Blattebene — es annotiert, es verschlüsselt nicht, validiert nicht, lehnt nicht ab, erzwingt keinen Zustellmechanismus und ändert kein gerendertes Byte. Die vollständige Aussage steht unter vocabulary/compact-form-authoring.md „Was das Schlüsselwort nicht tut“.
sensitive und compliance.aggrega.ai/data-class sind zwei verschiedene Achsen, nebeneinander dokumentiert und nie vermischt. sensitive ist ein Boolean auf einem Blatt oder einem Slot: Dieses Datum oder dieser Bindungspunkt verarbeitet geheimes Material. compliance.aggrega.ai/data-class ist ein abgestuftes Label auf einem ganzen Knoten — public, internal, restricted —, das den Daten, die eine Komponente hält, eine Governance-Identität gibt. Das eine ist pro Datum und binär, das andere pro Knoten und geordnet; keines ersetzt das andere, und eine Entität kann beide tragen. Das Label wird unter vocabulary/labels-and-annotations.md und architecture/08-credential-model.md „Daten-Governance rund um Credentials“ behandelt.
Schemaprojektion aus featuresSchema
Deklarierte Slots werden in ein JSON Schema 2020-12-Fragment projiziert, das die Form des Anbindungsblocks beschreibt. Zwei Arten von Füllung werden dagegen validiert: der Anbindungsblock einer Komponente, die ein importiertes Modul beisteuert, sobald die Komposition aufgebaut ist, die es importiert, und eine Anbindung, die auf einer breiteren Ebene deklariert ist, gegen den Slot jeder Komponente, die sie erreicht. Der Anbindungsblock einer Komponente, die das Aggregate selbst deklariert, wird stattdessen am Dokumentschema des Aggregate und an der Allowlist inject des Slots gemessen (siehe unten), und das Fragment ist so geformt, dass beide bei jeder Füllung zum selben Urteil kommen. Die Projektion berührt nie die Festplatte; sie existiert nur im Speicher, und das schema: einer Component muss die Anbindungssäule nie von Hand verfassen.
Eingabe-featuresSchema:
featuresSchema: root_password: inject: [] user_password: inject: [env, file]Projiziertes Fragment (im Speicher; Darstellung in Kompaktform):
# The OUTER object is open: an attachment under a name no slot declares is# admitted, because a free attachment is legal authoring.root_password: type: { type: string } description: { type: string } values: type: object additionalProperties: true # inject admits only an empty block — inject: [] means the Recipe controls # delivery, so a fill may name no mechanism inject: {}user_password: type: { type: string } description: { type: string } values: type: object additionalProperties: true inject: env: { type: array } file: { type: array } # arg is absent — not in the inject allowlistDie beiden Tiefen sind unabhängig. Das äußere Objekt ist offen, sodass ein deklarierter Slot nie die Anbindungen verbietet, die die Entität nicht aufgezählt hat. Das eigene Fragment jedes deklarierten Slots ist geschlossen, sodass eine Füllung, die einen deklarierten Slot belegt, dennoch an die Form dieses Slots gebunden ist.
Das Fragment beschreibt nur die FORM. Es enthält keine Aussage darüber, welche Slots belegt sein müssen, weil ein als required markierter Slot von einer Anbindung belegt werden kann, die aus einem breiteren Geltungsbereich hereinkaskadiert — wodurch der Block, den dieses Fragment beschreibt, leer bleibt. Die Anforderung wird daher gegen die Anbindungsmenge geprüft, die eine Komponente am Ende hat, und nicht gegen das, was ein einzelner Block deklariert, und die beiden Fragen widersprechen sich nie, weil nur eine von ihnen jemals an den geschriebenen Block gestellt wird.
Die zulässigen Schlüssel spiegeln die Schlüssel wider, die eine Anbindung überall tragen darf, sodass ein Schlüssel, der auf einer freien Anbindung zulässig ist, auch auf einer Slot-Füllung zulässig bleibt. Jeder in der Allowlist stehende Zustellmechanismus ist eine Liste von Zustelleinträgen — dieselbe Form, die inject: überall annimmt; der Slot schränkt ein, welche Mechanismus-NAMEN erscheinen dürfen, nicht, wie ein Eintrag aussieht.
Wo die inject-Allowlist durchgesetzt wird
Die Allowlist bindet beide Seiten des Slots, in zwei verschiedenen Schritten.
Gegenüber der Workload des Recipe, im Render-Schritt: Eine Workload, die über die Anbindungseinträge ihres Containers auf einen Slot verweist, muss einen Slot nennen, den die Entität deklariert, und muss einen Zustellmechanismus wählen, den die inject-Allowlist des Slots zulässt; ein Verweis auf einen Blackbox-Slot (inject: []), auf einen Mechanismus außerhalb der Allowlist oder auf einen Slot, den die Entität nie deklariert hat, bricht den Build ab. Die Diagnose nennt das Recipe, den Container-Pfad und den betroffenen Slot und wird als Katalogfehler eingestuft — das Recipe hat den Fehler gemacht.
Gegenüber der eigenen Anbindung des Aggregate, wenn seine Anbindungen aufgelöst werden und vor jedem Rendering: Ein inject:-Block auf einer Füllung, die einen deklarierten Slot belegt, darf nur Mechanismen nennen, die die Allowlist des Slots zulässt, und ein Blackbox-Slot lässt keinen zu — seine leere Allowlist besagt „das Recipe stellt dies intern zu; schreiben Sie die Zustellung nicht vor“, und das Verfassen einer Zustellung dafür bricht den Build ab. Die Diagnose ist auf der Anbindung positioniert und nennt den Slot und den betroffenen Mechanismus, zusammen mit den Mechanismen, die der Slot zulässt, sofern er welche zulässt; sie wird als Entwicklerfehler eingestuft, weil das Aggregate den Fehler gemacht hat. Ein leerer inject: {}-Block nennt keinen Mechanismus, schreibt also keine Zustellung vor und wird auf jedem Slot akzeptiert, einen Blackbox-Slot eingeschlossen — gleichermaßen auf einer Komponente, die das Aggregate deklariert, auf einer, die ein importiertes Modul beisteuert, und auf einer Anbindung, die auf einer breiteren Ebene deklariert ist. Eine freie Anbindung — eine unter einem Namen, den kein Slot deklariert — unterliegt keiner solchen Einschränkung, weil die Allowlist zum Slot gehört und nicht zum Block.
Der durchgängige Ablauf durch die Kompilierungspipeline — wie eine Anbindung im Aggregate mit einem Credential-Feature (etwa core/secret-value) und dann mit einem Provider-spezifischen FeatureRecipe verbunden wird, das die Credential an die laufende Workload zustellt — wird in examples/05-credential-features durchgearbeitet.
Ein Schlüssel, den der Aufrufer vorlegt, und ein Schlüssel, den der Server prüft
Wo eine Komponente eine andere aufruft, die einen Schlüssel prüft, hält jedes Ende den Schlüssel auf seiner eigenen Seite, in einem Slot, den es selbst deklariert. Das ist eine Konvention, der der Katalog der Standardbibliothek folgt; der Compiler setzt nichts davon durch — er prüft die Slots jeder Komponente gegen die eigenen Anbindungen dieser Komponente, leitet ihre Strings durch und vergleicht nie, was eine Komponente hält, mit dem, was eine andere hält.
- Der Schlüssel, den ein Aufrufer vorlegt, gehört dem Aufrufer. Er liegt in einem Slot, den der Socket des Aufrufers für jede Verbindung deklariert — siehe „Slots, die jede Verbindung füllt“ oben —, sodass ein Aufrufer, der mehrere Ziele erreicht, für jedes einen Schlüssel hält. Der
model-Socket voncore/ai-agent/crewaideklariert diesen Slot alscredential, und seine Recipes stellen zu, was ihn füllt, alsOPENAI_API_KEY. Diemodels-Sockets voncore/gateway/litellm,core/gateway/kongundcore/gateway/apisixdeklarieren ihn ebenfalls, und ihre Recipes stellen den Schlüssel jeder Verbindung unter einer eigenen Variablen zu, benannt nach dem Alias der Verbindung, sodass jedes Modell, das das Gateway bereitstellt, einen eigenen Schlüssel hält. Ein Schlüssel, den eine Component stattdessen in einem eigenen Slot deklariert, ist ein einziger Schlüssel für jede Verbindung, die sie herstellt. - Der Schlüssel, den ein Server prüft, ist der eigene Slot des Servers.
core/ai-model/vllm,core/ai-model/teiundcore/ai-model/tgideklarieren jeweils einen optionalenapi_key, und jedes ihrer Recipes stellt zu, was ihn füllt, als die Variable, aus der der Server seinen Schlüssel liest. Das LiteLLM-Modell und -Gateway deklarierenapi_keyfür den Schlüssel, den LiteLLM seinen Master Key nennt. - Keines der Enden sieht die Anbindungen des anderen. Eine Anbindung an einer Verbindung ist eine der Anbindungen des Aufrufers und erreicht nur das Rendering des Aufrufers, und die gerenderte Ausgabe eines Servers ist dieselbe, was auch immer die Verbindungen, die ihn erreichen, tragen. Ein als
requiredmarkierter Slot wird von der Komponente geschuldet, die ihn deklariert, nie von den mit ihr verbundenen Komponenten, und das Füllen des Slots eines Endes füllt auf dem anderen nichts — den Schlüssel auf beiden Enden zu deklarieren ist also das Minimum und kein Duplikat. - Beide Enden lesen einen Parameter, sodass der Schlüssel, den der Aufrufer vorlegt, und der Schlüssel, den der Server prüft, nicht auseinander geschrieben werden können.
# Aggregate fragment — one parameter feeds both endsspec: parameters: model_key_secret: { type: string } components: model: type: core/ai-model/vllm values: { model: Qwen/Qwen2.5-0.5B-Instruct } features: api_key: # the key the server verifies type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-key agent: type: core/ai-agent/crewai # values (role, goal, backstory, …) elided uses: model: local: target: model features: credential: # the key the caller presents type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-keyEin Server, der einen einzigen Schlüssel prüft, kann seine Aufrufer nicht unterscheiden: vLLM, TEI und TGI prüfen jeweils einen einzigen Schlüssel, sodass jeder Aufrufer denselben vorlegt, wie viele Verbindungen den Server auch erreichen. Ob die beiden Enden auf ein Secret verweisen oder jedes ein eigenes hält, ergibt sich daraus, wo jeder Provider ein Secret per Referenz auflöst, und das Manifest wählt die Realisierung jedes Endes — Credential-Modell arbeitet beide Fälle durch.
Eine Credential, die eine Komponente für sich selbst hält — etwa ein Schlüssel, mit dem sie ihre eigenen Sitzungen signiert —, ist ein Slot ihres eigenen featuresSchema: wie jeder andere. Ein Passwort, das sie einem Datenspeicher vorlegt, den sie über einen ihrer Sockets erreicht, ist der oben beschriebene Schlüssel des Aufrufers und liegt daher auf dieser Verbindung als credential: Der backend-Socket von core/gateway/kong deklariert ihn, und seine Recipes zur Workload-Synthese stellen ihn als KONG_PG_PASSWORD zu, und der cache_store-Socket von core/gateway/litellm deklariert ihn für das Passwort, das sein semantischer Cache dem Store vorlegt, zugestellt als REDIS_PASSWORD. Wo eine Verbindung ein Paar vorlegt — eine Zugriffsschlüssel-ID und das zugehörige Geheimnis —, ist die geheime Hälfte credential und die ID-Hälfte credential_id, wie beim store-Socket von core/ai-agent/agenta-api.
Selbstinjektion: spec.inject
Eine Component kann ein Top-Level-Array spec.inject: deklarieren, das die zulässigen Zustellungsmechanismen für die Selbstinjektion auflistet. Ist es vorhanden, können Entwickler im Aggregate einen Block inject: auf Komponentenebene verwenden, um die eigenen Schlüssel aus values: oder provides: der Component direkt in deren eigene Zustellungspipe einzuspeisen (die Umgebungsvariablen ihres Containers, eingehängte Dateien oder Prozessargumente). Ist spec.inject: nicht vorhanden oder leer, ist die Selbstinjektion auf Komponentenebene verboten — das Recipe steuert die gesamte interne Verdrahtung, entsprechend dem Black-Box-Muster, das usesSchema[].inject: [] und featuresSchema[].inject: [] auf die komponentenübergreifende Zustellung bzw. die Zustellung von Credentials anwenden.
# Component declares its self-inject allowlist:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/web-server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: inject: [env, file] schema: values: log_level: { type: string, default: info } tls_enabled: { type: boolean, default: false } provides: health_endpoint: { type: string }# Aggregate fragment — developer dictates self-inject delivery:components: api: type: core/web-server values: log_level: debug tls_enabled: true inject: env: - in: LOG_LEVEL value: '{{"{{"}} .values.log_level }}' - in: TLS_ENABLED value: '{{"{{"}} .values.tls_enabled }}' file: - in: /etc/web/health-probe from: health_endpointJedes Template unter value: beginnt mit {{"{{"}} statt mit {{. Der gesamte Text des Aggregate wird einmal als Template gelesen, zur Parameterinterpolation, bevor die Auflösung der Selbstinjektion läuft, und .values existiert zu diesem Zeitpunkt nicht; das Escaping setzt {{ wieder ein, damit die Auflösung der Selbstinjektion es auswerten kann. Siehe Text, der eigene doppelte geschweifte Klammern enthält.
Feldsemantik. spec.inject: ist ein Array von Mechanismusnamen. Drei Werte sind definiert:
env— Umgebungsvariablen im Container.file— Pfade eingehängter Dateien.arg— Kommandozeilenargumente des Prozesses.
Die Semantik entspricht genau der von usesSchema[].inject und featuresSchema[].inject — dasselbe Vokabular, dasselbe Black-Box-Muster bei Weglassen, dieselbe Authoring-Form auf der Seite des Aggregate. Der Unterschied liegt in der Quelle: usesSchema[].inject regelt, wie die provides einer komponentenübergreifenden Abhängigkeit in die Zustellungspipe des Konsumenten fließen; featuresSchema[].inject regelt, wie ein Credential einen Container erreicht; spec.inject regelt, wie die eigenen values und provides der Component deren eigenen Container erreichen.
Authoring-Disziplin. Eine Component core/web-server, die spec.inject: [env, file] deklariert, entscheidet sich für transparente Zustellung — der Autor des Aggregate bestimmt, welche Umgebungsvariablennamen welche Werte tragen. Eine Component, die spec.inject: [] deklariert (oder das Feld weglässt), hält die Zustellung opak — das valuesMapping: des Recipe entscheidet, welche Felder in welche Container-Variablen fließen, und der Entwickler kann dies im Aggregate nicht überschreiben. Das Black-Box-Muster eignet sich für Components mit stabilem Vertrag (eine Component core/postgres-db, deren Recipe weiß, wie das DB-Passwort in eine Umgebungsvariable POSTGRES_PASSWORD verdrahtet wird); das transparente Muster eignet sich für Components, bei denen die Absicht des Entwicklers legitimerweise Zustellungsdetails benennt (ein core/web-server, dessen Anwendung LOG_LEVEL aus einem nicht standardmäßigen Variablennamen liest, den der Entwickler anpassen möchte).
Fehlermodi. Ein Aggregate eines Entwicklers, das einen Block inject: auf einer Component verwendet, deren spec.inject: fehlt oder leer ist, hält den Build beim Laden des Workspace an („Self-inject on a component without an allowlist“ (Selbstinjektion auf einer Komponente ohne Allowlist)). Ein Block inject:, der einen Mechanismus verwendet, der nicht in der Allowlist steht, hält mit derselben Bedingung an und nennt den Mechanismus sowie die von der Allowlist zugelassenen („Self-inject mechanism not in the component’s allowlist“ (Selbstinjektionsmechanismus nicht in der Allowlist der Komponente)). Auch eine Kollision von Zustellungsschlüsseln zwischen Selbstinjektion, komponentenübergreifender Injektion und Credential-Injektion hält den Build an („Duplicate delivery key across inject sources“ (Doppelter Zustellungsschlüssel über Injektionsquellen hinweg)). Unter errors/fatal-halts.md finden Sie die Meldungsform jedes Fehlers.
Katalog-Authoring: Erweitern von Basis-Components
Platform Architects verwenden das Schlüsselwort extends, um spezialisierte Schnittstellen über Unternehmens- oder Community-Baselines zu legen. Das Erweitern komponiert die Struktur und erbt die Datensäulen vollständig. Der Compiler durchläuft die Kette von der Basis abwärts; die beiden Hälften verhalten sich unterschiedlich, und dieser Unterschied ist das gesamte Authoring-Modell.
Was das Erweitern komponiert. Diese Oberflächen werden entlang der Kette zusammengeführt, wobei die erweiternde Component pro Schlüssel gewinnt und Listen ohne Duplikate, beginnend mit der Basis, verkettet werden:
| Oberfläche | Wie sie komponiert wird |
|---|---|
metadata.labels | pro Schlüssel zusammengeführt; bei einem gemeinsamen Schlüssel gewinnt der Wert der erweiternden Component |
metadata.annotations | pro Schlüssel zusammengeführt, mit derselben Rangfolge — deshalb erreicht das Präsenzmandat einer Basis jede Component, die sie erweitert |
spec.featuresSchema | Vereinigung der Attachment-Slots; ein Slot, den die erweiternde Component erneut deklariert, ersetzt den gleichnamigen Eintrag der Basis |
spec.usesSchema | Vereinigung der Topologie-Sockets, mit derselben Ersetzungsregel pro Name |
spec.inject | die beiden Allowlists der Selbstinjektion werden verkettet, Einträge der Basis zuerst, Duplikate verworfen |
spec.assertions | benannte Regeln akkumulieren sich, Regeln der Basis zuerst — und diese eine Oberfläche lässt keine Ersetzung pro Name zu; siehe „Die Vererbung von Assertions ist additiv“ weiter unten |
Ein Socket, den die erweiternde Component hinzufügt, kann eigene kantenspezifische valueSchema und infraSchema tragen; diese sind Verträge für die Kanten dieses Sockets, keine Ergänzungen der eigenen Säulen der Component.
Der Rest von metadata: bleibt bei dem Dokument, das ihn deklariert. labels und annotations sind die einzigen Metadaten, die entlang der Kette weitergegeben werden. name, version, description, maintainers, license, repository, home und keywords gehören der erweiternden Component selbst und werden genau so gelesen, wie sie sie verfasst hat — eine Component, die description: weglässt, hat keine, statt die ihrer Basis zu übernehmen. Identität und Herkunft gehören zu dem Dokument, das Sie gerade lesen, sodass ein Wrapper nie mit dem verwechselt wird, was er umhüllt.
Was das Erweitern vollständig erbt. Die drei Datensäulen — values, infra, provides — werden nicht komponiert. Eine erweiternde Component verfasst keinen Säuleninhalt: Sie schreibt den literalen Marker schema: inherited und erhält den Block schema: ihrer Basis genau so, wie die Basis ihn verfasst hat. Entlang einer Kette beliebiger Tiefe trägt jede Component darin den Block der Kettenwurzel unverändert, sodass aggrega inspect --resolved auf einem Blatt dieselben Säulen zeigt wie auf der Wurzel.
Das veröffentlichte Component-Schema legt fest, welches der drei möglichen Ergebnisse zulässig ist, und weist die beiden anderen beim Laden des Dokuments zurück — mit jeweils einer anderen Diagnose, weil es unterschiedliche Fehler sind:
extends:mit Säuleninhalt unterschema:wird zurückgewiesen. Der Vertrag der Component ist der ihrer Basis; ein zweiter, abweichender Vertrag hat keinen Ort, an dem er existieren könnte.extends:mit vollständig weggelassenemschema:wird zurückgewiesen. Bei einer Auslassung könnte ein Leser einen geerbten Säulenblock nicht von einem vergessenen unterscheiden.schema: inheritedohneextends:wird zurückgewiesen. Der Marker benennt, woher die Säulen stammen, und diese Component hat keine Basis, von der sie sie übernehmen könnte.
Eine erweiternde Component kann die Schlüsselmenge nicht umgestalten. Sie deklariert keine Säulenschlüssel, kann also einen von ihrer Basis deklarierten Schlüssel weder verbergen noch entfernen noch umtypisieren, und sie fügt keine eigenen hinzu. Ein neuer Säulenschlüssel gehört zu der Component, deren Vertrag ihn besitzt. Was immer die Basis bereitstellt, stellt alles, was sie erweitert, identisch bereit.
Eine Spezialisierung verschärft über assertions:. Wenn eine Spezialisierung weniger zulassen muss als die Säulen ihrer Basis — einen engeren Zahlenbereich, eine Teilmenge eines geerbten enum: —, drückt sie das in ihrem eigenen Block assertions: aus: Eine Regel dort weist einen Wert zurück, den das geerbte Schema akzeptiert. Dies ist die Oberfläche, auf der die Verschärfung stattfindet; siehe „Der Block assertions:“ weiter unten.
Die letzten beiden Absätze sind eine einzige Regel, und jede Hälfte für sich allein führt in die Irre: Eine Verengung der Schlüsselmenge ist unmöglich, eine Verschärfung der Constraints ist möglich. Wer nur die erste nimmt, schließt, dass eine Spezialisierung nichts einschränken kann; wer nur die zweite nimmt, schließt, dass sie den Vertrag umgestalten kann. Beides trifft nicht zu — die Schlüsselmenge ist durch die Basis festgelegt, und die darin zugelassenen Werte können per Prädikat eingeschränkt werden.
Die Vererbung von Assertions ist additiv, und die Akkumulation beginnt bei der Wurzel. Eine Instanz einer erweiternden Component wird gegen jede Regel geprüft, die ihre Kette deklariert, sowie gegen die Regeln, die die Component selbst deklariert, wobei die geerbten zuerst ausgewertet werden. Entlang einer Kette beliebiger Tiefe akkumulieren sich die Regeln von der Kettenwurzel abwärts; verletzt eine Instanz mehr als eine Regel, wird daher diejenige gemeldet, die am weitesten oben in der Kette deklariert ist — der grundlegendste Vertrag antwortet zuerst.
Da die Vererbung hinzufügt statt zu ersetzen, darf eine erweiternde Component einen geerbten Regelnamen nicht wiederverwenden, um eine andere Regel zu deklarieren: Das wird zurückgewiesen, wenn die extends-Kette gegen den Katalog aufgelöst wird, mit einer Diagnose, die beide Components und den gemeinsamen Namen nennt. Die Prüfung benötigt die Basis-Component, daher meldet sie sich, wenn der Katalog validiert wird oder ein Build die Kette auflöst — die Validierung des erweiternden Dokuments für sich allein kann es nicht erkennen. Der Regelname ist ein stabiler Bezeichner, daher ist weder das Entfernen der Regel der Basis noch ihr stillschweigendes Umbenennen eine Option, und die Korrektur ist eine Umbenennung in der erweiternden Component. Eine geerbte Regel Byte für Byte unter ihrem eigenen Namen erneut anzugeben, wird als die wirkungslose Operation akzeptiert, die es ist.
aggrega pull ruft die Basis ab. Eine Basis ist eine Abhängigkeit jedes Release, das eine Component erreicht, die sie erweitert, unabhängig davon, ob sie sonst irgendwo genannt wird. aggrega pull folgt jedem extends: bis zum Ende der Kette, ruft eine Basis, die kein Katalogverzeichnis enthält, aus der Registry ab und verzeichnet jede Basis im Lockfile des Release, referenziert vom spec.extends der Component, die sie nennt; ein Build liest die Basis von dort. Ein Manifest bildet daher nur den eigenen Typ eines Wrappers ab und nichts weiter — die Basis braucht nur dann eine eigene Zuordnungszeile, wenn ein Aggregate auch eine Instanz der Basis deklariert. Ein aggrega validate über den gesamten Katalog liest eine Basis auf dieselbe Weise, sodass eine in einer Registry veröffentlichte Basis dort unter Nennung von aggrega pull abgelehnt wird, bis ein Pull sie abgerufen hat.
Die Formate für Schemainhalte finden Sie unter architecture/13-catalog-and-registry.md §3.
Beispiel A: Die Basis-Component (die Unternehmens-Baseline) Der Platform Architect definiert einen grundlegenden Unternehmensserver. Diese Basis setzt das erforderliche Label für das operative Cloud-Primitiv und legt die Sicherheitseinschränkungen im Schema fest. Da der Säulenblock unverändert vererbt wird, erreicht jede Einschränkung hier jede erweiternde Component genau so, wie sie verfasst wurde.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/base-enterprise-server version: 1.0.0 labels: component.aggrega.ai/type: "server"spec: inject: [env] schema: values: # The corporate baseline constraint. Every Component extending this base # receives this leaf verbatim; none of them can restate or loosen it. tls_enabled: { type: boolean, enum: [true], default: true }
# An open range at the baseline. A specialization that needs a tighter # bound expresses it as an assertion, not as a redeclared schema leaf. timeout_ms: { type: integer, default: 5000 } assertions: # A baseline invariant. It is evaluated for instances of this Component AND # for instances of every Component extending it, under this same name. audit-window-is-observable: | {{- if lt (int .values.timeout_ms) 100 -}} {{- fail "the corporate baseline needs timeout_ms of at least 100 so requests are observable" -}} {{- end -}}Beispiel B: Die erweiternde Component (Spezialisierung der Baseline) Ein Gateway wird aus dieser Baseline spezialisiert. Es übernimmt die Säulen der Basis vollständig, fügt eigene Struktur hinzu — ein Label, einen Selbstinjektionsmechanismus, einen Topologie-Socket mit einem Attachment-Slot darauf — und verschärft das geerbte Timeout über eine Assertion. Es wiederholt die Regel audit-window-is-observable der Baseline nicht: Diese Regel wird geerbt und zuerst ausgewertet, sodass eine Instanz dieses Gateways beide Grenzen erfüllen muss — mindestens 100 und höchstens 2000.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/gateway/kong version: 1.0.0 labels: # Every Component declares the reserved base-ontology key, including one # that extends: the envelope requires it on the document itself. component.aggrega.ai/type: "server" api.aggrega.ai/protocol: "http" # merged with the base's labelsspec: extends: core/base-enterprise-server schema: inherited # values, infra and provides are the base's, verbatim inject: [file] # concatenates with the base's [env] -> [env, file] usesSchema: # a socket of its own; the base declared none backend: required: true selector: "component.aggrega.ai/type=stateful-server" inject: [env] featuresSchema: # a slot each connection through it fills credential: sensitive: true inject: [env] description: Password the gateway presents to the configuration backend this connection reaches. assertions: # The tightening. The inherited schema admits any integer for timeout_ms; # this gateway admits only 2000 or less, so the rule rejects a value the # inherited pillar block would accept. timeout-within-gateway-budget: | {{- if gt (int .values.timeout_ms) 2000 -}} {{- fail "the gateway must answer within 2000ms: set timeout_ms to 2000 or less" -}} {{- end -}}Das Recipe, das diese Schnittstelle core/gateway/kong gegen ein physisches Helm-Chart implementiert, finden Sie unter entities/recipe, Beispiel C (kong-gateway).
Der Block assertions:
Component.spec.assertions: ist eine optionale Map benannter Regeln, die architektonische Invarianten des Component-Vertrags ausdrücken — feldübergreifende Regeln, die das Authoring des Entwicklers erfüllen muss, unabhängig davon, welches Recipe an die Component gebunden wird. Jeder Schlüssel ist ein Regelbezeichner, der in der Fehlermeldung erscheint; jeder Wert ist ein Go-Template-Rumpf. Der Compiler wertet sie pro Instanz nach der Schemavalidierung und vor der Recipe-Bindung aus, in der Reihenfolge, in der sie geschrieben sind, und die erste fehlschlagende Regel hält den Build mit der eigenen Fehlermeldung dieser Regel an, gemäß dem Loud-Guardrails-Vertrag.
spec: assertions: replication-needs-two-secondaries: | {{- if eq .values.architecture "replication" -}} {{- if lt (int .values.secondary.replicaCount) 2 -}} {{- fail "architecture=replication requires secondary.replicaCount >= 2" -}} {{- end -}} {{- end -}}Die obige Regel ist eine Eigenschaft des Component-Vertrags — welches Recipe auch immer gebunden wird (Bitnami-Chart, selbst geschriebene Alternative, künftige Implementierung), der Replikationsmodus erfordert mindestens zwei sekundäre Replikate.
In assertions: verschärft eine erweiternde Component. Eine Component, die per extends: eine Basis erweitert, erbt den Säulenblock der Basis wörtlich und deklariert keinen eigenen Säuleninhalt; eine Spezialisierung, die weniger zulassen muss als das geerbte Schema, formuliert die Einschränkung daher hier als Prädikat statt als verengtes Schemablatt — eine Regel, die einen Wert zurückweist, den die geerbten Säulen akzeptieren. Das ausgearbeitete Beispielpaar und das vollständige Vererbungsverhalten finden sich unter „Katalog-Authoring: Erweitern von Basis-Components“ weiter oben: Regeln akkumulieren sich entlang der Kette von der Wurzel her, und die Wiederverwendung eines geerbten Regelnamens für eine andere Regel wird zurückgewiesen, statt sie ersetzen zu lassen.
Der Compiler prüft nicht, ob zwei Regeln beide erfüllbar sind. Eine Regel ist ein Template-Prädikat, kein Constraint, über den der Compiler schlussfolgert; ein Regelpaar, das kein Wert gleichzeitig erfüllen kann — eine Basis, die mindestens 100 verlangt, und eine Spezialisierung, die höchstens 50 verlangt —, erzeugt daher beim Laden des Katalogs keine Warnung. Es zeigt sich auf dem gewöhnlichen Weg: Eine Instanz wird verfasst, der Build hält bei derjenigen der beiden an, die zuerst auslöst, und die Meldung dieser Regel ist das, was der Autor liest. Erwarten Sie nicht, dass ein Widerspruch im Voraus gemeldet wird; prüfen Sie die Verschärfung einer Spezialisierung gegen das, was ihre Basis bereits verlangt.
Verwenden Sie assertions: für echte feldübergreifende Regeln. Constraints pro Feld (Bereich, Muster, Enum) gehören in Schlüsselwörter von schema:; benutzerdefinierte Prädikate pro Feld gehören in validate: der Kompaktform; bedingte Form (ob die Constraints eines Teilbaums gelten) gehört in when:. Die vollständige Authoring-Grammatik — Felder des Template-Kontexts, die Konvention für Meldungen mit {{ fail }}, die Auswertungsphase und ausgearbeitete Beispiele für die Rollen Component und Recipe — finden Sie unter templates/assertions-block.md.