Zum Inhalt

Internes Architekturpapier: Jade Control Surface über RuntimeBus und Query-Projektionen

Status

Arbeitsentwurf.

Zweck

Dieses Dokument beschreibt eine Architektur für eine webbasierte Jade-Control-Surface, die nicht als eigenständige Logikschicht implementiert wird, sondern als UI-Client über bereits vorhandene Jade-Schnittstellen.

Die Oberfläche soll mehrere Rollen abdecken:

  • REPL / Session-Konsole
  • Explain- und Inspector-UI
  • Test- und Benchmark-Ansicht
  • Runtime-Monitoring
  • Dokumentations- und Navigationsoberfläche

Der zentrale Architekturgrundsatz lautet:

Die Control Surface besitzt keinen privilegierten Direktzugriff auf Compiler- oder Runtime-Interna. Sie spricht ausschließlich über wohldefinierte Commands und Queries.

1. Architekturthese

Die Jade-Control-Surface ist kein eigenes Subsystem mit Sonderrechten. Sie ist ein Client über zwei bereits vorhandene Kommunikationsachsen:

  • RuntimeBus für verändernde, reihenfolgenabhängige Laufzeitaktionen
  • Query-Projektionen für lesende, deterministische, erklärende und dokumentierende Ansichten

Daraus folgt:

  1. Die UI darf keine Subsystem-Interna direkt lesen oder verändern.
  2. Alle mutierenden Operationen werden als Commands modelliert.
  3. Alle Anzeige- und Explain-Funktionen werden als Queries auf stabile Artefakte modelliert.
  4. Console, Proof, Bytecode, Tests, Monitoring und Docs sind nur verschiedene Projektionen auf denselben zugrundeliegenden Artefaktgraphen.

2. Ziele

2.1 Primäre Ziele

  • Eine einheitliche Arbeitsoberfläche für Jade schaffen
  • Dieselben internen Wahrheiten in mehreren Views sichtbar machen
  • Diagnose, Typableitungen, Lowering, Runtime-Zustand und Metriken nachvollziehbar machen
  • Lokale CLI, Web-UI, Tests und spätere Editor-Integrationen auf denselben Kernschnittstellen aufbauen

2.2 Sekundäre Ziele

  • Dokumentation ausführbar und inspizierbar machen
  • Benchmarks nicht nur messen, sondern erklären
  • Testing auf Artefakte statt auf rohe Textausgabe stützen
  • Monitoring auf dieselben Runtime-Read-Models aufbauen

2.3 Nicht-Ziele

  • Keine Browser-seitige Reimplementierung von Compiler- oder Runtime-Logik
  • Kein Direktzugriff des Web-Frontends auf VM-, TypeEngine- oder JME-Interna
  • Kein monolithisches "evalAndReturnEverything"-API
  • Kein UI-zentriertes Datenmodell

3. Normative Grundsätze

3.1 Subsystem-Kapselung bleibt unangetastet

Die Control Surface darf bestehende Kapselungsgesetze nicht aufweichen. Sie konsumiert nur öffentliche Schnitte.

3.2 Commands und Queries bleiben strikt getrennt

Mutierende Operationen laufen über RuntimeBus-artige Command-Schnittstellen. Lesende Ansichten laufen über Query-Projektionen.

3.3 Das UI arbeitet auf Artefakten, nicht auf freien Textblöcken

Die zentrale Einsicht für Jade ist:

Nicht Tabs sind die eigentliche Struktur, sondern Artefakte mit stabiler Identität.

Ein REPL-Lauf erzeugt adressierbare Artefakte, auf die unterschiedliche Ansichten zeigen können.

3.4 Ansichten sind Projektionen

Console, Proof, Type Graph, Lowering, Bytecode, Testberichte und Monitoring zeigen dieselben Vorgänge aus unterschiedlicher Perspektive. Keine View besitzt eigene Wahrheit.

4. Kernmodell: Artefakte und Identitäten

Die Control Surface darf nicht auf flüchtigen UI-Zuständen basieren. Stattdessen wird ein stabiles Identitätsmodell eingeführt.

4.1 Zentrale IDs

  • SessionId
  • EvaluationId
  • ArtifactId
  • ExpressionId
  • TypeId
  • ProtoId
  • HandleId
  • BenchmarkRunId
  • TestRunId
  • DocPageId

4.2 Bedeutung

SessionId

Identifiziert eine REPL-, Script-, Test- oder Playground-Session.

EvaluationId

Identifiziert einen konkreten Eval-Vorgang innerhalb einer Session.

