@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
@@ -12,6 +12,7 @@ export * from "./MastraSchemaConverter.d.cts";
12
12
  export * from "./MastraConditionBridge.d.cts";
13
13
  export * from "./MastraEventBridge.d.cts";
14
14
  export * from "./MastraWorkflowCompiler.d.cts";
15
+ export * from "./MastraDefaultStepHandlers.d.cts";
15
16
  export * from "./MastraWorkflowManager.d.cts";
16
17
  export * from "./MastraResumeGuard.d.cts";
17
18
  export * from "./MastraGraphExecutionBackend.d.cts";
@@ -12,6 +12,7 @@ export * from "./MastraSchemaConverter.d.mts";
12
12
  export * from "./MastraConditionBridge.d.mts";
13
13
  export * from "./MastraEventBridge.d.mts";
14
14
  export * from "./MastraWorkflowCompiler.d.mts";
15
+ export * from "./MastraDefaultStepHandlers.d.mts";
15
16
  export * from "./MastraWorkflowManager.d.mts";
16
17
  export * from "./MastraResumeGuard.d.mts";
17
18
  export * from "./MastraGraphExecutionBackend.d.mts";
@@ -29,6 +29,10 @@ export declare const GRAPH_MASTRA_RESUME_STATE_INVALID = "GRAPH_MASTRA_RESUME_ST
29
29
  export declare const GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE = "GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE";
30
30
  /** No Mastra agent is available for an agent-backed node. */
31
31
  export declare const GRAPH_MASTRA_AGENT_UNAVAILABLE = "GRAPH_MASTRA_AGENT_UNAVAILABLE";
32
+ /** The Mastra execute path did not terminate within its run-level timeout. */
33
+ export declare const GRAPH_MASTRA_EXECUTE_TIMEOUT = "GRAPH_MASTRA_EXECUTE_TIMEOUT";
34
+ /** The Mastra execute path was aborted by the caller's cancellation signal. */
35
+ export declare const GRAPH_MASTRA_EXECUTE_ABORTED = "GRAPH_MASTRA_EXECUTE_ABORTED";
32
36
  /** The wired Mastra runtime exposes no workflow-management surface. */
33
37
  export declare const GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE = "GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE";
34
38
  /** A managed workflow id has no workflow registered on the runtime. */
@@ -102,6 +106,14 @@ export interface MastraBackendConfig extends Record<string, unknown> {
102
106
  suspendStateReader?: MastraSuspendStateReader;
103
107
  /** Maximum accepted serialised `resumeData` size, in bytes. */
104
108
  maxResumeBytes?: number;
109
+ /**
110
+ * Run-level terminal timeout, in milliseconds, for {@link MastraGraphExecutionBackend.execute}.
111
+ * A translated run that has not terminated within this bound fails closed with
112
+ * {@link GRAPH_MASTRA_EXECUTE_TIMEOUT} instead of pinning the run slot and event
113
+ * stream indefinitely; mirrors the Dagster `terminalTimeoutMs` bound. Defaults
114
+ * to five minutes when omitted.
115
+ */
116
+ terminalTimeoutMs?: number;
105
117
  }
106
118
  /**
107
119
  * Mastra-authoritative snapshot of a suspended run as exposed by the host's
@@ -29,6 +29,10 @@ export declare const GRAPH_MASTRA_RESUME_STATE_INVALID = "GRAPH_MASTRA_RESUME_ST
29
29
  export declare const GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE = "GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE";
30
30
  /** No Mastra agent is available for an agent-backed node. */
31
31
  export declare const GRAPH_MASTRA_AGENT_UNAVAILABLE = "GRAPH_MASTRA_AGENT_UNAVAILABLE";
32
+ /** The Mastra execute path did not terminate within its run-level timeout. */
33
+ export declare const GRAPH_MASTRA_EXECUTE_TIMEOUT = "GRAPH_MASTRA_EXECUTE_TIMEOUT";
34
+ /** The Mastra execute path was aborted by the caller's cancellation signal. */
35
+ export declare const GRAPH_MASTRA_EXECUTE_ABORTED = "GRAPH_MASTRA_EXECUTE_ABORTED";
32
36
  /** The wired Mastra runtime exposes no workflow-management surface. */
33
37
  export declare const GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE = "GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE";
34
38
  /** A managed workflow id has no workflow registered on the runtime. */
