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

Manifest

Die konzeptionelle Rolle der Entität Manifest (Domäne 4 — die Zuordnungstabelle, die abstrakte Schnittstellen an konkrete Recipes bindet) ist in architecture/04-entity-taxonomy.md beschrieben. Diese Seite behandelt die Authoring-Oberfläche des Manifest: wie es neben dem Release steht, die Form der flachen URI-Zuordnung, die Komposition über extends, die Regeln für URI-Kurzschreibweisen, annotationsgesteuerte Feature-Bindungen und das plattformreservierte Präfix aggrega.ai/.

Manifest vs. Release: Trennung der Zuständigkeiten

Das Manifest und das Release tragen Verantwortlichkeiten, die sich nicht überschneiden:

  • Das Manifest legt fest, welches Recipe jeden Katalogtyp realisiert, und über das spec.capability dieses Recipe den Provider (z. B. Helm, Helm-chart, Compose), der ihn rendert. Es ist die Zuordnungstabelle — ein pro Projekt in Git committeter Datensatz darüber, welches konkrete Recipe jede abstrakte Schnittstelle implementiert; die Versionen und Digests, an die ein Build diese Recipes bindet, werden separat im Lockfile jedes Release fixiert.
  • Das Release legt das Ziel fest (z. B. den physischen Ausgabeordner für die Generierung von GitOps-Artefakten). Es ist der Deployment-Router — eine umgebungsspezifische Beschreibung, wo die kompilierten Artefakte landen.

Das Release-Schema enthält auf keiner Verschachtelungsebene ein Feld provider; das Provider-Dispatching gehört ausschließlich zum Manifest.

Der Kompilierungspfad. Wenn ein Benutzer aggrega build --release release.yaml ausführt, löst der Compiler physische Artefakte auf, indem er beide Quellen zusammenführt:

  1. Ziel lesen. Der Compiler durchsucht die Grenzen des Release — zum Beispiel enthält die Grenze ovh-cluster-3 die Komponente user-db (Typ: core/postgres:1.0.0).
  2. Manifest durchsuchen. Er öffnet das Manifest, auf das das Release über sein Feld manifest: verweist.
  3. Zweistufige Suche. Er prüft zuerst die Stufe name auf "user-db". Wird nichts gefunden, prüft er die Stufe type auf "core/postgres:1.0.0" (versioniert), dann auf "core/postgres" (unversioniert).
  4. Recipe auflösen. Der Wert des passenden Eintrags ist eine Recipe-URI; das Recipe, das sie benennt, deklariert in spec.capability, welcher Provider es rendert.
  5. Ausgabegenerierung. Der Compiler kennt nun den Zielordner (dist/boundaries/ovh-cluster-3/), den Provider (Helm-Rendering über Wasm) und das Artefakt (den Quellcode des Recipe). Ahead-of-Time-GitOps-Grenzen werden durchgängig eingehalten.

Flache URI-Zuordnung

Der Block mappings: des Manifest ist eine flache Zuordnung von Komponententyp-URI zu Recipe-URI (und von Funktionstyp-URI zu FeatureRecipe-URI). Die Zuordnung ist auf Manifest-Ebene agnostisch gegenüber der Capability; die Bestimmung der Capability ergibt sich zur Render-Zeit aus dem Feld spec.capability jeder aufgelösten Recipe, nicht aus der strukturellen Form des Manifest. Der Block gliedert die Zuordnungen unter zwei Schlüsseln der obersten Ebene:

  • components.type ordnet einer Komponententyp-URI eine Recipe-URI zu. Jede Komponenteninstanz des deklarierten Typs wird in die angegebene Recipe aufgelöst. Die Zuordnung ist pro Komponententyp eins zu eins. Ein Schlüssel, der nicht den exakten Typ einer Instanz nennt, erreicht sie dennoch über die Basis des Typs, wenn kein Schlüssel diesen exakten Typ nennt und kein anderer Schlüssel für dieselbe Basis geschrieben ist — ein ohne Version geschriebener Schlüssel (core/postgres) oder einer, der eine andere Version nennt (core/postgres:1.0.0), kann also eine Instanz von core/postgres:2.0.0 erreichen —, aber die Recipe, die er nennt, muss die eigene Version jeder solchen Instanz implementieren: Eine auf diese Weise erreichte Instanz von core/postgres:2.0.0, die einer Recipe mit der Deklaration implements: core/postgres:1.0.0 zugeordnet ist, hält den Build an. Ordnen Sie eine solche Instanz mit einem Schlüssel, der ihre Version nennt (core/postgres:2.0.0), einer Recipe zu, die sie implementiert.
  • features.type ordnet einer Funktionstyp-URI eine FeatureRecipe-URI zu. Jede Feature-Anbindung des deklarierten Typs wird in das angegebene FeatureRecipe aufgelöst. Anmeldedaten-Features (mit dem Label feature.aggrega.ai/kind: secret) befinden sich in derselben Zuordnung features.type wie operative Features — das vereinheitlichte Feature-Entitätsmodell.

