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

Gesellschaftsverträge

Aggrega ist absichtlich ein meinungsloser Compiler. Gemäß den grundlegenden Invarianten, die in architecture/05-invariants.md dokumentiert sind, parst der Compiler YAML, durchläuft Graphen, wertet Label-Schnittmengen aus und leitet Strings zwischen Komponenten weiter — aber er überwacht nicht, was Entwickler in values, parameters, infra, provides oder locals schreiben; er setzt weder Benennungskonventionen noch Port-Konventionen noch die semantischen Labels durch, die ein Architekt erfindet; er errät den Zweck einer Komponente nicht aus Namen. Viele Disziplinen, die wie Compiler-Regeln klingen, sind tatsächlich Gesellschaftsverträge: Best Practices, die durch eine Authoring-Konvention statt durch Schema- oder Laufzeitdurchsetzung aufrechterhalten werden.

Wo diese Neutralität endet, verdient es, klar gesagt zu werden, denn es ist eine einzige Linie, und sie wird leicht überinterpretiert. Einige Schlüssel gehören Aggrega selbst — reserviert, mit den Werten, die sie annehmen, im veröffentlichten Schema festgeschrieben —, und diese prüft das Schema tatsächlich, so wie es jedes andere deklarierte Feld prüft. Die Wertemenge eines Schlüssels zu deklarieren, den die Plattform selbst definiert, bedeutet nicht, dass der Compiler eine Bedeutung in das hineinliest, was Sie geschrieben haben; es ist die Plattform, die sagt, was ihr eigener Schlüssel bedeutet. Alles, was Sie unter einem eigenen Schlüssel schreiben, bleibt genau so unüberwacht, wie diese Seite es beschreibt.

Diese Seite ist das kanonische Inventar der Gesellschaftsverträge der Sprache. Autoren, die diese Gesellschaftsverträge auf dieser Seite kennenlernen, können nachvollziehen, warum der Compiler einen gemäß Konvention fehlerhaften Build akzeptiert (er tut es — der Compiler interpretiert die Konvention nicht) und wo die Verantwortung dafür liegt, die Verletzung zu erkennen (Authoring-Disziplin, Aufmerksamkeit der Reviewer oder ein Linter-Plugin, das von aggrega lint ausgeführt wird).

Drei Klassen von Disziplin

Die Disziplinen von Aggrega teilen sich in drei Klassen, je nachdem, wie die Disziplin durchgesetzt wird. Die Einteilung ist wichtig, weil jede Klasse einen anderen Fehlermodus hat, wenn die Disziplin verletzt wird.

Durch das Schema durchgesetzt

Die Disziplin wird durch die Validierung mit JSON Schema 2020-12 beim Laden durchgesetzt (das JSON Schema der Entitätshülle sowie die Deklarationen schema: auf Säulenebene in Component- und Feature-Entitäten). Ein Verstoß erzeugt einen fatalen Abbruch, bevor der Build fortschreitet; der Compiler verweigert die Fortsetzung. Autoren, die versuchen, eine durch das Schema durchgesetzte Disziplin zu verletzen, sehen einen expliziten Validierungsfehler, der auf das Feld und die Einschränkung verweist.

Beispiele: die Pflichtfelder der Entitätshülle (apiVersion / kind / metadata.name / metadata.version); der SemVer-Regex auf metadata.version; die geschlossene Wertemenge des reservierten Labels component.aggrega.ai/type; das mechanische Verbot von Blöcken values: im Release-Schema (gemäß Invariante 5); die Ablehnung von extends zusammen mit aggregate im Release (die Invariante der einzigen Quelle der Wahrheit); die Formregeln des Recipe, die den Kompositionsvertrag der Eingabearten durchsetzen.

Durch das Schema durchgesetzte Disziplinen sind die stärksten Garantien, die die Sprache bietet. Der Compiler verweigert das Rendern von allem, was gegen sie verstößt.

Durch ein Policy-Plugin durchgesetzt

Die Disziplin wird durch ein Wasm-Plugin durchgesetzt, das an einem der dokumentierten Socket-Punkte läuft (die Governance-Rolle label-transform beim Aufbau der Topologie; die Governance-Rolle ir-verdict bei der statischen Analyse; der Out-of-Band-Linter-Socket). Ein Verstoß erzeugt je nach Gating-Semantik des Sockets entweder einen Policy-Fehler, der den Build abbricht (In-Band-Sockets), oder eine beratende Warnung (Out-of-Band-Sockets).

