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

Veröffentlichungsoberfläche

Jede Katalog-YAML von Aggrega trägt einen einheitlichen Satz von Metadatenfeldern, die die Entität für die Katalogverteilung beschreiben: wer sie pflegt, unter welcher Lizenz sie ausgeliefert wird, wo ihr Quellcode liegt, über welche Schlüsselwörter sie bei der Suche gefunden wird. Zusammen bilden diese Felder die Veröffentlichungsoberfläche — das Metadatenvokabular, auf das sich Katalogherausgeber und die Werkzeuge, die es konsumieren, verlassen, getrennt vom inhaltsseitigen Mechanismus metadata.labels / metadata.annotations, der in labels-and-annotations.md dokumentiert ist.

Diese Seite dokumentiert die Felder der Veröffentlichungsoberfläche, das Inventar der Beschreibungsfelder im Korpus (Beschreibungen der Hülle, der Instanz und auf Feldebene), den vorgesehenen Zweck des maintainer-Felds und seinen verifizierten Konsumenten sowie die Asymmetrien der Pflichtfelder pro Entität (welche Felder jede Entität heute verlangt und wo die Asymmetrien beabsichtigt sind).

Die Felder der Veröffentlichungsoberfläche

Die folgenden Felder erscheinen auf jeder Entität der Domäne 2 (Component, Feature) und der Domäne 3 (Recipe, FeatureRecipe, Plugin) sowie auf dem Aggregate als wiederverwendbarem Modul. Sie erscheinen auch auf Manifest und Release, mit reduzierter Semantik (Workspace-Zuordnung statt Katalogveröffentlichung).

FeldTypZweckKonsument
descriptionstringMenschenlesbare Zusammenfassung der EntitätHover-Karten im Editor (aggrega serve); das Werkzeug describe, das ein Assistent aufruft (aggrega mcp); eine durchsuchbare Annotation am veröffentlichten Artefakt (aggrega push); aggrega inspect
maintainersArray von ObjektenWer die Entität besitzt (name, email, url)catalog_metadata pro Knoten in der IR, auf Component-Knoten
licensestringRechtliche Compliance (typischerweise ein SPDX-Bezeichner)catalog_metadata pro Knoten in der IR, auf Component-Knoten
repositoryString (URL)Git-Repository, in dem der Quellcode liegtcatalog_metadata pro Knoten in der IR, auf Component-Knoten — nichts anderes liest es
homeString (URL)URL der Dokumentation / des Wikiscatalog_metadata pro Knoten in der IR, auf Component-Knoten — nichts anderes liest es
keywordsArray von StringsTags für die Auffindbarkeitcatalog_metadata pro Knoten in der IR, auf Component-Knoten — kein Suchindex konsumiert sie

Alle sechs Felder sind auf jeder Entität, die sie trägt, optional. Ein Katalogautor, der die gesamte Gruppe weglässt, erzeugt eine gültige YAML — die Veröffentlichungsoberfläche ist für Entitäten gedacht, die zur Katalogverteilung bestimmt sind; Entitäten für den internen Gebrauch können sie ohne Folgen weglassen.

Die Spalte Konsument ist für das, was heute ausgeliefert wird, vollständig, und zwei ihrer Konsequenzen verdienen es, klar ausgesprochen zu werden, weil sie ändern, was sich zu schreiben lohnt:

  • description ist das einzige Feld mit mehr als einem Leser. aggrega serve rendert es in die Hover-Karte für Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest und die vier Bibliotheksarten (SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) — nicht für Plugin oder Release. Das Werkzeug describe, das aggrega mcp bereitstellt, gibt es für eine Entität jeder Art zurück. aggrega push stempelt es als durchsuchbare Annotation auf das veröffentlichte Artefakt. aggrega inspect gibt es für jede Art unter dem Kopf der Entität aus und gibt kein anderes Feld der Veröffentlichungsoberfläche aus.
  • repository, home und keywords werden validiert und mitgeführt, und nichts liest sie über die IR hinaus. Keine Auflistungsoberfläche, keine Katalogseite und kein Suchindex konsumiert sie. Sie zu schreiben, hält eine Herkunft fest, die mit der Entität reist und aus der IR-Ausgabe und von einer Governance-Policy lesbar ist; es macht die Entität nirgends auffindbar.