Jeder Block akzeptiert neben type auch eine Ebene name, die einen bestimmten Instanznamen einer Recipe-URI (oder FeatureRecipe-URI) zuordnet. Die Namensebene hat Vorrang vor der Typebene: Eine in components.name genannte Instanz wird in diese Recipe aufgelöst, während jede andere Instanz desselben Typs über components.type aufgelöst wird. Damit lässt sich eine Überschreibung pro Instanz ausdrücken — zwei Instanzen eines Komponententyps können über zwei verschiedene Recipes bereitgestellt werden (beispielsweise verwenden die meisten Datenbankinstanzen die global zugeordnete Recipe, während eine Instanz auf eine andere physische Implementierung festgelegt ist), ohne den Komponententyp zu forken oder das Manifest zu duplizieren. Die Überschreibung gilt einheitlich: Die genannte Instanz wird über die überschreibende Recipe gerendert und pinnt auch ihre Quelle aus ihr. features.name ist die symmetrische Ebene für Feature-Anbindungen, deren Schlüssel der eigene Name der Anbindung ist — der Schlüssel, unter dem sie in den features: einer Komponente geschrieben ist —, nie der Name der Komponente, an die sie angebunden ist. Das Beispiel für die Rezept-Überschreibung pro Instanz führt einen minimalen Fall mit zwei Instanzen von Anfang bis Ende durch.

Eine Anbindung, die eine Verbindung trägt, wird über den Namen angesprochen, den sie auf der konsumierenden Komponente annimmt: <alias>.<slot>, der Alias, unter dem die Verbindung geschrieben ist, ein Punkt und der Slot, den die Anbindung füllt (siehe den Verbindungseintrag des Aggregate). So kann die Anmeldeinformation einer Verbindung anders realisiert werden als jede andere Anbindung ihres Typs:

spec:
mappings:
features:
type:
core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
name:
# The credential the "gpt" connection carries in its "credential" slot.
gpt.credential: helm/k8s-external-secret:1.0.0

Der Eintrag wird wie jeder andere Eintrag der Namensebene gepinnt und verifiziert, wie der nächste Absatz beschreibt. Auch das Feature, das die Anbindung nennt, wird gepinnt und verifiziert, genau wie das Feature einer auf der Komponente selbst geschriebenen Anbindung, unter dem Verbindungseintrag, den sein Autor geschrieben hat — siehe Das Lockfile.

Ein Schlüssel unter name muss etwas benennen, das der Build enthält. Die Ebene wird über den exakten Namen abgeglichen, sodass ein Schlüssel in components.name, der keine Komponenteninstanz im Build ist, oder ein Schlüssel in features.name, der dort keine Anbindung ist — meist der Name der Komponente, an der eine Anbindung sitzt, geschrieben dort, wo der eigene Name der Anbindung hingehört —, von nichts konsultiert würde, und die Instanzen, für die er gedacht war, würden stillschweigend über die Ebene type aufgelöst. Stattdessen hält der Build bei einem solchen Schlüssel an, bevor etwas gerendert wird, und nennt das Manifest, den Schlüssel, die Namen dieser Art, die der Build enthält, und den Namen, den Sie vermutlich gemeint haben — siehe A Manifest name mapping names nothing in the build (Eine Namenszuordnung des Manifest benennt nichts im Build).

Eine per Name gebundene Realisierung wird wie eine per Typ gebundene gepinnt und verifiziert. aggrega pull beschafft jede Recipe und jedes FeatureRecipe, das eine der beiden Ebenen bindet — aus einem Katalogverzeichnis, dem Cache oder einer Registry — und zeichnet jede im Lockfile des Release mit ihrer aufgelösten Version und ihrem Inhalts-Digest auf, unter dem Zuordnungseintrag, der sie bindet: manifest.spec.mappings.components.name.<instance> für einen Eintrag der Namensebene, neben manifest.spec.mappings.components.type.<type> für einen der Typebene. aggrega build hält jede von ihnen an ihrem Pin fest. Ein Lockfile, das keine Zeile für eine Realisierung enthält, die das Manifest bindet, hält den Build als veraltet an und nennt die Realisierung und den Eintrag, der sie bindet; eine Realisierung, deren Inhalt sich seit dem Pull geändert hat, hält ihn auf dieselbe Weise an und nennt beide Digests. In beiden Fällen zeichnet aggrega pull --release <release> die Realisierung in ihrem aktuellen Stand auf. Wie ein Eintrag unter type wird ein Eintrag unter name gepinnt, unabhängig davon, ob das Release eine Instanz dieses Namens deklariert, sodass ein Eintrag unter name, der eine Recipe nennt, die kein Katalog und keine Registry enthält, den Pull anhält; ein Eintrag unter name, der keine Instanz nennt, die der Build enthält, wird ebenfalls gepinnt und hält den Build an, wie der vorige Absatz beschreibt.

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: production-manifest
version: 1.0.0
spec:
mappings:
components:
type:
# Component-type → Recipe URI. A Recipe URI is at most two segments: an
# optional leading capability, then the recipe name. The bare one-segment
# form (last line) is the common case.
core/datastore/postgres: helm/postgres:1.2.0
core/api-server: helm/api-helm:0.5.0
core/python-worker: standard-python-worker:2.0.0
features:
type:
# Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones.
core/data-masking: helm/data-masking-litellm:1.0.0
core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0

