@decaf-ts/as-graph 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (146) hide show
  1. package/README.md +167 -5
  2. package/dist/as-graph.cjs +1 -1
  3. package/dist/as-graph.cjs.map +1 -1
  4. package/dist/as-graph.js +1 -1
  5. package/dist/as-graph.js.map +1 -1
  6. package/lib/cjs/dagster/DagsterGraphExecutionBackend.cjs +102 -11
  7. package/lib/cjs/dagster/DagsterGraphExecutionBackend.cjs.map +1 -1
  8. package/lib/cjs/dagster/DagsterGraphQLClient.cjs +738 -0
  9. package/lib/cjs/dagster/DagsterGraphQLClient.cjs.map +1 -0
  10. package/lib/cjs/dagster/index.cjs +1 -0
  11. package/lib/cjs/dagster/index.cjs.map +1 -1
  12. package/lib/cjs/engine/execution/GraphExecutionEngine.cjs +7 -0
  13. package/lib/cjs/engine/execution/GraphExecutionEngine.cjs.map +1 -1
  14. package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs +39 -0
  15. package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs.map +1 -1
  16. package/lib/cjs/engine/index.cjs +1 -0
  17. package/lib/cjs/engine/index.cjs.map +1 -1
  18. package/lib/cjs/engine/services/GraphNodeModelService.cjs +129 -0
  19. package/lib/cjs/engine/services/GraphNodeModelService.cjs.map +1 -0
  20. package/lib/cjs/engine/services/GraphWorkflowService.cjs +33 -0
  21. package/lib/cjs/engine/services/GraphWorkflowService.cjs.map +1 -1
  22. package/lib/cjs/mastra/MastraDefaultStepHandlers.cjs +217 -0
  23. package/lib/cjs/mastra/MastraDefaultStepHandlers.cjs.map +1 -0
  24. package/lib/cjs/mastra/MastraEventBridge.cjs +10 -3
  25. package/lib/cjs/mastra/MastraEventBridge.cjs.map +1 -1
  26. package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs +111 -13
  27. package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs.map +1 -1
  28. package/lib/cjs/mastra/MastraWorkflowCompiler.cjs +3 -3
  29. package/lib/cjs/mastra/MastraWorkflowCompiler.cjs.map +1 -1
  30. package/lib/cjs/mastra/index.cjs +1 -0
  31. package/lib/cjs/mastra/index.cjs.map +1 -1
  32. package/lib/cjs/mastra/types.cjs +5 -1
  33. package/lib/cjs/mastra/types.cjs.map +1 -1
  34. package/lib/cjs/nest/graph/GraphBackendHost.cjs +232 -0
  35. package/lib/cjs/nest/graph/GraphBackendHost.cjs.map +1 -0
  36. package/lib/cjs/nest/graph/GraphExecutionModule.cjs +38 -1
  37. package/lib/cjs/nest/graph/GraphExecutionModule.cjs.map +1 -1
  38. package/lib/cjs/nest/graph/index.cjs +1 -0
  39. package/lib/cjs/nest/graph/index.cjs.map +1 -1
  40. package/lib/cjs/nest/graph/main.cjs +112 -12
  41. package/lib/cjs/nest/graph/main.cjs.map +1 -1
  42. package/lib/cjs/ram/GraphNodeRepository.cjs +40 -0
  43. package/lib/cjs/ram/GraphNodeRepository.cjs.map +1 -0
  44. package/lib/cjs/ram/index.cjs +1 -0
  45. package/lib/cjs/ram/index.cjs.map +1 -1
  46. package/lib/cjs/shared/graph/GraphNodeConverters.cjs +43 -0
  47. package/lib/cjs/shared/graph/GraphNodeConverters.cjs.map +1 -0
  48. package/lib/cjs/shared/graph/GraphNodeModel.cjs +74 -0
  49. package/lib/cjs/shared/graph/GraphNodeModel.cjs.map +1 -0
  50. package/lib/cjs/shared/graph/index.cjs +2 -0
  51. package/lib/cjs/shared/graph/index.cjs.map +1 -1
  52. package/lib/esm/dagster/DagsterGraphExecutionBackend.js +102 -11
  53. package/lib/esm/dagster/DagsterGraphExecutionBackend.js.map +1 -1
  54. package/lib/esm/dagster/DagsterGraphQLClient.js +733 -0
  55. package/lib/esm/dagster/DagsterGraphQLClient.js.map +1 -0
  56. package/lib/esm/dagster/index.js +1 -0
  57. package/lib/esm/dagster/index.js.map +1 -1
  58. package/lib/esm/engine/execution/GraphExecutionBackend.js.map +1 -1
  59. package/lib/esm/engine/execution/GraphExecutionEngine.js +7 -0
  60. package/lib/esm/engine/execution/GraphExecutionEngine.js.map +1 -1
  61. package/lib/esm/engine/execution/LocalGraphExecutionBackend.js +39 -0
  62. package/lib/esm/engine/execution/LocalGraphExecutionBackend.js.map +1 -1
  63. package/lib/esm/engine/index.js +1 -0
  64. package/lib/esm/engine/index.js.map +1 -1
  65. package/lib/esm/engine/services/GraphNodeModelService.js +120 -0
  66. package/lib/esm/engine/services/GraphNodeModelService.js.map +1 -0
  67. package/lib/esm/engine/services/GraphWorkflowService.js +34 -1
  68. package/lib/esm/engine/services/GraphWorkflowService.js.map +1 -1
  69. package/lib/esm/mastra/MastraCapabilities.js.map +1 -1
  70. package/lib/esm/mastra/MastraDefaultStepHandlers.js +212 -0
  71. package/lib/esm/mastra/MastraDefaultStepHandlers.js.map +1 -0
  72. package/lib/esm/mastra/MastraEventBridge.js +10 -3
  73. package/lib/esm/mastra/MastraEventBridge.js.map +1 -1
  74. package/lib/esm/mastra/MastraGraphExecutionBackend.js +112 -14
  75. package/lib/esm/mastra/MastraGraphExecutionBackend.js.map +1 -1
  76. package/lib/esm/mastra/MastraWorkflowCompiler.js +3 -3
  77. package/lib/esm/mastra/MastraWorkflowCompiler.js.map +1 -1
  78. package/lib/esm/mastra/index.js +1 -0
  79. package/lib/esm/mastra/index.js.map +1 -1
  80. package/lib/esm/mastra/types.js +4 -0
  81. package/lib/esm/mastra/types.js.map +1 -1
  82. package/lib/esm/nest/graph/GraphBackendHost.js +189 -0
  83. package/lib/esm/nest/graph/GraphBackendHost.js.map +1 -0
  84. package/lib/esm/nest/graph/GraphExecutionModule.js +39 -2
  85. package/lib/esm/nest/graph/GraphExecutionModule.js.map +1 -1
  86. package/lib/esm/nest/graph/index.js +1 -0
  87. package/lib/esm/nest/graph/index.js.map +1 -1
  88. package/lib/esm/nest/graph/main.js +79 -12
  89. package/lib/esm/nest/graph/main.js.map +1 -1
  90. package/lib/esm/ram/GraphNodeRepository.js +31 -0
  91. package/lib/esm/ram/GraphNodeRepository.js.map +1 -0
  92. package/lib/esm/ram/index.js +1 -0
  93. package/lib/esm/ram/index.js.map +1 -1
  94. package/lib/esm/shared/graph/GraphNodeConverters.js +38 -0
  95. package/lib/esm/shared/graph/GraphNodeConverters.js.map +1 -0
  96. package/lib/esm/shared/graph/GraphNodeModel.js +65 -0
  97. package/lib/esm/shared/graph/GraphNodeModel.js.map +1 -0
  98. package/lib/esm/shared/graph/index.js +2 -0
  99. package/lib/esm/shared/graph/index.js.map +1 -1
  100. package/lib/types/dagster/DagsterGraphExecutionBackend.d.cts +40 -4
  101. package/lib/types/dagster/DagsterGraphExecutionBackend.d.mts +40 -4
  102. package/lib/types/dagster/DagsterGraphQLClient.d.cts +231 -0
  103. package/lib/types/dagster/DagsterGraphQLClient.d.mts +231 -0
  104. package/lib/types/dagster/index.d.cts +1 -0
  105. package/lib/types/dagster/index.d.mts +1 -0
  106. package/lib/types/engine/execution/GraphExecutionBackend.d.cts +27 -0
  107. package/lib/types/engine/execution/GraphExecutionBackend.d.mts +27 -0
  108. package/lib/types/engine/execution/GraphExecutionEngine.d.cts +9 -0
  109. package/lib/types/engine/execution/GraphExecutionEngine.d.mts +9 -0
  110. package/lib/types/engine/execution/LocalGraphExecutionBackend.d.cts +14 -0
  111. package/lib/types/engine/execution/LocalGraphExecutionBackend.d.mts +14 -0
  112. package/lib/types/engine/index.d.cts +1 -0
  113. package/lib/types/engine/index.d.mts +1 -0
  114. package/lib/types/engine/services/GraphNodeModelService.d.cts +54 -0
  115. package/lib/types/engine/services/GraphNodeModelService.d.mts +54 -0
  116. package/lib/types/engine/services/GraphWorkflowService.d.cts +21 -0
  117. package/lib/types/engine/services/GraphWorkflowService.d.mts +21 -0
  118. package/lib/types/mastra/MastraCapabilities.d.cts +0 -5
  119. package/lib/types/mastra/MastraCapabilities.d.mts +0 -5
  120. package/lib/types/mastra/MastraDefaultStepHandlers.d.cts +74 -0
  121. package/lib/types/mastra/MastraDefaultStepHandlers.d.mts +74 -0
  122. package/lib/types/mastra/MastraGraphExecutionBackend.d.cts +29 -0
  123. package/lib/types/mastra/MastraGraphExecutionBackend.d.mts +29 -0
  124. package/lib/types/mastra/MastraWorkflowCompiler.d.cts +3 -3
  125. package/lib/types/mastra/MastraWorkflowCompiler.d.mts +3 -3
  126. package/lib/types/mastra/index.d.cts +1 -0
  127. package/lib/types/mastra/index.d.mts +1 -0
  128. package/lib/types/mastra/types.d.cts +12 -0
  129. package/lib/types/mastra/types.d.mts +12 -0
  130. package/lib/types/nest/graph/GraphBackendHost.d.cts +152 -0
  131. package/lib/types/nest/graph/GraphBackendHost.d.mts +152 -0
  132. package/lib/types/nest/graph/GraphExecutionModule.d.cts +23 -0
  133. package/lib/types/nest/graph/GraphExecutionModule.d.mts +23 -0
  134. package/lib/types/nest/graph/index.d.cts +1 -0
  135. package/lib/types/nest/graph/index.d.mts +1 -0
  136. package/lib/types/ram/GraphNodeRepository.d.cts +13 -0
  137. package/lib/types/ram/GraphNodeRepository.d.mts +13 -0
  138. package/lib/types/ram/index.d.cts +1 -0
  139. package/lib/types/ram/index.d.mts +1 -0
  140. package/lib/types/shared/graph/GraphNodeConverters.d.cts +15 -0
  141. package/lib/types/shared/graph/GraphNodeConverters.d.mts +15 -0
  142. package/lib/types/shared/graph/GraphNodeModel.d.cts +24 -0
  143. package/lib/types/shared/graph/GraphNodeModel.d.mts +24 -0
  144. package/lib/types/shared/graph/index.d.cts +2 -0
  145. package/lib/types/shared/graph/index.d.mts +2 -0
  146. package/package.json +15 -3