Eine Disziplin wird nur dort auf diese Weise durchgesetzt, wo ein Plugin läuft, das sie prüft: Die Wasm-Laufzeit ruft Plugins an den dokumentierten Socket-Punkten auf, und eine Disziplin, die kein Plugin prüft, bleibt eine Konvention. Der Veröffentlichungs-Linter, den aggrega lint ausführt, prüft einen Teil einer Konvention auf dieser Seite — siehe Konventionen, die eine Linter-Regel prüft. Keine Regel des Veröffentlichungs-Linters prüft die Hermetizität (die Sprig-FuncMap stellt Helfer bereit, die die deterministische Ausgabe brechen, gemäß dem Vorbehalt zum Determinismus in templates/sprig-functions.md) oder die Benennung von Cloud-Ressourcen (Recipes, deren Ausgaben von valuesMapping: auf Felder für Cloud-Ressourcennamen ohne Interpolation von release_name / instance_id verweisen, gemäß entities/recipe.md „Cloud-resource naming discipline (Benennungsdisziplin für Cloud-Ressourcen)“); ein eigenes Linter-Plugin kann beides prüfen.

Zur Vertragsoberfläche der Wasm-Plugins und zum Platzierungskriterium (der Linter-Socket gegenüber den Verdikt-Rollen der Governance) siehe plugins/plugin-contract.md.

Durch Konvention aufrechterhalten

Die Disziplin wird ausschließlich durch Authoring-Disziplin und die Aufmerksamkeit der Reviewer aufrechterhalten. Der Compiler setzt sie nicht durch; kein Schema lehnt den Verstoß ab; kein Wasm-Plugin meldet ihn. Autoren lernen die Disziplin aus der Dokumentation, befolgen sie, weil die architektonische Form von ihr abhängt, und verlassen sich auf das PR-Review, um Versäumnisse zu erkennen. Ein Verstoß erzeugt kein Signal zur Compile-Zeit — der Build gelingt, die gerenderte Ausgabe funktioniert, soweit der Compiler es weiß, und der Disziplinverstoß tritt erst zutage, wenn nachgelagerte Werkzeuge oder das Laufzeitverhalten von der Konvention abhängen.

Durch Konvention aufrechterhaltene Disziplinen sind die tragende Liste, die Autoren aus der Dokumentation lernen müssen. Der Compiler interpretiert sie nicht; sie falsch umzusetzen, bricht den Build nicht, aber es bricht die architektonische Form, von der Aggrega abhängt. Der Großteil dieser Seite dokumentiert sie.

Die Konventionen

Die folgenden Gesellschaftsverträge werden durch Konvention aufrechterhalten. Jeder Eintrag nennt die Disziplin, die Oberfläche, auf der die Konvention dokumentiert ist, und den Fehlermodus bei einem Verstoß. Jeder behält seine Nummer, wo immer er steht: Gesellschaftsvertrag 3, die Disziplin der reservierten Präfixe, wird für Annotationsschlüssel von einer Linter-Regel geprüft und ist unter Konventionen, die eine Linter-Regel prüft beschrieben.

1. Den passenden operativen Typ für die Komponente wählen

Das reservierte Label component.aggrega.ai/type benennt, welche Art von Ding eine Komponente ist, aus einer geschlossenen Menge universeller Cloud-Primitive: server, worker, task, function, stateful-server, resource. Die Zugehörigkeit zu dieser Menge wird durch das Schema durchgesetzt, nicht durch Konvention aufrechterhalten. Aggrega definiert diesen Schlüssel und die Werte, die er akzeptiert, das Component-Schema zählt sie auf, und ein Dokument mit einem anderen Wert wird beim Laden abgelehnt — E0215, die Bedingung entity-envelope-invalid, nennt das Label und listet die Werte auf, die es annimmt. Diese Ablehnung ist das, was dieser Eintrag nicht abdeckt.

