mxrb 0.1.3 → 0.1.4

data/docs/de-DE/project-structure.md

@@ -2,8 +2,18 @@
 
 [Português](../pt-BR/project-structure.md) · [English](../en-US/project-structure.md) · **Deutsch**
 
-Der von `mxrb export` erzeugte Baum trennt anwendungsweite Richtlinien,
-Modulverhalten, erhaltene native Units und Assets:
+`mxrb export` bietet zwei explizite Modi. `--mode mendix` ist der Standard und
+behält den geschichteten Mendix-DSL-Baum. `--mode ruby` erzeugt eine
+konventionelle ausführbare Ruby-Anwendung mit React + Vite.
+
+## Mendix-Modus
+
+```sh
+bundle exec mxrb export App.mpr app-source --mode mendix
+```
+
+Dieser Baum trennt anwendungsweite Richtlinien, Modulverhalten, erhaltene
+native Units und Assets:
 
 ```text
 project.rb
@@ -29,4 +39,193 @@ Die Struktur unterstützt Ruby zu einem neuen Mendix-Projekt, Ruby auf einem
 exportierten Baseline, Mendix zu bearbeitbarem Ruby und den strukturell
 gleichwertigen Mendix → Ruby → Mendix Round-trip.
 
+## Ruby-Modus
+
+Der Ruby-Modus kann auch ohne vorhandenes Mendix-Projekt beginnen:
+
+```sh
+bundle exec mxrb init CustomerPortal --mode ruby
+cd CustomerPortal
+bundle install
+npm install --prefix frontend
+bundle exec mxrb run .
+```
+
+Der Befehl erzeugt direkt die konventionelle Anwendung mit `app/models`,
+`app/dtos`, `app/services`, `app/pages` und React + Vite. Eine reversible
+Mendix-Basis bleibt unter `.mxrb` isoliert und bestimmt nicht die bearbeitbare
+Quellstruktur. Das aktuelle Projekt wird so als MPR materialisiert:
+
+```sh
+bundle exec mxrb generate project.rb build/CustomerPortal.mpr
+```
+
+Neue Ruby-Models werden zu Entitäten, DTOs zu nicht-persistenten Entitäten und
+bidirektionale Deklarationen werden in das MPR synchronisiert. Ruby- oder
+React-Code ohne native Mendix-Repräsentation bleibt mit Prüfsumme eingebettet
+und erscheint beim nächsten Export unverändert. Nicht darstellbare strukturelle
+Änderungen führen explizit zum Fehler, statt unbemerkt teilweise konvertiert zu
+werden.
+
+Ein vorhandenes MPR wird so konvertiert:
+
+```sh
+bundle exec mxrb export App.mpr app-ruby --mode ruby
+```
+
+```text
+app/
+  models/
+  dtos/
+  services/
+  pages/
+config/application.rb
+frontend/
+  package.json
+  vite.config.ts
+  tsconfig.json
+  src/{main.tsx,App.tsx,types.ts,nanoflows.ts,app.css}
+project.rb
+.mxrb/
+  ruby-app.json
+  runtime/App.mpr
+  mendix/
+```
+
+Persistente Entitäten werden Records. Nicht persistente Entitäten werden
+DTO-Klassen und verwenden immer das Suffix `_dto.rb`, wodurch mehrdeutige
+`_2.rb`-Namen entfallen. Services sind normale Ruby-Klassen und delegieren
+anfangs an den nativen Pure-Ruby-Interpreter. Pages stellen dem React-TypeScript-
+Frontend native Metadaten bereit. Der Export leitet `types.ts` aus Entitäten,
+Enumerationen, Pages, Widgets, Kontexten, Effekten und API-Verträgen ab;
+`npm run typecheck` ist Bestandteil des Vite-Builds.
+
+Nach der einmaligen Installation der Ruby- und Frontend-Abhängigkeiten startet
+ein einziger Befehl beide Prozesse:
+
+```sh
+bundle install
+npm install --prefix frontend
+bundle exec mxrb run .
+```
+
+`mxrb run` überwacht die über Puma 8 bereitgestellte Ruby-JSON-API auf Loopback
+und den Vite-Server. Vite
+leitet `/api` an Ruby weiter. `--server-port` legt den Backend-Port fest und
+`--client-port` den Frontend-Port. `--no-frontend` startet nur die API. Die
+bisherigen Namen `--api-port` und `--port` bleiben kompatible Aliase.
+Die globale Option `--no-progress` ist optional und blendet nur Fortschritt aus.
+
+Zwei optionale Stacks ergänzen vertraute Ruby-Konventionen, ohne den
+Standard-Ruby-Modus zu ändern:
+
+```sh
+bundle exec mxrb init ServiceDesk --mode ruby --flymetothemoon
+bundle exec mxrb export App.mpr app-rails --mode ruby --onrails
+```
+
+`--flymetothemoon` ergänzt Sinatra, Puma, ActiveRecord, Rake und RSpec.
+`--onrails` ergänzt Rails, Puma, ActiveRecord und RSpec. Beide behalten React +
+Vite als integriertes Anwendungs-Frontend und verwenden weiterhin
+`mxrb run .`. ActiveRecord-Migrationen besitzen nur Ruby-Tabellen; für das
+Mendix-Domain-Model und seine Round-trips bleibt das MXRB-Manifest maßgeblich.
+
+## Domain-Model-Diagramm im Browser
+
+Domain Models eines oder mehrerer Mendix-Module lassen sich als
+DBeaver-inspiriertes ER-Diagramm öffnen:
+
+```sh
+bundle exec mxrb diagram-er App.mpr --module Sales
+bundle exec mxrb diagram-er App.mpr --module Sales --module Billing \
+  --output build/App-layout.mpr
+```
+
+In der Seitenleiste lassen sich mehrere Module gleichzeitig auswählen und ihre
+modulübergreifenden Assoziationen anzeigen. Die Seite bietet außerdem
+Entitätssuche, Drag-and-drop-Positionierung, Zoom, Anpassen, Auto-Anordnung,
+Raster, Attributsichtbarkeit, Beziehungsrouting und ziehbare Quell-/Zielanker.
+Persistente Entitäten sind blau, DTOs/non-persistent gelb und OQL Views grün.
+**Layout im MPR speichern** schreibt Positionen und lokale Anker in native
+Mendix-Felder. Modulübergreifende Anker ohne natives BSON-Feld werden als
+isolierte visuelle MXRB-Metadaten in derselben sicheren Kopie gespeichert.
+Standard ist `App.domain-layout.mpr`; eine vorhandene Ausgabe darf nur mit
+`--force` ersetzt werden.
+
+**PNG exportieren** lädt ein hochauflösendes Bild der ausgewählten Module mit
+den aktuellen Farben, Attributen und Routen herunter. Der PNG-Export ändert das
+MPR nicht; das Layout muss separat gespeichert werden, wenn die Positionen
+einen Round-trip überstehen sollen.
+
+Der Vordergrundmodus bleibt verfügbar und belegt das Terminal bis `Ctrl+C`.
+Mit dem verwalteten Lifecycle läuft der ER-Editor im Hintergrund; beim Stoppen
+bleibt die Layout-Kopie erhalten und das Quell-MPR wird weder bearbeitet noch
+entfernt:
+
+```sh
+bundle exec mxrb diagram-er up App.mpr --module Sales
+bundle exec mxrb diagram-er status App.mpr
+bundle exec mxrb diagram-er down App.mpr
+bundle exec mxrb diagram-er up App.mpr       # dieselbe Kopie fortsetzen
+bundle exec mxrb diagram-er destroy App.mpr --yes
+```
+
+`destroy` stoppt den Server und entfernt ausschließlich die von diesem
+Lifecycle erzeugte Kopie samt externen Inhalten. Die Steuerung nutzt einen
+privaten authentifizierten Loopback-Endpunkt; Zustand und Token liegen in lokal
+zugriffsbeschränkten Dateien.
+
+Die Editor-Oberfläche ist in React + TypeScript implementiert und verwendet nur
+die APIs des Ruby-Servers. Das Vite-Bundle wird nach `lib/mxrb/web_ui`
+kompiliert, in die Gem aufgenommen und lokal ausgeliefert. Node.js ist daher
+für die Nutzung des installierten Editors nicht erforderlich, und es wird kein
+CDN kontaktiert. Für die UI-Entwicklung werden in `frontend/modeler`
+`npm install`, `npm run typecheck` und `npm run build` ausgeführt.
+ER, UML, OQL und das generische `--mode ruby`-Backend verwenden denselben
+eingebetteten Puma-Adapter. `puma ~> 8.0` ist eine direkte MXRB-Abhängigkeit und
+bringt transitiv `nio4r ~> 2.0` mit; WEBrick gehört nicht zum HTTP-Stack.
+
+## UML-Diagramme
+
+UML ist eine zusätzliche, vom ER-Editor unabhängige Implementierung. Sie nutzt
+Port 4569 und verändert das Domain-Model-Layout nicht. Der Viewer vereint
+Klassen-, Microflow-Aktivitäts- und Aufrufsequenzdiagramme mit Mermaid:
+
+Derselbe Server veröffentlicht unter `http://127.0.0.1:4569/modeler` einen
+visuellen React- und TypeScript-Katalog für Module, Seiten, Microflows und
+Nanoflows, Navigation, Sicherheit, Integrationen und Einstellungen. Diese erste
+erweiterte Oberfläche ist schreibgeschützt; Mutationen bleiben gesperrt, bis
+Fail-Closed-Validierung und Roundtrip-Garantien dem ER-Editor entsprechen.
+
+```sh
+bundle exec mxrb uml App.mpr
+bundle exec mxrb uml App.mpr --export=class --module Sales
+bundle exec mxrb uml App.mpr --export=activity \
+  --microflow=Sales.CreateOrder --format=plantuml
+bundle exec mxrb uml App.mpr --export=sequence \
+  --root=Sales.CreateOrder --depth=3
+bundle exec mxrb uml App.mpr --export=sequence --module=Sales
+```
+
+Ohne `--export` läuft der gemeinsame Viewer unter
+`http://127.0.0.1:4569`. Textexporte verwenden standardmäßig Mermaid;
+PlantUML wird mit `--format=plantuml` gewählt. Sequenzdiagramme akzeptieren
+entweder einen tiefenbegrenzten Einstiegspunkt oder alle internen Aufrufe eines
+Moduls. Der Viewer verwendet denselben React-+-TypeScript-Workspace; Mermaid ist
+lokal gebündelt, damit die Darstellung auch offline funktioniert.
+
+## Versionswechsel und Round-trips
+
+Beide Modi behalten stabile Mendix-IDs und die vollständige native Baseline für
+Upgrades, Downgrades und wiederholte Round-trips. Im Ruby-Modus werden
+Model-/DTO-Deklarationen zurück in das MPR kompiliert. Ruby-Service-Bodies und
+React-Quellen werden mit SHA-256 in einer MXRB-Quelltabelle innerhalb des MPR
+gespeichert; ein späterer Export mit `--mode ruby` stellt die exakt bearbeiteten
+Dateien wieder her.
+
+Für Konstrukte ohne semantischen Ruby-zu-Mendix-Compiler bleibt das native
+Mendix-Verhalten maßgeblich. Das Coverage-Manifest weist diesen Status explizit
+aus, statt eine stille Konvertierung zu behaupten. Der erhaltene Ruby-/React-
+Quellcode überlebt den Mendix-Round-trip auch ohne direkte Studio-Pro-Darstellung.
+
 [Zurück zum Index](README.md)

