Katalog und Registry
Dieses Kapitel definiert, wie die Plattform über den OCI-Katalog (Open Container Initiative) unternehmensweit skaliert: wie der Katalog aufgebaut ist, wie eine Referenz aufgelöst wird, wie eine Entität veröffentlicht und gepinnt wird und welchen Namensformen Katalogentitäten folgen.
Der Aggrega-Katalog: Registry-Taxonomie und Auflösung
Der Aggrega-Compiler stützt sich auf eine streng typisierte, von OAM inspirierte Registry, um abstrakte Entwicklerabsicht (Domäne 1) in konkrete Ops-Realität (Domäne 3) aufzulösen. Um ein offenes, verteiltes Ökosystem zu unterstützen und zugleich eine nahtlose Entwicklererfahrung zu wahren, folgen alle Schemas, Infrastruktur-Bindings, programmierbaren Policies und Adapter-Plugins einer standardisierten URI-Taxonomie der Open Container Initiative (OCI). Da jede Katalogentität per URI adressierbar ist, ruft aggrega pull die Entitäten, die ein Release benötigt, in den Cache ab und pinnt sie in seiner Lockfile, und ein Build liest sie von dort. Der lokale Workspace des Entwicklers enthält nur seine Aggregate- und Release-Dateien, keine Kopie des Katalogs.
1. Zentrale Verzeichnisstruktur (der Katalog)
Der Ordner aggrega-catalog der Standardbibliothek (und jeder konforme Katalog von Drittanbietern) ist so organisiert, dass er die Trennung der Zuständigkeiten physisch durchsetzt. Die Struktur trennt abstrakte Schnittstellen explizit von ihren konkreten Infrastrukturimplementierungen.
Bei Components und Features werden URI-Segmente 1:1 auf Pfadsegmente im Dateisystem abgebildet. Components verwenden eine URI mit drei Segmenten ({publisher}/{category}/{name}), wobei das Kategoriesegment eine aus einer geschlossenen Menge kognitiver Kategorien trägt — dasselbe Wort wie das Label component.aggrega.ai/category der Komponente (die 1:1-Spiegelung des Verzeichnisses, geprüft durch die Regel category-matches-directory des Veröffentlichungs-Linters). Features bleiben flach ({publisher}/{name}) — eine kleine Menge, die langsam wächst. Die operative ontologische Klassifizierung (stateful-server, server usw.) liegt im Label component.aggrega.ai/type, nie in der Verzeichnisstruktur; kognitive Fähigkeits-Labels (datastore.aggrega.ai/engine, agent.aggrega.ai/autonomy, …) legen verhaltensbezogene Teilmengen darüber. Die Web-UI des Hubs verwendet Labels zum Filtern und Suchen; Kategorien dienen sowohl der Navigation im Dateisystem als auch der Browse-Achse des Katalogs.
Der folgende Baum ist in seinem Inhalt illustrativ und in seiner Form exakt. Wo eine Entität vollständig dargestellt ist, reicht sie bis hinunter zu ihrer Blattdatei, sodass sich ein ganzer realer Pfad aus dem Diagramm ablesen lässt: welche Verzeichnisebene welches URI-Segment trägt, wo das verpflichtende Versionssegment liegt und welchen Dateinamen jede Entitätsart am Blatt verwendet. Er zeigt eine Handvoll Einträge pro Ebene statt des vollständigen Katalogsinhalts — ... markiert eine Auslassung, und die daneben geschriebenen Namen sind weitere Einträge auf derselben Ebene.
aggrega-catalog/│├── schemalibrary/ # TIER 3: Reusable JSON Schema 2020-12 definitions│ │ # Shared shapes (BaseComponentParameter,│ │ # BaseDatastoreParameter) consumed from a Component or│ │ # Feature schema via $ref: <Library>#/schemas/<name>│ │ # Path: {name}/{version}/library.yaml│ ││ ├── ai-datastores/│ │ └── 1.0.0/│ │ └── library.yaml│ └── base-components/│ └── 1.0.0/│ └── library.yaml│├── workloadlibrary/ # TIER 3: Reusable Workload template fragments│ │ # Shared bodies (StatelessService) consumed from a│ │ # Recipe via workload: { $import: <Library>#/workloads/<name> }│ │ # Path: {name}/{version}/library.yaml│ ││ └── base-workloads/│ └── 1.0.0/│ └── library.yaml│├── component/ # DOMAIN 2: Abstract Interfaces│ │ # URI: {publisher}/{category}/{name}│ │ # Path: {publisher}/{category}/{name}/{version}/component.yaml│ │ # type: core/datastore/mariadb:1.0.0│ │ # → component/core/datastore/mariadb/1.0.0/component.yaml│ ││ ├── core/ # "core" = official Aggrega standard library│ │ ├── ai-agent/ # AI agent frameworks, platforms, patterns│ │ │ └── ... # anthropic, crewai, langflow, pydantic-ai, …│ │ ├── ai-model/ # model providers and inference runtimes│ │ │ └── ... # ai21, anthropic, azure-openai, openai, …│ │ ├── ai-tool/ # tools agents invoke│ │ │ └── ... # browser, mcp, search, …│ │ ├── ai-pipeline/ # AI data/processing pipelines│ │ │ └── ... # argo-workflows, temporal│ │ ├── datastore/ # persistent datastores│ │ │ ├── mariadb/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ ├── postgres/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ └── ... # etcd, ferretdb, qdrant, redis, valkey, …│ │ ├── gateway/ # API and AI gateways│ │ │ └── ... # apisix, contour, kong, nginx, …│ │ ├── compute/ # generic compute primitives│ │ │ └── ... # function, keda, server, task, worker, …│ │ ├── messaging/ # event buses, queues│ │ │ └── ... # kafka, nats, rabbitmq, …│ │ ├── observability/ # metrics, logs, traces│ │ │ └── ... # grafana, loki, otel-collector, prometheus, tempo, …│ │ ├── security/ # identity, secrets, certificates│ │ │ └── ... # cert-manager, external-secrets, keycloak, …│ │ ├── devtool/ # developer-facing tooling│ │ │ └── ... # adminer, promptlayer, …│ │ └── storage/ # object/file storage, and the backup controllers│ │ │ # that copy a cluster's resources, or its│ │ │ # volumes' files, into a bucket│ │ ├── s3-object-store/│ │ │ └── 1.0.0/│ │ │ └── component.yaml│ │ └── ... # barman-cloud-plugin, gcs, k8up, velero, …│ └── example/ # a second publisher, same three-segment shape│ └── compute/│ └── greeter/│ └── 1.0.0/│ └── component.yaml│├── feature/ # DOMAIN 2: Abstract Interfaces│ │ # Flat: {publisher}/{name} (no category segment)│ │ # Path: {publisher}/{name}/{version}/feature.yaml│ │ # type: core/data-masking:1.0.0│ │ # → feature/core/data-masking/1.0.0/feature.yaml│ ││ ├── core/│ │ ├── data-masking/│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ ├── secret-value/ # feature.aggrega.ai/kind: secret│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ └── ... # k8s-dns-resolver, public-ingress, retry-policy, …│ └── ... # other publishers, same flat shape│├── aggregate/ # DOMAIN 1: Reusable Aggregate Modules│ │ # Path: {publisher}/{name}/{version}/aggregate.yaml│ └── core/│ ├── keycloak/│ │ └── 1.0.0/│ │ └── aggregate.yaml│ └── ... # agenta, apisix, dify, harbor, kong, thanos, …│├── recipe/ # DOMAIN 3: Concrete Implementations│ │ # Organized by CAPABILITY (the one a Recipe declares│ │ # in spec.capability).│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ │ # The version directory may bundle the Recipe's own│ │ # source charts or modules beside recipe.yaml.│ │ # OCI: hub.aggrega.ai/recipe/helm/mariadb:1.0.0│ ││ ├── helm/│ │ ├── mariadb/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── postgres/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── compose/│ │ └── mariadb/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── terraform/│ │ └── mariadb-rds-module/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── module/ # bundled Terraform source│ │ ├── main.tf│ │ └── variables.tf│ └── cloudformation/│ └── postgres-rds/│ └── 1.0.0/│ └── recipe.yaml│├── feature-recipe/ # DOMAIN 3: Concrete Implementations│ │ # Capability leads the path, same as recipes.│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ ││ ├── helm/│ │ ├── k8s-secret-from-parameter/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── public-ingress/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── chart/ # bundled Helm source│ │ ├── Chart.yaml│ │ └── templates/│ │ └── ingress.yaml│ ├── compose/│ │ └── dotenv-secret/│ │ └── 1.0.0/│ │ └── recipe.yaml│ └── ... # terraform, cloudformation│└── plugin/ # ARTIFACTS: Plugin entities, each a content-addressed │ # reference to a Wasm artifact. The compiled artifact │ # is published separately and is not stored here. │ # Path: {pluginType}/{name}/{version}/plugin.yaml │ ├── linter/ │ └── publishing/ │ └── 0.5.0/ │ └── plugin.yaml └── provider/ # the directory mirrors metadata.pluginType ├── helm/ │ └── 0.5.0/ │ └── plugin.yaml └── ... # cloudformation, compose, helm-chart, terraformDie Komponentenkategorien sind eine geschlossene Menge, und diese Menge — nicht das Dateisystem — ist die maßgebliche Instanz für Kategorien. Ein Kategoriewert, der noch keine Entität hat, ist reserviertes Vokabular: Die Browse-Achse bleibt stabil, und ein Autor weiß, wo eine künftige Komponente landen wird, sodass ein leeres Regal korrekt ist und keine Lücke, die einen Bewohner schuldet. Da der Katalog keine Platzhalterdateien enthält, wird das Verzeichnis für einen solchen Wert angelegt, wenn seine erste Entität eintrifft.
Die maßgebliche Liste — jede Kategorie, was sie enthält, die operativen type-Werte, die ihre Entitäten typischerweise tragen, und welche Verzeichnisse existieren — ist der Abschnitt Component-Kategorien des Leitfadens zu den Katalogkonventionen, der zusammen mit dem Katalog der Standardbibliothek veröffentlicht wird, den er regelt.
Die type-Achse trägt nur die operativen Primitive — kognitives Vokabular erscheint dort nie, und das veröffentlichte Component-Schema zählt die Werte auf, die der reservierte Schlüssel annimmt, sodass ein dort geschriebenes kognitives Wort beim Laden des Dokuments abgelehnt wird. Die Aufteilung in drei Achsen: operativer type (wie die Infrastruktur die Komponente behandelt), kognitive category (was sie ist, gespiegelt durch das Verzeichnis) und rollenspezifische Fähigkeits-Labels (verhaltensbezogene Teilmengen — eine Entität ist category: datastore plus der datastore.aggrega.ai/engine-Wert, den ihre eigene Produktidentität trägt, sodass core/datastore/qdrant vector trägt und core/datastore/redis kv, und beide Achsen abfragbar sind). Eine Fähigkeit, deren Zutreffen davon abhängt, was ein Autor konfiguriert, wird überhaupt nicht im Katalog geführt: Sie wird zur Kompilierzeit von der Rolle label-transform des Governance-Sockets injiziert, die die vom Entwickler deklarierten values liest. Rein KI-bezogene Kategorien tragen das Präfix ai-; Kategorien mit doppeltem Verwendungszweck erscheinen ohne Präfix, wobei die KI-Ausprägung durch Fähigkeits-Labels ausgedrückt wird. Kategorien werden danach gewählt, wie Benutzer navigieren und stöbern, nicht danach, wie der Compiler klassifiziert — das Kategorievokabular und die Fähigkeits-Labels sind Begriffe, mit denen der Compiler Selektoren abgleicht und denen er keine Bedeutung beimisst. Der Name einer Komponente wiederholt ihre Kategorie nicht: Das OpenAI-Modell der Standardbibliothek ist core/ai-model/openai, nicht core/ai-model/openai-model.
2. Das geteilte Schema und die Pipeline der Bridge-Synthese
Um den Boilerplate pro Component rund um die Deklarationen der Topologie-Sockets zu beseitigen, teilt Aggrega die Validierung in zwei Teile und prüft jeden dort, wo sein Gegenstand liegt:
usesSchema(deklaratives YAML). Deklariert die Topologie-Sockets, die eine Katalogentität anbietet, und gibt jedem einen Vertrag. Die Go-CLI liest es nativ, um während der statischen Analyse dieselector:-Zeichenfolgen für den Label-Abgleich zu extrahieren und die erlaubteninject-Mechanismen zu validieren. Jeder Socket-Eintrag unterstützt ein optionales Feldrequired: true(Standardfalse) — ist es gesetzt, gibt der Compiler einen Validierungsfehler aus, wenn in diesem Socket keine Abhängigkeit deklariert ist. Das ist das Socket-Gegenstück zur Semantik vonrequired: truebei Einträgen infeaturesSchema: Beide brechen den Build ab. Einen Socket hier zu deklarieren ist das, was der Katalog der Standardbibliothek tut, und bleibt der bessere Weg — aber es ist nicht die einzige Möglichkeit, wie ein Entwickler eine Kante ziehen kann. Der Autor eines Aggregate kann an seiner eigenen Komponente einen Socket benennen, den diesesusesSchemanicht deklariert, auch an einer Entität, die überhaupt keinusesSchemadeklariert; ein solcher Ad-hoc-Socket trägt keinen Selektor, keineinject-Allowlist und kein Schema pro Kante, gerade weil es hier keinen Eintrag gibt, der sie tragen könnte. Dieuseseines Feature-Attachments und dieusespro Kante eines Release sind auf diese Weise nicht offen — beide dürfen nur einen deklarierten Socket benennen. Den vollständigen Vertrag und das, worauf ein Ad-hoc-Socket verzichtet, finden Sie unter dependency-resolution §„Domäne 2: Das geteilte Schema“.- Desugaring. Verwenden Entwickler die YAML-Array-Kurzform (
uses: databases: ["db1"]), normalisiert die CLI sie in eine Map ({"db1": {"target": "db1"}}). - Bridge-Synthese. Der Compiler projiziert die Slot-Tabelle
featuresSchema:in ein Fragment nach JSON Schema 2020-12 — eine Eigenschaft pro Attachment-Slot, die die Form einer Füllung beschreibt, die ihn binden darf, mit einem Erweiterungsschlüsselwortx-aggrega-inject:an einem Slot, der eineinject-Allowlist deklariert. Die JSON-Schema-Validierung ignoriert Erweiterungsschlüsselwörter bei der strukturellen Validierung, und nichts liest eines davon aus dem Fragment zurück: Eine Prüfung, die die Allowlist eines Slots benötigt, liest den Slot selbst. Die Socket-TabelleusesSchema:wird in kein Fragment projiziert.selector:undinject:eines Sockets bleiben im typisierten YAML, das der Architekt geschrieben hat, und werden dort gelesen, und dasvalueSchema:/infraSchema:pro Kante eines Sockets wird für sich allein gekapselt und kompiliert, ohne dass eine Einschränkung darum herum erfunden wird. - Komposition. Der Plattformarchitekt schreibt eine strikte
schema:-Deklaration (kompakte Form oder vollständiges JSON Schema 2020-12), dievalues,infraundprovidesdefiniert. Diese Deklaration ist der eigene Vertrag der Entität und wird für sich allein kompiliert: Weder das Slot-Fragment noch die Socket-Tabelle wird in sie eingefügt. Jede Oberfläche wird dort geprüft, wo ihr Gegenstand liegt, sodass ein Socket-Fehler an dem Socket-Eintrag gemeldet wird, den der Architekt geschrieben hat, und nicht an einem Pfad innerhalb desschema:-Blocks — und der Architekt schreibt weiterhin keinenuses-Boilerplate.
Beispiel — eine Socket-Deklaration und was der Compiler damit macht: Das YAML des Plattformarchitekten
spec: usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: ["env", "file", "ssm_param"] # env and file are core mechanisms; ssm_param is a user-provided mechanism
schema: values: ha_mode: { type: boolean, default: false } infra: replicas: { type: integer, min: 1 } provides: host: { type: string, required: true }
assertions: # The Architect can write cross-pillar invariants against the unified instance content. ha-mode-needs-two-databases: | {{- if eq .values.ha_mode true -}} {{- if lt (len .uses.databases) 2 -}} {{- fail "ha_mode=true requires at least two database attachments" -}} {{- end -}} {{- end -}}Was der Compiler damit macht Die Socket-Tabelle wird als das typisierte YAML gelesen, das sie ist: Die selector:-Zeichenfolge geht an die native Label-Matching-Engine, und die inject:-Liste schränkt ein, welche Bereitstellungsmechanismen eine Kante durch diesen Socket benennen darf. Der schema:-Block wird separat kompiliert, als eigener values / infra / provides-Vertrag der Entität. Der statische Analysator liest die selector:-Zeichenfolge aus dem Socket-Eintrag, den der Architekt geschrieben hat — zusammen mit appliesTo / appliesToAnyOf aus den Feature-Entitäten — und wertet den Label-Abgleich gegen die metadata.labels jedes Ziels aus, um die knotenübergreifende Typsicherheit zu validieren.
Selektoren im Kubernetes-Stil in usesSchema
Die native Label-Matching-Engine des Go-Compilers wertet Selektor-Strings mit der standardmäßigen Selektionssemantik im Kubernetes-Stil aus (AND per Komma, OR per in(), NOT per !=/notin()). Dieselbe Engine — und dieselbe Grammatik für Selektor-Strings — wertet auch die Selektoren für Feature-Anhänge aus (appliesTo und jedes Element von appliesToAnyOf). Die Selektorschicht ist ausschließlich das Topologie-Gate — die schema:-Deklarationen pro Säule validieren den Inhalt von values, infra und provides unabhängig davon. Nachdem der Go-Compiler beim Aufbau der Topologie die topologischen Kanten gezogen hat, liest der Static Analyzer die selector-Strings aus den Socket-Einträgen, die der Architect verfasst hat, und wertet sie gegen die Katalog-labels des Zielknotens aus, um die knotenübergreifende Typsicherheit zu validieren.
usesSchema: # 1. The AND Operator (Comma) databases: selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
# 2. The OR Operator (Set-based 'in') datastores: selector: "datastore.aggrega.ai/engine in (relational, vector)"
# 3. The NOT Operator internal_systems: selector: "compliance.aggrega.ai/data-class!=public"Ein Selektor, den die Engine nicht als eine ihrer sechs Anforderungsformen lesen kann — eine leere Anforderung, ein Schlüssel mit Leerzeichen oder einem von =, !, (, ) und dem Komma, eine nicht geschlossene Menge —, hält den Build an jeder Kante an, die er schützt, statt als ein anderer Selektor gelesen zu werden. Die Selektor-Grammatik listet die Formen und jede Ablehnung auf.
3. Schemaformate und Komposition
Um sowohl strikte Validierung als auch Standard-Katalogmetadaten (Autor, Version, Beschreibung) bereitzustellen, werden die Definitionen von Domäne 2 (Schnittstellen) und Domäne 3 (Implementierungen) als YAML-Envelopes geschrieben. Domäne 2 verwendet eingebettete schema:-Deklarationen in kompakter Form (der Standard; ~15 Schlüsselwörter, mechanisch in JSON Schema 2020-12 umgewandelt) oder in vollständigem JSON-Schema-YAML.
Warum jedes Katalog-YAML den Envelope wiederholt. Der Envelope (Block aus apiVersion, kind, metadata) steht am Anfang jeder Katalogdatei — Component, Feature, Recipe, FeatureRecipe, Aggregate, Manifest, Release, Plugin —, unabhängig davon, wie kurz der Rumpf ist. Die Wiederholung ist beabsichtigt: Jede Datei ist darauf ausgelegt, als eigenständiges Artefakt geparst, validiert, gelintet und inspiziert zu werden. Eine einzelne Datei, die aus der OCI-Registry geholt, in eine CI-Sandbox gelegt oder in einem Editor eines Drittanbieters geöffnet wird, muss genug Selbstbeschreibung enthalten, damit nachgelagerte Werkzeuge erkennen können, welche Art von Entität sie darstellt und welche Schemaversion gilt. Die Verzeichnisposition ersetzt nie den Envelope: Jeder Parser, Validator und Linter liest die Art der Entität und die Schemaversion aus dem Envelope. Die Kosten sind mechanischer Boilerplate pro Datei; der Nutzen ist, dass die Garantie eigenständiger Werkzeuge über die OCI-Verteilungsoberfläche, das lokale Dateisystem und die Oberflächen IDE / CI / inspect hinweg gilt. Autoren kopieren den Envelope aus vorhandenen Dateien, wenn sie neue Kataloginhalte verfassen, oder beginnen mit aggrega scaffold <kind>, das ein Startdokument für die Art ausgibt, in dem apiVersion und kind bereits ausgefüllt sind.
Um das DRY-Prinzip (Don’t Repeat Yourself, „Wiederhole dich nicht“) einzuhalten, verwendet der Katalog zwei unterschiedliche Kompositionsmechanismen:
- Gemeinsame SchemaLibrary-Einträge (dokumentübergreifendes
$ref:): Wiederverwendbare JSON-Schema-Definitionen werden in SchemaLibrary-Katalogentitäten (Tier 3) gespeichert. Sie werden per Identität über dokumentübergreifendes$ref:(<library>#/schemas/<entry>, ohne Host — die Version stammt aus der Lockfile) aus jedem konsumierenden Component- oder Feature-Schema referenziert. Die Kette wird zur Kompilierzeit durchlaufen. Die Authoring-Form der Bibliotheksentität finden Sie unter entities/schemalibrary, die Auflösungssemantik unter vocabulary/cross-document-ref. - Einfachvererbung (
extends): Für vollständige Komponenten-Baselines können Entitäten die Eigenschaftextends: "URI"verwenden. Der Go-Compiler liest die Kette der übergeordneten Elemente rekursiv und führt die YAML-Metadaten per Deep Merge zusammen (wobei Labels bei Konflikten überschrieben und Arrays angehängt werden). Danach gehen die beiden Katalogarten bei den Datensäulen getrennte Wege. Dasschema:eines Feature wird mit dem seiner Basis gemäß der Komposition von JSON Schema 2020-12 zusammengesetzt. Eine erweiternde Component verfasst überhaupt keinen Säuleninhalt: Sie schreibt den literalen Markerschema: inheritedund erhält denschema:-Block ihrer Basis genau so, wie die Basis ihn verfasst hat, in jeder Tiefe einer Kette. Was eine solche Component stattdessen zusammensetzt, ist Struktur — ihre Attachment-Slots (featuresSchema), Topologie-Sockets (usesSchema), die Self-Inject-Allowlist (inject) und benannteassertionswerden alle entlang der Kette zusammengeführt. Siehe entities/component für die Beispiele zur Erweiterung von Basis- und Kindkomponenten + governance-and-compliance §„Vererbung und Veröffentlichungsdisziplin“ dazu, was die Vererbung konstruktionsbedingt regelt und was eine Regel der Veröffentlichungsdisziplin bleibt.
Siehe entities/component für die Beispiele zur Erweiterung von Basis- und Kind-Komponenten und entities/recipe für das Verfassen von Recipe-Pointern und -Mappern mit vollständigen Beispielen.
4. Die Workspace-Konfiguration (.aggrega-config.yaml)
Die Datei .aggrega-config.yaml im Workspace-Stammverzeichnis ist die Workspace-Konfiguration des Projekts — die eigene Deklaration des Workspace, geeignet für die Versionskontrolle, so wie go.mod oder package.json. Das Verzeichnis .aggrega/ bleibt per Konvention außerhalb der Versionskontrolle — tragen Sie es in .gitignore ein, wie Sie es mit node_modules/ oder .terraform/ tun würden.
Der Abschnitt workspace ist die Stammmarkierung: Sein Vorhandensein kennzeichnet das Workspace-Stammverzeichnis, und er enthält nur die Katalogverzeichnisse, die den Stamm definieren — catalog_dirs und die Map releases, die einem Release eigene Katalogverzeichnisse gibt. Jede andere Einstellung steht auf oberster Ebene. Viele sind Einzelwerte; andere sind Abschnitte, die die Einstellungen eines Belangs unter einem einzigen Schlüssel bündeln. Jedes Feld ist optional und hat dokumentierte Standardwerte. Die vollständige, aktuelle Menge der Schlüssel oberster Ebene, jeweils mit Typ, Standardwert und Bedeutung, wird aus dem Schema unter schema/other/aggrega-config generiert; das folgende Beispiel zeigt die Stammmarkierung zusammen mit einigen der Einzelwert-Einstellungen:
workspace: # Root marker; presence marks the workspace root catalog_dirs: # Ordered list of local catalog directories (checked before cache) - ./aggrega-catalogdefault_registry: hub.aggrega.ai # Default registry for unqualified URIsoffline: false # Set true for air-gapped environmentsauto_pull: true # Opt in to the implicit pull; the default is false, keeping build read-onlyartifact_cache_dir: .aggrega/cache # On-disk artifact cache rootEin signing:-Block enthält die Standardwerte für das Signieren von Artefakten, die aggrega push --sign und aggrega sign verwenden, sowohl auf oberster Ebene (global) als auch pro Registry:
signing: # Global signing defaults fulcio_url: https://fulcio.sigstore.dev # Keyless certificate authority (defaults to public-good) rekor_url: https://rekor.sigstore.dev # Keyless transparency log (defaults to public-good) timestamp_url: https://tsa.example.com/api/v1/timestamp # Optional RFC3161 timestamp authority (no default; opt-in) key_path: ./keys/signing.pem # Optional: path to a held keyed-key PEM (a pointer, never inline material)registries: - host: hub.example.com signing: # Per-registry override of the global signing block key_path: ./keys/hub.pemDie Rangfolge pro Feld ist CLI-Flag > signing pro Registry > globales signing > Public-Good-Standard. Fulcio und Rekor verwenden standardmäßig die Public-Good-Instanzen von Sigstore und sind daher optional; timestamp_url hat keinen Standardwert — der vertrauenswürdige schlüssellose Zeitstempel ergibt sich aus der Aufnahme in das Transparency-Log von Rekor, und eine RFC3161-Zeitstempelstelle ist Opt-in (setzen Sie timestamp_url oder --timestamp-url mit einem vollständigen Endpunkt, um eine zu aktivieren). Sicherheit: Der signing:-Block enthält kein geheimes Material — das OIDC-Identitätstoken ist nie ein Konfigurationsfeld (ein kurzlebiges Geheimnis, das zum Zeitpunkt des Signierens bereitgestellt wird: an einem interaktiven Terminal über einen Browser-Ablauf oder auf GitHub Actions aus dem Workflow bezogen und andernfalls mit --identity-token übergeben oder als AGGREGA_IDENTITY_TOKEN oder SIGSTORE_ID_TOKEN exportiert), und der private Schlüssel steht nie inline; key_path ist ein Pfad zu einer Schlüsseldatei. Das ist die bewusste Asymmetrie zur Verifizierungsseite, die einen öffentlichen Schlüssel inline festlegt, während auf der Signierseite immer nur ein Schlüsselpfad steht.
Markieren Sie einen Stamm ohne vendorte Kataloge, indem Sie workspace: {} schreiben. Die Liste catalog_dirs unterstützt Monorepo-Setups, in denen ein gemeinsamer Katalog in einem benachbarten Verzeichnis liegt. Der Compiler prüft jedes Verzeichnis der Reihe nach. Das Flag offline: true verhindert jeden Netzwerkzugriff — der Compiler verwendet nur lokale Pfade und den Cache und hält an, wenn eine Entität lokal nicht gefunden wird. Die in Abschnitte gegliederten Einstellungen bündeln jeweils einen Belang. Darunter: Regler für die Strenge zur Build-Zeit und Authoring-Hinweise; die Wasm-Attachment-Sockets auf Workspace-Ebene (governance, linter, importer, providers, cli), die jeweils eine Liste von Plugin-Referenzen aufnehmen; die Lint-Strenge pro Regel, einschließlich der Policy-Schalter für die Veröffentlichungsdisziplin; die Feinabstimmung des Parse-Caches des Daemons und die Größe seines Worker-Pools für die Anfrageverteilung; und die Größenobergrenze für den maschinenweiten Speicher kompilierter Module. Wieder andere enthalten die Standardwerte für das Signieren und das Signaturvertrauen sowie das eigene Verhalten des Daemons. Jeder Schlüssel oberster Ebene ist vollständig unter schema/other/aggrega-config dokumentiert.
Drei verschiedene Caches sind konfigurierbar, und es lohnt sich, sie kurz auseinanderzuhalten, weil ihre Namen ähnlich sind, ihre Geltungsbereiche aber nicht. artifact_cache_dir benennt den unten beschriebenen Inhaltscache auf der Festplatte pro Workspace. parse_cache begrenzt den In-Memory-Parse-Cache des Daemons, der nur so lange lebt wie der Daemon. compiled_module_cache begrenzt den Festplattenspeicher für kompilierten Plugin-Maschinencode — einen der Caches, die alle Workspaces auf der Maschine gemeinsam nutzen, weil die kompilierte Form eines Plugins vom Plugin abhängt und nicht vom Projekt, das es verwendet:
# .aggrega-config.yaml — most at home in the global config file, since the store is machine-widecompiled_module_cache: max_bytes: 53687091200 # Default 50 GiB; 0 disables the capUnter den Caches, die alle Projekte auf der Maschine gemeinsam nutzen, ist er derjenige, der die Cache-Nutzung auf der Festplatte dominieren kann, da jedes Plugin, das die Maschine ausführt, einmal in ihn kompiliert und behalten wird; daher ist er der einzige mit einer dauerhaften Größenobergrenze. Jeder Aufruf, der den Speicher öffnet, wendet die Obergrenze an, bevor er etwas kompiliert, und entfernt ganze Einträge, die am frühesten kompilierten zuerst, bis der Rest hineinpasst. (Ein Build, der mit --disable-plugin-cache läuft, kompiliert stattdessen in den Arbeitsspeicher, sodass er den Speicher weder vergrößert noch verkleinert.) Das Entfernen eines Eintrags kostet eine spätere Neukompilierung und sonst nichts; deshalb ist es sicher, die Obergrenze zu senken und sie anzuwenden, während andere Builds auf derselben Maschine laufen. Setzen Sie sie über das, was ein einzelner Build kompiliert: Weil die Obergrenze vor dem Kompilieren angewendet wird, führt eine Obergrenze unterhalb des Working Sets eines einzelnen Builds dazu, dass jeder Build dieselben Module verwirft und neu kompiliert, und aus demselben Grund kann der Speicher zwischen Builds über der Obergrenze liegen und wird zu Beginn des nächsten Builds erneut verkleinert. aggrega cache status meldet die Größe des Speichers, und aggrega cache evict --max-size verkleinert ihn bei Bedarf auf eine auf der Befehlszeile angegebene Obergrenze.
Das Stammverzeichnis artifact_cache_dir enthält drei parallele Unterbäume, die ein einziger Aufruf von aggrega pull einheitlich befüllt, einen pro Klasse festgelegter Abhängigkeiten: <artifact_cache_dir>/entities/<encoded-kind>/<encoded-reference>/<encoded-version>/ für Katalogentitäten (Components, Features, Recipes, FeatureRecipes, Aggregates, die Bibliotheken und Plugins mit den ausführbaren Dateien, die sie veröffentlichen), wobei die Art diejenige ist, unter der die Entität veröffentlicht wird, sodass zwei Entitäten unterschiedlicher Art, die eine Referenz und eine Version gemeinsam haben — eine Component und ein Recipe desselben Namens —, zwei Slots belegen; <artifact_cache_dir>/source-artifacts/<kind>/<host>/<path>/<version>/<digest-prefix>/ für Quellartefakte, die aus den spec.source-Feldern von Recipe / FeatureRecipe geholt werden (Helm-Charts, Compose-Fragmente); und <artifact_cache_dir>/inputs/sha256/<hex-digest> für externe Eingaben — die entfernten Dokumente, die ein Provider beim Rendern vom Host anfordert, etwa ein $ref in der values.schema.json eines Charts, das auf eine URL zeigt. Jeder Cache-Slot eines Quellartefakts enthält das maßgebliche .tgz-Archiv, ein abgeleitetes Verzeichnis extracted/, das bei jedem Lesen durch einen Build neu erzeugt wird, und eine Datei metadata.yaml, die die Identität {kind, url, version, digest, mediatype, pulled_at} des Artefakts festhält. Jeder Cache-Slot einer Entität enthält das veröffentlichte Artefakt so, wie es geholt wurde, und das OCI-Manifest, gegen das es verifiziert wird. Der Slot jeder Art, deren Dokument eine Datei neben sich benennen kann — ein Recipe, ein FeatureRecipe, eine Component, ein Feature —, enthält außerdem ein abgeleitetes Verzeichnis extracted/ mit den Dateien, die dieses Artefakt mitführt, in einem nach dem Inhalts-Digest des Artefakts benannten Verzeichnis: das Dokument und die Dateien, die die Entität deklariert hat, wenn sie als Archiv veröffentlicht wurde, und nur das Dokument, wenn sie als ihr Dokument veröffentlicht wurde (§6). Das Verzeichnis der Entität wird dort bei jedem Lesen aus dem verifizierten Artefakt angelegt, genauso wie die Dateien eines Quellartefakts: Jede Datei wird gegen das Artefakt geprüft, eine in diesem Verzeichnis von Hand geänderte oder hinzugefügte Datei wird verworfen statt gelesen, nichts anderes unter extracted/ wird gelesen, und ein Artefakt, das die Verifizierung nicht besteht, wird abgelehnt, bevor irgendetwas angelegt wird. Ein Lesevorgang schreibt nur das neu, was vom Artefakt abweicht, sodass Builds, die gleichzeitig denselben Cache lesen — Anfragen, die aggrega serve nebeneinander bearbeitet, oder zwei Befehle über einem Workspace —, die ihnen übergebenen Dateien jeweils vollständig vorfinden. Das 12-stellige Segment <digest-prefix> trennt dasselbe {kind, url, version}, das bei unterschiedlichen Upstream-Digests neu getaggt wurde, in verschiedene Slots. Eine externe Eingabe braucht keinen solchen Slot: Sie wird als einzelne Datei gespeichert, die nach dem Inhalts-Digest benannt ist, auf den die Lockfile sie festlegt, sodass das, was ein späterer Build liest, über die Festlegung adressiert wird und nicht über die URL, von der die Bytes kamen — und genau das ermöglicht es diesem Build, die Eingabe bei gesperrtem Netzwerk bereitzustellen.
Neben diesen dreien können drei weitere Verzeichnisse erscheinen, und keines enthält Inhalte festgelegter Abhängigkeiten: index/ enthält die durchsuchbaren Snapshots pro Registry, die aggrega registry update schreibt (§8), signatures/ speichert jedes verifizierte Signatur-Bundle unter seinem eigenen Digest im Cache, sodass ein späterer Lesevorgang den zwischengespeicherten Blob erneut gegen den Digest prüft, unter dem er erfasst wurde, statt das Bundle erneut zu holen, und catalog-snapshots/ bewahrt jeden veröffentlichten Katalog-Snapshot auf, den ein Import gelesen hat (§8) — das Archiv und sein Manifest in einem nach dem Manifest-Digest benannten Slot, wobei der Katalogbaum bei jedem Lesevorgang aus dem Archiv ausgelegt wird, sowie eine Datei current, die den Snapshot nennt, den der Workspace liest, wo nichts einen anderen nennt.
Das Dokumentations-Bundle gehört nicht dazu. Seine Bytes hängen nur von der Registry ab, in der es veröffentlicht ist, und von der Version, unter der es veröffentlicht ist; daher wird es einmal pro Maschine aufbewahrt, neben dem Speicher kompilierter Module unter demselben benutzerbezogenen Cache-Stammverzeichnis, unter docs-bundles/<encoded-reference>/<encoded-version>/ unterhalb dieses Stammverzeichnisses: das Bundle, das Manifest, gegen das es verifiziert wird, und die Signaturen, die beim Holen verifiziert wurden. artifact_cache_dir reicht nicht bis dorthin. Bevor eine Seite daraus gelesen wird, werden diese Signaturen erneut verifiziert, und zwar unter der eigenen Signaturprüfung des lesenden Workspace für die Registry des Bundles, sodass eine Kopie, die die lockereren Einstellungen eines Workspace eingelassen haben, nicht an einen Workspace ausgeliefert wird, dessen Prüfung sie ablehnt — siehe aggrega-explain und aggrega-cache.
artifact_cache_dir wird relativ zum Workspace-Stammverzeichnis geschrieben und bezeichnet dasselbe Verzeichnis, unabhängig davon, aus welchem Verzeichnis ein Befehl aufgerufen wird oder welche Katalogverzeichnisse durchsucht werden. Ein absoluter Wert wird beim Laden der Konfiguration mit einer Diagnose abgelehnt, die das Feld benennt: Jeder Leser der Einstellung löst sie gegen das Workspace-Stammverzeichnis auf, sodass ein absoluter Pfad einen Ort bezeichnen würde, den keiner von ihnen erreicht, und der Fehler sonst stumm bliebe — der Cache, den ein Pull schreibt, wäre unbemerkt nicht mehr der Cache, den ein Build liest. Der Cache darf in einem Katalogverzeichnis liegen, und im Standardlayout tut er das, da ein Katalogverzeichnis häufig das Workspace-Stammverzeichnis selbst ist. Was er nicht darf, ist, ein Katalogverzeichnis zu sein: Ein Katalogscan überspringt den Cache, sodass ein Cache-Verzeichnis, das zugleich ein Katalogverzeichnis ist, den gesamten Inhalt dieses Verzeichnisses aus jedem Scan herausnimmt. artifact_cache_dir: . bezeichnet das Workspace-Stammverzeichnis, was im Standardlayout genau dieser Fall ist, und wird beim Laden der Konfiguration mit einer Diagnose abgelehnt, die das Feld benennt — ebenso wie jede andere Schreibweise, die sich auf das Workspace-Stammverzeichnis reduziert. Diese beiden Formen sind, zusammen mit dem oben genannten absoluten Pfad, diejenigen, die die Konfigurationsprüfung von sich aus erkennen kann. Ein Wert, der ein anderes Katalogverzeichnis bezeichnet — sub in einem Workspace, dessen catalog_dirs sub aufführt —, wird ohne Beanstandung geladen, und das einzige Symptom ist, dass die Entitäten darunter nicht mehr gefunden werden. Den Cache aus jedem in workspace.catalog_dirs aufgeführten Verzeichnis herauszuhalten, gehört daher zum Schreiben der Konfiguration und ist nichts, was sie für Sie prüft.
Das Überspringen des Caches verhindert, dass ein Auflösungsartefakt so gelesen wird, als hätte ein Autor es geschrieben. Ein Cache-Slot enthält Bytes, die ein Abruf aus der Registry dort abgelegt hat, gespeichert unter der Koordinate, unter der sie abgerufen wurden, und verbürgt durch einen Digest der Lockfile; ein Scan, der einen solchen als verfassten Kataloginhalt aufnähme, würde Bytes übernehmen, die nichts verifiziert hat, auf einem Pfad, den der Autor nicht bearbeiten kann. Eine Folge sei klar ausgesprochen: Enthält der Cache eine Entität, die keine Lockfile festlegt — zurückgelassen von einem abgebrochenen Pull, von Hand hineinkopiert oder verwaist, als ein Release aufhörte, sie zu referenzieren —, ist diese Entität für einen Katalogscan nicht sichtbar, und ein Build oder eine Validierung, die von ihr abhängt, hält mit der Meldung an, dass die Entität nicht gefunden wurde. Abhilfe schafft ein erneuter Pull des Release, sodass die Entität über die Lockfile aufgelöst und ihr Digest erfasst wird; der Abbruch benennt die Entität, sodass die fehlende Festlegung identifiziert werden kann. Die Alternative — sie trotzdem aufzulösen — ist genau das unverifizierte Lesen, das das Überspringen des Caches verhindern soll.
Das Lockfile gilt pro Release: Das Auflösen von release.yaml schreibt release.lock daneben (der Dateistamm der Release-Datei plus .lock). aggrega pull löst Abhängigkeiten auf und schreibt das Lockfile; aggrega build liest es und verwendet die gepinnten Versionen unabhängig vom Zustand der Registry zum Build-Zeitpunkt. Workspaces committen das Lockfile, wenn die Reproduzierbarkeit des Builds über Maschinen hinweg wichtig ist; nachdem sich eine Entität, eine Bibliothek, ein Plugin oder das Release selbst im Workspace geändert hat, aktualisiert aggrega pull --release <release> es, indem es das Geänderte neu auflöst und jeden anderen Pin beibehält, und mit aggrega pull --upgrade --release <release> wird eine neuere Version übernommen, die eine Registry jetzt anbietet. Das Lockfile verzeichnet jede aufgelöste Entität mit ihrer Art, ihrer URI wie verfasst, der aufgelösten Version, dem Inhalts-Digest und den referenzierenden Stellen. Art und URI identifizieren gemeinsam einen Eintrag, sodass ein Release, dessen Aggregate und Manifest einen Namen gemeinsam haben, für jedes der beiden einen Eintrag verzeichnet und eine Änderung an einem der beiden den nächsten Build anhält, bis ein Pull sie verzeichnet:
# release.lockentities: - kind: component uri: core/datastore/mariadb:1.0.0 resolved_version: 1.0.0 digest: sha256:5deeedb9acc1be00d4e0f98e55e01d301a0bcc01d702c015a9d9628ff573650a referenced_from: - aggregate.spec.components.db.type - kind: recipe uri: mariadb-bitnami:1.0.0 resolved_version: 1.0.0 digest: sha256:215b54e2da1ce512fcdccff87f6f71daac707bc77e4214b60b946b27a24e483a referenced_from: - manifest.spec.mappings.components.type.core/datastore/mariadb:1.0.0generated_at: "2026-06-11T16:48:15Z"mapping_libraries: []plugins: []release: release.yamlschema_libraries: []source_artifacts: []version: 1Jeder gepinnte Eintrag trägt Art + URI + aufgelöste Version + inhaltsadressierbaren Digest. Der Digest wird bei jedem Abruf verifiziert; Bytes, die nicht zum gepinnten Digest passen, halten den Build mit einem Integritätsfehler an. Der Digest einer Entität wird über das gebildet, was eine Veröffentlichung von ihr trägt — ihr Dokument und jede Datei, die sie daneben deklariert, jeweils über Pfad und Bytes — und nicht über die Bytes, in denen sie übertragen wird, sodass dieselbe Entität denselben Digest verzeichnet, ob sie aus einem Katalogverzeichnis gelesen oder aus einer Registry abgerufen wird, wie auch immer ihr Archiv komprimiert wurde und welche Berechtigungsbits, das Ausführungsbit eingeschlossen, ein Checkout ihren Dateien gegeben hat. Gegen den eigenen Digest der Registry über die veröffentlichten Bytes wird ein Abruf zuerst geprüft, und zwar über das Manifest, dessen Digest ein über die Registry aufgelöster Eintrag neben seinem eigenen verzeichnet.
5. Das dreistufige Modell der Entitätsauflösung
Der Compiler löst jede während der Kompilierung angetroffene Entitätsreferenz über eine strikte kaskadierende Suche auf. Die drei Stufen — lokaler Pfad, Workspace und Cache sowie Registry — entsprechen drei Authoring-Workflows, die in einem gesunden Aggrega-Projekt nebeneinander bestehen: ein Release, das die Dateien neben sich benennt, ein Team, das einen eingecheckten Katalog plus zuvor abgerufenen Cache nutzt, und ein Pull, der für ein noch nicht abgerufenes Artefakt die Registry erreicht. Die Stufe Workspace und Cache und die Registry-Stufe derselben Kaskade werten type-Felder in Aggregates aus, URI-Werte in Manifest-Mappings, implements-Deklarationen an Recipes und FeatureRecipes sowie plugin-Referenzen in Recipe- und FeatureRecipe-Pipelines; die Stufe des lokalen Pfads wird nur von den Dateien erreicht, die ein Release und sein Manifest benennen.
Lokaler Pfad. Eine aggregate-, manifest- oder extends-Referenz eines Release oder das extends eines Manifest, die mit ./ oder ../ beginnt (ein relatives POSIX-Pfadpräfix), wird direkt von der Festplatte relativ zum Release gelesen. Keine Katalogsuche, kein Registry-Aufruf. Das explizite Präfix unterscheidet auf syntaktischer Ebene die Absicht eines lokalen Pfads von der Namenssuche: Ein Release, das aggregate: ./aggregate.yaml schreibt, benennt eine Datei; aggregate: checkout benennt ein Aggregate über seinen metadata.name. Der Resolver untersucht nie den Inhalt des Strings, um zu entscheiden, welche Stufe gilt — das Präfix ist das Unterscheidungsmerkmal. Jede andere Referenz, einschließlich eines Component-type in einem Aggregate, wird über die Stufe Workspace und Cache und die Registry-Stufe aufgelöst: Eine lokal verfasste Entität wird unter catalog/ im Workspace-Root oder in einem Verzeichnis abgelegt, das workspace.catalog_dirs aufführt, und ein als relativer Dateipfad geschriebener type hält den Build als eine Entität an, die kein Katalog enthält.
Workspace und Cache. Eine Referenz ohne explizites lokales Pfadpräfix wird zuerst in den Verzeichnissen gesucht, die in workspace.catalog_dirs aufgeführt sind (projektlokale Katalogbäume, die im Repository verfasst oder dorthin vendored wurden — siehe §4 für die Form der Konfiguration) — oder, für ein Release, dem die Konfiguration unter workspace.releases eigene Verzeichnisse gibt, in diesen — dann im Verzeichnis catalog/ des Workspace-Roots und danach in artifact_cache_dir (dem von Git ignorierten Ort .aggrega/cache/, der aus früheren Registry-Auflösungen abgerufene Artefakte enthält und dessen Teilbäume §4 beschreibt). Der Cache-Treffer ab dem zweiten Build ist das, was die innere Schleife netzwerkfrei hält, selbst wenn das Projekt von entferntem Kataloginhalt abhängt.
Registry. Liefert die Stufe Workspace und Cache keinen Treffer, führt aggrega pull — oder ein Build, der mit --auto-pull oder der Workspace-Einstellung auto_pull läuft — einen ORAS-basierten OCI-Pull gegen default_registry (Standard hub.aggrega.ai) aus, entpackt das Artefakt für nachfolgende Builds in den Cache und fährt mit der aufgelösten Entität fort. Ein Build ohne beides liest nur, was seine Lockfile festlegt, und hält an, wenn die Lockfile fehlt, wobei er aggrega pull nennt. Die OCI-URI-Form, die der Registry-Aufruf konstruiert, folgt der in §6 beschriebenen Entitätstyp-Taxonomie (Artefakt-Packaging & OCI-Taxonomie). Kurzform-URIs in Aggregates und Manifests werden vor dem Registry-Aufruf in ihre vollständige OCI-Form expandiert; die Inferenzregeln hinter dieser Expansion finden sich in der Manifest-Referenz Kontextabhängige Kurzform-URIs und in §8 unten.
Vorrang und Shadowing. Der Auflösungsvorrang ist strikt lokaler Pfad > Workspace und Cache > Registry. Eine Entität in einem lokalen Katalogverzeichnis mit derselben Identität wie eine Registry-Entität überschattet die Registry-Entität — das ist beabsichtigt und lässt Katalogautoren Änderungen vor der Veröffentlichung ausprobieren. Dasselbe Shadowing gilt zwischen catalog_dirs und dem Cache: Eine in einem Katalogverzeichnis des Workspace vorhandene Entität wird einer gecachten Kopie vorgezogen, sodass lokale Änderungen an einem vendored Katalog sofort wirksam werden.
Innerhalb der Stufe Workspace und Cache ist catalog_dirs ein geordneter Vorrang-Stack nach dem Prinzip „der Erste gewinnt“. Erscheint dieselbe Entitätsidentität in mehr als einem aufgeführten Katalogverzeichnis, gewinnt das früher aufgeführte Verzeichnis und das spätere Vorkommen wird überschattet — überschrieben, nicht geladen und kein Fehler. So kann ein Projekt sein eigenes Katalogverzeichnis vor ein gemeinsam genutztes oder vendored Verzeichnis legen und ausgewählte Entitäten anhand ihrer Identität überschreiben, während der Rest auf das gemeinsam genutzte Verzeichnis durchfällt. Die Überschreibung ist beobachtbar: Das Auflösungsdetail meldet, welches Verzeichnis gewonnen hat und welches überschattet wurde, sodass eine Schichtung nie stillschweigend erfolgt. Shadowing gilt nur über Verzeichnisse hinweg; zwei Dateien in einem einzigen Verzeichnis, die dieselbe Identität beanspruchen, sind ein Authoring-Fehler und halten das Laden an. Ein mehr als einmal genanntes Verzeichnis — durch ein --catalog-Flag und in catalog_dirs oder zweimal in der Liste — ist ein einziger Eintrag des Stacks, der einmal an der Stelle durchsucht wird, an der es zuerst genannt wurde, sodass ein Shadowing immer zwei verschiedene Dateien betrifft und nie ein gegen sich selbst gelesenes Verzeichnis. Da der Vorrang der vom Autor kontrollierten Verzeichnisreihenfolge folgt, ist die aufgelöste Menge deterministisch.
Das Verzeichnis catalog/ des Workspace-Roots tritt diesem Stack an seinem Ende bei, nicht an seinem Anfang, und nur, wenn das Verzeichnis existiert — sodass alles, was ein Projekt aufführt, bei einer Kollision gewinnt, und das Aufführen eines nicht verwandten Verzeichnisses nie stillschweigend dazu führt, dass es nicht mehr gelesen wird. Es wird übersprungen, wenn ein aufgeführter Eintrag es bereits erreicht, da das Durchlaufen eines aufgeführten Verzeichnisses rekursiv ist und ein Stack, der den Workspace-Root nennt, es bereits gelesen hat. catalog_dirs wegzulassen und es als leere Liste zu schreiben, sind unterschiedliche Aussagen: Weggelassen liest der Workspace weiterhin catalog/; als [] geschrieben liest er überhaupt keinen lokalen Katalog, und so erklärt ein Workspace, dass er keinen hat.
Air-gapped Builds. Das Setzen von offline: true (§4) überspringt die Registry-Stufe vollständig. Eine Referenz, die in der Stufe des lokalen Pfads oder in der Stufe Workspace und Cache nicht aufgelöst werden kann, führt zu einem Fehler wegen fehlender Entität, statt stillschweigend einen Netzwerkaufruf zu versuchen, was CI-Pipelines, die das Netzwerk rechtlich nicht erreichen dürfen, einen deterministischen Fail-fast-Vertrag gibt.
Wo die Kaskade wirkt. Die Kaskade lädt die Entität in den Speicher; weitere darauf aufbauende Auflösungsmechanismen — die zweistufige Manifest-Suche nach type vs. name, der Versionsabgleich von implements in drei Formen (exakt / Major-kompatibler Bereich / unversioniert) unter vocabulary/inheritance-and-interface und die achsenweise Recipe-Auswahl nach Provider und Komponenteninstanz — arbeiten auf Entitäten, die der Resolver bereits durch diese Kaskade gezogen hat.
6. Artefakt-Packaging & die OCI-Taxonomie (Capability als führendes Segment)
Aggrega behandelt Infrastrukturlogik so, wie Docker Container-Images behandelt, und nutzt die Standards der Open Container Initiative (OCI) über ORAS (OCI Registry As Storage). Benutzer können ihren Aggrega-Katalog in jeder Standard-Registry hosten (GHCR, AWS ECR, Aggrega Hub).
Da Recipes strikt 1:1 an eine Rendering-Capability gebunden sind — ein Recipe nennt eine Capability in spec.capability und kann nicht zwei ansprechen —, ist der sauberste Weg, sie in einer OCI-Registry zu organisieren, die Capability in das führende Repository-Segment zu legen.
Die OCI-Taxonomie deckt alle Entitätstypen ab. Ein Repository-Name ist das Kind-Segment — das kind der Entität, kleingeschrieben — gefolgt von der Identität der Entität, durchgehend kleingeschrieben:
hub.aggrega.ai/component/core/datastore/mariadb:1.0.0— Component, Publishercore, Kategoriedatastorehub.aggrega.ai/component/core/compute/api-server:1.0.0— Component, Publishercore, Kategoriecomputehub.aggrega.ai/feature/core/data-masking:1.0.0— Feature, Publishercore(flach, keine Kategorien)hub.aggrega.ai/aggregate/core/db-module:1.0.0— Wiederverwendbares Aggregate-Modulhub.aggrega.ai/recipe/helm/mariadb:1.0.0— Recipe, Capabilityhelmhub.aggrega.ai/recipe/helm-chart/mariadb:1.0.0— Recipe, Capabilityhelm-charthub.aggrega.ai/recipe/compose/mariadb:1.0.0— Recipe, Capabilitycomposehub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0— FeatureRecipe, Capabilityhelmhub.aggrega.ai/schemalibrary/aidatastores:1.0.0— SchemaLibrary, gemeinsam genutzte Schemadefinitionen; dermetadata.nameAIDatastoresin PascalCase wird im Repository-Namen kleingeschriebenhub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0— MappingLibrary, gemeinsam genutzte Go-Template-Mapping-Fragmentehub.aggrega.ai/plugin/provider/helm:0.5.0— Plugin, Socket-Typprovider(das Segmentmetadata.pluginType)
Die veröffentlichbaren Kinds umfassen die Katalog-Authoring-Kinds zusammen mit dem Aggregate, einem wiederverwendbaren Modul (veröffentlichbar, ob es später als spec.aggregate der obersten Ebene eines Release referenziert oder im aggregates:-Block eines anderen Aggregate verschachtelt wird), und dem Plugin, einer inhaltsadressierten Referenz auf ein WebAssembly-Artefakt, das der Compiler routet und die Laufzeitumgebung ausführt. Das Plugin ist ein strukturelles veröffentlichbares Artefakt statt eines Katalog-Authoring-Kinds. Release und Manifest sind deploymentseitige Eingaben, die in der Versionskontrolle liegen und nie gepusht werden — aggrega push lehnt sie ab —, daher haben sie keinen Veröffentlichungs-Mediatype. aggrega push --list-kinds meldet die Menge, die das installierte Binary veröffentlicht, ein Kind pro Zeile. Jedes veröffentlichbare Kind hat seinen eigenen OCI-Mediatype in jeder der beiden Formen, die eine Veröffentlichung annimmt:
| Entitätsart | Als ihr Dokument veröffentlicht | Mit den von ihr deklarierten Dateien veröffentlicht |
|---|---|---|
| Component | application/vnd.aggrega.component.v1beta1+yaml | application/vnd.aggrega.component.v1beta1+tar+gz |
| Feature | application/vnd.aggrega.feature.v1beta1+yaml | application/vnd.aggrega.feature.v1beta1+tar+gz |
| Recipe | application/vnd.aggrega.recipe.v1beta1+yaml | application/vnd.aggrega.recipe.v1beta1+tar+gz |
| FeatureRecipe | application/vnd.aggrega.featurerecipe.v1beta1+yaml | application/vnd.aggrega.featurerecipe.v1beta1+tar+gz |
| Aggregate | application/vnd.aggrega.aggregate.v1beta1+yaml | — deklariert keine Datei |
| SchemaLibrary | application/vnd.aggrega.schemalibrary.v1beta1+yaml | — deklariert keine Datei |
| MappingLibrary | application/vnd.aggrega.mappinglibrary.v1beta1+yaml | — deklariert keine Datei |
| WorkloadLibrary | application/vnd.aggrega.workloadlibrary.v1beta1+yaml | — deklariert keine Datei |
| ArtifactLibrary | application/vnd.aggrega.artifactlibrary.v1beta1+yaml | — deklariert keine Datei |
| Plugin | application/vnd.aggrega.wasmplugin.v1beta1+yaml | — veröffentlicht über sein eigenes Manifest |
Was eine Veröffentlichung trägt, und damit ihre Form, ergibt sich aus dem, was die Entität deklariert — nicht aus ihrem Kind und nicht aus dem, was in ihrem Verzeichnis liegt. Eine Veröffentlichung trägt das Entitätsdokument und die Dateien, die die Entität selbst daneben nennt: die lokale source: eines Recipe oder eines FeatureRecipe — ein Verzeichnis reist mit jeder Datei darunter, die die in seinem entity.lock verzeichneten Ignore-Regeln behalten —, jede Datei, die seine Einträge valuesMapping:, workload: und artifacts: mit $import: importieren, und das entity.lock, das sein Pin-Schritt geschrieben hat; sowie jede Schemadatei, die eine Component oder ein Feature importiert, jede Datei einer Importkette eingeschlossen. Nichts anderes im Verzeichnis reist mit: Eine Notiz, eine README oder die Ausgabe eines Builds neben der Entität ist kein Teil dessen, was sie veröffentlicht, wie auch immer sie heißt, und ändert nicht die Form, in der sie veröffentlicht wird. Eine Entität, die nichts nennt, wird als ihr verfasstes Dokument veröffentlicht, Byte für Byte, unter dem +yaml-Mediatype ihres Kinds; eine, die eine Datei nennt, wird als gzip-komprimiertes tar aus dem Dokument und diesen Dateien veröffentlicht, unter dem +tar+gz-Mediatype ihres Kinds. Ein Aggregate, ein Plugin und die Bibliotheks-Kinds deklarieren keine Datei neben ihrem Dokument, daher werden sie immer als das Dokument veröffentlicht — ein Aggregate an einem Workspace-Root eingeschlossen, da jeder Pfad, den es deklariert, eine andere Entität nennt und keine Datei, die es trägt; ebenso ein Recipe, dessen Inhalt vollständig inline ist. Eine entfernte Quelle ist eine Referenz und keine Datei, sie trägt also nichts, obwohl das entity.lock, das ihren Pin verzeichnet, ein solches Recipe zu einem Archiv macht. Das Versionssegment jedes Mediatypes ist allen veröffentlichbaren Kinds gemeinsam, und das Kodierungssegment sagt, welche der beiden Formen die Bytes haben. Nachgelagerte Werkzeuge dispatchen auf den vollständigen Mediatype-String — Kind, Version und Kodierung zusammen.
Eine verfasste Form nennt kein Verzeichnis, das eine Veröffentlichung kennen kann: eine lokale Quelle, die als Template geschrieben ist. Ihr Verzeichnis wird erst ausgewählt, wenn ein Release das Template ausfüllt, daher trägt die Entität jede Datei in ihrem eigenen Verzeichnis, die ihre verzeichneten Ignore-Regeln behalten, damit jedes Verzeichnis, das ein Release auswählt, mitgereist ist; aggrega push weist darauf hin, wenn das geschieht. Nur das Genannte zu tragen hat einen Preis, und er fällt auf den Konsumenten: Eine Datei, die eine Entität liest und nirgends nennt, reist nicht mit, und es ist der Build eines Konsumenten — nicht der Push des Publishers —, der auf ihr Fehlen trifft und den fehlenden Pfad in seinem Cache-Slot nennt.
Welche Dateien eines Quellverzeichnisses zur Entität gehören, wird einmal entschieden, wenn die Entität gepinnt wird, und verzeichnet. Das Plugin, das die Capability der Entität im Workspace des Autors bedient, deklariert, was sein Ökosystem nie ausliefert — die Versionskontrollverzeichnisse eines Chart-Plugins und dessen Beachtung der .helmignore eines Charts, das .terraform/ eines Modul-Plugins —, und die .aggregaignore des Autors neben der Entität hat das letzte Wort. Der Pin-Schritt verzeichnet dieses Plugin und die zusammengesetzten Regeln im entity.lock, und die Veröffentlichung, jeder Vergleich der Pins der Quelle, die Lockfile-Zeile der Entität und das Rendering wenden alle die verzeichneten Regeln an, statt erneut ein Plugin zu fragen, sodass das Veröffentlichte genau das ist, was der eigene Build des Autors rendert, und ein geändertes Binding oder ein neueres Binary keinen Digest verschiebt, bis die Entität erneut gepinnt wird. Der Compiler hat keine Meinung zu irgendeinem Ökosystem: Die Regeln stammen vom Plugin und vom Autor, und der Compiler gleicht sie nur ab. Ein symbolischer Link unter den Dateien einer Entität wird abgelehnt statt verfolgt, da das, worauf er zeigt, unter seinem Namen reisen würde. aggrega pin erläutert die Regeln vollständig.
Der Name eines Recipe enthält weder ein Domänenpräfix noch die Capability: Das Verzeichnis des Entitätstyps und das Capability-Segment sagen bereits beides.
Namenskonvention: Components (Domäne 2) verwenden {publisher}/{category}/{name}, und Features (Domäne 2) sowie wiederverwendbare Aggregates (Domäne 1) verwenden {publisher}/{name}, wobei das Publisher-Segment den Anbieter/Autor nennt (core = offizielle Standardbibliothek, acme = Unternehmen). Entitäten der Domäne 3 (Recipe, FeatureRecipe) verwenden {capability}/{name}, wobei die Capability der Provider ist, den die Entität in spec.capability deklariert; eine Referenz kann die Entität auch unqualifiziert nennen, nur mit dem Blatt. Recipe-Namen enthalten auch die Capability NICHT, da sie bereits das führende Segment der kanonischen URI ist.
Recipes verwenden das Schlüsselwort implements, um sich an die Schnittstelle zu binden, die sie erfüllen. Das Feld implements unterstützt exakten Abgleich, Abgleich über einen Major-kompatiblen Bereich oder unversionierten Abgleich (siehe vocabulary/inheritance-and-interface zum Versionsabgleich von implements). Das Recipe eines Mapping-Eintrags im Manifest muss den Typ implementieren, für den es gemappt ist, oder eine Basis, die dieser Typ per extends erweitert: den Schlüssel des Eintrags sowie den Typ jeder Component-Instanz, die der Schlüssel in einer Version erreicht, die er nicht nennt, und zwar in der Version, als die der Build diese Instanz kompiliert — so kann ein Schlüssel eine Instanz nicht an ein Recipe schicken, das für eine andere Version ihres Typs geschrieben wurde.
Wenn ein Ops-Engineer aggrega push ausführt, veröffentlicht die CLI die Entität in dieser Form, unveränderlich unter ihrer Version. Ein Konsument ruft sie über das dreistufige Auflösungsmodell ab, cacht sie lokal in .aggrega/cache/ und legt das, was sie trägt, im Cache-Slot der Entität (§4) aus — die Dateien eines Archivs oder nur das Dokument.
Eine gepullte Entität liest die Dateien, die sie mitführt, genau so, wie sie sie neben sich in einem Katalogverzeichnis liest. Die Entität wird von ihrem Platz in diesem ausgelegten Baum gelesen, sodass ein relatives source: oder $import:, das sie deklariert — ausgeschrieben oder von einem Template erzeugt —, innerhalb dessen aufgelöst wird, was veröffentlicht wurde, und ein Pfad, der das eigene Verzeichnis der Entität verlässt, dort genauso abgelehnt wird wie in einem Katalogverzeichnis. Nichts außerhalb des Baums wird an seiner Stelle gelesen: weder das Verzeichnis, aus dem ein Build läuft, noch eine im Cache-Slot platzierte Datei. Eine Component oder ein Feature, deren Schema aus einer Datei importiert wird, führt diese Datei mit, sodass eine gepullte Kopie den veröffentlichten Vertrag lädt und die dagegen verfassten Werte genau so validiert, wie es eine aus einem Katalogverzeichnis gelesene Kopie tut.
Das Auslesen der Entität aus einem Paket ist der umgekehrte Schritt, und er identifiziert die Entität anhand dessen, was das Dokument ist, statt anhand seines Namens: das Dokument auf der obersten Ebene des Pakets, dessen kind: ein veröffentlichbarer Entitätstyp ist. Der Name der Entitätsdatei ist eine Konvention des Katalogs und kein Vertrag, sodass recipe.yaml das ist, was der Katalog der Standardbibliothek schreibt, und nicht das, was das Format verlangt, und eine neben der Entität mitgeführte Datei — ein Chart-Template, ein Compose-Fragment — nicht mit ihr verwechselt wird. Die Regel kann nicht umgekehrt funktionieren, ausgerichtet auf den Typ, den der Konsument sucht: Ein Typ wird aus der Entität gelesen, die sich im Paket befindet, sodass es in dem Moment, in dem das Paket geöffnet werden muss, keinen Typ gibt, an dem man sich ausrichten könnte. Die lesende Seite bricht ab, statt zu wählen, wenn die oberste Ebene eines Pakets zwei Entitätsdokumente enthält — das Paket, das ein anderer Client erzeugt, indem er ein ganzes Verzeichnis mit zwei Entitäten packt, und das dann unter jeder ihrer veröffentlichten Koordinaten als ein einziges Artefakt läge. Die Veröffentlichung dieses Produkts kann es nicht erzeugen, weil jede Entität nur mitführt, was sie deklariert, und die veröffentlichende Seite lehnt ein solches Verzeichnis zudem ab: Jeder Typ hat ein eigenes Verzeichnis außer Aggregate, Release und Manifest, und aggrega pin und aggrega push lehnen eine Entität jedes anderen Typs ab, neben der eine weitere Entität liegt, während ein Katalog-Ladevorgang, ein Lint und ein Build das Verzeichnis unangetastet lassen. Wie ein Verzeichnis heißt, wird auf keiner der beiden Seiten beurteilt: Das Layout <name>/<version>/ ist die Konvention des Katalogs der Standardbibliothek.
Eine veröffentlichte Entität wird über denselben Schritt gelesen. Eine Koordinate führt genau eine Kopie ihrer Entität mit, in der Form, die ihre Deklarationen ihr gegeben haben, und eine Person betrachtet sie mit aggrega inspect oci://<registry>/<repository>:<tag> statt über eine daneben veröffentlichte lesbare Kopie — es gibt also keine zweite Kopie, die von der abweichen könnte, die ein Build auflöst. Der Befehl entpackt ein Archiv nach der obigen Regel, liest die Entität eines Plugin aus seinem Manifest statt aus der mit ihm veröffentlichten ausführbaren Datei und stellt das Ergebnis so dar, wie eine Datei dieses Typs dargestellt wird; siehe Eine veröffentlichte Entität lesen.
Durchsuchbare Manifest-Annotationen. Jede Veröffentlichung versieht das OCI-Manifest des Artefakts mit einer kleinen Menge durchsuchbarer Annotationen, sodass ein Registry-Index oder ein Katalog-Browser Artefakte nach ihren Katalog-Metadaten filtern kann, ohne den Inhalt jeder Entität abzurufen und zu parsen. Jede Entität führt ihre menschenlesbare Beschreibung (die Standard-OCI-Beschreibungsannotation) sowie ihre Katalogkategorie und ihren Typ mit. Ein Plugin führt zusätzlich seinen Socket-Typ und die Capabilities mit, die es bedient. Diese Annotationen liest aggrega registry update in den lokalen durchsuchbaren Index zurück (§8).
Jede veröffentlichte Datei hat einen Namen. Jede Datei, die eine Veröffentlichung mitführt, wird im Manifest mit der Standardannotation org.opencontainers.image.title benannt, also mit dem Namen, unter dem ein generischer OCI-Client diese Datei schreibt, wenn er das Artefakt in ein Verzeichnis pullt. Der Name sagt, was die Datei ist, und ihre Erweiterung folgt dem Media Type der Datei:
| Was veröffentlicht wird | Die Datei, die ein generischer OCI-Client schreibt |
|---|---|
| eine als ihr Dokument veröffentlichte Entität | entity.yaml |
| eine mit den von ihr deklarierten Dateien veröffentlichte Entität | entity.tar.gz |
| ein Plugin | entity.yaml, die Entität, neben entity.wasm, ihrer ausführbaren Datei |
| eine an ein Artefakt angehängte Signatur | signature.json |
| eine an ein Artefakt angehängte Deprecation-Markierung | deprecation.json |
ein mit aggrega push-artifact veröffentlichtes Datenartefakt | der mit --name angegebene Name |
So legt oras pull hub.aggrega.ai/component/core/compute/server:1.0.0 -o ./server die veröffentlichte Entität unter ./server/entity.yaml ab, Byte für Byte so, wie sie veröffentlicht wurde. oras überspringt einen Deskriptor, der keinen Namen trägt, und meldet trotzdem Erfolg, weshalb jeder Deskriptor, den eine Veröffentlichung packt, einen trägt. Der Name wird allein aus dem Media Type abgeleitet, nie aus dem Namen der veröffentlichten Datei, sodass dieselben Bytes, aus einer anders benannten Datei veröffentlicht, dasselbe Manifest erzeugen. Eine mit ihren Dateien veröffentlichte Entität kommt als ihr Paket an: entity.tar.gz benennt das Paket, und die Entität darin wird nach der obigen Regel gefunden statt über einen Dateinamen. Die eigene Auflösung von Aggrega liest diese Namen nie — sie wählt jede Datei nach ihrem Media Type aus und vertraut ihr anhand ihres Digests —, sie sind also für jeden anderen Client da.
7. Die Recipe-Architektur: Pointer und Mapper
Siehe entities/recipe für die vollständige Authoring-Oberfläche des Recipe — source: (Pointer), valuesMapping: (Mapper, mit drei Authoring-Modi: Inline-Block-Scalar, Datei-$import:, Bibliotheks-$import: auf einen Eintrag einer MappingLibrary), Wasm-gesteuerte Quellschemas, native IaC-Unterstützung und durchgearbeitete Beispiele.
8. Die Standard-Registry und kontextabhängige Kurz-URIs
Um aufgeblähtes YAML zu vermeiden, löst der Compiler Kurz-URIs kontextabhängig anhand der Schemaposition auf, an der sie vorkommen. Die Standard-Registry wird in .aggrega-config.yaml konfiguriert (standardmäßig hub.aggrega.ai).
Ein Registry-Host hat genau eine Lesart. Jedes registries[].host wird als der Host selbst geschrieben — ein kleingeschriebener Hostname mit einem Punkt, localhost, ein einzelner Name gefolgt von einem Port, eine IPv4-Adresse oder eine IPv6-Adresse in eckigen Klammern, jeweils mit einem optionalen :port und ohne Schema, Pfad, Anmeldedaten oder Großbuchstaben —, weil diese Schreibweise der Schlüssel ist, unter dem jede registryspezifische Vertrauensrichtlinie gefunden wird, und die eingebaute Signaturanforderung des offiziellen Hubs an hub.aggrega.ai gebunden ist. default_registry benennt einen Host auf dieselbe Weise und darf ihm einen Repository-Pfad folgen lassen, etwa ghcr.io/acme: Alles, was über die Standard-Registry veröffentlicht wird, landet dann unter diesem Pfad, und jede Kurzreferenz wird darunter aufgelöst, während das Vertrauen weiterhin allein vom Host bestimmt wird. default_registry kann stattdessen als name: eines registries-Eintrags geschrieben werden und steht dann für den Host dieses Eintrags. Der Name wird einmal gelesen, während die Konfiguration aufgelöst wird, und zwar gegen die Einträge, die nach jeder Konfigurationsdatei und der Umgebung gelten, sodass jeder Leser der Standard-Registry — die Veröffentlichung, die Standortbindung, die Signaturprüfung und jede Vertrauensabfrage — den Host dieses einen Eintrags liest und keiner von ihnen einen Host erreicht, der wie der Name geschrieben ist; ein Name, dem ein Pfad folgt, wird abgelehnt, da ein Name für einen Eintrag und nicht für einen Ort steht. Ein Name wird vor einer Host-Schreibweise abgeglichen, und ein Name, den zwei Einträge tragen, wird als mehrdeutig abgelehnt. Dieselbe Lesart entscheidet drei Dinge, die ein Pull mit dem Host tut: den Registry-Standort, an den eine hostlose Katalogidentität gebunden wird, ob das abgerufene Artefakt überhaupt eine Registry benennt, deren Signatur geprüft wird, und gegen welche Vertrauensrichtlinie diese Prüfung läuft. Eine Schreibweise, die eine Registry erreichen könnte, während sie deren Richtlinie verfehlt — Großbuchstaben, ein expliziter HTTPS-Standardport, ein Schema, Anmeldedaten, ein Pfad am Host eines registries-Eintrags —, wird dort abgelehnt, wo sie konfiguriert ist, unter Nennung der zu schreibenden Schreibweise, und ebenso ein einzelner Name ohne Port, der keinen Eintrag benennt, denn das ist die Form des ersten Segments einer Katalogidentität und nicht die eines Hosts. Die Ablehnung gilt auf jeder Ebene, die den Wert setzen kann: in der Konfigurationsdatei, wo das Schema dieselbe Form als Pattern für jedes registries[].host angibt; in der Umgebungsvariable AGGREGA_DEFAULT_REGISTRY; und auf der Befehlszeile. Jeder Host, den eine Konfiguration benennen kann, ist also einer, dessen Artefakte unter der für ihn geschriebenen Richtlinie verifiziert werden. Der Host wird allein nach seiner Schreibweise beurteilt; ob der Name aufgelöst wird oder dort eine Registry antwortet, ist Laufzeitzustand, den der Compiler nie abruft. Konfiguration erläutert die akzeptierten Formen mit Beispielen.
Kurz-URIs werden kontextabhängig anhand des Manifest aufgelöst; die spezifischen Inferenzregeln finden Sie unter ../language-reference/entities/manifest.md §Kontextabhängige Kurz-URIs.
Registries verwalten
aggrega registry verwaltet die Registries, die der Workspace kennt, und ihre Richtlinie für das Signaturvertrauen. Die Identität einer Registry ist ihr Host; die Unterbefehle teilen sich ein Adressierungsmodell:
aggrega registry add <host>registriert eine Registry und pinnt ihre Vertrauensrichtlinie, wobei beim ersten Kontakt die von der Registry angebotene Richtlinie abgerufen wird, sofern nicht Vertrauens-Flags eine manuell angeben. Ein optionales--name <alias>hängt einen sprechenden Alias an denselben nach Host geschlüsselten Eintrag — der Host bleibt die Identität, und der Alias wird überall dort zu ihm aufgelöst, wo eine Registry benannt wird. Ein Alias ist über alle Registries hinweg eindeutig.aggrega registry listgibt jede konfigurierte Registry aus — Host, Alias, eine kurze Zusammenfassung der Vertrauenslage und eine Markierung an der Standard-Registry — in aufsteigender Host-Reihenfolge. Der Befehl liest die aufgelöste Konfiguration und greift auf kein Netzwerk zu.aggrega registry remove <name|host>entfernt den Vertrauensrichtlinien-Eintrag einer Registry, adressiert über ihren Host oder ihren Alias. Es entfernt nur die Vertrauensrichtlinie: Der Zeigerdefault_registrybleibt unangetastet und die Möglichkeit, zu diesem Host zu pushen, bleibt unberührt, sodass der Host auf das Standardvertrauen zurückfällt, statt unerreichbar zu werden. Eindefault_registry, das als Name des entfernten Eintrags geschrieben ist, benennt danach nichts mehr und wird abgelehnt, bis es neu geschrieben wird.aggrega registry updateaktualisiert den lokalen durchsuchbaren Index, der unten beschrieben wird.
Wo immer eine Registry benannt wird — ein Argument eines registry-Unterbefehls oder das Flag --registry bei aggrega push und aggrega push-artifact —, interpretiert derselbe Resolver das Token: Ein konfigurierter Alias wird zu seinem Host aufgelöst, und jedes andere Token wird als der Host gelesen, den es benennt, wobei Schema, Pfad und Anmeldedaten einer Referenz verworfen werden. Wo dieser Host zu etwas wird, gegen das eine Signaturentscheidung getroffen wird — das Ziel von aggrega push oder aggrega push-artifact oder der Schlüssel, unter dem aggrega registry add einen Eintrag schreibt —, wird er an die eine oben beschriebene Lesart gebunden und unter Nennung der zu schreibenden Schreibweise abgelehnt, wenn er nicht so geschrieben ist. Ein nicht registrierter Host, der so geschrieben ist, ist ein legitimes Ziel und wird akzeptiert.
Der lokale durchsuchbare Index
aggrega registry update [<name|host>] erstellt einen lokalen durchsuchbaren Index der Registries, die der Workspace kennt. Der Befehl durchläuft die Repositories jeder konfigurierten Registry, wählt jeweils die höchste veröffentlichte Version aus, liest die durchsuchbaren Manifest-Annotationen dieser Version (§6) und schreibt einen Index pro Registry in den Artefakt-Cache. Ohne Argument indiziert er jede konfigurierte Registry; mit einem einzelnen Registry-Argument (einem Host oder einem Alias) indiziert er nur diese.
Der Index folgt dem von Paketmanagern bekannten Modell der expliziten Aktualisierung: registry update ist der Befehl, der die Registries kontaktiert, und ein späteres aggrega search liest den geschriebenen Index offline. Die Datensatzdatei einer Registry ist deterministisch — zwei Aktualisierungen gegen denselben Registry-Zustand erzeugen byte-identische Bytes, und der Aktualitätszeitstempel liegt in einer benachbarten Datei, sodass er die Datensätze nie verändert. Ein Repository ohne veröffentlichte Version oder eines, das nicht gelesen werden kann, wird übersprungen, sodass ein einzelnes unlesbares Repository nie den gesamten Index scheitern lässt.
Der veröffentlichte Katalog-Snapshot
Jede Veröffentlichung des Katalogs der Standardbibliothek veröffentlicht auch den Katalog als Ganzes: ein einziges OCI-Artefakt, ein mit gzip komprimiertes Tar-Archiv aller Dateien, die der Katalogbaum bei dem Commit enthält, den diese Veröffentlichung veröffentlicht hat, unter catalog/snapshot in der Registry, in der der Katalog veröffentlicht wird — hub.aggrega.ai/catalog/snapshot für den offiziellen Hub. Es wird erst gepusht, nachdem jede Entität dieser Veröffentlichung in der Registry liegt, sodass es keine Entität nennt, die die Registry nicht enthält. Es wird mit dem Commit, aus dem es gebaut wurde, und mit latest getaggt, und es wird vom Herausgeber schlüssellos signiert, wie jede Entität der Veröffentlichung, sodass die Identität des Herausgebers es gemäß der Vertrauensrichtlinie der Registry verifiziert; latest wechselt erst dann auf einen Snapshot, wenn dieser signiert ist. Das Archiv wird in einem einzigen festen Layout geschrieben — Einträge in aufsteigender Reihenfolge ihrer Namen, jeweils mit demselben Modus, demselben Eigentümer und derselben Änderungszeit —, sodass ein Commit immer dasselbe Tar-Archiv ergibt.
Sein einziger Leser ist ein Import, dessen Workspace keinen Katalogordner nennt: kein workspace.catalog_dirs, kein AGGREGA_CATALOG_DIRS und kein Verzeichnis catalog/ im Stammverzeichnis des Workspace. aggrega import, der Import der Editor-Sitzung und das Import-Werkzeug des Assistenten führen dieselbe Operation aus, sodass jeder den Snapshot auf dieselbe Weise bezieht. Der Import ruft ihn aus der Standard-Registry des Workspace über dieselbe Egress-Kontrolle und dieselbe Anmeldung wie ein Pull ab, verifiziert seine Signatur gemäß der Vertrauensrichtlinie dieser Registry, bevor irgendetwas behalten wird, legt ihn im Artefakt-Cache des Workspace ab und liest ihn dort als Katalogordner, an seinen Digest gebunden — so werden dem Importer die Components des Katalogs angeboten, und --target entwirft ein Manifest aus seinen Recipes, auf genau dem Weg, den ein Katalogordner nimmt. Der Datensatz, den der Import neben seine Entwürfe schreibt, nennt den Snapshot über seinen Manifest-Digest, sodass ein späterer Import derselben Entwürfe denselben Katalog ohne Anfrage liest, und aggrega import --upgrade ruft den neuesten Snapshot ab und importiert von da an gegen ihn. Im Offline-Modus bricht ein Import, der einen Snapshot abrufen müsste, ab und nennt, was auszuführen ist. Ein Workspace, der einen Katalogordner nennt, importiert gegen diesen und ruft keinen Snapshot ab. Kein anderer Befehl liest den Snapshot: Ein Pull, ein Build und eine Validierung lösen jede Entität über die Stufen aus §5 auf und pinnen sie im Lockfile, und die Entwürfe eines Imports referenzieren Katalogentitäten über ihren Namen, sodass ihr Bauen diese Entitäten auf dieselbe Weise auflöst.
9. Lockfile-Pinning und Unveränderlichkeit von Artefakten
Die Disziplin des Lockfile-Pinnings verankert jede Abhängigkeit an einem bestimmten inhaltsadressierbaren Artefakt. Bei der ersten Lockfile-Auflösung (aggrega pull) befragt der Resolver die Registry, wählt eine Version gemäß der dreiförmigen Einschränkung der URI (exakt / Bereich / unversioniert) und schreibt die gepinnte Version + den Digest in die <release-stem>.lock des Release. Nachfolgende Aufrufe von aggrega build verwenden die gepinnten Werte unabhängig von der Veränderlichkeit der Registry; neue Versionen können veröffentlicht werden, ohne das bestehende Lockfile zu beeinflussen.
Das Pinning-Modell trägt eine tragende Regel: Sobald ein name:version in einer Registry veröffentlicht ist und zum Digest D aufgelöst wird, ist diese Zuordnung dauerhaft. Das erneute Veröffentlichen desselben name:version mit anderem Inhalt wird beim Push abgelehnt. aggrega push selbst erzwingt dies bei jeder Veröffentlichung: Es löst das vorhandene Artefakt unter name:version in der Ziel-Registry auf; ist es vorhanden und stimmt der Digest mit dem Inhalt überein, der gepusht werden soll, lädt der Push nichts hoch und hängt nur an, was dieser Veröffentlichung noch fehlt — ihr Veröffentlichungsdatum und ihre Signatur, wo der Push signiert; ist es vorhanden und weicht der Digest ab, bricht der Push mit einem Unveränderlichkeitsverletzungs-Fehler ab, der beide Digests nennt.
Unveränderlichkeit ist wegen zweier Konsequenzen wichtig:
- Lockfile-Pins sind ehrlich. Wenn das Lockfile
mariadb:1.0.0mit dem DigestDfesthält, erhält ein Build, der per Digest abruft, die Bytes vonD. Ohne Unveränderlichkeit könnte eine Änderung auf Registry-Seite die Bytes vonDunter dem Lockfile-Pin austauschen und so die Stabilität vom Lock-Zeitpunkt bis zum Build-Zeitpunkt untergraben. Reproduzierbare Builds beruhen auf dieser Garantie. - Metadatenänderungen nach der Veröffentlichung haben einen klaren Weg. Eine veröffentlichte Version als veraltet zu markieren, Signaturschlüssel zu rotieren oder Attestierungen zu ergänzen, kann nicht durch Ändern des veröffentlichten Artefakts geschehen (die Regel verbietet es). Es muss durch Veröffentlichen einer neuen Patch-Version oder eines Sidecar-Artefakts geschehen, das die Metadatenänderung separat festhält. Beide Wege sind nachvollziehbar — eine neue Version oder ein Sidecar erscheint als eigener Registry-Eintrag —, und keiner verändert die Bytes des ursprünglichen Artefakts.
Die Unveränderlichkeitsregel gilt einheitlich für jedes über OCI veröffentlichte Aggrega-Artefakt (Entitäten, SchemaLibrary, MappingLibrary, Wasm-Plugins, die über pipeline[].plugin: eines Recipe / pipeline[].plugin: eines FeatureRecipe / plugins.{governance,linter,importer}[]: der Workspace-Konfiguration referenziert werden). Alles, was über name:version plus einen Inhalts-Digest im Lockfile gepinnt ist, unterliegt der Unveränderlichkeit.
Die Unveränderlichkeit ist bedingungslos, und keine Konfiguration lockert sie. Es gibt kein Flag und keine Einstellung der Workspace-Konfiguration, die ein Überschreiben erlaubt, weil die Registry keinen Überschreibungspfad bereitstellt, den ein Betreiber aktivieren könnte. Geänderter Inhalt wird unter einer neuen Version veröffentlicht, und aggrega lint --pre-publish prüft, ob die Versionserhöhung zur Klassifizierung der Änderung passt.
Die erneute Auflösung zu einer neueren Version erfordert eine ausdrückliche Aktion des Benutzers: aggrega pull --upgrade --release <release> <uri> löst eine einzelne Abhängigkeit neu auf und hält dabei jeden anderen Pin fest, und aggrega pull --upgrade --release <release> löst alle Abhängigkeiten gegen den aktuellen Registry-Zustand neu auf. Abhängigkeiten in Bereichsform und in unversionierter Form werden zur neuesten passenden Version neu aufgelöst; Pins in exakter Form bewegen sich nicht, sofern der Benutzer nicht ausdrücklich auf eine andere exakte Version aktualisiert. Das Lockfile ist die maßgebliche Quelle für Builds; die vom Benutzer eingegebene Form drückt die Versionseinschränkung zum Authoring-Zeitpunkt aus.
10. Durchsetzung der Namensform von Katalogentitäten
Namen von Katalogentitäten folgen Patterns pro Entitätstyp — unten aufgezählt und pro Typ in der Übersicht der Entitätsreferenz ausführlich beschrieben. Sie sind eine andere Oberfläche als die Instanznamen, die ein Entwickler in ein Aggregate oder ein Release schreibt und die unabhängig vom Typ ein gemeinsames Pattern haben; dieses Pattern steht unter ../language-reference/02-naming-conventions.md „Instanznamen“. Das Feld metadata.name, das ein Katalog-YAML deklariert, ist nicht immer identisch mit der kanonischen Referenz-URI der Entität: Component und Feature betten Publisher- und Gruppierungssegmente direkt in metadata.name ein; Recipe und FeatureRecipe deklarieren ein metadata.name, das nur aus dem Blatt besteht, und ihre kanonische zweisegmentige URI kombiniert dieses Blatt mit der spec.capability, die die Entität deklariert; jeder Bibliothekstyp deklariert ein PascalCase-Token in metadata.name.
Formen pro Entitätstyp:
- Component — drei Kebab-Case-Segmente
{publisher}/{category}/{name}, deklariert inmetadata.name. Beispiel:core/datastore/postgres. - Feature — zwei Kebab-Case-Segmente
{publisher}/{name}, deklariert inmetadata.name. Beispiel:core/data-masking. - Recipe — ein einzelnes Kebab-Case-Blatt in
metadata.name(z. B.postgres). Die kanonische Referenz-URI{capability}/{name}(gemäß §6 oben) kombiniert die deklariertespec.capabilityder Entität mit diesem Blatt; das führende Segment wird mitspec.capabilityabgeglichen, nicht mit dem Speicherort der Entität auf der Festplatte, sodass das Verschieben einerrecipe.yamlnicht ändert, wie sie referenziert wird. Der Katalog der Standardbibliothek legt die Entität unter<catalog-root>/recipe/<capability>/<name>/<version>/recipe.yamlab, sodass der Baum die Koordinate spiegelt, doch diese Spiegelung ist eine Konvention des Katalogs und nicht die Quelle der URI. Eine Referenz kann das Rezept auch ohne Präfix benennen — nur das Blatt, ohne Capability-Segment —, was in der Praxis die vorherrschende Form ist und immer dann aufgelöst wird, wenn ein einziges Rezept im Katalog den Namen trägt. In einer Recipe-URI erscheint kein Publisher-Segment, und eine Referenz mit einem dritten Segment passt auf kein Rezept. - FeatureRecipe — ein einzelnes Kebab-Case-Blatt in
metadata.name(z. B.k8s-secret-from-parameter), symmetrisch zum Recipe: kanonische URI{capability}/{name}aus der deklariertenspec.capabilityplus dem Blatt, das Blatt ohne Präfix wird auf dieselbe Weise akzeptiert, und der Baum<catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yamlspiegelt die Koordinate per Konvention. - Die Bibliothekstypen — SchemaLibrary, MappingLibrary, WorkloadLibrary und ArtifactLibrary — ein einzelnes PascalCase-Token in
metadata.name, das auf^[A-Z][A-Za-z0-9]*$passt (z. B.BaseComponents,AIDatastores,BaseWorkloads). Die Form ist bei jedem Bibliothekstyp dieselbe, sodass das Verschieben eines Eintrags zwischen Bibliotheken nie eine Umbenennung nach einer anderen Konvention bedeutet. Der JSON-Schema-Umschlag jedes Bibliothekstyps deklariert das Pattern ebenfalls, zusätzlich zu der unten beschriebenen Prüfung.
Für Component, Feature, Recipe und FeatureRecipe akzeptiert das JSON Schema für metadata.name jede nicht leere Zeichenkette, sodass für diese Typen nichts an der Form strukturell ist. Jede dokumentierte Form — einschließlich der Bibliothekstypen, deren Umschläge ihr Pattern ebenfalls deklarieren — wird vom Plugin für die Veröffentlichungsdisziplin geprüft, das die Patterns als Regex-Quelle der Wahrheit mitführt, die mit der Compiler-Distribution geteilt wird. Keinem Typ wird hier eine Form gegeben, die das Plugin dann ignoriert.
Die Prüfung ist optional: Ein einziger Befehl führt sie durch, und er läuft nur, wenn ein Autor sie anfordert. Die beiden Befehle, von denen man am häufigsten annimmt, dass sie sie durchführen, tun es nicht:
aggrega lintmeldet Verstöße gegen die Namensform. Das Plugin vergleicht dasmetadata.namejeder Entität mit dem Pattern für ihren Typ. Die Prüfung läuft, wenn ein Autoraggrega lintaufruft — für eine einzelne Entität, für die Abhängigkeitshülle eines Release mit--releaseoder für jede Katalogentität, wenn der Befehl ohne Argument aufgerufen wird —, und derselbe Regelsatz ist über die editorseitige Werkzeugoberfläche erreichbar, die die CLI bereitstellt. Die Befunde sind beratend: Sie werden mit dem Schweregradwarngemeldet und führen nicht zum Abbruch.
warn: E0278 name-shape: metadata.name "mariadbSynth" does not match the documented pattern for Recipe entities (^[a-z][a-z0-9-]*$)Der Befund beginnt mit seinem Schweregrad und dem Kurzcode, unter dem seine Regel registriert ist und den aggrega explain E0278 erläutert. Der Pfad der betroffenen Datei wird über dem Befund ausgegeben, und ein Lauf über den gesamten Katalog schließt mit einer Zählung der geprüften Entitäten und der erhobenen beratenden Befunde.
aggrega buildprüft die Namensform nicht. Die gerenderte Ausgabe hängt nicht von Aggrega-Entitätsnamen ab, daher gibt ein Build über einen Katalog mit nicht konformen Namen weder eine Warnung noch eine Diagnose aus und ist genau so erfolgreich, wie er es sonst wäre.- Auch
aggrega pushprüft die Namensform nicht. Die Veröffentlichung lehnt aus anderen Gründen ab — vor allem wegen der obigen Unveränderlichkeitsregel, nach der das erneute Veröffentlichen eines vorhandenenname:versionmit anderem Inhalt abbricht. Wo eine Ablehnungaggrega lint --pre-publishnennt, teilt sie dem Autor mit, welchen Befehl er ausführen soll; der Push führt ihn nicht aus.
Da weder das Bauen noch das Veröffentlichen die Form prüft, führt ein Katalog, der die Einhaltung der Konvention wünscht, aggrega lint bewusst aus — in einem Pre-Commit-Hook oder als Pipeline-Schritt. Beachten Sie, dass ein Befund zur Namensform beratend ist: aggrega lint meldet ihn und endet trotzdem erfolgreich, sodass eine Pipeline, die die Konvention als Schranke nutzen will, die gemeldeten Befunde liest, statt sich auf den Exit-Status zu verlassen.
Eine Richtlinie pro Workspace unterdrückt die Regel:
# .aggrega-config.yaml — lint sectionlint: publishing_discipline: allow_nonstandard_names: true # default falseIst die Richtlinie gesetzt, meldet die Namensform-Regel überhaupt nichts. Sie kann auch für einen einzelnen Aufruf mit aggrega lint --allow-nonstandard-names gesetzt oder mit --no-allow-nonstandard-names wieder zwangsweise abgeschaltet werden. Legitime Verwendungen sind Kataloge, die nie veröffentlicht werden, Experimente mit mehreren Publishern und Entitäten für Sonderzwecke.
11. Annotationsgesteuerte Feature-Expansion
Der Block mappings.features.annotations des Manifest deklariert Bindungen zwischen Annotationsschlüsseln und Feature-Typen sowie eine nach Säulen gruppierte Routing-Tabelle (maps.infra, maps.values), die die Eigenschaften des Feature-Schemas benennt, die jede Annotation befüllen darf. Die Teilphase der Annotationsexpansion innerhalb der Auflösung durchläuft Release-Grenzen von außen nach innen und Aggregate-Subsysteme von außen nach innen, berechnet die effektiven Annotationsmengen pro Komponente über Kaskade und Überschreibung mit Null-Opt-out für den gesamten Wert und pro Unterschlüssel und fügt synthetische Feature-Anbindungen ein, die in ihrer IR-Provenienz origin: annotation tragen. Die vollständige Darstellung der Bindungsform und des Authorings findet sich unter language-reference/entities/manifest.md und language-reference/providers/well-known-annotations.md; dieser Abschnitt dokumentiert die Mechanismen zur Katalog-Ladezeit und zur Inspect-Zeit, auf die sich der Expansionspfad stützt.
Schema-Kompilier-Cache. Das spec.schema.{infra,values} jedes Feature wird einmal pro Build kompiliert und über Kaskadendurchläufe hinweg wiederverwendet. Wiederholte Typvalidierung pro Unterschlüssel gegen dasselbe Feature-Schema (ein Kaskadenbereich pro Komponente, bei Hunderten von Komponenten) liest das kompilierte Schema, statt es erneut zu kompilieren. Zwischen Builds wird nichts aufbewahrt, sodass ein geändertes Feature-Schema vom nächsten Build neu kompiliert wird.
Validierung der Bindungsziele (Katalog-Laden). Beim Laden des Katalogs durchläuft der Compiler jede features.annotations-Bindung des Manifest und prüft, ob jeder unter maps.infra und maps.values deklarierte Punktpfad einer Eigenschaft entspricht, die spec.schema.<pillar> des referenzierten Feature tatsächlich deklariert. Eine Bindung, die zu einem Pfad routet, den das Feature-Schema nicht auflistet, bricht das Laden des Katalogs mit einem klaren OPS_ERROR ab, der den Bindungsschlüssel, den fehlenden Pfad, die Feature-URI und den Quellort nennt.
Lint für Schema-Säulen-Überschneidungen (Katalog-Laden). Eine beratende Warnung wird ausgelöst, wenn das spec.schema eines Feature denselben Eigenschaftsnamen in beiden Säulen infra und values deklariert. Die Überschneidung ist selten beabsichtigt — gleichnamige Eigenschaften in verschiedenen Säulen verwischen die Authoring-Absicht (welche Säule greift, wenn eine Annotation auf den gemeinsamen Namen zielt?) und verkomplizieren Diagnosemeldungen. Die Warnung blockiert nicht und hat kein Opt-out: Ein Autor, der die Überschneidung beabsichtigt, behält sie samt Warnung, und einer, der sie nicht beabsichtigt, benennt die Eigenschaft in einer Säule um.
Lint für Überschneidungen der Bindungs-Maps (Auflösung). Eine beratende Warnung wird ausgelöst, wenn ein Unterschlüsselpfad in den Bindungen des Manifest sowohl unter maps.infra als auch unter maps.values erscheint. Ein Pfad, der in beiden Säulenlisten erscheint, ist inkohärent — ein einzelner Annotations-Unterschlüssel kann nicht gleichzeitig zu beiden Säulen routen, und der deterministische Tie-Break, den der Compiler anwendet (ein Pfad in beiden Listen routet zu infra; eine im Aggregate geschriebene Annotation darf nur über values routen, sodass eine dort für diesen Pfad geschriebene abgewiesen wird), ist ein Sicherheitsnetz, keine beabsichtigte Authoring-Form. Die Warnung blockiert nicht; Autoren, die die Warnung ignorieren, erhalten trotzdem einen sauberen Build, wobei der Tie-Break in der IR-Provenienz sichtbar ist.
Provenienz-Darstellung in aggrega inspect. Der Befehl inspect stellt pro Feature-Anbindung eine Klammer dar, die die Quelle jedes befüllten Blatts festhält:
[explicit]— das Feature wurde explizit über einenfeatures:-Block eines Aggregate oder Release angebunden.[annotation: <key> from <source>]— jedes befüllte Blatt stammt aus demselben Annotationsschlüssel. Die Klammer nennt den Schlüssel und den Ort, an dem die Annotation deklariert wurde: die Datei und den gepunkteten Schlüsselpfad darin.- Klammern pro Blatt — seitenübergreifende Komposition, bei der jedes befüllte Blatt mit seiner eigenen Quellklammer dargestellt wird (einige
[explicit], einige[annotation: <key> from <source>]). Diese Form macht den Merge sichtbar, bei dem pro Feld das Explizite gewinnt: Wenn eine explizite Anbindung und ein Annotationsbeitrag auf dieselbe Feature-Instanz an derselben Component zielen, aber unterschiedliche Blätter schreiben, bleiben beide Beiträge auf ihren jeweiligen Blättern bestehen, und die Inspect-Ausgabe nennt die Quelle jedes Blatts einzeln.
Die Inspect-Darstellung liest die säulenspezifischen Maps values_provenance und infra_provenance der IR — die während der Annotationsexpansion zusammen mit dem Einfügen der synthetischen Anbindungen befüllt werden — und gibt die Klammerform aus, die die gemeinsame Quelle der Blätter am besten zusammenfasst. Der Inspect-Mechanismus ist die kanonische Introspektionsoberfläche, um zu verstehen, warum eine bestimmte Feature-Anbindung auf einer bestimmten Component gelandet ist und woher ihre Werte stammen.