Was Konvention bleibt, ist, welcher der Werte zu der Komponente vor Ihnen passt. Nichts prüft, dass eine relationale Datenbank mit stateful-server statt server gelabelt ist oder dass ein Queue-Consumer worker statt task ist; der Selektor wertet jeden Wert aus, den er findet, ohne ihm eine Bedeutung beizumessen. Der Architekt, der eine Component verfasst, wählt den Wert, der beschreibt, wie die Infrastruktur sie behandeln muss, und nachgelagerte Selektoren, Policy-Plugins und Wasm-Rendering-Plugins verlassen sich alle darauf, dass diese Wahl ehrlich ist.

Klassifizierung auf einer eigenen Achse. Die geschlossene Menge regelt nur diesen einen reservierten Schlüssel und nichts anderes. Ein Katalog, der eine Klassifizierung benötigt, die Aggrega nicht definiert — eine Ebene, eine Datenzone, eine Serviceklasse oder eine feinere Aufteilung der operativen Primitive —, fügt einen eigenen Label-Schlüssel neben dem reservierten hinzu. Das Component-Schema akzeptiert jeden weiteren Label-Schlüssel mit einem String-Wert, und dieselbe Selektor-Mechanik liest ihn, sodass acme.aggrega.ai/storage-tier: oltp neben component.aggrega.ai/type: stateful-server steht und das appliesTo eines Feature oder der selector eines Sockets auf beide zielen kann. Die Erweiterung erfolgt über einen eigenen Schlüssel, nie über einen Wert innerhalb des Schlüssels von Aggrega.

Dokumentiert in: architecture/02-ecosystem-philosophy.md (die operative Ontologie) + labels-and-annotations.md (Präfixdisziplin) + errors/sentinels.md (E0215).

Fehlermodus: Ein Wert aus der Menge, der nicht zur Komponente passt, führt alles in die Irre, was das Label liest. Ein Datenspeicher mit dem Label server wird von einem Feature oder einem Socket abgelehnt, das stateful-server selektiert — ein Abbruch, der den Selektor nennt, nicht das falsche Label —, und ein Policy-Plugin oder ein Rendering-Plugin, das das Label liest, behandelt ihn als zustandslose Rechenleistung. Wo nur solche Leser ihn sehen, gelingt der Build; der Fehler tritt erst zutage, wenn die gerenderten Artefakte den Cluster erreichen.

2. Trennung von .context.annotations.* in drei Buckets

Kaskadierte Annotationen landen in drei benannten Buckets — .context.annotations.release, .context.annotations.catalog, .context.annotations.aggregate —, von denen jeder eine andere Absicht trägt. Das Ziel der Disziplin: release ist „wo diese Komponente läuft, verwaltet von Ops“; catalog ist „was diese Komponente ist, verfasst vom Architekten“; aggregate ist „was diese Komponente tut, verfasst vom Entwickler“.

Der Compiler setzt die Grenzen zwischen den Buckets nicht durch. Die drei Buckets teilen eine flache Form string → string; das Template eines Recipe kann alle drei lesen, und nichts verhindert, dass eine Annotation einer Release-Boundary als kognitive Metadaten interpretiert oder eine Katalog-Annotation in infra: geleitet wird. Die Trennung wird von Autoren aufrechterhalten, die Annotationen in den richtigen Bucket schreiben, und von Reviewern, die Lecks zwischen Buckets erkennen.

Dokumentiert in: labels-and-annotations.md (Die Drei-Bucket-Trennung ist ein Gesellschaftsvertrag).

Fehlermodus: Routing-Logik, die von der Unterscheidung der Bucket-Absichten abhängt (z. B. ein Recipe, das .context.annotations.release.aggrega.ai/region in ein Terraform-Feld region leitet), verbraucht stillschweigend jede Annotation, die im Bucket erscheint, unabhängig von der Authoring-Absicht. Der Build gelingt; die gerenderte Ausgabe kann semantisch falsche Werte enthalten.

4. Abgeschlossenheit von provides: im Recipe

Die Templates provides: eines Recipe schließen nur über die eigenen Daten des Knotens — .values, .infra, .context.instance_id, .context.rendered_name, wo der Provider des Knotens einen meldet, die aufgelösten .locals des Knotens sowie statische Strings. Verweise auf .context.inject und .context.uses sind verboten, weil die provides-Auswertung diese Templates in beliebiger Reihenfolge ausführt; das Lesen knotenübergreifender Daten würde sie an die topologische Iterationsreihenfolge koppeln, die das Design bewusst vermeidet. .locals gehört zur Oberfläche, statt außerhalb zu liegen: Die locals des Knotens werden in der Präambel derselben Stufe vor seinen provides aufgelöst, und sie sind knotenlokal, sodass ihr Lesen in Bezug auf die Reihenfolge nichts kostet. Einen Schlüssel zu nennen, den der locals-Block nicht deklariert, führt zum Abbruch.