package/README.md CHANGED
@@ -144,10 +144,10 @@ npm install @decaf-ts/as-graph
144
144
 
145
145
  | Import | Contains |
146
146
  | --- | --- |
147
- | `@decaf-ts/as-graph` | Backend engine: `GraphExecutionEngine`, planning, validation, auth, loops, pinning, run lifecycle, value store, and the built-in node classes |
148
- | `@decaf-ts/as-graph/shared` | UI-known contracts: `@node`/`@graph`/`@port` decorators, the canonical `GraphWorkflowDocument` and its builder/reader/serializer, manifest catalogue types, constants, and frontend-safe execution-state projections |
147
+ | `@decaf-ts/as-graph` | Backend engine: `GraphExecutionEngine`, planning, validation, auth, loops, pinning, run lifecycle, value store, the built-in node classes, and the node-kind persistence service (`GraphNodeModelService`) |
148
+ | `@decaf-ts/as-graph/shared` | UI-known contracts: `@node`/`@graph`/`@port` decorators, the canonical `GraphWorkflowDocument` and its builder/reader/serializer, manifest catalogue types, the persistable `GraphNodeModel` catalogue row with its manifest converters, constants, and frontend-safe execution-state projections |
149
149
  | `@decaf-ts/as-graph/nest` | NestJS HTTP/SSE wiring: catalogue, workflow persistence and run-lifecycle controllers |