Bestimmung der Capability zur Render-Zeit. Der Manifest-Eintrag bindet einen Komponententyp an eine Recipe-URI. Eine Recipe-URI hat höchstens zwei Segmente — eine optionale führende Capability, dann den Rezeptnamen — plus ein optionales :version; der Resolver teilt nur am ersten /, sodass ein Verweis mit einem dritten Segment kein Rezept benennt und die Auflösung anhält. Zur Render-Zeit lädt der Resolver die Recipe per direktem URI-Lookup gegen Lockfile und Katalog, und das Feld spec.capability jeder Recipe bestimmt die Dispatch-Gruppierung pro (Pfad, Capability). Die strukturelle Form des Manifest bleibt flach, unabhängig davon, wie viele Anbieter der weitere Katalog unterstützt.

Direkter URI-Lookup

Der Zuordnungswert des Manifest ist eine Recipe-URI. Der Compiler löst die URI direkt gegen Lockfile und Katalog auf und gibt die passende Recipe zurück. Er iteriert nicht über die Deklarationen in spec.implements, um eine Recipe zu finden, die einen Komponententyp „implementiert“. Jeder Manifest-Eintrag bindet den vom Entwickler verfassten Komponententyp an eine bestimmte Recipe-URI; die Wahl ist im Inhalt des Manifest explizit und eindeutig.

spec.implements ist eine Konsistenzprüfung über die Zuordnungstabelle. Der Wert spec.implements der aufgelösten Recipe MUSS mit dem Komponententyp-Schlüssel des Manifest für diesen Zuordnungseintrag übereinstimmen — oder mit einer Basis, die dieser Schlüssel per extends erweitert, in beliebiger Tiefe der Kette, da eine für eine Basis geschriebene Recipe alles implementiert, was diese erweitert. Ein Wert, der mit keinem von beiden übereinstimmt, erzeugt einen OPS_ERROR mit einer klaren Diagnose, die den Manifest-Eintrag, die aufgelöste Recipe und den widersprüchlichen Wert spec.implements nennt. Die Prüfung erfolgt einmal pro Zuordnungseintrag des Manifest, über das zusammengesetzte Manifest und bevor irgendeine Recipe aufgelöst wird — statisch, deterministisch und ohne etwas über die eigene Kette extends des zugeordneten Typs hinaus zu durchlaufen. Ein Schlüssel in components.type, der eine Komponenteninstanz in einer Version erreicht, die er nicht nennt, wird für diese Instanz noch einmal auf dieselbe Weise beurteilt, wobei der eigene Typ der Instanz in der Version, als die der Build sie kompiliert, an die Stelle des Schlüssels tritt, wie Flache URI-Zuordnung beschreibt. Siehe ../vocabulary/inheritance-and-interface.md dazu, was die Recipe einer Basis einer Spezialisierung erspart und was nicht.

Jeder Befehl, der die Abhängigkeiten eines Release liest, führt sie aus, und jeder entscheidet selbst, was ein Befund bedeutet: aggrega build und aggrega pull halten an, da beide etwas erzeugen, das Sie anschließend verwenden würden, während aggrega validate und aggrega lint ihn mit ihren übrigen Befunden melden und mit einem Exit-Code ungleich null beenden, und der Editor veröffentlicht ihn als eine Diagnose unter den anderen. aggrega lint ist die Ausnahme bei der Beurteilung einer Instanz: Es beurteilt die Zuordnungseinträge und nicht die Instanzen, die sie erreichen, und meldet ihn daher nicht, während aggrega build, aggrega pull und aggrega validate --release es tun. Siehe ../errors/fatal-halts.md für die Diagnose und ihre Behebung.

Die Konsistenzprüfung ist die einzige Zuordnungsoberfläche, die die Kette extends liest. Die Auswahl der Recipe bleibt am Zuordnungsschlüssel exakt: Ein Komponententyp, der eine zugeordnete Basis erweitert, braucht hier dennoch einen eigenen Eintrag und erhält keinen durch Vererbung.