Dies ist eine Regel mit zwei Hälften, von denen jede nennt, wo sie geprüft wird. Der Compiler prüft die erste: Die provides-Auswertung prüft jedes Template gegen eine positive Allowlist der Wurzeln, die sein Kontext definiert, bevor das Template ausgeführt wird, sodass ein Lesen von .context.inject / .context.uses mit einem expliziten Fehler abbricht, statt leer zu rendern; die Regel ist auch in templates/expansion-matrix.md, Zeile 6, dokumentiert. Die Konvention hält die zweite aufrecht: Das umfassendere Muster (provides-is-public; locals-is-private) ist in der Konvention verankert.

Dokumentiert in: templates/expansion-matrix.md Zeile 6 + vocabulary/data-pillars.md „provides: and locals: — public face vs private face (provides: und locals: — öffentliches Gesicht vs. privates Gesicht)“.

Fehlermodus: Der Compiler erkennt die verbotenen Verweise und bricht den Build zur Zeit der Template-Auswertung ab, wenn sie direkt in provides: erscheinen. Die umfassendere Disziplin öffentlich gegenüber privat (keinen internen Zustand über Schlüssel von provides: offenlegen) ist reine Konvention — Autoren, die provides: als Recipe-internen Namensraum behandeln, erzeugen Verträge, von denen Aufrufer abhängen; ein Refactoring wird zu einer Breaking Change.

5. Determinismus — nicht-hermetische Helfer in Templates des Render-Pfads

Die Invariante der deterministischen Ausgabe von Aggrega (Invariante 8 in architecture/05-invariants.md) verlangt byteidentische Ausgabe für byteidentische Eingabe. Die vollständige FuncMap von Sprig stellt Helfer bereit, die Umgebungszustand lesen (Leser der Uhrzeit now / date; Zufallsgeneratoren randAlpha / uuidv4; Leser der Umgebungsvariablen env / expandenv; Netzwerkauflöser getHostByName). Autoren, die diese Helfer aus einem Template aufrufen, das zur gerenderten Ausgabe beiträgt, brechen den Determinismusvertrag.

Der Compiler erkennt und blockiert die Verwendung nicht-hermetischer Helfer nicht. Die Sprig-FuncMap stellt sie gemäß templates/sprig-functions.md „Determinism caveat (Vorbehalt zum Determinismus)“ bereit; die Disziplin wird von Autoren aufrechterhalten, die diese Helfer in Templates des Render-Pfads vermeiden, und von Reviewern, die ihre Verwendung im PR-Review erkennen.

Dokumentiert in: templates/sprig-functions.md „Determinism caveat (Vorbehalt zum Determinismus)“.

Fehlermodus: Die Build-Ausgabe unterscheidet sich zwischen Läufen derselben Eingabe. Die Abweichung tritt zur Zeit des GitOps-Diffs zutage, wenn nachgelagerte Werkzeuge (ArgoCD, Flux) eine unerwartete Drift zwischen der committeten Manifestdatei und dem Clusterzustand sehen, oder zur Zeit eines Audits, wenn zwei Kompilierungen derselben Eingabe unterschiedliche Artefakte erzeugen.

Keine Regel des Veröffentlichungs-Linters prüft Templates auf Aufrufe nicht-hermetischer Helfer. Der Name des Helfers steht im Template, sodass ein eigenes Linter-Plugin ihn finden kann (siehe Konventionen, die eine Linter-Regel prüft).

6. Säulengrenzen (Wegweiser, keine Mauern)

Säulengrenzen sind Authoring-Disziplin, keine Durchsetzung durch die Sprache. Die Template-Engine erlaubt säulenübergreifende Lesezugriffe an jeder Stelle, sofern sie nicht ausdrücklich durch Abgeschlossenheitsregeln verboten sind (z. B. provides: und source: eines Recipe, die .context.inject / .context.uses lesen). Autoren sollten:

  • .values für die kognitive Nutzlast lesen (vom Entwickler verfasste Absicht).
  • .infra für die physische Dimensionierung lesen (von Ops verfasste Dimensionierung).
  • .context.uses.<alias>.provides.<key> für komponentenübergreifende Zeiger-Strings lesen.
  • .context.inject für die Zustellungs-Pipe nach der Hydration lesen.