@@ -102,6 +106,14 @@ export interface MastraBackendConfig extends Record<string, unknown> {
102
106
  suspendStateReader?: MastraSuspendStateReader;
103
107
  /** Maximum accepted serialised `resumeData` size, in bytes. */
104
108
  maxResumeBytes?: number;
109
+ /**
110
+ * Run-level terminal timeout, in milliseconds, for {@link MastraGraphExecutionBackend.execute}.
111
+ * A translated run that has not terminated within this bound fails closed with
112
+ * {@link GRAPH_MASTRA_EXECUTE_TIMEOUT} instead of pinning the run slot and event
113
+ * stream indefinitely; mirrors the Dagster `terminalTimeoutMs` bound. Defaults
114
+ * to five minutes when omitted.
115
+ */
116
+ terminalTimeoutMs?: number;
105
117
  }
106
118
  /**
107
119
  * Mastra-authoritative snapshot of a suspended run as exposed by the host's
@@ -0,0 +1,152 @@
1
+ /**
2
+ * @module as-graph/nest/graph/GraphBackendHost
3
+ * @summary Boot-time engine-variant selection for the graph backend host (SAA-706).
4
+ * @description Resolves which of the three pluggable graph engines — the built-in
5
+ * local reference interpreter, the `@mastra/core` translated backend, or the
6
+ * read-only Dagster backend — a host boots, constructs and registers that
7
+ * backend, and assembles the {@link GraphExecutionModule} options that make the
8
+ * Nest host serve the matching C20 capability manifest (`graph/engines`) and the
9
+ * per-engine workflow catalogue (`graph/engines/{engineId}/workflows`).
10
+ *
11
+ * The host never stubs an engine: each variant constructs the real backend. A
12
+ * translated/remote backend whose host wiring is absent (no Mastra runtime, no
13
+ * Dagster client) still boots and serves the manifest; its catalogue then reports
14
+ * the engine's honest `NOT_SUPPORTED` verdict through the engine facade, exactly
15
+ * as `GraphEngineController` maps it to `501`. The variant is chosen at boot by
16
+ * the `GRAPH_BACKEND_ENGINE` environment variable, so switching engines is a
17
+ * configuration change, never a code change.
18
+ */
19
+ import type { GraphWorkflowDocument } from "../../shared/graph/index.d.cts";
20
+ import type { GraphExecutionBackend } from "../../engine/execution/GraphExecutionBackend.d.cts";
21
+ import { type MastraBackendConfig } from "../../mastra/types.d.cts";
22
+ import type { DagsterClient } from "../../dagster/DagsterTypes.d.cts";
23
+ import type { GraphExecutionModuleOptions } from "./GraphExecutionModule.d.cts";
24
+ /**
25
+ * The graph engine variants a host can boot. Each maps one-to-one onto the
26
+ * backend flavour it registers, which is also the allowlisted engine id the C20
27
+ * manifest advertises.
28
+ */
29
+ export type GraphEngineVariant = "local" | "mastra" | "dagster";
30
+ /** Every bootable engine variant, in manifest order. */
31
+ export declare const GRAPH_ENGINE_VARIANTS: readonly GraphEngineVariant[];
32
+ /** Environment variable selecting the engine variant the host boots. */
33
+ export declare const GRAPH_BACKEND_ENGINE_ENV = "GRAPH_BACKEND_ENGINE";
34
+ /** The engine variant a host boots when none is configured. */
35
+ export declare const DEFAULT_GRAPH_ENGINE_VARIANT: GraphEngineVariant;
36
+ /**
37
+ * Parses a configured engine variant, failing closed on an unknown value so a
38
+ * typo never silently boots the wrong engine.
39
+ *
40
+ * @param value - The raw configured value (`undefined`/empty selects the fallback).
41
+ * @param fallback - The variant to use when no value is configured.
42
+ * @returns The resolved engine variant.
43
+ * @throws {GraphExecutionError} when the value names no known variant.
44
+ */
45
+ export declare function parseGraphEngineVariant(value: string | undefined, fallback?: GraphEngineVariant): GraphEngineVariant;
46
+ /**
47
+ * Reads the engine variant from an environment bag (defaults to `process.env`),
48
+ * applying {@link parseGraphEngineVariant}.
49
+ *
50
+ * @param env - The environment to read from.
51
+ * @returns The resolved engine variant.
52
+ */
53
+ export declare function graphEngineVariantFromEnv(env?: NodeJS.ProcessEnv): GraphEngineVariant;
54
+ /** Environment variable gating boot-time demo-workflow seeding (F5 hardening). */
55
+ export declare const GRAPH_SEED_DEMO_ENV = "GRAPH_SEED_DEMO";
56
+ /**
57
+ * Resolves whether the standalone host seeds the demo workflow fixture registry
58
+ * at boot (F5 hardening). Seeding is enabled by default so a source checkout
59
+ * keeps its fixtures; a production host sets `GRAPH_SEED_DEMO=off` (also accepts
60
+ * `false` / `0` / `no` / `disabled`, case-insensitive) to suppress owner-less
61
+ * demo seeding without a code change. An unset or empty value keeps the default
62
+ * (enabled), so existing hosts are unaffected.
63
+ *
64
+ * @param env - The environment to read from (defaults to `process.env`).
65
+ * @returns `true` when boot-time demo seeding is enabled.
66
+ */
67
+ export declare function graphDemoSeedEnabledFromEnv(env?: NodeJS.ProcessEnv): boolean;
68
+ /** Host wiring for the Dagster variant: the client port plus its gate options. */
69
+ export interface GraphDagsterHostOptions {
70
+ /**
71
+ * The read-only Dagster client port. When omitted the backend still boots and
72
+ * serves the manifest, but its catalogue reports `NOT_SUPPORTED` because no
73
+ * deployment transport is wired.
74
+ */
75
+ client?: DagsterClient;
76
+ /** Opt-in gate for launching/replaying EXISTING workflows. Defaults to off. */
77
+ executionEnabled?: boolean;
78
+ /** Host-supplied default run tags. */
79
+ tags?: Record<string, string>;
80
+ }
81
+ /**
82
+ * Options for {@link createGraphBackendHost}: the selected variant plus the
83
+ * per-variant host wiring. Unused wiring for the unselected variant is ignored.
84
+ */
85
+ export interface GraphBackendHostOptions {
86
+ /** The engine variant to boot. */
87
+ variant: GraphEngineVariant;
88
+ /**
89
+ * Host wiring for the Mastra variant: the real `@mastra/core` runtime and the
90
+ * node-kind step handlers. Absent wiring boots a catalogue-less Mastra host.
91
+ */
92
+ mastra?: MastraBackendConfig;
93
+ /** Host wiring for the Dagster variant. */
94
+ dagster?: GraphDagsterHostOptions;
95
+ /**
96
+ * Canonical workflow documents seeded into the selected engine's catalogue at
97
+ * boot (the host's fixture registry). Forwarded to the module options so the
98
+ * per-engine workflow catalogue serves the fixture set for whichever variant
99
+ * the host booted. The seed stays engine-dependent and read-only for Dagster.
100
+ */
101
+ seedWorkflows?: readonly GraphWorkflowDocument[];
102
+ /**
103
+ * Existing module options to extend. The host overrides only `backend` and
104
+ * `engines.defaultEngineId`, so a caller keeps its auth, limits, adapter, and
105
+ * rate-limit configuration.
106
+ */
107
+ base?: GraphExecutionModuleOptions;
108
+ }
109
+ /**
110
+ * The result of {@link createGraphBackendHost}: the resolved variant, the
111
+ * allowlisted engine id it advertises, the constructed backend (absent for the
112
+ * local variant, which the engine constructs itself), and the assembled module
113
+ * options ready for `GraphExecutionModule.forRoot`.
114
+ */
115
+ export interface GraphBackendHost {
116
+ /** The resolved engine variant. */
117
+ variant: GraphEngineVariant;
118
+ /** The allowlisted engine id the manifest advertises for this variant. */
119
+ engineId: string;
120
+ /**
121
+ * The constructed backend the host selected, or `undefined` for the local
122
+ * variant (the engine constructs the built-in backend itself).
123
+ */
124
+ backend?: GraphExecutionBackend;
125
+ /** Module options carrying the selected backend and default engine id. */
126
+ moduleOptions: GraphExecutionModuleOptions;
127
+ }
128
+ /**
129
+ * Builds the bootable graph backend host for one engine variant: constructs and
130
+ * registers the selected backend, selects it as the registry current so the
131
+ * engine facade's default engine follows the variant, and assembles the
132
+ * {@link GraphExecutionModule} options that advertise that engine's capability
133
+ * manifest and per-engine workflow catalogue.
134
+ *
135
+ * @param options - The host options (variant, per-variant wiring, base options).
136
+ * @returns The resolved host, including the module options to boot.
137
+ */
138
+ export declare function createGraphBackendHost(options: GraphBackendHostOptions): Promise<GraphBackendHost>;
139
+ /**
140
+ * Loads the host's demo workflow fixture registry for boot-time seeding. This is
141
+ * the engine driver's seeding path (R4): the fixture registry is imported only
142
+ * by tests and by this loader. Because the registry is excluded from release
143
+ * packaging, the loader is best-effort — it returns the fixture documents when
144
+ * the registry is present (a source checkout or development install) and an
145
+ * empty set when it is absent (a published package), never failing the boot.
146
+ *
147
+ * @returns The canonical documents to seed, or an empty array when the registry
148
+ * is unavailable.
149
+ */
150
+ export declare function loadGraphDemoWorkflows(): Promise<readonly GraphWorkflowDocument[]>;
151
+ /** The allowlisted engine id for a variant (the backend flavour). */
152
+ export declare function graphEngineIdOf(variant: GraphEngineVariant): string;
@@ -0,0 +1,152 @@
1
+ /**
2
+ * @module as-graph/nest/graph/GraphBackendHost
3
+ * @summary Boot-time engine-variant selection for the graph backend host (SAA-706).
4
+ * @description Resolves which of the three pluggable graph engines — the built-in
5
+ * local reference interpreter, the `@mastra/core` translated backend, or the
6
+ * read-only Dagster backend — a host boots, constructs and registers that
7
+ * backend, and assembles the {@link GraphExecutionModule} options that make the
8
+ * Nest host serve the matching C20 capability manifest (`graph/engines`) and the
9
+ * per-engine workflow catalogue (`graph/engines/{engineId}/workflows`).
10
+ *
11
+ * The host never stubs an engine: each variant constructs the real backend. A
12
+ * translated/remote backend whose host wiring is absent (no Mastra runtime, no
13
+ * Dagster client) still boots and serves the manifest; its catalogue then reports
14
+ * the engine's honest `NOT_SUPPORTED` verdict through the engine facade, exactly
15
+ * as `GraphEngineController` maps it to `501`. The variant is chosen at boot by
16
+ * the `GRAPH_BACKEND_ENGINE` environment variable, so switching engines is a
17
+ * configuration change, never a code change.
18
+ */
19
+ import type { GraphWorkflowDocument } from "../../shared/graph/index.d.mts";
20
+ import type { GraphExecutionBackend } from "../../engine/execution/GraphExecutionBackend.d.mts";
21
+ import { type MastraBackendConfig } from "../../mastra/types.d.mts";
22
+ import type { DagsterClient } from "../../dagster/DagsterTypes.d.mts";
23
+ import type { GraphExecutionModuleOptions } from "./GraphExecutionModule.d.mts";
24
+ /**
25
+ * The graph engine variants a host can boot. Each maps one-to-one onto the
26
+ * backend flavour it registers, which is also the allowlisted engine id the C20
27
+ * manifest advertises.
28
+ */
29
+ export type GraphEngineVariant = "local" | "mastra" | "dagster";
30
+ /** Every bootable engine variant, in manifest order. */
31
+ export declare const GRAPH_ENGINE_VARIANTS: readonly GraphEngineVariant[];
32
+ /** Environment variable selecting the engine variant the host boots. */
33
+ export declare const GRAPH_BACKEND_ENGINE_ENV = "GRAPH_BACKEND_ENGINE";
34
+ /** The engine variant a host boots when none is configured. */
35
+ export declare const DEFAULT_GRAPH_ENGINE_VARIANT: GraphEngineVariant;
36
+ /**
37
+ * Parses a configured engine variant, failing closed on an unknown value so a
38
+ * typo never silently boots the wrong engine.
39
+ *
40
+ * @param value - The raw configured value (`undefined`/empty selects the fallback).
41
+ * @param fallback - The variant to use when no value is configured.
42
+ * @returns The resolved engine variant.
43
+ * @throws {GraphExecutionError} when the value names no known variant.
44
+ */
45
+ export declare function parseGraphEngineVariant(value: string | undefined, fallback?: GraphEngineVariant): GraphEngineVariant;
46
+ /**
47
+ * Reads the engine variant from an environment bag (defaults to `process.env`),
48
+ * applying {@link parseGraphEngineVariant}.
49
+ *
50
+ * @param env - The environment to read from.
51
+ * @returns The resolved engine variant.
52
+ */
53
+ export declare function graphEngineVariantFromEnv(env?: NodeJS.ProcessEnv): GraphEngineVariant;
54
+ /** Environment variable gating boot-time demo-workflow seeding (F5 hardening). */
55
+ export declare const GRAPH_SEED_DEMO_ENV = "GRAPH_SEED_DEMO";
56
+ /**
57
+ * Resolves whether the standalone host seeds the demo workflow fixture registry
58
+ * at boot (F5 hardening). Seeding is enabled by default so a source checkout
59
+ * keeps its fixtures; a production host sets `GRAPH_SEED_DEMO=off` (also accepts
60
+ * `false` / `0` / `no` / `disabled`, case-insensitive) to suppress owner-less
61
+ * demo seeding without a code change. An unset or empty value keeps the default
62
+ * (enabled), so existing hosts are unaffected.
63
+ *
64
+ * @param env - The environment to read from (defaults to `process.env`).
65
+ * @returns `true` when boot-time demo seeding is enabled.
66
+ */
67
+ export declare function graphDemoSeedEnabledFromEnv(env?: NodeJS.ProcessEnv): boolean;
68
+ /** Host wiring for the Dagster variant: the client port plus its gate options. */
69
+ export interface GraphDagsterHostOptions {
70
+ /**
71
+ * The read-only Dagster client port. When omitted the backend still boots and
72
+ * serves the manifest, but its catalogue reports `NOT_SUPPORTED` because no
73
+ * deployment transport is wired.
74
+ */
75
+ client?: DagsterClient;
76
+ /** Opt-in gate for launching/replaying EXISTING workflows. Defaults to off. */
77
+ executionEnabled?: boolean;
78
+ /** Host-supplied default run tags. */
79
+ tags?: Record<string, string>;
80
+ }
81
+ /**
82
+ * Options for {@link createGraphBackendHost}: the selected variant plus the
83
+ * per-variant host wiring. Unused wiring for the unselected variant is ignored.
84
+ */
85
+ export interface GraphBackendHostOptions {
86
+ /** The engine variant to boot. */
87
+ variant: GraphEngineVariant;
88
+ /**
89
+ * Host wiring for the Mastra variant: the real `@mastra/core` runtime and the
90
+ * node-kind step handlers. Absent wiring boots a catalogue-less Mastra host.
91
+ */
92
+ mastra?: MastraBackendConfig;
93
+ /** Host wiring for the Dagster variant. */
94
+ dagster?: GraphDagsterHostOptions;
95
+ /**
96
+ * Canonical workflow documents seeded into the selected engine's catalogue at
97
+ * boot (the host's fixture registry). Forwarded to the module options so the
98
+ * per-engine workflow catalogue serves the fixture set for whichever variant
99
+ * the host booted. The seed stays engine-dependent and read-only for Dagster.
100
+ */
101
+ seedWorkflows?: readonly GraphWorkflowDocument[];
102
+ /**
103
+ * Existing module options to extend. The host overrides only `backend` and
104
+ * `engines.defaultEngineId`, so a caller keeps its auth, limits, adapter, and
105
+ * rate-limit configuration.
106
+ */
107
+ base?: GraphExecutionModuleOptions;
108
+ }
109
+ /**
110
+ * The result of {@link createGraphBackendHost}: the resolved variant, the
111
+ * allowlisted engine id it advertises, the constructed backend (absent for the
112
+ * local variant, which the engine constructs itself), and the assembled module
113
+ * options ready for `GraphExecutionModule.forRoot`.
114
+ */
115
+ export interface GraphBackendHost {
116
+ /** The resolved engine variant. */
117
+ variant: GraphEngineVariant;
118
+ /** The allowlisted engine id the manifest advertises for this variant. */
119
+ engineId: string;
120
+ /**
121
+ * The constructed backend the host selected, or `undefined` for the local
122
+ * variant (the engine constructs the built-in backend itself).
123
+ */
124
+ backend?: GraphExecutionBackend;
125
+ /** Module options carrying the selected backend and default engine id. */
126
+ moduleOptions: GraphExecutionModuleOptions;
127
+ }
128
+ /**
129
+ * Builds the bootable graph backend host for one engine variant: constructs and
130
+ * registers the selected backend, selects it as the registry current so the
131
+ * engine facade's default engine follows the variant, and assembles the
132
+ * {@link GraphExecutionModule} options that advertise that engine's capability
133
+ * manifest and per-engine workflow catalogue.
134
+ *
135
+ * @param options - The host options (variant, per-variant wiring, base options).
136
+ * @returns The resolved host, including the module options to boot.
137
+ */
138
+ export declare function createGraphBackendHost(options: GraphBackendHostOptions): Promise<GraphBackendHost>;
139
+ /**
140
+ * Loads the host's demo workflow fixture registry for boot-time seeding. This is
141
+ * the engine driver's seeding path (R4): the fixture registry is imported only
142
+ * by tests and by this loader. Because the registry is excluded from release
143
+ * packaging, the loader is best-effort — it returns the fixture documents when
144
+ * the registry is present (a source checkout or development install) and an
145
+ * empty set when it is absent (a published package), never failing the boot.
146
+ *
147
+ * @returns The canonical documents to seed, or an empty array when the registry
148
+ * is unavailable.
149
+ */
150
+ export declare function loadGraphDemoWorkflows(): Promise<readonly GraphWorkflowDocument[]>;
151
+ /** The allowlisted engine id for a variant (the backend flavour). */
152
+ export declare function graphEngineIdOf(variant: GraphEngineVariant): string;
@@ -11,6 +11,8 @@
11
11
  import { DynamicModule, Type } from "@nestjs/common";