data/docs/de-DE/runtime-ruby.md

@@ -0,0 +1,104 @@
+# Runtime ohne Java
+
+Der Ruby-Modus startet das Backend ohne Mendix Java Runtime. Beim Öffnen einer
+exportierten Anwendung migriert MXRB automatisch eine umgebungsspezifische
+SQLite-Datenbank, öffnet den Microflow-Interpreter, registriert Lifecycle-Hooks,
+erzwingt die Sicherheit und startet Scheduled Events.
+
+Profile liegen unter `config/environments/`, typischerweise als
+`development.env`, `qa.env`, `staging.env` und `production.env`. Die Priorität
+lautet Prozessumgebung, Profildatei, `.env.<Profil>`, dann `.env`. Die Auswahl
+erfolgt mit `--environment qa` oder `MXRB_ENV=qa`; `mxrb env . --environment qa`
+zeigt Quellen und Schlüsselnamen, niemals Werte.
+
+```bash
+mxrb run . --environment qa
+mxrb test App.mpr smoke.rb --native --environment qa
+```
+
+Jedes Profil verwendet standardmäßig `.mxrb/runtime/<Umgebung>.sqlite3`. Die
+Migration leitet Entitäten, Attribute, Assoziationen und System-Member ab.
+Additive Änderungen sind idempotent, inkompatible Änderungen verwenden einen
+transaktionalen Rebuild. Nicht persistente Entitäten bleiben im Speicher.
+
+Die Ruby-API bietet Login und Bearer-Token, Sessions, Schema, Navigation,
+Seiten, Microflows, CRUD und Published REST. Rollen, Entitätsregeln,
+Member-Rechte und der sichere XPath-Teil werden für jede Anfrage geprüft.
+Zugangsdaten stammen aus `MXRB_USERS_JSON` und `MXRB_AUTH_TOKENS` und gehören in
+ignorierte lokale Dateien oder den Secret Manager des Deployments.
+
+Scheduled Events laufen im stdlib-basierten MXRB-Scheduler mit Minuten-,
+Stunden- und Tagesintervallen, Overlap-Schutz und kontrolliertem Shutdown.
+IANA-Zeitzonen wie `Europe/Berlin` verwenden `tzinfo` und berücksichtigen
+Sommerzeitwechsel. Unbekannte Zonen führen zu einem Fehler statt unbemerkt auf
+UTC zurückzufallen; `UTC`, `local` und numerische Offsets werden ebenfalls
+unterstützt.
+
+Sitzungen und Scheduler-Koordination verwenden standardmäßig die native
+SQLite-Datei `.mxrb/runtime/<Umgebung>-shared.sqlite3`, ohne externen Dienst.
+Mehrere Instanzen müssen mit `MXRB_SHARED_STORE_PATH` dieselbe Datei verwenden.
+Idempotente Claims pro Ereignis/Zeitfenster und per Heartbeat erneuerte
+Overlap-Leases sind atomar; ein unvollständiger Claim kann nach Lease-Ablauf
+übernommen werden. Der Standard-Lease beträgt 300 Sekunden und lässt sich über
+`MXRB_SCHEDULER_LEASE_TTL` ändern. `:memory:`, `memory` oder `local` aktivieren
+explizit den prozesslokalen Modus.
+
+Java Custom Actions starten niemals eine JVM. Jede erlaubte Action benötigt
+einen expliziten Ruby-Adapter, der in `config/adapters.rb` unter dem
+qualifizierten Namen registriert wird:
+
+```ruby
+Mxrb::RubyApp::Registry.register_java_custom_action('Orders.CalculateTotal') do |arguments|
+  Calculator.call(
+    items: arguments.fetch('Items'),
+    discount: arguments.fetch('Discount')
+  )
+end
+```
+
+Die Schlüssel sind die Parameternamen aus dem Mendix-Modell. Basiswerte werden
+im Microflow-Kontext ausgewertet; Entity-, Microflow- und Mapping-Referenzen
+werden als qualifizierte Namen übergeben. Der Rückgabewert wird nur bei aktivem
+`UseReturnVariable` zugewiesen (oder beim Legacy-Format, das ausschließlich
+`ResultVariableName` deklariert). Eine nicht registrierte Action schlägt mit
+ihrem Namen und einem Registrierungshinweis geschlossen fehl; es gibt weder
+Klassenerkennung noch JAR-Ausführung oder JVM-Fallback. REST, App Services, SOAP,
+Mappings und Dokumenterzeugung verwenden weiterhin typbezogene Ruby-Adapter.
+Im Browser bleibt JavaScript/React; Backend und APIs laufen ohne Java Runtime.
+
+## Ruby → Mendix → Ruby-Zertifizierung
+
+Das reproduzierbare Zertifizierungsszenario befindet sich in
+[`spec/fixtures/flymetothemoon/project.rb`](../../spec/fixtures/flymetothemoon/project.rb).
+Es modelliert Kunden, Produkte, Bestellungen und Positionen in Ruby, inklusive
+Enumeration, Indizes, Assoziationen, Microflows, Nanoflow, Scheduled Event und
+einer Seite mit Data Grid. Der Test
+[`spec/flymetothemoon_roundtrip_spec.rb`](../../spec/flymetothemoon_roundtrip_spec.rb)
+prüft folgende Anwendungsfälle:
+
+- ein Mendix-11.12.1-MPR aus der Ruby-DSL erzeugen und validieren;
+- über die echte CLI mit `--mode ruby --flymetothemoon` exportieren;
+- Sinatra, Puma, ActiveRecord und RSpec bereitstellen, ohne Java-, JAR- oder
+  Bytecode-Dateien zu erzeugen;
+- Erzeugung, Aggregation, Verzweigung, CRUD und Seitenmetadaten in der
+  Ruby-Runtime mit SQLite ausführen;
+- eine unveränderte Anwendung kompilieren und das MPR strukturell mit der
+  Quelle vergleichen;
+- ein Attribut hinzufügen und einen Microflow durch idiomatisches Ruby ersetzen;
+- erneut exportieren und nachweisen, dass Ruby-Code und Mendix-Modell einen
+  zweiten strukturell identischen Roundtrip überstehen.
+
+Der isolierte Test wird so ausgeführt:
+
+```bash
+bundle exec rspec spec/flymetothemoon_roundtrip_spec.rb
+```
+
+Für generierte Oberflächen wird das deklarative Szenario
+[`spec/fixtures/frontend_browser/sudoku_full_flow.json`](../../spec/fixtures/frontend_browser/sudoku_full_flow.json)
+mit `script/frontend_browser_acceptance` in einem echten Chromium ausgeführt.
+Es deckt die Brettpositionen 73 und 74, Auswahl, Werteingabe sowie den Wechsel
+zwischen Easy, Medium und Hard ab. Jeder kritische Klick wartet auf Microflow-POST
+und Assoziations-GET und muss innerhalb von 250 ms enden. Galerieabfragen werden
+in SQLite nach Kontext gefiltert; über eine inverse Assoziation geladene Objekte
+behalten ihre Verknüpfung, wenn nur Attribute gespeichert werden.

