Status: Leitdokument / Informativ mit normativem Kern Priorität bei Konflikt: Normative Fachspezifikationen (
00bis11, CompilerDB-, TypeFn-, Engine-/Descriptor- und Runtime-Specs) gelten im Detail. Dieses Dokument definiert die übergreifenden Architekturprinzipien und verweist auf die ausführbaren Constitution-Blueprints. Hinweis: Die alte v1.3-Fassung ist historischer Kontext. Diese Fassung beschreibt die Constitution nicht mehr als rein prosaisches Dokument, sondern als menschenlesbare Projektion eines blueprint-basierten Constitution-Systems.
Jade Design Constitution v2.0¶
Status: Grundsatzdokument und Charta
Zielgruppe: Mitwirkende, fortgeschrittene Nutzer und interessierte Leser
Umfang: Architekturprinzipien von Jade VM, JDL, Ringen, Descriptoren, CompilerDB, RuntimeBus und Constitution-Enforcement.
0. Zweck dieses Dokuments¶
Jade ist ein langfristiges Projekt. Code, Implementierungen, Stdlib-Strukturen und Werkzeuge werden sich ändern. Die Constitution hält fest, welche Architekturentscheidungen dabei stabil bleiben müssen.
Dieses Dokument ist nicht mehr die einzige normative Quelle. Jade besitzt ein ausführbares Constitution-Modell:
ConstitutionSpec deklarativer Blueprint
ConstitutionEngine validiert und materialisiert Regeln
ConstitutionDescriptor geprüfter Regelvertrag pro Ring und Namespace
Compilerphasen konsumieren Descriptoren an Enforcement-Gates
Die Prosa-Constitution erklärt diese Struktur. Die konkrete Durchsetzung erfolgt über Constitution-Blueprints und materialisierte ConstitutionDescriptoren. Das klingt bürokratisch, ist aber immerhin maschinenlesbare Bürokratie. Menschen haben Schlimmeres mit YAML getan.
Wenn eine zukünftige Designentscheidung dieser Constitution widerspricht, gibt es nur zwei legitime Optionen:
- Das Design wird so geändert, dass es zur Constitution passt.
- Die Constitution wird explizit geändert, mit Begründung und Versionseintrag.
1. Architekturformel¶
Jade folgt einer festen Schichtung:
Ring 0 / D = JME-zentrierter Maschinenkern und Trust Anchor
Ring 1 / jade:: = JDL-seitige Semantik- und Descriptor-Schicht
Ring 2 / jdl:: = user-facing Stdlib, Services, Blueprints, Engines
Ring 2 / User = Anwendungscode, Projekt-Constitutions, Plugins
Blueprint = deklarative Beschreibung
Engine = Auswertung einer Beschreibung
Descriptor = materialisierter Vertrag zwischen Semantik und Maschine
Constitution = deklarativer Regelvertrag über erlaubte Semantik
Der wichtigste Satz lautet:
D besitzt Mechanik. JDL besitzt Semantik. Descriptoren verbinden beides.
Jade strebt kein vollständiges Self-Hosting-Dogma an. Die JME, VM-Loop, Scheduler-Kern, RuntimeBus, CompilerDB-Storage, Seed Loader, Intrinsic Dispatch und Host-Integration bleiben Ring 0. So viel Semantik wie möglich wandert in JDL; so wenig Mechanik wie nötig bleibt in D.
2. Identität und Umfang von Jade¶
2.1 Jade ist VM-first¶
Jade ist eine sprachzentrierte virtuelle Maschinenplattform für JDL mit eigenem typisiertem Mid-Level-IR, eigener VM, eigener Memory Engine, eigenem Effektsystem und eigener Descriptor-Pipeline.
Jade ist nicht zuerst:
- ein offenes IR für jede beliebige Sprache,
- ein universelles Backend für jede CPU-Architektur,
- ein Ersatz für LLVM,
- ein allgemeines Plugin-System mit Sprachsyntax.
Es kann später breiter werden. Der Ausgangspunkt bleibt JDL auf der Jade VM.
2.2 POSIX als Zielplattform¶
Jade zielt initial und bewusst auf POSIX-kompatible Betriebssysteme. Nicht-POSIX-Unterstützung wird nicht präventiv entworfen. Sollte sie notwendig werden, braucht sie eine explizite Änderung der Constitution.
2.3 Internes IR zuerst¶
Jade verwendet ein internes typisiertes IR als Compiler- und Optimierungsrepräsentation. Dieses IR ist zunächst Implementierungsdetail. Es wird erst stabilisiert, wenn mehrere Frontends oder mehrere Backends diese Stabilität tatsächlich brauchen. Ewige IRs auf Vorrat sind eine bewährte Methode, sich selbst frühzeitig einzubetonieren.
3. Kein undefiniertes Verhalten¶
Jade lehnt undefiniertes Verhalten als Designwerkzeug ab.
Jedes Programm, das die Ausführungsstufe erreicht, befindet sich in einem von zwei Zuständen:
Gültiges IR
Alle Struktur-, Typ-, Policy-, Effekt- und Ringregeln sind erfüllt.
Verhalten ist definiert.
Ungültiges IR
Eine Invariante ist verletzt.
Der Verifier lehnt das Programm ab.
Laufzeitfehler sind Traps mit definierter Semantik. Division durch Null, ungültiger Indexzugriff, geschlossener Handle oder gescheiterte Runtime-Policy führen zu kontrollierten Fehlern, nicht zu semantischem Nebel.
4. Core, Extended und Backends¶
4.1 Core-Instruktionen¶
Der Execution Core ist klein, stabil und direkt ausführbar. Jedes ausführbare Jade-Programm wird am Ende vollständig in Core-Instruktionen ausgedrückt.
Core-Instruktionen dürfen nicht leichtfertig erweitert werden. Eine Core-Instruktion ist ein Vertrag mit der VM, dem Verifier und allen zukünftigen Tools. So etwas fügt man nicht hinzu, weil einem ein Lowering-Pass gerade müde vorkommt.
4.2 Extended-Instruktionen¶
Extended-Instruktionen sind High-Level-Formen für Frontends, Optimierung und Lesbarkeit. Sie müssen vor Verifikation und Ausführung zu Core gelowert werden.
Plugins dürfen Extended-Instruktionen ergänzen, aber niemals Core-Instruktionen verändern oder deren Semantik überschreiben.
4.3 Backends bleiben dünn¶
Backends übersetzen bereits bewiesene und gelowerte Repräsentationen. Sie erfinden keine neue Semantik, keine neuen Effekte und keine neuen Safety-Regeln. Optimierung und Semantik leben im Jade-IR und in der Pass-/Descriptor-Pipeline, nicht im Backend.
5. Pass-Pipeline, IR-Invarianten und Verifier¶
Ein Pass ist eine Analyse oder Transformation über IR oder eine daraus abgeleitete Repräsentation.
Jeder Pass deklariert:
preconditions welche Invarianten vorher gelten müssen
postconditions welche Invarianten danach garantiert sind
invalidations welche Invarianten gebrochen werden können
Der Verifier ist Gatekeeper. Er prüft an definierten Pipeline-Grenzen:
- nach Frontend-/IR-Erzeugung,
- nach großen Pass-Gruppen,
- vor Lowering zu Core,
- vor Ausgabe oder Laden ausführbarer Artefakte.
Compilernahe Engines wie IRBuilderEngine oder GeneratorEngine dürfen Artefakte erzeugen, aber keine Type-, Effect-, Dispatch-, FFI- oder Constitution-Semantik nachträglich erfinden.
6. Speichermodell und JME¶
6.1 Ring 0 ist JME-zentriert¶
Ring 0 ist die JME-zentrierte Maschinen- und Integritätsebene.
Die JME besitzt die zentrale Autorität über:
Speicheridentität
Handles
Generation Counter
Refcounts
Arenen und Pools
Layoutbindung zur Runtime
Drop-/Lifetime-Durchsetzung
Handle-Gültigkeit
VM-Loop, Scheduler-Kern, RuntimeBus, Intrinsic Dispatch, FFI/JadeValue Bridge, CompilerDB-Storage und Seed Loader sind ebenfalls Ring-0-nahe mechanische Substrate. Sie sind aber nicht gleichrangige semantische Autoritäten über Speicher. Für Speicher- und Handle-Wahrheiten ist die JME der Eigentümer.
6.2 Handles statt roher Pointer¶
JDL kennt keine rohen Pointer. JDL-Code arbeitet mit typisierten Handles, Werten und Descriptoren. Pointer existieren nur unterhalb der Sprachgrenze, insbesondere in FFI- und Ring-0-Mechanik.
Handles sind opak. Operationen auf Handles laufen über JME-vermittelte Regeln. Kein Usercode, Plugin oder Ring-2-Code darf JME-Tabellen direkt manipulieren.
6.3 TypeEngine vs. JME¶
Die TypeEngine ist semantische Autorität über Typbeschreibung. Die JME ist operative Autorität über Runtime-Repräsentation und Speicherintegrität.
TypeEngine erzeugt TypeDescriptor, LayoutDescriptor, Policy-/Meta-Descriptoren
JME konsumiert diese Descriptoren und verwaltet Runtime-Zustand
Die TypeEngine verwaltet keine Runtime-Typen direkt. Sie erzeugt Verträge. Die JME erzwingt sie.
7. Effekte und Runtime-Grenzen¶
Effekte sind Teil von Typ- und IR-Semantik. Effektgrenzen sind harte Constraints für Optimierungen, Scheduling und Ausführung.
Jade unterscheidet:
Die CompilerDB ist Query-/Descriptor-Substrate. Der RuntimeBus ist Command-Substrate. Beide sind kontrollierte Zugangspunkte zu tieferen Ringen. Usercode greift auf keinen von beiden direkt zu.
Effects referenzieren Services und deklarierte Dependencies, nicht native Symbole oder rohe Intrinsics.
8. Blueprints, Engines und Descriptoren¶
8.1 Blueprint¶
Ein Blueprint ist eine getypte, deklarative Beschreibung. Er beschreibt Absicht, nicht Ausführung.
Blueprints sind serialisierbar und enthalten keine gefangene Runtime-Closure mit verstecktem Zustand. Handler-Slots müssen über qualifizierte Funktionsreferenzen oder capture-freie Funktionen modelliert werden.
8.2 Engine¶
Eine Engine ist eine typisierte Auswertungsinstanz für ein Blueprint- oder Descriptor-Subject. Sie validiert, beschreibt, materialisiert oder instanziiert.
Die Engine-Abstraktion ist ring-neutral. Eine konkrete EngineDefinition gehört jedoch zu einem Ring-Kontext:
Ring 1 Engines
ParserEngine, TypeEngine, TypeFnEvaluator, ProtocolDispatcherEngine,
FfiBindingEngine, IRBuilderEngine, GeneratorEngine, ConstitutionEngine
Ring 2 Engines
HttpEngine, TestEngine, ActorEngine, EffectRuntime, TransportEngines,
User-/Plugin-Engines, App-spezifische Runtime-Engines
Der alte Satz „Engines sind Ring-2-Code“ ist damit falsch. Manche Engines sind Ring 2. Compilernahe Engines sind Ring 1. Die Fachwelt atmet erleichtert auf, falls sie jemals davon erfahren sollte.
8.3 Descriptor¶
Descriptoren sind die materialisierte Mitte:
Blueprint / TypeSubject / ConstitutionSpec
-> Engine / TypeFnEvaluator / ConstitutionEngine
-> Descriptor / Patch
-> Materializer / Runtime / Ring-0-Domäne
Ring-0-Domänen konsumieren Descriptoren. Sie interpretieren keine hohe JDL-Semantik.
9. Constitution as Descriptor¶
9.1 Constitution ist kein bloßes Dokument¶
Eine Constitution ist ein deklarativer Regel-Blueprint, der von einer ConstitutionEngine geprüft und in einen ConstitutionDescriptor materialisiert wird.
ConstitutionSpec
-> ConstitutionEngine
-> ConstitutionDescriptor
-> RuleIndex / EnforcementHooks
-> Compilerphasen
Die ConstitutionEngine führt keine beliebige Programmlogik aus. Sie normalisiert deklarative Regeln in eine endliche, querybare Rule-Algebra. Freie Callbacks als Verfassungsrecht wären nur ein Plugin-System mit Perücke.
9.2 Regeln¶
Constitution-Regeln besitzen die Form:
trigger wann geprüft wird
selector auf welche Subjects/Descriptoren die Regel passt
predicate welche Bedingung gelten muss
action Diagnostic, Deny, Require, Warn, Seal
Typische Trigger:
OnNamespaceLoad
OnImport
OnTypeSubject
OnApplyRefinement
OnProvide
OnEffectDescriptor
OnDescriptorCommit
OnIrVerify
OnArtifactEmit
Regeln prüfen ausschließlich über definierte CompilerDB-Queries und materialisierte Descriptoren.
9.3 Monotonie¶
Constitutions sind monoton:
niedriger Ring / übergeordneter Namespace setzt Grenze
höherer Ring / untergeordneter Namespace darf nur weiter einschränken
Deny gewinnt. Require kann hinzugefügt, aber nicht entfernt werden. Warn darf zu Error verschärft werden. Error darf nicht lokal entschärft werden, außer über ausdrücklich erlaubte Trust-Mechanismen, die keine Ringgrenzen überschreiben.
Ring 2 darf sich selbst fesseln. Ring 2 darf sich keine Schlüssel für Ring 0 malen.
9.4 Ring-spezifische Constitutionen¶
Ring0Constitution
Ursprung: Bootstrap Seed / D / JME
Status: sealed
Validierung: Ring 0
Inhalt: Speicher, Handles, Runtime-Facts, Intrinsics, VM-Fundamente
Ring1Constitution
Ursprung: jade::constitution
Validierung: gegen Ring0Constitution
Inhalt: TypeFns, EngineProvider, Descriptor-Materialisierung, CompilerDB-Regeln
Ring2StdlibConstitution
Ursprung: jdl::constitution
Validierung: gegen Ring0 + Ring1
Inhalt: user-facing Stdlib, Services, Blueprints, Effects, Runtime-Engines
Ring2UserConstitution
Ursprung: Package-/Projekt-Constitution
Validierung: gegen Ring0 + Ring1 + jdl::
Inhalt: lokale Projektregeln, restriktive Policies, Team-Invarianten
9.5 Namespace-Discovery¶
Constitutions können in constitution.jdl oder explizit über mod.jdl deklariert werden. prelude.jdl ist nicht der richtige Ort für Autorität; Prelude ist Bequemlichkeit, Constitution ist Recht. Diese Dinge zu vermischen wäre eine sehr effiziente Methode, zukünftige Leser zu verärgern.
10. Namespaces und Zugriffshierarchie¶
Jade unterscheidet System- und User-Namespace:
app:: / user::* darf jdl:: importieren
jdl:: darf kontrolliert jade:: importieren
jade:: darf jade::intrinsics:: importieren
jade::intrinsics:: spricht mit RuntimeBus / Ring 0
jade:: ist Ring-1-nahes JDL: dünne Systemschicht, Intrinsic-Wrapping, EngineProvider, Descriptor-nahe Implementierungen.
jdl:: ist Ring-2-Stdlib: user-facing Types, Protocols, Blueprints, Services, Effects, Collections, Engines ohne direkten Maschinenkontakt.
Usercode ist ebenfalls Ring 2, darf aber die jdl::-Constitution nur weiter einschränken, nicht lockern.
11. Graceful Degradation¶
Jade kennt definierte Traps und lokale Fehlergrenzen.
Ein Laufzeitfehler invalidiert den lokalen Scope, nicht automatisch das Gesamtsystem. Arenas und Handles liefern natürliche Fehler- und Cleanup-Grenzen.
Vollständiger Prozessabbruch ist nur legitim bei:
Ring-0-Korruption
JME-Invariantverletzung
Verifier-/DescriptorStore-Korruption
nicht wiederherstellbarer VM-interner Zustand
TypeFn-, Constitution-, Provider- oder Userland-Fehler sind normalerweise Diagnostics, Build-Fehler, Traps oder lokal isolierte Runtime-Fehler. Sie sind kein Freifahrtschein zum Prozessabbruch.
12. Debug als Referenz¶
Debug-Ausführung ist die Referenzsemantik. Release-Ausführung muss beobachtungsäquivalent sein.
Unterschiede bei beobachtbarem Verhalten sind Compiler-, VM- oder Runtime-Bugs. Optimierung darf Semantik nicht neu erfinden, nur vorhandene Semantik effizienter darstellen. Tragisch, dass man das überhaupt aufschreiben muss, aber Optimierer sind bekanntlich optimistisch bis zur Strafbarkeit.
13. JadeOS und Jade Node¶
JadeOS ist initial kein eigener Kernel. JadeOS ist die verteilte Betriebsform von Jade Nodes:
Jade Node = ausführende Zelle
JadeOS = Mesh aus Nodes, SystemSpecs, ContentStore, Policies und Generations
Ein Node konsumiert Blueprints, SystemSpecs und Artefakte, materialisiert Descriptoren, prüft Policies und führt Services aus.
Langfristige Bare-Metal- oder eigene Kernel-Unterlagen sind nicht ausgeschlossen, aber nicht der Kern der JadeOS-Idee. Die Constitution darf JadeOS nicht als Vorwand nutzen, um Jade 0.1 mit zukünftiger Kernel-Fantasie zu belasten. Erst die Node- und Mesh-Schicht muss tragen.
14. Versionierung und Änderungen¶
Diese Fassung ist v2.0.
Änderungen an der Constitution müssen enthalten:
- Versionsnummer,
- betroffene Prinzipien,
- Grund der Änderung,
- Auswirkungen auf bestehende Specs,
- Migrationshinweise für ConstitutionDescriptoren, falls relevant.
15. Glossar¶
Ring 0¶
JME-zentrierter Maschinen- und Integritätskern. Enthält JME als zentrale Autorität sowie mechanische Substrate wie VM-Loop, Scheduler-Kern, RuntimeBus, Intrinsic Dispatch, CompilerDB-Storage, Seed Loader und Host-Integration.
Ring 1¶
JDL-seitige Semantik- und Descriptor-Schicht. Enthält compilernahe Engines und Systemmodule in jade::.
Ring 2¶
User-facing Stdlib (jdl::) und Anwendungscode. Darf weiter einschränken, aber keine tieferen Ringregeln lockern.
Blueprint¶
Getypte deklarative Beschreibung. Beschreibt Absicht, nicht Ausführung.
Engine¶
Typisierte Auswertungsinstanz. Ring-neutraler Begriff; konkrete EngineDefinitions gehören zu konkreten Ring-Kontexten.
Descriptor¶
Geprüfter materialisierter Vertrag zwischen JDL-Semantik und Ring-0-/Compiler-/Runtime-Mechanik.
ConstitutionSpec¶
Blueprint, der Regeln für einen Ring oder Namespace deklariert.
ConstitutionDescriptor¶
Materialisierte, geprüfte und indexierte Regelbasis, die Compilerphasen konsumieren.
MaterializationPatch¶
Geprüfte Änderungsabsicht an Meta-, Type-, Provide-, Dispatch-, Constitution- oder Artifact-Descriptoren. Patches werden durch den Materializer atomar committed.
TypeFnContext¶
Compile-Time-Kontext für TypeFns. Enthält eine eingeschränkte db-Fassade, Ziel-Subject bei Refinements und Proof-/Diagnostic-Kontext.
Änderungsprotokoll¶
Version 2.0¶
- Constitution als blueprint-basiertes, descriptor-materialisiertes System eingeordnet.
- Ring 0 als JME-zentrierter Maschinenkern geschärft.
- Ring 1 als
jade::-Semantik- und Descriptor-Schicht definiert. - Ring 2 in
jdl::-Stdlib und Usercode unterschieden. - Alte Aussage „Engines und Blueprints sind Ring-2-Konzepte“ korrigiert.
- ConstitutionEngine, ConstitutionSpec und ConstitutionDescriptor eingeführt.
- Monotonie-Regel für Namespace- und Ring-Constitutions definiert.
- JadeOS als Mesh-/Node-Betriebsform korrigiert, nicht primär als Kernel-Projekt.
Version 1.3¶
Historische Fassung mit Blueprint-Engine-Architektur, Graceful Degradation und alter Ring-2-Engine-Zuordnung.
Ende der Jade Design Constitution v2.0