ExpressionId

Identifiziert einen Ausdruck oder eine diagnostisch relevante Teilstruktur innerhalb einer Evaluation.

ArtifactId

Identifiziert ein aus einem Vorgang entstandenes oder daran geknüpftes Artefakt. Beispiele: - Resultatwert - Typprojektion - Proof Trace - Lowered IR - Bytecode-Listing - Runtime Snapshot - Diagnostic Bundle

4.3 Grundregel

Ein Benutzer klickt im UI nie "auf einen Tab", sondern implizit auf ein Artefakt oder auf eine Referenz auf ein Artefakt.

Beispiel: - Klick auf letzten Wert in der Console - UI kennt EvaluationId und ArtifactId - Type-, Proof- und Bytecode-Ansicht laden nur andere Projektionen für dieselbe Artefaktbasis

5. Schreibseite: Commands

Die Schreibseite modelliert jede verändernde Aktion explizit. Das Web-UI sendet keine Direktaufrufe an beliebige Systeme.

5.1 Grundsatz

Commands sind: - side-effecting - reihenfolgenabhängig - nicht cachebar - zustandsverändernd - immer durch den Zustandsbesitzer auszuführen

5.2 Erste Command-Kandidaten

Session

  • CreateSession
  • ResetSession
  • DestroySession
  • SetSessionMode

Ausführung

  • EvalSource
  • LoadModule
  • RunScript
  • InterruptEvaluation

Runtime / Debug

  • SetTraceMode
  • SetReifyMode
  • RetainHandle
  • ReleaseHandle
  • SpawnTask
  • OpenArena
  • CloseArena

Qualität / Automation

  • RunTests
  • RunBenchmark
  • WarmBenchmark
  • PinBaseline

5.3 Command-Ergebnisse

Commands sollen keine unstrukturierten UI-Strings liefern, sondern mindestens:

  • Status
  • neue oder betroffene IDs
  • entstandene Artefakte
  • Diagnostik-Referenzen
  • Timestamps / Sequenznummern

Beispiel:

EvalSource liefert nicht nur "ok" oder "error", sondern etwa:

  • EvaluationId
  • primary_result_artifact
  • diagnostic_bundle_artifact
  • proto_artifact
  • runtime_snapshot_artifact

6. Leseseite: Queries und Projektionen

Die Leseseite liefert read-only Views auf bestehende Wahrheit.

6.1 Grundsatz

Queries sind: - seiteneffektfrei - deterministisch innerhalb ihres Geltungsbereichs - cachebar, sofern die Quelle stabil ist - auf Sichtbarkeit, Erklärung und Navigation ausgerichtet

6.2 Query-Kategorien

Session-Queries

  • GetSessionSummary(SessionId)
  • GetBindings(SessionId)
  • GetOpenHandles(SessionId)
  • GetOpenScopes(SessionId)

Evaluation-Queries

  • GetEvaluationSummary(EvaluationId)
  • GetEvaluationTimeline(EvaluationId)
  • GetEvaluationDiagnostics(EvaluationId)

Explain-/Type-Queries

  • GetTypeProjection(ArtifactId)
  • GetTruthProfile(ArtifactId)
  • GetProofTrace(ArtifactId, label)
  • ExplainWhy(ArtifactId, goal)
  • ExplainWhyNot(ArtifactId, goal)

Lowering-/VM-Queries

  • GetLoweredIr(ArtifactId)
  • GetProto(ArtifactId)
  • GetBytecode(ProtoId)
  • GetRegisterLayout(ProtoId)
  • GetJadeValueLayout(ArtifactId)

Runtime-Queries

  • GetRuntimeSnapshot(EvaluationId)
  • GetHandleInventory(SessionId)
  • GetArenaStats(SessionId)
  • GetSchedulerState(SessionId)
  • GetMessagingState(SessionId)

Quality-Queries

  • GetTestReport(TestRunId)
  • GetBenchmarkReport(BenchmarkRunId)
  • GetBenchmarkSeries(SymbolId | DocPageId)

Docs-/Navigation-Queries

  • GetDocPage(DocPageId)
  • GetSymbolSummary(SymbolId)
  • FindExamples(SymbolId)
  • GetModuleOverview(ModuleId)

6.3 Read Models statt Einheits-JSON

Die Leseseite soll keine universelle Monsterantwort erzeugen. Stattdessen werden gezielte Read Models bereitgestellt, etwa:

  • ConsoleEntryView
  • ProofTraceView
  • TypeSummaryView
  • ProtoView
  • RuntimeSnapshotView
  • BenchmarkOverviewView
  • TestRunView
  • DocPageView