150
- | `@decaf-ts/as-graph/ram` | Adapter-backed persistence: `GraphRunModel`/`GraphRunEventModel`/`GraphValueModel` and their `@repository()` classes, the `RamGraphRunStore`/`RamGraphRunEventStore` stores, and the `createRamGraphAdapter` helper |
150
+ | `@decaf-ts/as-graph/ram` | Adapter-backed persistence: `GraphRunModel`/`GraphRunEventModel`/`GraphValueModel` and their `@repository()` classes, the `GraphNodeRepository` node-kind rows, the `RamGraphRunStore`/`RamGraphRunEventStore` stores, and the `createRamGraphAdapter` helper |
151
151
  | `@decaf-ts/as-graph/mastra` | Mastra execution backend: `MastraGraphExecutionBackend`, the workflow compiler, condition/event bridges, schema converter, resume guard, and the Mastra capability table. Runs canonical documents on a host-injected `@mastra/core` runtime (pinned `1.74.0`) |
152
152
  | `@decaf-ts/as-graph/dagster` | Dagster execution backend: `DagsterGraphExecutionBackend`, the workflow translator, event bridge, result mapper, capability table (`DAGSTER_CAPABILITY_TABLE`), and Dagster identifier/condition-grammar helpers. Driven through a host-injected `DagsterClient` port against the pinned engine contract (`1.13.25`; Dagster is Python-side, there is no JavaScript runtime dependency) |
