@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/rmt-vnext-primitive-migration.md

@@ -0,0 +1,119 @@
+# RMT vNext Primitive Migration
+
+- Contract: `xtend.rmt.vnext.primitive-migration-preview.v1`
+- Workpackage: `RMT-VNEXT-PRIM-08`
+- Status: `in_progress`
+- Source fixture: `tests/fixtures/rmt-app-platform-tooling.rmt`
+- Local gate: `node scripts/run_xtend_tests.js rmt-vnext-compatibility --json`
+
+## Ziel
+
+`RMT-VNEXT-PRIM-08` schiebt Legacy- und App-Platform-JSON-Authoring in den
+Hintergrund. Bestehende App-Platform-Primitive-Records bleiben als
+Compiler-Target und Compatibility-Evidence erhalten, aber die primaere
+Authoring-Flaeche ist RMT vNext.
+
+Der Migrationspfad erzeugt deshalb keinen neuen Legacy-Arbeitsmodus. Er erzeugt
+einen vNext-Preview-Draft aus vorhandenen App-Platform-Records und kompiliert
+diesen Draft direkt wieder durch den vNext-Compiler. Erst wenn dieser Draft
+State, DataSources, Actions, Events, Portals, Overlays, Resources, Surfaces,
+Lanes und Kernel-Records absenken kann, gilt die Migration als kompatibel.
+
+## Preview- und Apply-Plan-Vertrag
+
+Die API `createAppPlatformPrimitiveMigrationPreview(...)` erkennt
+App-Platform-JSON-Dokumente mit Primitive-Domains wie `state`, `dataSources`,
+`actions`, `events`, `portals`, `overlays`, `resources` und `surfaces`.
+
+Der Preview-Report enthaelt:
+
+- `schema: "xtend.rmt.vnext.primitive-migration-preview.v1"`
+- `workpackage: "RMT-VNEXT-PRIM-08"`
+- `languageMode: "legacy-app-platform-json"`
+- `vNextAuthoring.role: "default"`
+- `legacyAuthoring.role: "compiler-target"`
+- `legacyAuthoring.backgrounded: true`
+- `authoringDraft` mit vNext-Primitive-Syntax
+- `authoringDraftCompileStatus: "compiled"`
+- `projection.appPlatform` und `projection.kernelRecords`
+- `domainMapping` fuer die erkannten Primitive-Familien
+
+Report-only-Mode schreibt keine Quelle um. Er meldet stattdessen
+`rmt.vnext.migration.opt_in_required` und
+`rmt.vnext.primitive_migration.preview_available`. Preview-Mode ist bewusst
+opt-in, damit vorhandene downstream Fixtures nicht still migriert werden.
+
+Die API `createAppPlatformPrimitiveMigrationApplyPlan(...)` baut darauf auf
+und erzeugt einen deterministischen Apply-Plan:
+
+- `schema: "xtend.rmt.vnext.primitive-migration-apply-plan.v1"`
+- `status: "apply-plan-ready"`, wenn der vNext-Draft kompiliert und eine
+  Projektion erzeugt werden kann
+- `status: "blocked"`, wenn JSON-Parsing oder vNext-Kompilation fehlschlagen
+- `targetPath` als Zielpfad-Hinweis, standardmaessig
+  `<quelle>.vnext.rmt`
+- `automaticWrite: false`
+- `writePolicy: "manual-apply-only"`
+
+Der Apply-Plan fuehrt keinen Datei-Write aus. Er ist ein pruefbarer Handoff
+fuer Agenten, CLIs oder Editoren, die den vNext-Draft nach Review in einen
+neuen Authoring-Pfad uebernehmen wollen. Legacy/App-Platform-JSON bleibt dabei
+Mirror und Compiler-Target, nicht die Benutzeroberflaeche.
+
+## Authoring-Draft
+
+Das App-Platform-Fixture wird in eine vNext-Shell dieser Form ueberfuehrt:
+
+```rmt
+template epic18.app-platform-tooling.fixture {
+  state items type collection initial []
+
+  datasource items from fixture records.generic-items {
+    contract "domain.record.generic-item.v1[]"
+  }
+
+  action load-items {
+    effect fetch datasource items
+    reduce state.items = result.records
+  }
+
+  portal app root "#app-root" layer surface
+
+  surface workspace kind window component workspace {
+    repeat from datasource items
+    portal app
+
+    lane visible weight 70 {
+      hydrate workspace from datasource items
+    }
+
+    on open-detail target ref.row -> action open-detail {
+      payload id from detail.id
+    }
+  }
+}
+```
+
+Die Preview normalisiert bekannte App-Platform-Prefixes fuer vNext-Authoring:
+`state.items` wird zu `state items`, `datasource.items` zu
+`datasource items`, `surface.workspace` zu `surface workspace` und
+`action.open-detail` zu `action open-detail`. Runtime- und Kernel-Records
+bleiben ueber die Compiler-Projektion korrelierbar.
+
+## Gate-Erwartung
+
+Das Compatibility-Gate prueft fuer PRIM-08:
+
+- App-Platform-Primitive-JSON wird als `legacy-app-platform-json` erkannt.
+- Report-only-Mode verlangt explizites Preview-Opt-in.
+- Preview-Mode erzeugt einen vNext-Draft und kompiliert ihn.
+- Apply-Plan-Mode erzeugt denselben Draft, einen Zielpfad-Hinweis und eine
+  blockierende Compile-/Parse-Pruefung, ohne Dateien zu schreiben.
+- Die Projektion enthaelt App-Platform- und Kernel-Records.
+- Legacy wird als `compiler-target` markiert, nicht als Authoring-Pfad.
+- Die Compatibility-Matrix akzeptiert App-Platform-Preview und native vNext-
+  Quelle gemeinsam.
+
+Damit wird die Upgrade-Regel testbar: Legacy ist weiterhin beweisbar
+kompatibel, aber die Developer Experience fuer neue App-Shell-Arbeit liegt in
+vNext.