spec.implements schlägt auch Kandidaten vor. Eine Instanz, deren Typ keine Manifest-Zuordnung hat, hält den Build mit einem OPS_ERROR an, der die Rezepte, deren spec.implements diesen Typ implementieren kann, als Pin-Kandidaten auflistet; die Editor-Vervollständigung für einen Zuordnungswert reiht dieselben passenden Rezepte zuerst. Beide Oberflächen lesen spec.implements gegen den angeforderten Typ selbst, sodass ein Rezept, das eine der Basen dieses Typs implementiert, nicht als Kandidat angeboten wird, obwohl die Zuordnung als konsistent beurteilt würde. spec.implements deklariert somit, was ein Rezept implementieren kann, und informiert die Wahl des Menschen — in der Konsistenzprüfung, in der Diagnose bei fehlender Zuordnung und in der Vervollständigung —, aber es löst nie einen Build auf. Die Manifest-Zuordnung ist die explizite Bereitstellungsentscheidung des Benutzers, im Lockfile für die Reproduzierbarkeit gepinnt; der Katalog wählt nie eine Bereitstellung im Namen des Benutzers.

Drei Formen für das Versionssegment der URI

Eine Recipe-URI im Manifest kann die Version in einer von drei Formen tragen:

  • Exakt — helm/postgres:1.2.0. Das Lockfile muss genau diese Version pinnen; bei der ersten Auflösung des Lockfiles pinnt der Resolver diese Version; enthält der Katalog oder die Registry diese Version zum Zeitpunkt der Auflösung nicht, hält das Laden des Workspace mit einem Fehler an.
  • Bereich — helm/postgres:^1.2.0. Semver-Bereich mit der Standard-MVS-Regel; bei der ersten Auflösung des Lockfiles pinnt der Resolver die höchste verfügbare Version, die den Bereich erfüllt.
  • Unversioniert — helm/postgres. Kein Suffix :version; bei der ersten Auflösung des Lockfiles pinnt der Resolver die neueste verfügbare Version.

Nachfolgende Builds verwenden die im Lockfile gepinnte Version, unabhängig von der vom Benutzer eingegebenen Form. Eine erneute Auflösung auf eine neuere Version erfordert eine explizite Aktion des Benutzers — aggrega pull --upgrade --release <release> <uri> löst eine einzelne Abhängigkeit neu auf und hält dabei jeden anderen Pin, oder aggrega pull --upgrade --release <release> löst alle neu auf —; das Lockfile ist die maßgebliche Quelle für Builds; die vom Benutzer eingegebene Form ist die Art, wie der Benutzer die Versionsbeschränkung beim Verfassen ausdrückt.

Capability-qualifizierte Verweise

Die Identität einer Recipe im Katalog ist auf die Capability bezogen: Zwei Rezepte können einen metadata.name und eine Version teilen und dabei unterschiedliche Werte für spec.capability deklarieren. Die Registry-Identität ist recipe/{capability}/{name}:{version}, abgeleitet aus der Art des Rezepts, seinem spec.capability ohne einen eventuell darin enthaltenen Versions-Pin und seinem Namen; der Katalogbaum der Standardbibliothek spiegelt diese Koordinate per Konvention unter recipe/{capability}/{name}/. Ein Zuordnungswert des Manifest nennt das Rezept in einer der beiden Genauigkeiten:

  • Einfach — mariadb:1.0.0. Wird aufgelöst, wenn genau ein Rezept im Katalog den Namen trägt; in der Praxis die vorherrschende Form.
  • Capability-qualifiziert — compose/mariadb:1.0.0. Das Segment vor dem ersten / nennt das spec.capability des Rezepts, ohne dessen Versions-Pin — ein in den Verweis geschriebener Pin wird abgelehnt (E0095). Erforderlich, wenn mehr als ein Rezept denselben Namen ausliefert: Ein einfacher Verweis, der auf zwei Rezepte passt, ist mehrdeutig und hält bei der Auflösung deutlich an, statt stillschweigend eines auszuwählen.

Eine Recipe-URI hat keine weiteren Positionen. Der Resolver teilt nur am ersten /, sodass compose/mariadb die Capability compose und das Rezept mariadb nennt, und ein Verweis mit drei Segmenten passt in keiner der beiden Genauigkeiten auf ein Rezept.

Die oben beschriebenen Formen des Versionssegments gelten für beide Varianten.

In einer Registry veröffentlichte Entitäten in Zuordnungen

Eine Entität, die aus einer Registry statt aus einem lokalen Katalog konsumiert wird, wird mit genau derselben Identität referenziert, die eine lokale verwendet: Der Verweis enthält weder einen Registry-Host noch ein Segment für die Entitätsart. Der Resolver liefert beides — den Host aus der konfigurierten Standard-Registry des Workspace, das Art-Segment aus der Stelle, an der der Verweis im Schema steht — gemäß den Regeln für Kontextabhängige Kurz-URIs weiter unten. Wenn weder ein lokales Katalogverzeichnis noch der Cache eine Kopie enthält, ruft aggrega pull — oder ein mit --auto-pull ausgeführter Build — die Entität vom abgeleiteten Ort ab, legt sie im Cache ab und pinnt die aufgelöste Version und den Inhalts-Digest im Lockfile; nachfolgende Builds verwenden den Cache ohne Netzwerkzugriff.