153
153
 
@@ -407,7 +407,7 @@ A backend declares its contract to the facade:
407
407
  | `local` | Whether the backend executes in-process. |
408
408
  | `codeMode` | `"hostSide"` (code-mode surfaces run through the facade-owned sandbox evaluator) or `"unsupported"`. The facade fails closed with `GRAPH_CODE_MODE_UNSUPPORTED_BACKEND` before delegating a code-mode workflow to any backend that is not local and not `"hostSide"`. |
409
409
  | `capabilities` | Optional `GraphBackendCapabilities` (`codeMode` plus `workflows: { list, get }`). When omitted, the facade derives them from the declared `codeMode` and the presence of the optional `listWorkflows`/`getWorkflow` methods (`resolveGraphBackendCapabilities`), so an unsupported operation is reported as `not_supported` instead of silently returning an empty result. |
410
- | optional methods | `listWorkflows` / `getWorkflow` (workflow catalogue seam), `cancel`, `resume`, `release`, `dispose`. |
410
+ | optional methods | `listWorkflows` / `getWorkflow` (workflow catalogue seam), `seedWorkflows` (workflow seeding seam), `cancel`, `resume`, `release`, `dispose`. |
411
411
 
412
412
  Engine-level reads of the active backend: `engine.backend`,
413
413
  `engine.backendCapabilities`, `engine.listWorkflows()` (active backend),
@@ -416,6 +416,30 @@ and the flavour-scoped `engine.listEngineWorkflows(flavour)` /
416
416
  with `GRAPH_EXECUTION_BACKEND_NOT_REGISTERED` (unknown flavour) or