package/docs/rmt-vnext-primitive-parser-ast.md

@@ -0,0 +1,76 @@
+# RMT vNext Primitive Parser AST
+
+- Contract: `xtend.rmt.vnext-primitive-parser-ast.v1`
+- Workpackage: `RMT-VNEXT-PRIM-02`
+- Status: `completed`
+- Parent backlog: [RMT vNext Primitive Compiler Backlog](./rmt-vnext-primitives-compiler-backlog.md)
+- Grammar contract: [RMT vNext Primitive Grammar Design](./rmt-vnext-primitive-grammar-design.md)
+- Parser module: `tools/rmt-language/vnext-parser.js`
+- Parser suite: `tests/rmt-language/rmt_vnext_parser_suite.js`
+- Fixture: `tests/rmt-language/fixtures/vnext-primitives-grammar-design.rmt`
+
+## Ziel
+
+PRIM-02 erweitert den bestehenden vNext-Parser so, dass die in PRIM-01
+definierte Primitive-Syntax als echte AST-Nodes sichtbar wird. Der Slice bleibt
+abwaertskompatibel mit der bisherigen `template/surface/lane`-Syntax.
+
+Compiler-Lowering und Kernel-Ingestion bleiben Folgearbeit in
+`RMT-VNEXT-PRIM-04`. Die erste App-Graph-Semantik ist in
+`RMT-VNEXT-PRIM-03` gestartet.
+
+## Implementierter Parser-Umfang
+
+Der Parser akzeptiert jetzt die Design-Fixture
+`vnext-primitives-grammar-design.rmt` ohne Syntaxdiagnosen und erzeugt
+initiale AST-Nodes fuer:
+
+| Primitive | AST Nodes |
+|-----------|-----------|
+| State | `RmtStateDeclaration`, `RmtInitialBlock`, `RmtInitialValueEntry`, `RmtPrimitiveValue`, `RmtTypeReference` |
+| Selector | `RmtSelectorDeclaration`, `RmtSelectorWhereClause`, `RmtSelectorFindClause`, `RmtSelectorSortClause`, `RmtSelectorOutputClause` |
+| DataSource | `RmtDataSourceDeclaration`, `RmtPrimitiveSourceReference`, `RmtDataSourceMethodClause`, `RmtDataSourceContractClause`, `RmtDataSourceResultClause`, `RmtDataSourceFallbackClause` |
+| Action | `RmtActionDeclaration`, `RmtActionInputClause`, `RmtActionStatusClause`, `RmtEffectStatement`, `RmtReducerStatement`, `RmtEmitStatement`, `RmtActionResultHandler` |
+| Portal | `RmtPortalDeclaration`, `RmtPrimitiveAttribute`, `RmtPortalPolicyClause` |
+| Overlay | `RmtOverlayDeclaration`, `RmtOverlayPolicyClause` |
+| Resource | `RmtResourceDeclaration`, `RmtResourceImportClause`, `RmtResourceSourceClause`, `RmtResourceDisposeClause` |
+| Surface | erweiterte `RmtSurfaceDeclaration`, `RmtSurfaceHeaderClause`, `RmtSurfaceSourceClause`, `RmtSurfaceRepeatClause`, `RmtSurfaceKeyClause`, `RmtSurfacePortalClause`, `RmtSurfaceBoundsClause`, `RmtSurfacePreserveClause`, `RmtSurfaceDestroyClause` |
+| Event | erweiterte `RmtEventBinding`, `RmtEventSelector`, `RmtEventPayloadBlock`, `RmtEventPayloadMapping`, `RmtEventOptionClause` |
+
+## Parser-Grenzen
+
+- Selector-Ausdruecke wie `contains(record.name, state.media.filters.query)`
+  werden in PRIM-02 als deklarative Raw-Clause mit Source Range erhalten.
+  Die semantische Operator-AST folgt in PRIM-03.
+- Action-Result-Handler wie `on success -> reduce ...` erhalten den Effekttext
+  und die Source Range. Typisierte Effect-Nodes folgen in PRIM-03/04.
+- Der Compiler ignoriert unbekannte Template-Body-Nodes weiterhin, damit
+  bestehende vNext-Core-Builds stabil bleiben. Primitive-Lowering ist PRIM-04.
+- Der RMT-Kernel wird in PRIM-02 nicht ingestiert. Das Source-to-Sea-Gate ist
+  PRIM-06.
+
+## Verifikation
+
+Direkte lokale Checks:
+
+```bash
+node --check tools/rmt-language/vnext-parser.js
+node --check tests/rmt-language/rmt_vnext_parser_suite.js
+node -e "const { runRmtVNextParserSuite } = require('./tests/rmt-language/rmt_vnext_parser_suite'); const result = runRmtVNextParserSuite(); process.exit(result.ok ? 0 : 1)"
+node -e "const { runRmtVNextCompilerSuite } = require('./tests/rmt-language/rmt_vnext_compiler_suite'); const result = runRmtVNextCompilerSuite(); process.exit(result.ok ? 0 : 1)"
+```
+
+Der globale Runner `node scripts/run_xtend_tests.js rmt-vnext-parser --json`
+ist aktuell durch bestehende Merge-Conflict-Marker in
+`tests/references/reference_path_suite.js` blockiert, weil der Runner diese
+Suite beim Start importiert.
+
+## Handoff
+
+- `RMT-VNEXT-PRIM-03`: [RMT vNext Primitive Semantic Graph](./rmt-vnext-primitive-semantic-graph.md)
+  baut Indexe, Referenzen und Pre-Runtime-Diagnostics fuer die Primitive-AST-
+  Nodes auf.
+- `RMT-VNEXT-PRIM-04`: Primitive-AST und Semantic Graph in Core-/App-Platform-
+  Records absenken.
+- Language Server nachziehen: completions, hover, symbols und code actions fuer
+  die neuen Node-Typen.