# Aggregate fragment — a registry-published Component as the type:
components:
db:
type: core/datastore/mariadb:1.0.0

Da der Host und das Segment für die Entitätsart abgeleitet und nicht verfasst werden, adressiert das Schreiben eines davon in den Verweis nicht die veröffentlichte Entität — es erzeugt eine Identität, die kein Katalogeintrag trägt. Ein Verweis auf eine Component oder ein Feature ist deren metadata.name wörtlich plus ein optionales :version, unabhängig davon, ob die Entität aus dem lokalen Katalog, aus dem Cache oder aus einer Registry aufgelöst wird. Ein Workspace, der eine private Registry konsumiert, nennt diesen Host in seiner eigenen Konfiguration statt in jedem Verweis.

Vollständigkeitsprüfung

Nachdem alle Zuordnungen aufgelöst sind, prüft der Compiler, dass jede Komponenten- und Anbindungsinstanz (ein Anmeldedaten-Feature ist eine Anbindung wie jede andere) im Aggregate des Entwicklers eine aufgelöste Recipe oder ein aufgelöstes FeatureRecipe hat. Nicht zugeordnete Entitäten verursachen einen fatalen Abbruch mit einer expliziten Diagnose, die jede fehlende Entität auflistet und vorschlägt, welcher Schlüssel in components.type oder features.type hinzuzufügen ist, um die Lücke zu schließen.

YAML-Anker für DRY-Manifeste

Um aufgeblähtes YAML bei großen Zuordnungsmengen zu vermeiden, unterstützt das Manifest einen optionalen Block defs: für Standard-YAML-Anker (& und *):

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: global-base-manifest
version: 1.0.0
defs:
- &python_worker_recipe "helm/standard-python-worker:2.0.0"
spec:
mappings:
components:
type:
core/python-worker: *python_worker_recipe
core/postgres: helm/postgres:1.2.0

Feature-Aushandlung

Der Capability-Handshake verwendet dieselbe flache URI-Zuordnung:

  1. Der Entwickler bindet core/data-masking im Aggregate an eine Komponente an, unter einem eigenen Namen in der Zuordnung features: dieser Komponente.
  2. Der Compiler sucht core/data-masking in der Zuordnung features.type des Manifest.
  3. Wenn der Lookup zu einer FeatureRecipe-URI aufgelöst wird (z. B. helm/data-masking-litellm:1.0.0), existiert die Capability, und die Pipeline des FeatureRecipe wird in der definierten Reihenfolge ausgeführt.
  4. Wenn features.type keinen passenden Eintrag enthält, hält der Compiler den Build an und listet das nicht zugeordnete Feature auf.

Das Manifest akzeptiert außerdem einen Block features.annotations — eine parallele Authoring-Oberfläche, mit der ein Subsystem eines Release oder Aggregate Features per Annotationsschlüssel statt per Deklaration pro Komponente anbinden kann. Die Form der Bindung, die Side-vs-Pillar-Aufteilung, die festlegt, welche Authoring-Oberfläche welche Routing-Pfade verwendet, die Disziplin, nach der die explizite Anbindung gewinnt, und die Regel für Schema-Standardwerte stehen im eigenen Abschnitt Annotationsgesteuerte Feature-Bindungen weiter unten.

Komposition über extends

Ein Manifest kann eine einzelne extends:-Referenz deklarieren, die ein Basis-Manifest benennt, dessen mappings es erbt. Die Referenz ist keine URI und wird nie über den Katalog aufgelöst: Ein Manifest gehört zur Deployment-Seite und wird neben dem Release verfasst statt veröffentlicht, daher ist der Wert entweder ein relativer Pfad zu einer Manifest-Datei — ./base-manifest.yaml — oder der bloße metadata.name eines Manifest, das im eigenen Verzeichnis des Release liegt. Ein relativer Pfad muss zu einem Manifest innerhalb des Workspace führen — oder, wenn das Release außerhalb des Workspace benannt wurde (auf der Befehlszeile oder durch die Workspace-Konfiguration), innerhalb des Verzeichnisses, das dieses Release enthält, und für ein Manifest, das Sie allein auf der Befehlszeile außerhalb des Workspace benennen, innerhalb des Verzeichnisses, das das Manifest enthält: Ein Pfad, der nach oben hinausführt oder den ein symbolischer Link hinausträgt, wird abgelehnt, bevor die von ihm benannte Datei gelesen wird (siehe errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Ein Verweis auf eine andere Datei führt aus dem Verzeichnis hinaus, in dem er bleiben muss)”). Kind-Mappings überschreiben bei Schlüsselkollisionen die Basis und unterstützen so Overlay-Muster pro Umgebung (Staging/Prod-Parität mit gezielten umgebungsspezifischen Abweichungen) sowie Muster für die lokale Entwicklung, ohne alles vollständig kopieren zu müssen.