So bleibt die UI simpel und das Backend semantisch sauber.

7. Warum die UI artefaktzentriert sein muss

Das ursprüngliche Tab-Denken ist für Mockups praktisch, aber architektonisch zu schwach.

Tabs sind nur Darstellung. Artefakte sind die eigentliche semantische Einheit.

7.1 Beispielablauf

  1. Benutzer evaluiert task.send(ctx).
  2. EvalSource erzeugt eine EvaluationId.
  3. Daraus entstehen Artefakte:
  4. Diagnostic Bundle
  5. Type Projection für ctx
  6. Proof/Why-Not-Trace für Share(Send)
  7. optional Lowered IR
  8. optional Runtime Snapshot
  9. Console zeigt die Kurzfassung.
  10. Inspector lädt bei Bedarf weitere Projektionen derselben Artefakte.

7.2 Konsequenz

Die Oberfläche muss Deep Links innerhalb desselben Vorgangs erlauben: - Console → Proof - Console → Type - Console → Bytecode - Type → Why / Why not - Diagnostic → betroffener Ausdruck → Proof / Source / Lowering

Ohne stabiles Artefaktmodell wird das ein UI-Matsch aus Sonderfällen.

8. Kanonisches Ergebnisobjekt für Eval

Ein Eval-Vorgang braucht ein kanonisches strukturiertes Resultat.

8.1 Vorschlag

EvalResult
- session_id
- evaluation_id
- sequence_no
- started_at
- finished_at
- status                    // ok | error | trapped | interrupted
- primary_expression_id
- primary_result_artifact_id?
- diagnostic_bundle_artifact_id?
- proto_artifact_id?
- runtime_snapshot_artifact_id?
- emitted_artifact_ids[]

8.2 Eigenschaften

  • klein genug für jeden Client
  • reich genug für Deep Links
  • stabil genug für Tests und Historie
  • nicht an eine bestimmte Oberfläche gekoppelt

9. Beispielhafte UI-Sichten auf dieselben Artefakte

9.1 Console

Zeigt: - Eingabe - kompakte Resultatdarstellung - knappe Typinfo - Kurzdiagnostik - Referenzen auf EvaluationId und primäre Artefakte

9.2 Type View

Zeigt: - TypeId - Descriptor-Zusammenfassung - relevante Labels - Proven / Excluded / Unproven - ggf. Herkunft von Ableitungen

9.3 Proof View

Zeigt: - ausgewähltes Ziel, z. B. proven(Copyable) oder excluded(Share(Send)) - Regelkette - Voraussetzungen - Fixpoint-Zustand - Rule-Origin

9.4 Bytecode / Proto View

Zeigt: - ProtoId - Registerzahl - Constants - Opcodes - Source-Spans / Expression-Zuordnung - evtl. Intrinsic-Dispatch

9.5 Monitoring View

Zeigt: - Handle-Inventar - RC-/Generation-bezogene Runtime-Infos - Scheduler-/Task-Status - Arena- und Storage-Metriken - zeitliche Snapshots

9.6 Docs View

Zeigt: - Doku-Seite - referenzierte Symbole - ausführbare Beispiele - Link auf dieselben Artefakte wie REPL oder Tests

10. Testing und Benchmarking als normale Clients

Testing und Benchmarking dürfen keine isolierten Sonderwelten sein. Sie sollen dieselben Commands und Queries nutzen.

10.1 Tests

Ein Testlauf ist architektonisch: - ein Command zur Ausführung - ein Satz von Eval-/Check-Artefakten - ein TestRun-Read-Model zur Darstellung

Damit können Tests nicht nur "pass/fail", sondern auch: - Diagnostik - Typableitungen - Lowering-Deltas - Artefaktvergleiche bereitstellen.

10.2 Benchmarks

Ein Benchmarklauf ist ebenfalls: - ein Command zur Ausführung - ein oder mehrere Runtime-/Timing-Artefakte - ein Benchmark-Read-Model zur Darstellung

Damit wird erklärbares Benchmarking möglich: - Zeit - Allocations - RC-Druck - Instruktionsanzahl - Proto-/Lowering-Variation

11. Monitoring als Runtime-Projektion

Monitoring ist keine gesonderte Architektur. Es ist eine Projektion auf Runtime-Zustand.