data/docs/de-DE/runtime-schema-migrations.md

@@ -0,0 +1,44 @@
+# Schema-Migrationen der Ruby-Runtime
+
+`Mxrb::Runtime::SchemaMigrator` identifiziert Mendix-Entitäten, Attribute und
+Assoziationen anhand ihrer Storage-GUID. Wird ein Artefakt bei gleicher GUID
+umbenannt, bleiben die physische Tabelle beziehungsweise Spalte und ihre Daten
+erhalten.
+
+## Sichere Richtlinie
+
+- Tabellen und optionale Attribute werden automatisch und idempotent angelegt.
+- Pflichtattribute werden als `NOT NULL` erzeugt.
+- Wird ein vorhandenes Attribut verpflichtend, wird die Tabelle innerhalb
+  einer Transaktion neu aufgebaut. Vorhandene `NULL`-Werte verwenden den
+  deklarierten Standardwert; ohne Standardwert wird die Migration abgelehnt.
+- Ein neues Pflichtattribut in einer befüllten Tabelle benötigt einen
+  Standardwert.
+- Kompatible Änderungen erhalten Entitäts- und Assoziationsdaten.
+- Das Entfernen einer Entität, eines Attributs oder einer Assoziation löst
+  standardmäßig `Mxrb::Runtime::UnsafeSchemaMigrationError` aus und verändert
+  die Datenbank nicht.
+- Nach Prüfung des Plans und einem Backup kann die Bereinigung mit
+  `allow_destructive: true` freigegeben werden. Entfernt werden ausschließlich
+  in den MXRB-Metadaten registrierte Artefakte; fremde Tabellen werden niemals
+  abgeleitet oder gelöscht.
+
+Exportierte Ruby-Anwendungen deaktivieren destruktive Migrationen. Für einen
+kontrollierten Lauf nach einem Backup kann im gewählten Umgebungsprofil
+`MXRB_ALLOW_DESTRUCTIVE_MIGRATIONS=true` gesetzt werden. Jeder andere Wert
+bleibt fail-closed.
+
+```ruby
+database = SQLite3::Database.new('runtime.sqlite3')
+migrator = Mxrb::Runtime::SchemaMigrator.new(
+  project,
+  database: database,
+  allow_destructive: true
+)
+result = migrator.migrate!
+puts migrator.migration_plan.changes
+```
+
+DDL, Datenkopie, Metadaten-Update und freigegebene Bereinigung laufen in einer
+gemeinsamen SQLite-Transaktion. Eine Constraint-Verletzung oder ein anderer
+Fehler setzt die gesamte Migration zurück.