Die Template-Engine kontrolliert den Lesezugriff nicht. Ein Recipe-Template, das .infra.replicas liest, um ein Feld values: zu steuern, funktioniert; nichts verhindert den säulenübergreifenden Weg. Das Ziel der Disziplin sind Wegweiser — die Grenzen beschreiben die Authoring-Absicht (wem die Daten gehören), nicht eine Einschränkung zur Laufzeit.

Dokumentiert in: vocabulary/data-pillars.md „Pillar boundaries and authoring discipline (Säulengrenzen und Authoring-Disziplin)“.

Fehlermodus: Säulenübergreifendes Durchsickern — die kognitive Nutzlast des Entwicklers enthält Details der physischen Dimensionierung, oder die von Ops verfasste Dimensionierung enthält kognitive Metadaten. Der Build gelingt; die Authoring-Aufteilung in vier Domänen verwischt mit der Zeit, wenn Autoren die Säulen umgehen; die nachgelagerte Wartung wird schwieriger, während die Entsprechung zwischen Säulen und Datenfluss schwächer wird.

7. Workload-Semantik mit doppelter Quelle für containers.<name>.variables

Die Map variables: vereint zwei unterschiedliche Datenquellen über Go-Template-Ausdrücke: Literale der Entwicklersäule (Einträge, die .values / .infra / .locals lesen) und Daten der komponentenübergreifenden Pipe (Einträge, die .context.inject.env.<KEY> lesen). Autoren wählen pro Eintrag eine Quelle, je nachdem, ob der Wert komponentenlokal oder komponentenübergreifend abgeleitet ist.

Der Compiler unterscheidet die beiden Quellen nicht; beide fließen in dieselbe Kubernetes-Liste env: im gerenderten Deployment. Die Semantik der doppelten Quelle gilt nur zur Authoring-Zeit — die Disziplin besteht darin, die Absicht zu benennen (dieser Eintrag ist komponentenlokal; jener Eintrag ist komponentenübergreifend abgeleitet), damit künftige Maintainer lesen können, welche Einträge von welchen Ausgaben der inject-Hydration abhängen.

Dokumentiert in: entities/workload.md „Field-semantics essentials (Grundlagen der Feldsemantik)“ (variables).

Fehlermodus: Autoren, die die beiden Quellen nicht unterscheiden, verlieren die Spur, „welche Einträge an welche provides: eines Ziels gekoppelt sind“. Ein Refactoring der Schlüssel von provides: eines Ziels bricht stillschweigend jeden aufrufenden Eintrag in variables:, der über die inject-Pipe gelesen hat.

8. Benennungsdisziplin für Cloud-Ressourcen

Recipes, die Cloud-Ressourcennamen ausgeben (S3-Bucket-Namen, RDS-Datenbankkennungen, IAM-Rollennamen, CloudFormation-Stack-Namen — jedes Feld, dessen Wert einen globalen Namensraum beim Cloud-Anbieter belegt), müssen {{ .metadata.release_name }} und/oder {{ .context.instance_id }} mit dem gerenderten Namen verketten, um Kollisionen zu vermeiden, wenn dasselbe Recipe über mehrere Releases oder Komponenteninstanzen hinweg läuft.

Der Compiler untersucht die Ausgaben von valuesMapping: nicht auf Felder für Cloud-Ressourcennamen ohne diese Interpolationen. Die Disziplin wird von Recipe-Autoren aufrechterhalten (die wissen, welche Felder global eindeutige Ressourcen für den Ziel-Provider benennen) und von Reviewern (die Muster unbenannter Ressourcen im PR-Review erkennen).

Dokumentiert in: entities/recipe.md „Cloud-resource naming discipline (Benennungsdisziplin für Cloud-Ressourcen)“.