417
417
  `GRAPH_BACKEND_WORKFLOWS_NOT_SUPPORTED` (no listing/lookup support).
418
418
 
419
+ ##### Workflow seeding
420
+
421
+ Every backend exposes an optional `seedWorkflows(documents)` seam so a host can
422
+ register canonical `GraphWorkflowDocument`s into the driver's own persistence at
423
+ boot — each driver seeds into its own storage and serves the seeded entries
424
+ through its normal `listWorkflows`/`getWorkflow` path:
425
+
426
+ - `local` persists each document through the wired `workflowStore` write path
427
+ (`saveDocument`), so seeding honours the same boundary validation and
428
+ ownership rules as any other write, and fails closed with
429
+ `GRAPH_BACKEND_SEED_NOT_SUPPORTED` when no writable store is configured.
430
+ - `mastra` registers the documents in its compiled-workflow cache, so seeded
431
+ entries are served exactly like a workflow recorded by `execute`; seeded
432
+ entries are owner-less and therefore visible to every caller.
433
+ - `dagster` adds the documents to its read-only catalogue map alongside the
434
+ deployment's jobs — a host boot action, never an authoring surface: authoring
435
+ capabilities stay `not_supported`.
436
+
437
+ The engine facade wires it at boot: passing
438
+ `seedWorkflows: GraphWorkflowDocument[]` in the `GraphExecutionEngineConfig`
439
+ (or `GraphExecutionModuleOptions.seedWorkflows` for the NestJS module) makes the
440
+ engine call the active backend's `seedWorkflows` during `boot()`, failing closed
441
+ with `GRAPH_BACKEND_SEED_NOT_SUPPORTED` when the backend does not implement it.
442
+
419
443
  ##### Mastra backend (`@decaf-ts/as-graph/mastra`)
420
444
 
421
445
  `MastraGraphExecutionBackend` translates the canonical document into a Mastra
@@ -492,6 +516,7 @@ Run lifecycle and cached/pinned-value persistence always flows through Decaf rep
492
516
  | `GraphRunModel` / `GraphRunRepository` | Run lifecycle records (durable run history), persisted as `graph_run` rows |
493
517
  | `GraphRunEventModel` / `GraphRunEventRepository` | Run event envelopes (SSE replay/audit), persisted as `graph_run_event` rows; live subscribers stay in-process |
494
518
  | `GraphValueModel` / `GraphValueRepository` | Cached/pinned graph values (must survive restarts for pinning), persisted as `graph_value` rows; per-execution runtime values are not persisted |
519
+ | `GraphNodeRepository` | Node-kind catalogue rows (one row per registered kind, persisted as `graph_node`); the `GraphNodeModel` row class lives in `./shared` so backend stores and UI listing/forms share it |
495
520
  | `RamGraphRunStore` / `RamGraphRunEventStore` | Adapter-backed `GraphRunStore`/`GraphRunEventStore` implementations; construct with an initialized adapter |
496
521
  | `createRamGraphAdapter(alias?)` | Creates and initializes a `RamAdapter` (tests); production passes a durable adapter (e.g. TypeORM) |
497
522
  | `createGraphValueRepository(adapter)` | Factory for a fresh `GraphValueRepository` instance over the provided adapter |