data/docs/de-DE/validation-matrix.md

@@ -2,7 +2,7 @@
 
 [Português](../pt-BR/validation-matrix.md) · [English](../en-US/validation-matrix.md) · **Deutsch**
 
-Stand: 5. August 2026.
+Stand: 11. August 2026.
 
 ```text
 Original-MPR → validate → export → generate → validate → compare
@@ -17,6 +17,25 @@ Original-MPR → validate → export → generate → validate → compare
 | TreeviewDemo | 5.21.4 | v1 | bestanden |
 | GridViewPlayground | 6.10.8 | v1 | bestanden |
 
+Am 11. August wiederholte `script/validate_matrix` die Matrix mit **6/6
+erfolgreichen Läufen**: 1.506 Units, 1.734 Artefakte und 3.388 Referenzen in
+16,381 Sekunden.
+
+## Zusätzliches lokales Inventar
+
+`script/certify_mprs --cycles 2 --repair-hashes` zertifizierte sieben weitere
+MPRs in 14 aufeinanderfolgenden Roundtrips: **7/7 bestanden**, 2.799 Units,
+3.238 Artefakte und 4.819 Referenzen. Enthalten sind LearnNow, SLATaskApp,
+SLATaskAppNative, MyFirstModule, CourseManager, RubyBridgeSandbox und
+VetClinic.
+
+SLATaskApp enthielt einen veralteten Content-Hash, RubyBridgeSandbox zwei. Das
+Gate reparierte ausschließlich `Unit.ContentsHash` in temporären Kopien,
+protokollierte die geänderten UUIDs und bewahrte die ursprünglichen BSON-Bytes.
+Die Quelldateien wurden nicht verändert. Der zweite Roundtrip deckte außerdem
+als Strings deserialisierte Native-Widget-Typen auf und führte zu deren
+Korrektur.
+
 ## Tiefe Abdeckung
 
 Der Vergleich umfasst Metadaten, Security, Unit-Baum, Entitäten,
@@ -37,9 +56,9 @@ Gate.
 ## Semantik, Tests und Runtime
 
 - 1.778 Artefakte und 3.387 Referenzen;
-- 1.039 Beispiele, keine Fehler;
-- 100 % Zeilenabdeckung (17.224/17.224);
-- 100 % Branch-Abdeckung (6.811/6.811);
+- 1.329 Beispiele, keine Fehler;
+- 100 % Zeilenabdeckung (23.771/23.771);
+- 100 % Branch-Abdeckung (9.704/9.704);
 - Sudoku-Modellbewertung: 7/7;
 - funktionale Runtime-Tests: 3/3 lokal und 3/3 in Docker.
 
@@ -62,3 +81,22 @@ Deterministisches Fuzzing deckt 250 BSON-Dokumente und 50 atomare
 
 Die Matrix beweist die geprüften Szenarien, nicht universelle Kompatibilität
 mit jedem Mendix-Metamodell. Unbekannte `.mxunit`-Kodierungen werden abgelehnt.
+
+## Widget-Zertifizierung
+
+`script/certify_widgets --browser-report REPORT.json App.mpr` ist das
+Fail-Closed-Gate für tatsächlich verwendete Widgets des nativen Web-Compilers
+und Marketplace-Widgets. Es
+verlangt gemeinsam eine Page/Layout-Kompilierung ohne Fallback, die Auflösung
+jeder Pluggable-ID auf einen MPK-`.mjs`-Eintrag samt SHA-256, einen nativen
+Rspack-Build der Mendix-Version und bestandene Chromium-Evidenz, die alle
+geprüften Widget-Typen und IDs ohne sichtbare Runtime-/Widget-Fehler ausweist.
+
+Der MPK-Import oder ein erfolgreicher Bundle-Build allein zertifiziert kein
+Verhalten. Widgets mit erforderlicher Datenquelle, Attributbindung oder
+Elternplatzierung bestehen nur in einem korrekt konfigurierten Browserszenario.
+Zukünftige oder ungeprüfte Pakete scheitern als fehlende Evidenz, statt eine
+pauschale Kompatibilitätszusage zu erben.
+Das React/TypeScript-Frontend von `--mode ruby` besitzt eine getrennte Spur:
+Sein Chromium-Bericht zertifiziert diese Widgets, ohne zu behaupten, dass die
+entsprechenden Pluggable-Komponenten auch im Mendix Runtime bestanden haben.

data/docs/en-US/README.md

@@ -13,6 +13,7 @@
 - [Ruby-first roadmap](ruby-first-roadmap.md)
 - [Validation matrix](validation-matrix.md)
 - [Native compiler and Runtime](compiler.md)
+- [Java-free Ruby runtime and environments](runtime-ruby.md)
 - [Native build and Runtime quality report](native-runtime-quality-report.md)
 - [Writing projects](writing.md)
 - [Project scaffolds](scaffolds.md)

data/docs/en-US/oql-sql.md

@@ -42,6 +42,47 @@ Always verify physical table and column names against the database created by
 the exact Mendix Runtime. Association-path joins are reported as unsupported
 until Runtime storage metadata can prove the correct join.
 
+## Safe SQL-to-OQL conversion
+
+The reverse path accepts a read-only `SELECT` subset in PostgreSQL, SQL Server,
+or ANSI and emits logical OQL. Supplying the project restores the exact module,
+entity, and attribute casing:
+
+```ruby
+projection = Mxrb.open("Shop.mpr") do |project|
+  project.sql_to_oql(
+    'SELECT p."name" FROM "shop$product" p WHERE p."name" = :Name',
+    dialect: :postgresql
+  )
+end
+
+puts projection.oql if projection.supported?
+# SELECT p/Name FROM Shop.Product p WHERE p/Name = $Name
+```
+
+The unified `query` command converts in both directions. `--input -` reads
+stdin and `--json` returns the typed result:
+
+```sh
+bundle exec mxrb query \
+  'SELECT p."name" FROM "shop$product" p WHERE p."name" = :Name' \
+  --from sql --to oql --project Shop.mpr --dialect postgresql
+bundle exec mxrb query 'SELECT p/Name FROM Shop.Product p' \
+  --from oql --to sql --dialect sql_server
+bundle exec mxrb query --input query.sql --from sql --dialect sql_server --json
+```
+
+The subset includes aliases, explicit joins, comma-separated sources,
+`WHERE`, `GROUP BY`, `HAVING`, `UNION`, `ORDER BY`, `LIMIT`/`OFFSET`, known OQL
+functions, and named parameters (`:Name`, `@Name`, or `$Name`). Physical
+`module$entity` tables become `Module.Entity`; without `--project`, casing is
+inferred and the result has `inferred` confidence.
+
+Writes, multiple statements, CTEs, table subqueries in `FROM`/`JOIN`, positional
+parameters, unknown functions, and extensions without a safe OQL equivalent—such as `ILIKE`, `DISTINCT ON`,
+`TOP`, `::`, and `||` concatenation—return `supported? == false` with an
+explanation in `warnings`.
+
 ## Dialect-aware analysis
 
 `Oql::Analyzer` detects cost and portability patterns in the original source,