Die Markierung als veraltet ist kein Feld der Veröffentlichungsoberfläche. Eine Entität wird als veraltet markiert, indem nach der Veröffentlichung ein Marker für sie in der Registry erfasst wird — ein signierter Marker mit einem Schweregrad (warning, error oder retracted), einem Grund und einem Ersatz, beim Pull verifiziert. Jede Oberfläche, die die Lockfile liest, meldet ihn dann; build.halt_on_deprecated_severity entscheidet nur, ob er außerdem einen Build stoppt. Der Marker wird nie in der eigenen YAML der Entität geschrieben, und der Grund ist strukturell: Ein veröffentlichtes Artefakt ist unveränderlich, daher könnte ein beim Veröffentlichen darin eingefrorenes Flag nie eine später getroffene Entscheidung ausdrücken. Der Veraltungshinweis, den aggrega inspect für eine Katalog-Entität ausgibt, stammt aus dem Marker, für jede Art, die es über den Namen auflöst.

IR-Nutzung — catalog_metadata pro Knoten

Der Compiler überträgt die Felder der Veröffentlichungsoberfläche von jeder Component in den catalog_metadata-Block des jeweiligen Knotens, sichtbar im IR-Graphen, den ein Lauf zurückgibt (aggrega inspect <release> --ir-graph). Der Block enthält maintainers, license, repository, home und keywords — die fünf Felder, die die IR mitführt; description gehört nicht dazu. Werkzeuge, die auf dem Vertrag des IR-Graphen aufbauen, lesen die Metadaten von dort, statt die Katalog-YAML erneut zu lesen.

Nur Component-Knoten. Der Block wird befüllt, indem der Komponententyp des Knotens im Katalog als Component nachgeschlagen wird, daher erreicht die Veröffentlichungsoberfläche eines Feature, eines Recipe, eines FeatureRecipe oder eines Plugin nie die IR — diese Entitäten tragen die Felder, und die Felder werden validiert, aber aus ihnen entsteht kein IR-Knoten.

catalog_metadata entfällt vollständig aus dem IR-JSON, wenn jedes Feld der Veröffentlichungsoberfläche auf der Quell-Component leer oder null ist: Der Block wird weggelassen, statt mit leeren Werten ausgegeben zu werden. Dieselbe Eingabe ergibt daher dieselbe kompakte Ausgabe, was das IR-Diff über Läufe hinweg stabil hält.

Eine Governance-Policy kann den Block lesen. Ein Plugin, das unter plugins.governance in der Rolle ir-verdict angebunden ist, erhält den gesamten IR-Graphen, Knoten für Knoten, einschließlich des catalog_metadata jedes Component-Knotens — daher kann eine Policy einen Build anhand von license, repository, home, keywords oder maintainers eines Knotens annehmen oder ablehnen. Diese Reichweite ist spezifisch für den Governance-Socket: Das Rendering-Plugin eines Providers erhält eine begrenzte Projektion pro Knoten, die catalog_metadata nicht enthält, daher können Rendering-Plugins diese Felder nicht lesen.

Die drei Beschreibungstypen

Das Feld description erscheint einheitlich auf der Hülle, aber der Korpus enthält auch beschreibungsartige Strings innerhalb von Schema-Deklarationen (Beschreibungen pro Feld) und innerhalb von Säulenkörpern (Beschreibungen pro Instanz). Drei verschiedene Beschreibungstypen existieren nebeneinander; die folgende Tabelle grenzt sie voneinander ab.

TypWo sie liegtVerfasst vonZweck
Hüllenbeschreibungmetadata.description auf jeder EntitätKatalogherausgeberZusammenfassung der Entität als Ganzes, angezeigt in Hover-Karten des Editors und auf das veröffentlichte Artefakt gestempelt
InstanzbeschreibungFeld description neben einer Deklaration pro Instanz (z. B. featuresSchema.<slot>.description, usesSchema.<socket>.description)Schema-AutorBeschreibung pro Slot / pro Socket / pro Port, für Autoren konsumierender Entitäten, die die Deklaration lesen
Feldbeschreibungdescription:-Annotation von JSON Schema 2020-12 innerhalb des Inhalts von schema: / featuresSchema: / usesSchema: (Kompaktform oder vollständiges JSON Schema in YAML)Schema-AutorDokumentation pro Feld, die mit dem Schema reist