Deshalb sollte Monitoring auf denselben Grundbausteinen beruhen wie Inspector und Debug-UI: - Runtime Snapshots - Handle Inventory - Scheduler State - Storage/Arena Stats - Messaging/Signal Views

Wichtig ist dabei: - keine Direktzeiger - keine UI-seitige Interpretation von Rohstrukturen - nur read-only Views / Snapshots

12. Transport und Host-Strategie

12.1 Kein Zwang zu Jade-eigener HTTP-Stdlib in Phase 1

Die erste Control Surface muss nicht von Jade selbst gehostet werden. Sie kann in D über eine eingebettete VM laufen.

Das trennt: - Tooling-Host-Infrastruktur - Sprach-/Stdlib-Fähigkeiten

Diese Trennung ist gewollt.

12.2 Transportoptionen

  • lokaler In-Process-Client
  • CLI über denselben API-Kern
  • Webserver in D
  • Browser-Client via HTTP + Push/Streaming
  • später Editor- oder TUI-Clients

12.3 Streaming-Bedarf

Für folgende Fälle sind inkrementelle Updates sinnvoll: - laufende Benchmarks - Trace-Ausgaben - längere Testläufe - Monitoring - evtl. langlaufende Eval-Vorgänge

13. Sicherheit und Ressourcenmodell

Eine Web-Control-Surface erzeugt sofort die üblichen Probleme, die Menschen gern erst bemerken, wenn etwas brennt.

Früh mitzudenken sind:

  • Session-Isolation
  • Timeouts
  • Speicherlimits
  • Begrenzung langlaufender Commands
  • Trennung zwischen read-only Doku und auszuführendem Code
  • kontrollierte FFI-Sichtbarkeit
  • Debug-/Trace-Funktionen nicht standardmäßig global offenlegen

14. Einführung in Phasen

Phase 1: Kern ohne Web

  • VM-Core stabilisieren
  • internes EvalResult festlegen
  • lokale CLI-REPL über denselben API-Kern bauen
  • Session-, Eval- und Diagnoseartefakte einführen

Phase 2: Explain-Fähigkeiten

  • Type-Projektionen
  • Why / Why not
  • Proof Trace
  • Lowered IR / Proto / Bytecode

Phase 3: Quality-Layer

  • Testläufe als normale Commands
  • Testberichte als Read Models
  • Benchmarkläufe und Metriken

Phase 4: Web-Control-Surface

  • Browser-UI als Client
  • Artefaktbasierte Navigation
  • Inspector, Monitoring und Docs auf denselben Projektionen

Phase 5: Ausbau

  • Editor-Integration
  • persistente Historien
  • Vergleichsansichten
  • Multi-Session / Remote / Team-Szenarien

15. Entscheidungsregeln

Entscheidung 1

Die Control Surface wird nicht als privilegiertes Frontend implementiert.

Entscheidung 2

Die Trennung Commands vs. Queries bleibt auch für Web-Tooling strikt bestehen.

Entscheidung 3

Die zentrale Datenstruktur der Oberfläche ist ein Artefaktgraph mit stabilen IDs, nicht ein Satz loser UI-Tabs.

Entscheidung 4

CLI, Tests, Benchmarks und Web-UI konsumieren denselben API-Kern.

Entscheidung 5

Monitoring, Docs und Inspector werden als normale Projektionen modelliert, nicht als Sondermechanismen.

16. Offene Punkte

  • Exakte Form des kanonischen EvalResult
  • Welche Artefaktklassen in Phase 1 schon verpflichtend sind
  • Ob ExpressionId source-span-basiert, lowering-basiert oder hybrid modelliert wird
  • Wie stark CompilerDb-ähnliches Caching auf Runtime-nahe Read Models ausgedehnt werden soll
  • Welche Queries öffentlich, intern oder debug-only sind
  • Ob Benchmark- und Testartefakte persistent versioniert werden

17. Kurzfazit

Die Jade-Control-Surface ist architektonisch dann sinnvoll, wenn sie als ein weiterer Client über stabile Systemgrenzen gedacht wird.

Nicht das Web-UI ist die eigentliche Innovation. Die eigentliche Innovation ist, dass Jade genügend strukturierte interne Wahrheiten besitzt, um daraus: - eine REPL, - einen Explain-Inspector, - eine Test- und Benchmark-Oberfläche, - eine Monitoring-Ansicht, - und eine ausführbare Dokumentation

auf demselben Kern aufzubauen.

Wenn diese Linie gehalten wird, entsteht kein UI-Spielzeug, sondern ein echtes Jade-Lab.