@@ -549,6 +574,12 @@ summaries, `POST /graph/workflows/validate`), the asynchronous run lifecycle (`P
549
574
  The engine provider is a Decaf `ClientBasedService`: the module constructs `new GraphExecutionEngine()`
550
575
  and initializes it with `await engine.boot(config)`.
551
576
 
577
+ The module also mirrors the populated node catalogue into repository-backed rows at boot: a
578
+ `GraphNodeModelService` provider upserts every registered node-kind manifest as a `GraphNodeModel`
579
+ row (`syncFromCatalogue`), so node kinds are exposed through repository/adapter CRUD and listing
580
+ (`GraphNodeRepository`) for whichever engine the host booted — mirroring the
581
+ `GraphWorkflowService`/`GraphRunModelService` persistence pattern.
582
+
552
583
  The engine capability API serves a statically-derived, boot-time capability manifest
553
584
  (`GraphEngineCapabilityService`): it is built once from the backends registered in the
554
585
  `GraphExecutionBackendRegistry`, only allowlisted flavours (`local`, `mastra`, `dagster`) are advertised,
@@ -590,6 +621,7 @@ an authenticated owner user is rejected with `401`) and can be relaxed to `"opti
590
621
  | `initAdapter` / `adapterUser` | Secure-default adapter bootstrap: only `initAdapter: true` installs a standalone `RamAdapter`; otherwise the host must have configured a Decaf adapter via `DecafModule.forRoot(...)`, and construction fails closed with a `GraphStoreError` when none is current |
591
622
  | `valueAdapter` | Adapter backing cached/pinned value persistence; falls back to the globally configured adapter (`Adapter.current`) |
592
623
  | `runAdapter` | Adapter backing run and run-event persistence; falls back to `valueAdapter`, then to `Adapter.current`. Runs and run events always persist through the adapter-backed `@repository()` stores (`RamGraphRunStore` / `RamGraphRunEventStore`) — never a process-local map |
624
+ | `seedWorkflows` | Canonical workflow documents seeded into the active backend at boot through the backend's `seedWorkflows` seam (see [Workflow seeding](#workflow-seeding)) |
593
625
  | `credentialAuthorizer` | Stage-8 credential existence/authorization hook wired into the engine's document validator; without it, credential checks are shape/type-only |
594
626
  | `authHandler` | `AuthHandler` class installed via `DecafAuthModule.forRoot` (the for-nest pattern; typical values: `KeycloakAuthHandler` / `KeycloakNamespaceAuthHandler` from `@decaf-ts/integrations/nest`). It primes every request context with the authenticated `user` / `roles` / `namespaces` / `organization`, which `GraphAuthValidator` authorizes each workflow and node against |
595
627
  | `authGlobal` | When `true` (default when `authHandler` is set), the auth interceptor is registered globally; `false` installs the handler without a global interceptor (routes opt in with `@Auth()`) |
@@ -620,11 +652,141 @@ import { KeycloakAuthHandler } from "@decaf-ts/integrations/nest";
620
652
  export class AppModule {}
621
653
  ```
622
654
 
655
+ #### Running each backend + UI combination
656
+
657
+ The standalone host (`bin.as-graph-server`, `lib/cjs/nest/graph/main.cjs`) boots exactly one engine
658
+ variant, selected by `GRAPH_BACKEND_ENGINE`, and serves the C20 capability manifest
659
+ (`GET /graph/engines`) plus the per-engine workflow catalogue
660
+ (`GET /graph/engines/{engineId}/workflows`). The for-angular graph page talks to it over
661
+ `http://localhost:3000` (`GRAPH_BACKEND_URL`) and needs no code change when the variant changes — it
662
+ lists whatever the backend advertises and gates its actions on the served capabilities.
663
+
664
+ **Build first.** The scripts run the compiled entrypoint, so `npm run build` (or `build:prod`) must
665
+ have produced `lib/cjs/nest/graph/main.cjs`.
666
+
667
+ | Combination | Boot the backend | Run the UI | Backend port | Extra prerequisites |
668
+ | --- | --- | --- | --- | --- |
669
+ | standard (local engine) | `npm run start:backend` / `start:backend:local` | `npm run start` (for-angular, `:8110`) | `3000` | none — built-in reference interpreter |
670
+ | mastra | `npm run start:backend:mastra` | `npm run start` (for-angular, `:8110`) | `3000` | `@mastra/core` peer installed (`^1.77.0`) |
671
+ | dagster | `npm run start:backend:dagster` | `npm run start` (for-angular, `:8110`) | `3000` | a Dagster gateway + `DAGSTER_GRAPHQL_URL` (see below) |
672
+
673
+ From `for-angular`, `npm run start:dev` (local), `start:dev:mastra`, and `start:dev:dagster` boot
674
+ the backend and the UI together with `concurrently`.
675
+
676
+ | Variable | Default | Meaning |
677
+ | --- | --- | --- |
678
+ | `GRAPH_BACKEND_ENGINE` | `local` | `local` \| `mastra` \| `dagster`; an unknown value fails closed with `GRAPH_BACKEND_ENGINE_UNKNOWN` |
679
+ | `GRAPH_BACKEND_PORT` | `3000` | Backend HTTP port (the standalone binary also accepts the port as its first argument) |
680
+ | `DAGSTER_GRAPHQL_URL` | unset | Read-only Dagster client target. Without it the dagster backend still boots and serves the manifest, but the catalogue reports `NOT_SUPPORTED` (`501`) |
681
+ | `DAGSTER_EXECUTION_ENABLED` | `false` | Opt-in gate for launching/replaying existing Dagster runs |
682
+ | `GRAPH_BACKEND_URL` | `http://localhost:3000` | for-angular injection token for the backend base URL (a provider override, not an env var) |
683
+
684
+ The host binds to `127.0.0.1` and only admits `http://localhost`/`http://127.0.0.1` CORS origins
685
+ (development posture, SAA-595 F5).
686
+
687
+ ##### Demo workflow seeding
688
+
689
+ The standalone host seeds the demo workflow fixture registry into whichever
690
+ engine it boots: `loadGraphDemoWorkflows()` (exported from
691
+ `@decaf-ts/as-graph/nest`) imports the `graphWorkflowFixtures` registry from
692
+ `src/workflows` and passes its canonical documents as `seedWorkflows`, so each
693
+ driver's catalogue lists the full fixture set out of the box. The registry is
694
+ test-only content — `npm pack` excludes `lib/**/workflows` — so a
695
+ release-packaged host boots with an empty seed set and its catalogues behave
696
+ exactly as before (the mastra catalogue starts empty; the dagster catalogue
697
+ needs a wired client).
698
+
699
+ ##### Standard (local engine)
700
+
701
+ No backing service. Build the backend, boot it, and run the UI in a second terminal:
702
+
703
+ ```bash
704
+ # as-graph
705
+ npm run build && npm run start:backend # http://127.0.0.1:3000 (engine: local)
706
+ # for-angular
707
+ npm run start # http://localhost:8110
708
+ ```
709
+
710
+ Verify the backend advertises the local engine:
711
+
712
+ ```bash
713
+ curl -s http://127.0.0.1:3000/graph/engines # .defaultEngineId == "local"
714
+ ```
715
+
716
+ Open the workflow catalog (`http://localhost:8110/workflows`); the workflow table lists the
717
+ workflows persisted in the backend's local engine store, including the seeded demo fixture set.
718
+
719
+ ##### Mastra
720
+
721
+ In-process; the only prerequisite is the `@mastra/core` peer dependency (pinned `^1.77.0`),
722
+ resolved by `npm install` in `as-graph`. The host lazily builds a real `@mastra/core` runtime.
723
+
724
+ ```bash
725
+ npm run start:backend:mastra # engine: mastra, still on :3000
726
+ ```
727
+
728
+ The Mastra catalogue lists the workflows registered in the process: the seeded demo fixture set
729
+ (see [Demo workflow seeding](#demo-workflow-seeding)) plus every workflow already compiled/executed
730
+ in the process (its `workflowList`/`workflowLookup` capability). The manifest advertises the mastra
731
+ engine and its per-feature verdicts.
732
+
733
+ ##### Dagster
734
+
735
+ Dagster is Python-side and has no JavaScript runtime, so the backend lists/executes through a
736
+ host-injected `DagsterClient` built from `DAGSTER_GRAPHQL_URL`. Provision the pinned gateway fixture
737
+ (Docker; Dagster `1.13.25`) with the integration harness:
738
+
739
+ ```bash
740
+ # as-graph: boot + seed the pinned gateway and persist its GraphQL URL
741
+ npm run prepare-it-tests # publishes the gateway at http://127.0.0.1:3300/graphql
742
+ DAGSTER_GRAPHQL_URL=http://127.0.0.1:3300/graphql npm run start:backend:dagster
743
+ npm run teardown-it-tests # when done
744
+ ```
745
+
746
+ Without `DAGSTER_GRAPHQL_URL` the dagster host still boots and serves the manifest; with the
747
+ seeded fixture set its catalogue lists those fixtures read-only, while a release-packaged host
748
+ with an empty seed set answers `501` (`NOT_SUPPORTED`). To run against an already-running Dagster, set
749
+ `DAGSTER_GRAPHQL_URL` yourself and skip `prepare-it-tests`.
750
+
751
+ > **Environment note (CI sandbox):** inside a container (`/.dockerenv`), the fixture joins the
752
+ > runner's network namespace and binds `127.0.0.1:3000`, which collides with the graph backend's
753
+ > default port. On a normal host the fixture is published at `127.0.0.1:3300`, so there is no
754
+ > collision. Because the for-angular UI is wired to `http://localhost:3000`, run the Dagster gateway
755
+ > on a host (or another namespace) and keep the graph backend on `3000` when exercising the UI +
756
+ > dagster combination.
757
+
758
+ ##### Verifying the UI lists a backend's scenarios
759
+
760
+ 1. `GET /graph/engines` returns the manifest with `defaultEngineId` equal to the booted variant.
761
+ 2. `GET /graph/engines/{engineId}/workflows` returns that engine's catalogue (`200`), or `501` when
762
+ the engine declares no listing support (dagster without a client and without seeded fixtures).
763
+ 3. In the UI the workflow table shows the catalogue rows and gates create/run/save per the manifest
764
+ verdicts; switching variants requires no UI code change.
765
+
766
+ ##### Running each variant's test suite
767
+
768
+ | Variant | Command |
769
+ | --- | --- |
770
+ | standard (local) | `npm run test:integration:standard` |
771
+ | mastra | `npm run test:integration:mastra` |
772
+ | dagster | `npm run prepare-it-tests` then `npm run test:integration:dagster` (or `npm run teardown-it-tests` after) |
773
+ | backend host boot (all variants + standalone binary) | `npm run test:integration:backend` |
774
+
775
+ The dagster suite needs the gateway fixture (`prepare-it-tests`) and Docker; it skips honestly when
776
+ no gateway is prepared. The standalone-binary boot test needs the `lib/cjs` build and skips when it
777
+ is absent.
778
+
623
779
  #### Scripts
624
780
 
625
781
  | Script | Purpose |
626
782
  | --- | --- |
627
- | `npm run build` / `build:prod` | Compile ESM + CJS + types |
783
+ | `npm run build` / `build:prod` | Compile ESM + CJS + types; `postbuild`/`postbuild:prod` run the `check:emitted-specifiers` guard, which fails the build when any relative module specifier in the emitted `lib/cjs`/`lib/esm` output does not resolve |
784
+ | `npm run start:backend` / `start:backend:local` | Boot the standalone host with the built-in local engine (`:3000`) |
785
+ | `npm run start:backend:mastra` | Boot the standalone host with the Mastra engine (`GRAPH_BACKEND_ENGINE=mastra`) |
786
+ | `npm run start:backend:dagster` | Boot the standalone host with the Dagster engine (`GRAPH_BACKEND_ENGINE=dagster`) |
787
+ | `npm run test:integration:standard` / `:mastra` / `:dagster` | Run one engine variant's integration suite |
788
+ | `npm run test:integration:backend` | Run the host-boot integration suite (all variants + standalone binary) |
789
+ | `npm run prepare-it-tests` / `teardown-it-tests` | Provision / stop the pinned Dagster gateway fixture |
628
790
  | `npm run test:unit` / `test:integration` / `test:e2e` | Run the Jest unit / integration / e2e suites |
629
791
  | `npm run test:all` | Run the entire Jest suite (unit, integration, e2e) |
630
792
  | `npm run test:dist` | Re-run the full suite against the compiled `lib` and `dist` outputs |