Die drei Typen teilen das Wort „description“, liegen aber auf strukturell unterschiedlichen Ebenen. Die Hüllenbeschreibung gilt für die Entität als Ganzes; die Instanzbeschreibung gilt für eine Deklaration innerhalb eines Schema-Slots; die Feldbeschreibung gilt für einen bestimmten Wert innerhalb eines typisierten Schemas. Autoren, die eine Component schreiben:

  • Setzen Sie metadata.description einmal für die Component-Entität selbst.
  • Setzen Sie featuresSchema.admin_password.description einmal pro Credential-Slot, den die Component deklariert.
  • Setzen Sie description:-Annotationen pro Feld innerhalb des Blocks schema: — in Kompaktform (port: { type: integer, description: "..." }) oder als vollständiges JSON Schema in YAML —, um jedes Feld für alle zu dokumentieren, die das Schema der Component lesen.

Die drei Typen kaskadieren nicht und kollidieren nicht, und jeder erreicht eine andere Oberfläche — oder keine:

  • Hüllenbeschreibung — Hover-Karten des Editors, die durchsuchbaren Annotationen des veröffentlichten Artefakts und aggrega inspect, gemäß der obigen Spalte Konsument.
  • Feldbeschreibung — erscheint wörtlich im Schema-Auszug, den die Hover-Karte einer Component oder eines Feature rendert. Der Auszug umfasst nur spec.schema und ist auf seine ersten Zeilen gekürzt, daher erscheint eine Beschreibung tiefer im Block — oder eine innerhalb von featuresSchema: oder usesSchema: — dort nicht.
  • Instanzbeschreibung — deklariert und mit der Entität mitgeführt; keine ausgelieferte Oberfläche rendert sie eigenständig. aggrega inspect listet die Sockets und Funktions-Slots einer Component ohne deren Beschreibungen auf.

Zweck des maintainer-Felds

Das Feld maintainers trägt ein Array von Objekten, jedes mit name, email und url. Der Zweck und der verifizierte Konsument:

Zweck (informativ + IR-Herkunft). Das Feld ist für die Katalogveröffentlichung informativ: Die architektonische Absicht ist „wer ist für diese Katalog-Entität verantwortlich“ — ein Eigentumssignal, das mit der Entität reist. Keine Oberfläche stellt es als Kontaktliste dar, und keine eingebaute Prüfung vergleicht es mit irgendetwas.

Verifizierter Konsument (catalog_metadata pro Knoten). Der Compiler überträgt das metadata.maintainers jeder Component in das catalog_metadata.maintainers des jeweiligen Knotens in der IR, sichtbar im Graphen, den aggrega inspect <release> --ir-graph zurückgibt, wenn die Quell-Component eines deklariert hat. Das ist der einzige Leser des Felds. Eine Governance-Policy, die unter plugins.governance in der Rolle ir-verdict angebunden ist, sieht es dort, daher ist eine Eigentumsregel — jede Entität nennt mindestens einen Maintainer, die Domain eines Maintainers entspricht einer genehmigten Menge — gegen die IR statt gegen die Katalog-YAML ausdrückbar. Keine solche Regel wird ausgeliefert; der Socket ist der Ort, an den eine gehört.

Der Compiler erzwingt oder validiert den Inhalt von maintainer nicht über die strukturelle Form von JSON Schema hinaus (name erforderlich; email und url optional, beide String). Ob die aufgeführten Maintainer die Entität tatsächlich besitzen, ob ihre E-Mail erreichbar ist, ob ein Repository-Commit von einem von ihnen signiert ist — das sind Belange der Katalog-Governance, und keine ausgelieferte Prüfung wertet einen davon aus. Sie gehören in eine Governance-Policy, die ein Betreiber anbindet, nicht in den Compiler.

Asymmetrien der Pflichtfelder

Die Entitätsarten von Aggrega haben in ihren JSON Schemas leicht unterschiedliche Sätze von Pflichtfeldern. Die meisten Asymmetrien sind beabsichtigt und spiegeln die Rolle der Entität wider.

Die Pflichtfelder pro Entität (ohne apiVersion / kind / metadata.name / metadata.version, die jede Entität einheitlich verlangt):