Merge-Semantik. Wenn ein lokales Manifest ein Basis-Manifest erweitert, führt der Compiler pro Ebene eine flache Schlüsselersetzung durch — die Dictionaries type und name werden unabhängig voneinander zusammengeführt, nicht tief gemergt —, was O(1)-Lookups in den Dictionaries garantiert und das Vererbungsverhalten vorhersehbar hält. Innerhalb jeder Ebene überschreiben die Schlüssel des Kindes die des Elternteils.

Das Brückenmuster für die lokale Entwicklung. Eine häufige Verwendung von extends ist der Austausch eines Credential-FeatureRecipe für lokales Prototyping, ohne das Aggregate anzufassen. In der Produktion ordnet das Basis-Manifest das Credential-Feature core/aws-secrets-manager in der Ebene features.type einem Produktions-FeatureRecipe zu. Für lokales Prototyping stellt das Plattformteam ein local-manifest bereit, das die Basis erweitert und die Zuordnung des Credential-Feature gezielt so überschreibt, dass host-env-injector verwendet wird — ein lokales FeatureRecipe, das die Anmeldeinformation als Variablenreferenz wie ${SECRET_NAME} in die Compose-Datei liefert, die Docker Compose beim Start des Stacks aus der Shell-Umgebung oder einer .env-Datei ersetzt. Der Entwickler erhält einen standardmäßigen lokalen Workflow, und das Aggregate bleibt für die Produktion agnostisch gegenüber Capabilities.

Kontextabhängige Kurzform-URIs

Der Aggrega-Compiler verwendet kontextabhängige Inferenz, wenn er OCI-URIs in Manifests auflöst. Wenn ein Engineer den Fully Qualified Domain Name (FQDN) und den architektonischen Entitätstyp weglässt, greift der Compiler automatisch auf die Standard-Registry zurück (konfiguriert in .aggrega-config.yaml) und leitet den Entitätstyp daraus ab, wo die Zeichenkette im Schema steht.

Die Inferenzregeln:

  1. Standard-Domäne: Jeder URI ohne Domäne (z. B. python-worker-helm:1.0) wird die konfigurierte default_registry vorangestellt (Standard: hub.aggrega.ai/).
  2. Kontextabhängige Entitätserweiterung: Der Compiler hängt anhand des strikten Schema-Wörterbuchs den korrekten Entitätspfad an:
    • Zeichenketten unter Aggregate.spec.components[].type werden zu /component/ erweitert.
    • Zeichenketten unter Aggregate.spec.aggregates[].type werden zu /aggregate/ erweitert.
    • Zeichenketten unter Manifest.spec.mappings.components.type oder Manifest.spec.mappings.components.name werden zu /recipe/ erweitert.
    • Zeichenketten unter Manifest.spec.mappings.features.type oder Manifest.spec.mappings.features.name werden zu /featurerecipe/ erweitert. Dazu gehören auch Credential-Features (mit dem Label feature.aggrega.ai/kind: secret) — sie verwenden denselben FeatureRecipe-Pfad.
    • Zeichenketten, die pipeline[].plugin zugewiesen sind, werden zu /plugin/ erweitert.
  3. Drei-Ebenen-Vorrang: Bevor der Compiler die OCI-Inferenz anwendet, durchsucht er die Katalogverzeichnisse des Workspace und den Artefakt-Cache (die Workspace- und Cache-Ebene), wie im Drei-Ebenen-Modell der Entitätsauflösung definiert. Die OCI-Inferenz greift nur, wenn die Entität die Registry-Ebene erreicht. Ein Mapping-Schlüssel oder -Wert wird nie als Dateipfad gelesen: Ein lokal verfasstes Recipe oder FeatureRecipe liegt in einem Katalogverzeichnis — catalog/ im Stammverzeichnis des Workspace oder einem, das workspace.catalog_dirs aufführt — und wird über seine Referenz benannt.

Die Kurzform in Aktion:

# Capability-qualified — required when two recipes share the name "postgres":
"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:
"core/postgres": "postgres:2.0"
# Found in a local catalog directory or the cache; failing both, `aggrega pull`
# (or a build run with --auto-pull) fetches it from the registry location derived
# from the configured default registry and the Recipe kind.
# A private registry is named in workspace configuration, not in the reference.

Kein ops/-Präfix. Recipe-Namen tragen kein ops/-Präfix — das Entitätstyp-Verzeichnis recipe/ in der OCI-Taxonomie identifiziert die Domäne bereits, und Recipes werden ohne zusätzliches Präfix unter recipe/{capability}/{name} ausgeliefert. Manifests referenzieren Recipes über {capability}/{name} oder für die kontextabhängige Inferenz über den bloßen Namen. Die vollständige OCI-Taxonomie finden Sie in architecture/13-catalog-and-registry.md §6.