Fehlermodus: Zwei Releases desselben Aggregate (prod-billing und staging-billing) versuchen beide, eine Ressource mit demselben globalen Namen bereitzustellen; die zweite Bereitstellung schlägt zur Laufzeit mit einer cloudseitigen Ablehnung fehl. Der Aggrega-Build gelingt; der Fehler der Bereitstellung tritt erst zutage, wenn das zweite Release angewendet wird.

Keine Regel des Veröffentlichungs-Linters prüft Felder für Cloud-Ressourcennamen auf die erforderlichen Interpolationen; ein eigenes Linter-Plugin kann es (siehe Konventionen, die eine Linter-Regel prüft).

9. Component-Granularität — ein kohärenter Dienst pro Component

Eine Component modelliert einen kohärenten Dienst — einen einzelnen exponierten Dienst oder die Arbeitslast(en) eines Dienstes zusammen mit seinen nur intern genutzten Hilfs-Arbeitslasten. Wenn ein Chart Dienste bündelt, die eine andere Komponente sinnvoll eigenständig per use nutzen könnte — insbesondere fremde Infrastruktur wie eine Datenbank, einen Cache oder einen Message Broker, die Aggrega bereits als eigene Component modelliert —, setzt die Standardbibliothek dienstbezogene Components zu einem Sub-Aggregat-Modul (spec.aggregates + exportedComponents) zusammen, statt das gesamte Produkt als eine undurchsichtige Component zu kapseln. Die Disziplin: Mehrere Arbeitslasten innerhalb einer Component sind in Ordnung; unabhängige Nutzbarkeit ist die Linie, die eine Component in einen Stack aufteilt.

Der Compiler ist agnostisch gegenüber dieser Granularität. Er rendert alles, was die Schemavalidierung besteht — er untersucht weder, wie viele Dienste das Recipe einer Component bündelt, noch, ob einer davon eigenständig nutzbar ist. Ein Autor, der ein Produkt mit fünf Diensten als einzelne Component kapselt, erzeugt eine Component, die der Compiler ohne Beanstandung akzeptiert und rendert; die Konvention wird durch Authoring-Disziplin und die Aufmerksamkeit der Reviewer aufrechterhalten.

Dokumentiert in: ../../architecture/06-data-taxonomy-and-composition.md (Ein kohärenter Dienst pro Component — die Grenze der einzelnen Arbeitslast).

Fehlermodus: Eine monolithische Multi-Service-Kapselung wird erfolgreich gebaut, aber die gebündelten Dienste sind für die Topologie, den Selektor und die Policy unsichtbar — sie können nicht unabhängig skaliert, ersetzt oder als Abhängigkeit genutzt werden. Das spätere Refactoring des Monolithen in dienstbezogene Components ist eine Breaking Change für jeden Consumer, der auf den einzelnen gekapselten Knoten verwiesen hat.

Warum es Konventionen gibt

Jede dieser Konventionen ist bewusst Authoring-Disziplin, obwohl ein Schema oder eine Wasm-Policy jede von ihnen durchsetzen könnte. Die Begründung je Art von Gesellschaftsvertrag:

Erweiterbarkeit. Die Disziplin der reservierten Präfixe (Gesellschaftsvertrag 3) beschreibt das Vokabular der Standardbibliothek, nicht die Gesamtheit des gültigen Vokabulars. Unternehmenskataloge verfassen eigene Präfixe und Label-Schlüssel, um die Standardbibliothek zu erweitern; die Präfixkonvention per Schema durchzusetzen, würde „die Disziplin der Standardbibliothek“ in „die einzige zulässige Form der Sprache“ verwandeln — das ist die Mauer, die die Architektur bewusst vermeidet. Die Achse des operativen Typs (Gesellschaftsvertrag 1) bewahrt dieselbe Erweiterbarkeit auf einer anderen Oberfläche: Der reservierte Schlüssel, den Aggrega definiert, trägt eine geschlossene, durch das Schema durchgesetzte Menge, und ein Katalog erweitert, indem er einen eigenen Label-Schlüssel daneben hinzufügt statt eines Werts innerhalb des Schlüssels von Aggrega. Was das Schema prüft, ist die Wertemenge eines Schlüssels, der ihm gehört; offen bleibt jeder andere Schlüssel, und dort lebt das eigene Vokabular eines Katalogs.