EntitätZusätzliche PflichtfelderBegründung
Componentmetadata.labels.component.aggrega.ai/typeDie Label-Anforderung ist tragend für den Selektorabgleich: x-aggrega-selector:-Annotationen in usesSchema filtern Ziel-Components nach diesem Label; fehlt es, wird die Component beim Laden abgelehnt
Feature—Keine Anforderung an ein reserviertes Label; Features identifizieren sich über Name + Herausgeber
Recipespec.capability, spec.implementsCapability steuert den Provider-Dispatch; implements steuert die Component-Bindung
FeatureRecipespec.capability, spec.implementsWie bei Recipe
Pluginmetadata.pluginType, spec.abiVersionDer Socket-Typ, den das Plugin implementiert (Teil des Adressierungsblocks, der das Segment <pluginType> der abgeleiteten Koordinate plugin/<pluginType>/<name> liefert), und die ABI-Version, auf die es abzielt; der Ort der .wasm wird aus dieser Identität abgeleitet, statt geschrieben zu werden; ein Provider-Rendering-Plugin (pluginType: provider) trägt zusätzlich seinen Übersetzungsvertrag unter spec.provider
Aggregate—Ein Aggregate, das keines von components, subsystems oder aggregates deklariert, wird geladen und gebaut und rendert nichts
Manifestspec.mappingsDie Mapping-Ebenen sind der einzige Zweck des Manifest
Releasespec.aggregate, spec.manifest (ein Release, das extends deklariert, schreibt kein aggregate und darf manifest weglassen); metadata.environmentDie ersten beiden verankern den Build an einem bestimmten Aggregate + Manifest; die Umgebung wird als Label aggrega.ai/environment auf die gerenderte Ausgabe gestempelt

Die Component-Label-Anforderung ist tragend

Das Label component.aggrega.ai/type ist das einzige Label, das Aggrega für irgendeine Entität verlangt. Die Anforderung besteht, weil der usesSchema-Mechanismus der Standardbibliothek Zielkandidaten über x-aggrega-selector:-Annotationen filtert, die Selektor-Strings wie "component.aggrega.ai/type=database" tragen — der Selektor zieht die Labels des Ziels heran, um zu bestimmen, ob der Typ zu den vom Socket akzeptierten Typen passt. Das Component-Schema erzwingt es: Eine Component, die das Label weglässt, wird beim Laden abgelehnt (E0215), unter Nennung des fehlenden Schlüssels.

Die Anforderung ist daher kein Belang der Veröffentlichungsoberfläche (das Label dient nicht der Auffindbarkeit im Katalog), sondern ein Belang der Topologie: Jede Component trägt es, einschließlich Components für den internen Gebrauch, die nicht auf Katalogverteilung abzielen.

Das metadata.environment des Release ist erforderlich

Das Release-Schema verlangt metadata.environment, einen String, den der Build als Label aggrega.ai/environment auf die gerenderte Ausgabe stempelt.

Weitere Asymmetrien

Die übrigen Asymmetrien (Pflichtfelder von Recipe gegenüber Component, die mappings-Anforderung des Manifest) spiegeln die Rolle jeder Entität wider. Autoren, die einen einheitlichen Pflichtfeld-Vertrag über alle Entitätsarten hinweg wünschen, werden ihn nicht finden; die Asymmetrien sind gemäß dem rollengetriebenen Design beabsichtigt.

Querverweise

  • labels-and-annotations.md — inhaltsseitiger Metadatenmechanismus, der die Veröffentlichungsoberfläche ergänzt.
  • entities/component.md — die metadata.labels.component.aggrega.ai/type-Anforderung der Component und die Deklarationen schema / usesSchema / featuresSchema.
  • entities/release.md — das Feld metadata.environment des Release und seine Anforderung.
  • 10-status.md — der Status der Metadatenhülle.
  • architecture/02-ecosystem-philosophy.md — strikte API-Partitionierung und der Gestaltungsrahmen der Enterprise Metadata Suite.
  • architecture/13-catalog-and-registry.md §„Lockfile pinning and artifact immutability (Versions-Pinning in der Lockfile und Unveränderlichkeit von Artefakten)“ + §„Catalog entity name-shape enforcement (Durchsetzung der Namensform von Katalog-Entitäten)“ — was die Unveränderlichkeitsregel beim Veröffentlichen ablehnt und wo die Namensformen pro Entitätsart geprüft werden: Das Plugin für Veröffentlichungsdisziplin meldet sie als Hinweis, wenn ein Autor aggrega lint ausführt, und weder das Bauen noch das Veröffentlichen prüft sie.
  • architecture/11-governance-and-compliance.md §„Inheritance and publishing discipline (Vererbung und Veröffentlichungsdisziplin)“ — welche Governance-Regeln zum Plugin für Veröffentlichungsdisziplin gehören und welche stattdessen die Vererbung einer erweiternden Component konstruktionsbedingt regelt.