Annotationsgesteuerte Feature-Bindungen

Der Block features.annotations des Manifest deklariert Bindungen zwischen Annotationsschlüsseln und Feature-Typen sowie die Routing-Pfade, über die jede Bindung den Annotationswert sendet. Die Bindung ist die Authoring-Oberfläche, um sich wiederholende Feature-Anbindungen pro Komponente — das Muster, bei dem Dutzende von Komponenten innerhalb einer Grenze jeweils einen identischen features:-Block tragen — zu einzelnen Annotationsdeklarationen an Release-Grenzen oder Aggregate-Subsystemen zu verdichten.

Schema-Form:

spec:
mappings:
features:
type:
core/rewrite-host: helm/rewrite-host-helm:1.0.0
core/db-pool: helm/db-pool-helm:1.0.0
annotations:
feature.aggrega.ai/rewrite-host:
feature: core/rewrite-host
maps:
infra:
- upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool:
feature: core/db-pool
maps:
values:
- pool # Aggregate-side: routes annotation value into values.pool

Eine Bindung trägt ein Feld feature, das den Ziel-Feature-Typ benennt, und einen Block maps, der Unterschlüssel-Routen in Punktnotation nach Ziel-Säule gruppiert. Das Feld feature referenziert einen Feature-Typ, der auch im benachbarten Abschnitt features.type erscheinen muss (wo die Versionsbindung des FeatureRecipe liegt). Der Block maps deklariert zwei nach Säulen geschlüsselte Listen — maps.infra und maps.values —, die jeweils Pfadzeichenketten in Punktnotation enthalten, die auf die Eigenschaften spec.schema.<pillar>.<path> des Ziel-Feature verweisen. Eine Bindung muss über beide Listen hinweg mindestens einen Pfad deklarieren (das JSON Schema erzwingt minProperties: 1 für maps).

Provider-Polymorphie für denselben Annotationsschlüssel — z. B. feature.aggrega.ai/rewrite-host, gebunden an core/k8s-dns-resolver in einem Kubernetes-Deployment, aber an core/compose-bridge in einem lokalen Compose-Deployment — wird ausgedrückt, indem in verschiedenen Manifests verschiedene Feature-Typen gewählt werden; jedes Manifest bindet die Annotation an genau ein Feature, und das FeatureRecipe des gewählten Feature enthält die providerspezifische Implementierung.

Die Partitionierung nach Seite und Säule. Die Invariante des Aggregate als Authoring-Oberfläche beschränkt jede Authoring-Seite auf die Routing-Pfade einer einzigen Säule. Annotationen auf der Aggregate-Seite werden nur über maps.values-Pfade geroutet; Annotationen auf der Release-Seite nur über maps.infra-Pfade. Eine Bindung, die Pfade in beiden Säulen deklariert, unterstützt seitenübergreifende Komposition: Eine Annotation auf der Aggregate-Seite löst die Teilmenge der Values-Säule aus; eine Annotation auf der Release-Seite gegen denselben Schlüssel löst die Teilmenge der Infra-Säule aus; beide Beiträge werden zu einer Feature-Anbindung pro Paar (Component, Feature) mit beiden befüllten Säulen zusammengesetzt. Eine Abweichung zwischen Seite und Säule — z. B. eine Annotation auf der Aggregate-Seite gegen eine Bindung, die nur maps.infra deklariert — hält den Build mit einer klaren Diagnose an, die den Annotationsschlüssel, die geroutete Säule, die Authoring-Seite und die Quellposition benennt und unter der Domäne des Dokuments abgelegt wird, in dem der Annotationswert verfasst wurde.

Validierung der Pfadziele. Beim Laden des Katalogs prüft der Compiler, dass jeder unter maps.infra und maps.values deklarierte Punktpfad einer Eigenschaft entspricht, die spec.schema.<pillar> des Ziel-Feature tatsächlich deklariert. Eine Bindung, die auf einen Pfad routet, den das Feature-Schema nicht aufführt, hält das Laden des Katalogs mit einem klaren OPS_ERROR an, der die Bindung, das Ziel-Feature sowie die Säule und den Pfad benennt, über die sie geroutet hat. Schema-Formen, die sich einem einfachen Durchlaufen der Eigenschaften entziehen ($ref, patternProperties, Komposition mit oneOf / anyOf / allOf), beenden die statische Prüfung an diesem Zweig und überlassen es der nachgelagerten Schema-Validierung, Abweichungen zu erkennen.