AOT-Reinheit. Die Benennungsdisziplin für Cloud-Ressourcen (Gesellschaftsvertrag 8) und die Determinismus-Disziplin (Gesellschaftsvertrag 5) erfordern eine Untersuchung des Template-Inhalts, um festzustellen, ob ein Feld ein Cloud-Ressourcenname oder der Aufruf eines nicht-hermetischen Helfers ist. Die AOT-Reinheit (Invariante 2) bewahrt den Compiler davor, von Laufzeitzustand abzuhängen; eine statische Untersuchung der Templates ist machbar (ein Linter-Plugin liest die Templates der Entität so, wie sie geschrieben sind), doch sie im Kern-Compiler durchzuführen, koppelt Compiler-interne Logik an domänenspezifische Authoring-Belange. Die Architektur verlagert diese Prüfungen aus dem Compiler heraus in Wasm-Plugins gemäß Invariante 6 (die Wasm-ABI-Grenze).

Authoring-Flexibilität. Die Disziplin der Säulengrenzen (Gesellschaftsvertrag 6) und die Semantik mit doppelter Quelle von variables (Gesellschaftsvertrag 7) beschreiben Authoring-Muster statt Laufzeiteinschränkungen. Dieselbe Template-Syntax kann ein Muster ausdrücken, das die Disziplin einhält, oder eines, das sie verletzt; die Disziplin zu einer Laufzeitprüfung zu machen, würde vom Compiler verlangen, eine Authoring-Absicht zu interpretieren, auf die er keinen Zugriff hat. Die Architektur behandelt die Konvention als Dokumentation, aus der Autoren lernen, statt als Laufzeitinvariante. Auch die Component-Granularität (Gesellschaftsvertrag 9) gehört hierher: Unternehmen können ein Produkt in jeder Granularität kapseln, die ihr Katalog bevorzugt, und der Compiler — inhaltsneutral und meinungslos gemäß Invariante 1 — kann nicht wissen, ob eine gebündelte Arbeitslast eigenständig nutzbar ist, sodass die Grenze eines kohärenten Dienstes Authoring-Disziplin bleibt statt einer Schema-Mauer. Die Wahl des operativen Typs (Gesellschaftsvertrag 1) hat dieselbe Form: Das Schema legt fest, welche Werte es gibt, aber welcher davon eine bestimmte Komponente beschreibt, ist ein Modellierungsurteil darüber, wie die Infrastruktur sie behandeln muss, und nichts in einem Recipe oder einem Block values sagt dem Compiler, ob das Urteil richtig war.

Durchsetzung in zwei Hälften. Die Abgeschlossenheit von provides: im Recipe (Gesellschaftsvertrag 4) wird teilweise vom Compiler durchgesetzt — der Render-Pfad erkennt Lesezugriffe auf .context.inject / .context.uses in Templates von provides: und bricht ab. Die umfassendere Disziplin öffentlich gegenüber privat (keinen internen Zustand offenlegen) ist in der Konvention verankert, weil der Compiler ohne Authoring-Absicht nicht bestimmen kann, welche Strings Recipe-intern bleiben sollen.

Die drei Wege sind wichtig, weil jeder anzeigt, wo die Verantwortung für das Erkennen von Verstößen liegt. Durch das Schema durchgesetzt: der Compiler. Durch ein Policy-Plugin durchgesetzt: das Plugin, das sie prüft, wo eines läuft. Durch Konvention aufrechterhalten: Autoren und Reviewer. Autoren, die die Wege verinnerlichen, verstehen, welche Fehler der Compiler abfängt und welche stillschweigend bis zu nachgelagerten Werkzeugen oder zur Laufzeit durchgehen.

Konventionen, die eine Linter-Regel prüft

Der Veröffentlichungs-Linter, den aggrega lint ausführt, prüft eine Konvention auf dieser Seite teilweise: die Annotationsschlüssel von Gesellschaftsvertrag 3 weiter unten. Sein Befund ist beratend, und der Teil der Konvention, den er nicht erreicht, wird durch Konvention aufrechterhalten, wie die Einträge oben.