12
12
  import type { AuthHandler } from "@decaf-ts/for-http/server";
13
13
  import { Adapter } from "@decaf-ts/core";
14
+ import type { GraphWorkflowDocument } from "../../shared/graph/index.d.cts";
15
+ import type { GraphExecutionBackend } from "../../engine/execution/GraphExecutionBackend.d.cts";
14
16
  import { type GraphCredentialAuthorizer, type GraphNamespaceMatchOptions } from "../..//index.d.cts";
15
17
  import { type GraphCatalogueControllerOptions } from "./GraphNodeCatalogueController.d.cts";
16
18
  import { type GraphRunControllerOptions } from "./GraphRunController.d.cts";
@@ -66,6 +68,27 @@ export interface GraphExecutionModuleOptions {
66
68
  * registered backends and never read from the environment or a remote engine.
67
69
  */
68
70
  engines?: GraphEngineCapabilityOptions;
71
+ /**
72
+ * Pluggable execution backend the host selects as the engine's active backend
73
+ * (SAA-706). When omitted the engine falls back to the registry's current
74
+ * backend and then to the built-in {@link LocalGraphExecutionBackend}, so the
75
+ * standard local host needs no wiring. A host that boots a translated/remote
76
+ * engine (Mastra, Dagster) constructs its backend, registers it, and passes it
77
+ * here; the capability manifest then advertises that engine's flavour. The
78
+ * backend must already be registered under its flavour (constructing the
79
+ * wrapper does this) so the manifest and the per-engine catalogue agree.
80
+ */
81
+ backend?: GraphExecutionBackend<any>;
82
+ /**
83
+ * Canonical workflow documents to seed into the active backend's catalogue at
84
+ * boot, so the per-engine workflow catalogue
85
+ * (`graph/engines/{engineId}/workflows`) and the ownership-filtered serving
86
+ * list (`graph/workflows`) serve the host's fixture set for whichever engine
87
+ * the host booted. The seed is engine-dependent (persistence for local,
88
+ * translated catalogue for Mastra, read-only catalogue for Dagster) and fails
89
+ * closed when the active backend exposes no seed surface.
90
+ */
91
+ seedWorkflows?: readonly GraphWorkflowDocument[];
69
92
  /**
70
93
  * Production hosts MUST wire a {@link GraphCredentialAuthorizer} backed by
71
94
  * their credential store (DECAF-50 §4.8 stage 8). Without it, stage-8
@@ -11,6 +11,8 @@
11
11
  import { DynamicModule, Type } from "@nestjs/common";
12
12
  import type { AuthHandler } from "@decaf-ts/for-http/server";
13
13
  import { Adapter } from "@decaf-ts/core";
14
+ import type { GraphWorkflowDocument } from "../../shared/graph/index.d.mts";
15
+ import type { GraphExecutionBackend } from "../../engine/execution/GraphExecutionBackend.d.mts";
14
16
  import { type GraphCredentialAuthorizer, type GraphNamespaceMatchOptions } from "../..//index.d.mts";
15
17
  import { type GraphCatalogueControllerOptions } from "./GraphNodeCatalogueController.d.mts";
16
18
  import { type GraphRunControllerOptions } from "./GraphRunController.d.mts";
@@ -66,6 +68,27 @@ export interface GraphExecutionModuleOptions {
66
68
  * registered backends and never read from the environment or a remote engine.
67
69
  */
68
70
  engines?: GraphEngineCapabilityOptions;
71
+ /**
72
+ * Pluggable execution backend the host selects as the engine's active backend
73
+ * (SAA-706). When omitted the engine falls back to the registry's current
74
+ * backend and then to the built-in {@link LocalGraphExecutionBackend}, so the
75
+ * standard local host needs no wiring. A host that boots a translated/remote
76
+ * engine (Mastra, Dagster) constructs its backend, registers it, and passes it
77
+ * here; the capability manifest then advertises that engine's flavour. The
78
+ * backend must already be registered under its flavour (constructing the
79
+ * wrapper does this) so the manifest and the per-engine catalogue agree.
80
+ */
81
+ backend?: GraphExecutionBackend<any>;
82
+ /**
83
+ * Canonical workflow documents to seed into the active backend's catalogue at
84
+ * boot, so the per-engine workflow catalogue
85
+ * (`graph/engines/{engineId}/workflows`) and the ownership-filtered serving
86
+ * list (`graph/workflows`) serve the host's fixture set for whichever engine
87
+ * the host booted. The seed is engine-dependent (persistence for local,
88
+ * translated catalogue for Mastra, read-only catalogue for Dagster) and fails
89
+ * closed when the active backend exposes no seed surface.
90
+ */
91
+ seedWorkflows?: readonly GraphWorkflowDocument[];
69
92
  /**
70
93
  * Production hosts MUST wire a {@link GraphCredentialAuthorizer} backed by
71
94
  * their credential store (DECAF-50 §4.8 stage 8). Without it, stage-8
@@ -13,3 +13,4 @@ export * from "./GraphEngineCapabilityManifest.d.cts";
13
13
  export * from "./GraphEngineCapabilityService.d.cts";
14
14
  export * from "./GraphEngineController.d.cts";
15
15
  export * from "./GraphExecutionModule.d.cts";
16
+ export * from "./GraphBackendHost.d.cts";
@@ -13,3 +13,4 @@ export * from "./GraphEngineCapabilityManifest.d.mts";
13
13
  export * from "./GraphEngineCapabilityService.d.mts";
14
14
  export * from "./GraphEngineController.d.mts";
15
15
  export * from "./GraphExecutionModule.d.mts";
16
+ export * from "./GraphBackendHost.d.mts";
@@ -0,0 +1,13 @@
1
+ /**
2
+ * @module as-graph/ram/GraphNodeRepository
3
+ * @summary Adapter-backed repository for graph node-kind rows (SAA-774 R3).
4
+ * @description Repository for {@link GraphNodeModel} rows. Callers provide the
5
+ * adapter (a `RamAdapter` via {@link createRamGraphAdapter} in tests, a durable
6
+ * adapter in production); it is never created implicitly.
7
+ */
8
+ import { Repository, type Adapter } from "@decaf-ts/core";
9
+ import { GraphNodeModel } from "../shared/graph/index.d.cts";
10
+ /** Repository for {@link GraphNodeModel} rows. */
11
+ export declare class GraphNodeRepository extends Repository<GraphNodeModel, Adapter<any, any, any, any>> {
12
+ constructor(adapter?: Adapter<any, any, any, any>);
13
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * @module as-graph/ram/GraphNodeRepository
3
+ * @summary Adapter-backed repository for graph node-kind rows (SAA-774 R3).
4
+ * @description Repository for {@link GraphNodeModel} rows. Callers provide the
5
+ * adapter (a `RamAdapter` via {@link createRamGraphAdapter} in tests, a durable
6
+ * adapter in production); it is never created implicitly.
7
+ */
8
+ import { Repository, type Adapter } from "@decaf-ts/core";
9
+ import { GraphNodeModel } from "../shared/graph/index.d.mts";
10
+ /** Repository for {@link GraphNodeModel} rows. */
11
+ export declare class GraphNodeRepository extends Repository<GraphNodeModel, Adapter<any, any, any, any>> {
12
+ constructor(adapter?: Adapter<any, any, any, any>);
13
+ }
@@ -24,6 +24,7 @@ export * from "../engine/runs/GraphRunConverters.d.cts";
24
24
  export * from "./GraphRunEventModel.d.cts";
25
25
  export * from "./GraphRunStore.d.cts";
26
26
  export * from "./GraphRunEventStore.d.cts";
27
+ export * from "./GraphNodeRepository.d.cts";
27
28
  /**
28
29
  * Creates and initializes a {@link RamAdapter} for use with the ram-backed
29
30
  * stores. Tests use this; production passes a durable adapter instead.
@@ -24,6 +24,7 @@ export * from "../engine/runs/GraphRunConverters.d.mts";
24
24
  export * from "./GraphRunEventModel.d.mts";
25
25
  export * from "./GraphRunStore.d.mts";
26
26
  export * from "./GraphRunEventStore.d.mts";
27
+ export * from "./GraphNodeRepository.d.mts";
27
28
  /**
28
29
  * Creates and initializes a {@link RamAdapter} for use with the ram-backed
29
30
  * stores. Tests use this; production passes a durable adapter instead.
@@ -0,0 +1,15 @@
1
+ import type { GraphNodeManifest } from "./catalog/index.d.cts";
2
+ import { GraphNodeModel } from "./GraphNodeModel.d.cts";
3
+ /**
4
+ * Builds a {@link GraphNodeModel} row from a node-kind manifest, mirroring the
5
+ * display summary into dedicated columns while keeping the full JSON-safe
6
+ * manifest on the row.
7
+ */
8
+ export declare function manifestToNodeModel(manifest: GraphNodeManifest): GraphNodeModel;
9
+ /**
10
+ * Restores the JSON-safe {@link GraphNodeManifest} from a persisted
11
+ * {@link GraphNodeModel} row.
12
+ *
13
+ * @throws {ValidationError} When the row carries no manifest.
14
+ */
15
+ export declare function nodeModelToManifest(model: GraphNodeModel): GraphNodeManifest;
@@ -0,0 +1,15 @@
1
+ import type { GraphNodeManifest } from "./catalog/index.d.mts";
2
+ import { GraphNodeModel } from "./GraphNodeModel.d.mts";
3
+ /**
4
+ * Builds a {@link GraphNodeModel} row from a node-kind manifest, mirroring the
5
+ * display summary into dedicated columns while keeping the full JSON-safe
6
+ * manifest on the row.
7
+ */
8
+ export declare function manifestToNodeModel(manifest: GraphNodeManifest): GraphNodeModel;
9
+ /**
10
+ * Restores the JSON-safe {@link GraphNodeManifest} from a persisted
11
+ * {@link GraphNodeModel} row.
12
+ *
13
+ * @throws {ValidationError} When the row carries no manifest.
14
+ */
15
+ export declare function nodeModelToManifest(model: GraphNodeModel): GraphNodeManifest;
@@ -0,0 +1,24 @@
1
+ import { BaseModel } from "@decaf-ts/core";
2
+ import type { GraphNodeManifest } from "./catalog/index.d.cts";
3
+ /**
4
+ * Persistent row for a node kind exposed through repository/adapter CRUD.
5
+ *
6
+ * `kind` is the catalogue key and the primary key. The `name`, `category`,
7
+ * `group` and `description` columns mirror `manifest.display` so listings can be
8
+ * filtered and sorted without deserialising the full manifest.
9
+ */
10
+ export declare class GraphNodeModel extends BaseModel {
11
+ /** Registered node kind; the catalogue key and primary key, never generated. */
12
+ kind: string;
13
+ /** Display name mirrored from `manifest.display.name`. */
14
+ name?: string;
15
+ /** Display category mirrored from `manifest.display.category`. */
16
+ category?: string;
17
+ /** Display group mirrored from `manifest.display.group`. */
18
+ group?: string;
19
+ /** Display description mirrored from `manifest.display.description`. */
20
+ description?: string;
21
+ /** Full JSON-safe manifest for the kind. */
22
+ manifest?: GraphNodeManifest;
23
+ constructor(arg?: Partial<GraphNodeModel>);
24
+ }
@@ -0,0 +1,24 @@
1
+ import { BaseModel } from "@decaf-ts/core";
2
+ import type { GraphNodeManifest } from "./catalog/index.d.mts";
3
+ /**
4
+ * Persistent row for a node kind exposed through repository/adapter CRUD.
5
+ *
6
+ * `kind` is the catalogue key and the primary key. The `name`, `category`,
7
+ * `group` and `description` columns mirror `manifest.display` so listings can be
8
+ * filtered and sorted without deserialising the full manifest.
9
+ */
10
+ export declare class GraphNodeModel extends BaseModel {
11
+ /** Registered node kind; the catalogue key and primary key, never generated. */
12
+ kind: string;
13
+ /** Display name mirrored from `manifest.display.name`. */
14
+ name?: string;
15
+ /** Display category mirrored from `manifest.display.category`. */
16
+ category?: string;
17
+ /** Display group mirrored from `manifest.display.group`. */
18
+ group?: string;
19
+ /** Display description mirrored from `manifest.display.description`. */
20
+ description?: string;
21
+ /** Full JSON-safe manifest for the kind. */
22
+ manifest?: GraphNodeManifest;
23
+ constructor(arg?: Partial<GraphNodeModel>);
24
+ }
@@ -16,6 +16,8 @@ export * from "./layout/index.d.cts";
16
16
  export * from "./types.d.cts";
17
17
  export * from "./GraphRunModel.d.cts";
18
18
  export * from "./GraphWorkflowModel.d.cts";
19
+ export * from "./GraphNodeModel.d.cts";
20
+ export * from "./GraphNodeConverters.d.cts";
19
21
  export * from "./GraphResolution.d.cts";
20
22
  export * from "./GraphExecutionStateMapper.d.cts";
21
23
  export * from "./category-styles.d.cts";
@@ -16,6 +16,8 @@ export * from "./layout/index.d.mts";
16
16
  export * from "./types.d.mts";
17
17
  export * from "./GraphRunModel.d.mts";
18
18
  export * from "./GraphWorkflowModel.d.mts";
19
+ export * from "./GraphNodeModel.d.mts";
20
+ export * from "./GraphNodeConverters.d.mts";
19
21
  export * from "./GraphResolution.d.mts";
20
22
  export * from "./GraphExecutionStateMapper.d.mts";
21
23
  export * from "./category-styles.d.mts";