Formen von Annotationswerten. Eine Bindung verarbeitet Annotationswerte in drei Formen. Skalar — ein einzelner YAML-Wert (Zeichenkette, Zahl, Boolean). Ein Skalar, gepaart mit einer Bindung, die über beide Säulen hinweg genau einen Pfad deklariert, routet den Wert an diesen einen Pfad; ein Skalar, gepaart mit einer Bindung, die mehr als einen Pfad deklariert, ist ein mehrdeutiges Routing und hält den Build mit einer klaren Diagnose an, die unter der Domäne des Dokuments abgelegt wird, in dem der Annotationswert verfasst wurde. Strukturiert — eine YAML-Map, deren Unterschlüssel der obersten Ebene jeweils einem Punktpfad-Eintrag unter maps.infra oder maps.values entsprechen; jeder Unterschlüssel wird unabhängig an seine deklarierte Säule geroutet, und die Partitionierung nach Seite und Säule gilt pro Unterschlüssel. Explizites YAML-null — hebt die geerbte Bindung im Geltungsbereich der Kaskade auf (wobei ein null pro Unterschlüssel innerhalb eines strukturierten Werts einzelne Unterschlüssel aufhebt, während die übrigen bestehen bleiben). Die maßgebliche Authoring-Anleitung zu strukturierten Werten — Kaskaden-Merge pro Unterschlüssel, seitenübergreifende Komposition, Typvalidierung pro Unterschlüssel, die Disziplin der gelockerten Standardwerte für Schemafelder ohne deklarierten type — finden Sie in providers/well-known-annotations.md §“Strukturierte Annotationswerte”.

Die explizite Anbindung gewinnt bei Schlüsselkollisionen. Wenn eine Komponente eines Release oder eine Komponente eines Aggregate sowohl einen expliziten features:-Eintrag als auch eine Annotation trägt, die zum selben Feature-Schlüssel expandiert, bleibt der explizite Eintrag erhalten, und die Annotationsexpansion für diesen Schlüssel an dieser Komponente bewirkt nichts. Die synthetische Anbindung überschreibt nie eine vom Autor deklarierte Feature-Instanz. Autoren können daher die Annotationsexpansion für den Großteil der Komponenten verwenden und einzelne Komponenten gezielt überschreiben, indem sie einen expliziten features:-Eintrag mit demselben Schlüssel schreiben — der explizite Eintrag trägt die komponentenspezifische Anpassung, die Annotation kaskadiert unverändert auf jede andere Komponente.

Explizit gewinnt pro Blatt bei seitenübergreifender Komposition. Wenn eine explizite Anbindung und ein Annotationsbeitrag dieselbe Feature-Instanz befüllen, aber unterschiedliche Blätter schreiben, bleiben beide Beiträge bestehen, und das resultierende Feature trägt beide Blätter, wobei eine Provenienz pro Blatt die Quelle jedes Blatts festhält. Wenn eine explizite Anbindung und ein Annotationsbeitrag auf dasselbe Blatt innerhalb derselben Säule zielen, gewinnt der explizite Beitrag, und die IR hält die unterdrückte Annotations-Provenienz als Override-Markierung an diesem Blatt fest. Das Laden des Katalogs macht diesen Override zur Build-Zeit über eine beratende Lint-Warnung sichtbar, die den unterdrückten Annotationsschlüssel + die Quelle benennt.

Schema-Standardwerte zur Expansionszeit. Die synthetische Feature-Anbindung, die durch die Annotationsexpansion entsteht, trägt nur die Blätter, die der Annotationswert über die deklarierten Pfade der Bindung befüllt. Auf spec.schema des Ziel-Feature deklarierte Schema-Standardwerte werden zur Expansionszeit nicht in die synthetische Anbindung gemergt. Die Materialisierung von Standardwerten liegt in der Verantwortung der Rendering-Schicht des FeatureRecipe und wird einheitlich auf explizite und synthetische Anbindungen angewendet, sodass beide Pfade bei derselben effektiven Konfiguration dieselbe nachgelagerte Ausgabe erzeugen.

Trennung der Annotations-Namespaces:

PräfixEigentümerZweck
aggrega.ai/Nur die Aggrega-PlattformPlattformeigene Annotationen, die der Provider direkt liest (z. B. aggrega.ai/namespace).
feature.aggrega.ai/Offizielle StandardbibliothekIm Manifest gebundene Kurzformen für Feature-Annotationen.
{any-other-domain}/Unternehmen / CommunityBenutzerdefinierte Kurzformen für Feature-Annotationen.

Reservierung des Präfixes aggrega.ai/

Bindungen in features.annotations eines Manifest können das bloße Präfix aggrega.ai/ nicht verwenden — es ist plattformeigenen Annotationen vorbehalten, die der Compiler ausgibt (OTel-/Provenienz-Labels usw.). Unterpräfixe mit Geltungsbereich (component.aggrega.ai/*, compliance.aggrega.ai/*, unternehmensspezifisch acme.aggrega.ai/*) bleiben für das Authoring durch Benutzer verfügbar. Die Menge der plattformreservierten Annotationen finden Sie unter providers/well-known-annotations.