package/docs/rmt-vnext-primitive-semantic-graph.md

@@ -0,0 +1,118 @@
+# RMT vNext Primitive Semantic Graph
+
+- Contract: `xtend.rmt.vnext.primitive-semantic-graph.v1`
+- Workpackage: `RMT-VNEXT-PRIM-03`
+- Status: `completed`
+- Quelle: Media-Manager-Downstream-Transfer, `2026-05-19`
+
+## Ziel
+
+`RMT-VNEXT-PRIM-03` macht vNext-Primitives vor der Runtime semantisch
+sichtbar. Der Parser liefert typisierte AST-Knoten; der neue Graph baut daraus
+Indexe, Referenzen, Diagnostics und Completion-Hints fuer die App-Platform-
+Primitives.
+
+Die API ist additiv:
+
+```js
+const {
+  buildRmtVNextPrimitiveSemanticGraph
+} = require('./tools/rmt-language/semantic-graph');
+
+const graph = buildRmtVNextPrimitiveSemanticGraph({ text, filePath });
+```
+
+Der bestehende `buildSemanticGraph(...)` fuer Legacy/Core-RMT bleibt stabil.
+Der vNext-Primitive-Graph ist der neue Handoff zwischen Parser und spaeterem
+Lowering in Kernel Records.
+
+## Index-Domains
+
+Der Graph erzeugt eigene Domains fuer:
+
+- `states`
+- `selectors`
+- `dataSources`
+- `actions`
+- `surfaces`
+- `portals`
+- `overlays`
+- `resources`
+- `events`
+
+Jede Domain stellt `records`, `byId`, `ids` und Duplicate-Diagnostics bereit.
+Zusaetzlich liefert `catalogHints` direkt nutzbare IDs fuer Completions und
+Docs.
+
+## Referenzmodell
+
+PRIM-03 prueft die wichtigsten vNext-Primitive-Kanten:
+
+- Selector -> State
+- Action Effect -> DataSource
+- Reducer -> State
+- Surface Source/Repeat/Lifecycle -> Selector oder State
+- Surface -> Portal
+- Overlay -> Portal
+- Resource -> Owner Surface/Overlay
+- Resource Source -> Selector/State/Resource
+- Surface Destroy -> Resource
+- Event -> Action
+
+Die Referenzen sind analog zum bestehenden Semantic Graph aufgebaut:
+
+- `references.records`
+- `references.bySourcePointer`
+- `references.byTargetId`
+- `references.unresolved`
+
+Damit bleibt der spaetere Language-Server-Pfad fuer Go-to-Definition,
+References und Completion konsistent.
+
+## Diagnostics
+
+PRIM-03 fuehrt diese vNext-Primitive-Diagnostics ein:
+
+| Code | Bedeutung |
+|------|-----------|
+| `rmt.vnext.primitive.duplicate-id` | Ein Primitive ist in derselben Domain mehrfach definiert. |
+| `rmt.vnext.primitive.unknown-reference` | Eine Primitive-Referenz kann nicht aufgeloest werden. |
+| `rmt.vnext.primitive.owner-missing` | Eine Resource besitzt keinen Surface- oder Overlay-Owner. |
+| `rmt.vnext.primitive.unkeyed-repeat` | Ein Surface-Repeater besitzt keine `key`-Klausel. |
+| `rmt.vnext.primitive.payload-contract-missing` | Event oder Emit fuehrt zu Runtime-Payload ohne Contract. |
+| `rmt.vnext.primitive.initial-missing` | Ein State besitzt keinen initialen Wert. |
+| `rmt.vnext.primitive.resource-kind-missing` | Eine Resource besitzt keinen `kind`. |
+| `rmt.vnext.primitive.action-reducer-missing` | Eine Action besitzt Input, Status oder Effect, aber kein Reducer-Ziel. |
+| `rmt.vnext.primitive.effect-source-missing` | Ein `effect fetch` besitzt keine DataSource-, Selector- oder Resource-Quelle. |
+| `rmt.vnext.primitive.unsafe-html` | Unsicheres HTML wird ohne Trust Boundary sichtbar. |
+| `rmt.vnext.primitive.kernel-boundary` | Primitive-Import verletzt Kernel-/Fabric-Grenzen. |
+
+Die negative Fixture
+`tests/rmt-language/fixtures/vnext-primitives-semantic-invalid.rmt` beweist
+Cross-Reference-, Ownership-, Event-Payload-, Repeater- und Kernel-Boundary-
+Fehler als Pre-Runtime-Diagnostics.
+
+## Evidence
+
+Die Semantic-Graph-Suite prueft beide Richtungen:
+
+- `tests/rmt-language/fixtures/vnext-primitives-grammar-design.rmt` muss als
+  positiver vNext-Primitive-Graph ohne Error-Diagnostics indexieren.
+- `tests/rmt-language/fixtures/vnext-primitives-semantic-invalid.rmt` muss die
+  erwarteten PRIM-03-Diagnostics liefern.
+
+Gezielte lokale Gates:
+
+```bash
+node --check tools/rmt-language/semantic-graph.js
+node --check tests/rmt-language/rmt_semantic_graph_suite.js
+node -e "const suite=require('./tests/rmt-language/rmt_semantic_graph_suite'); const result=suite.runRmtSemanticGraphSuite({rootDir:process.cwd()}); process.exit(result.ok ? 0 : 1);"
+```
+
+## Naechster Handoff
+
+`RMT-VNEXT-PRIM-04` nutzt den neuen Graph als Lowering-Input. Der Compiler
+stoppt Primitive-Quellen mit Semantic-Errors vor dem Core-Output und erzeugt
+fuer valide Quellen deterministische Kernel-/App-Platform-Records.
+
+Handoff: [RMT vNext Primitive Lowering](./rmt-vnext-primitive-lowering.md)