Keine Regel des Veröffentlichungs-Linters prüft eine andere Konvention auf dieser Seite. Zwei davon können von einer Linter-Regel geprüft werden, weil der Verstoß in der Entität geschrieben steht: Determinismus (Gesellschaftsvertrag 5) — ein Template, das einen nicht-hermetischen Helfer aufruft — und die Benennung von Cloud-Ressourcen (Gesellschaftsvertrag 8) — eine Ausgabe von valuesMapping:, die eine Cloud-Ressource ohne Interpolation von release_name / instance_id benennt. Ebenso Label-Schlüssel unter den reservierten Präfixen (Gesellschaftsvertrag 3). Ein Workspace kann unter plugins.linter eigene Linter-Plugins neben dem Veröffentlichungs-Linter anhängen, um jede davon zu prüfen; Die Disziplinregeln listet die Regeln auf, die der Veröffentlichungs-Linter mitbringt.

Die anderen Konventionen (1, 2, 4, 6, 7, 9) hängen davon ab, was der Autor gemeint hat, was keine Regel aus dem Geschriebenen herausliest. Die Bucket-Trennung ist von Erweiterbarkeit getrieben (Unternehmenskataloge überschreiben sie) — eine Durchsetzung per Schema stünde im Widerspruch zu dieser Flexibilität. Was von der Achse des operativen Typs übrig bleibt, nachdem das Schema die Wertemenge festgelegt hat — die Wahl des Primitivs, das zur Komponente passt —, ist von der Authoring-Absicht getrieben: Der Compiler kann einen gut gewählten operativen Typ nicht von einem schlecht gewählten unterscheiden, weil beides Werte sind, die er akzeptiert. Die Disziplin der Säulengrenzen und die Semantik mit doppelter Quelle von variables sind von der Authoring-Absicht getrieben — der Compiler kann die Absicht nicht allein aus der Template-Syntax bestimmen. Die Abgeschlossenheit von provides: im Recipe wird teilweise durchgesetzt; die umfassendere Disziplin öffentlich gegenüber privat hängt davon ab, welche Schlüssel der Autor intern halten wollte, was nichts im Recipe angibt. Auch die Component-Granularität ist von der Authoring-Absicht getrieben — ob eine gebündelte Arbeitslast eigenständig nutzbar ist, ist ein Modellierungsurteil, das der Compiler nicht aus dem Recipe-Inhalt lesen kann.

3. Disziplin der reservierten Präfixe

Annotations- und Label-Schlüssel folgen der Form <namespace>/<name>. Fünf reservierte Präfixe tragen spezifische Authoring-Regeln: aggrega.ai/ (nur Plattform), feature.aggrega.ai/ (offizielle Feature-Kurzformen), component.aggrega.ai/ (Component-intrinsische Merkmale), aggregate.aggrega.ai/ (Aggregate-Modulidentität) und <any-other-domain>/ (Unternehmen / Community).

Der Compiler lehnt eine Annotation, die unter einem reservierten Präfix auf einer Katalogentität oder einem Release verfasst wurde, nicht ab; nur eine Annotationsbindung eines Manifest oder ein Ausgabe-Label eines Recipe, das einen Schlüssel unter aggrega.ai/ beansprucht, bricht den Build ab. Ein Unternehmen, das aggrega.ai/internal-billing-tag: "..." außerhalb des Vokabulars der Plattform deklariert, erzeugt eine Annotation, die der Compiler akzeptiert und kaskadierend durch das Bucket-System weitergibt; spätere Plattform-Updates, die ein echtes aggrega.ai/internal-billing-tag einführen, kollidieren stillschweigend.

Dokumentiert in: labels-and-annotations.md (Präfixdisziplin) + providers/well-known-annotations.md.

Fehlermodus: Eigene Annotationen unter reservierten Präfixen kollidieren mit künftigen Plattform-Annotationen gleichen Namens; das erwartete Verhalten der Plattform überschreibt den vom Unternehmen verfassten Wert stillschweigend oder besteht neben ihm, je nach Reihenfolge.

Der Veröffentlichungs-Linter, den aggrega lint ausführt, meldet einen Annotationsschlüssel einer Katalogentität unter aggrega.ai/, der nicht zu den bekannten Annotationen der Plattform gehört, sowie einen unter feature.aggrega.ai/ an einer anderen Entität als einem Feature als beratenden Befund (E0277). Label-Schlüssel, die anderen reservierten Präfixe und Annotationen außerhalb von metadata.annotations einer Entität — etwa die, die ein Release schreibt — werden nicht geprüft, sodass die Disziplin für sie eine Konvention bleibt.

Querverweise