@decaf-ts/as-graph 0.2.1 → 0.4.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 (285) hide show
  1. package/README.md +158 -2
  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/DagsterGraphEventBridge.cjs +344 -0
  7. package/lib/cjs/dagster/DagsterGraphEventBridge.cjs.map +1 -0
  8. package/lib/cjs/dagster/DagsterGraphExecutionBackend.cjs +789 -0
  9. package/lib/cjs/dagster/DagsterGraphExecutionBackend.cjs.map +1 -0
  10. package/lib/cjs/dagster/DagsterResultMapper.cjs +56 -0
  11. package/lib/cjs/dagster/DagsterResultMapper.cjs.map +1 -0
  12. package/lib/cjs/dagster/DagsterTypes.cjs +4 -0
  13. package/lib/cjs/dagster/DagsterTypes.cjs.map +1 -0
  14. package/lib/cjs/dagster/capabilities.cjs +102 -0
  15. package/lib/cjs/dagster/capabilities.cjs.map +1 -0
  16. package/lib/cjs/dagster/constants.cjs +92 -0
  17. package/lib/cjs/dagster/constants.cjs.map +1 -0
  18. package/lib/cjs/dagster/index.cjs +32 -0
  19. package/lib/cjs/dagster/index.cjs.map +1 -0
  20. package/lib/cjs/engine/constants.cjs +6 -1
  21. package/lib/cjs/engine/constants.cjs.map +1 -1
  22. package/lib/cjs/engine/execution/GraphCodeMode.cjs +137 -0
  23. package/lib/cjs/engine/execution/GraphCodeMode.cjs.map +1 -0
  24. package/lib/cjs/engine/execution/GraphExecutionBackend.cjs +89 -0
  25. package/lib/cjs/engine/execution/GraphExecutionBackend.cjs.map +1 -0
  26. package/lib/cjs/engine/execution/GraphExecutionBackendRegistry.cjs +107 -0
  27. package/lib/cjs/engine/execution/GraphExecutionBackendRegistry.cjs.map +1 -0
  28. package/lib/cjs/engine/execution/GraphExecutionEngine.cjs +250 -733
  29. package/lib/cjs/engine/execution/GraphExecutionEngine.cjs.map +1 -1
  30. package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs +804 -0
  31. package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs.map +1 -0
  32. package/lib/cjs/engine/execution/index.cjs +4 -0
  33. package/lib/cjs/engine/execution/index.cjs.map +1 -1
  34. package/lib/cjs/engine/index.cjs +4 -0
  35. package/lib/cjs/engine/index.cjs.map +1 -1
  36. package/lib/cjs/engine/runs/GraphRunService.cjs +61 -0
  37. package/lib/cjs/engine/runs/GraphRunService.cjs.map +1 -1
  38. package/lib/cjs/engine/services/GraphWorkflowService.cjs +33 -14
  39. package/lib/cjs/engine/services/GraphWorkflowService.cjs.map +1 -1
  40. package/lib/cjs/mastra/MastraCapabilities.cjs +171 -0
  41. package/lib/cjs/mastra/MastraCapabilities.cjs.map +1 -0
  42. package/lib/cjs/mastra/MastraConditionBridge.cjs +39 -0
  43. package/lib/cjs/mastra/MastraConditionBridge.cjs.map +1 -0
  44. package/lib/cjs/mastra/MastraEventBridge.cjs +486 -0
  45. package/lib/cjs/mastra/MastraEventBridge.cjs.map +1 -0
  46. package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs +351 -0
  47. package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs.map +1 -0
  48. package/lib/cjs/mastra/MastraResumeGuard.cjs +127 -0
  49. package/lib/cjs/mastra/MastraResumeGuard.cjs.map +1 -0
  50. package/lib/cjs/mastra/MastraSchemaConverter.cjs +124 -0
  51. package/lib/cjs/mastra/MastraSchemaConverter.cjs.map +1 -0
  52. package/lib/cjs/mastra/MastraWorkflowCompiler.cjs +461 -0
  53. package/lib/cjs/mastra/MastraWorkflowCompiler.cjs.map +1 -0
  54. package/lib/cjs/mastra/MastraWorkflowManager.cjs +401 -0
  55. package/lib/cjs/mastra/MastraWorkflowManager.cjs.map +1 -0
  56. package/lib/cjs/mastra/index.cjs +35 -0
  57. package/lib/cjs/mastra/index.cjs.map +1 -0
  58. package/lib/cjs/mastra/types.cjs +34 -0
  59. package/lib/cjs/mastra/types.cjs.map +1 -0
  60. package/lib/cjs/nest/graph/GraphEngineCapabilityManifest.cjs +136 -0
  61. package/lib/cjs/nest/graph/GraphEngineCapabilityManifest.cjs.map +1 -0
  62. package/lib/cjs/nest/graph/GraphEngineCapabilityService.cjs +140 -0
  63. package/lib/cjs/nest/graph/GraphEngineCapabilityService.cjs.map +1 -0
  64. package/lib/cjs/nest/graph/GraphEngineController.cjs +227 -0
  65. package/lib/cjs/nest/graph/GraphEngineController.cjs.map +1 -0
  66. package/lib/cjs/nest/graph/GraphExecutionModule.cjs +30 -2
  67. package/lib/cjs/nest/graph/GraphExecutionModule.cjs.map +1 -1
  68. package/lib/cjs/nest/graph/index.cjs +3 -0
  69. package/lib/cjs/nest/graph/index.cjs.map +1 -1
  70. package/lib/cjs/nest/graph/main.cjs +54 -0
  71. package/lib/cjs/nest/graph/main.cjs.map +1 -0
  72. package/lib/cjs/nest/graph/servingErrors.cjs +3 -0
  73. package/lib/cjs/nest/graph/servingErrors.cjs.map +1 -1
  74. package/lib/cjs/node/utility/code/node.cjs +11 -3
  75. package/lib/cjs/node/utility/code/node.cjs.map +1 -1
  76. package/lib/cjs/shared/graph/catalog/GraphManifestCompiler.cjs +2 -3
  77. package/lib/cjs/shared/graph/catalog/GraphManifestCompiler.cjs.map +1 -1
  78. package/lib/cjs/shared/graph/constants.cjs +8 -0
  79. package/lib/cjs/shared/graph/constants.cjs.map +1 -1
  80. package/lib/cjs/shared/graph/index.cjs +2 -1
  81. package/lib/cjs/shared/graph/index.cjs.map +1 -1
  82. package/lib/cjs/shared/graph/layout/GraphWorkflowLayout.cjs +146 -0
  83. package/lib/cjs/shared/graph/layout/GraphWorkflowLayout.cjs.map +1 -0
  84. package/lib/cjs/shared/graph/layout/index.cjs +23 -0
  85. package/lib/cjs/shared/graph/layout/index.cjs.map +1 -0
  86. package/lib/cjs/shared/graph/layout/layout-options.cjs +93 -0
  87. package/lib/cjs/shared/graph/layout/layout-options.cjs.map +1 -0
  88. package/lib/cjs/shared/ui/index.cjs +8 -10
  89. package/lib/cjs/shared/ui/index.cjs.map +1 -1
  90. package/lib/esm/dagster/DagsterGraphEventBridge.js +339 -0
  91. package/lib/esm/dagster/DagsterGraphEventBridge.js.map +1 -0
  92. package/lib/esm/dagster/DagsterGraphExecutionBackend.js +781 -0
  93. package/lib/esm/dagster/DagsterGraphExecutionBackend.js.map +1 -0
  94. package/lib/esm/dagster/DagsterResultMapper.js +51 -0
  95. package/lib/esm/dagster/DagsterResultMapper.js.map +1 -0
  96. package/lib/esm/dagster/DagsterTypes.js +2 -0
  97. package/lib/esm/dagster/DagsterTypes.js.map +1 -0
  98. package/lib/esm/dagster/capabilities.js +97 -0
  99. package/lib/esm/dagster/capabilities.js.map +1 -0
  100. package/lib/esm/dagster/constants.js +88 -0
  101. package/lib/esm/dagster/constants.js.map +1 -0
  102. package/lib/esm/dagster/index.js +15 -0
  103. package/lib/esm/dagster/index.js.map +1 -0
  104. package/lib/esm/engine/constants.js +5 -0
  105. package/lib/esm/engine/constants.js.map +1 -1
  106. package/lib/esm/engine/execution/GraphCodeMode.js +132 -0
  107. package/lib/esm/engine/execution/GraphCodeMode.js.map +1 -0
  108. package/lib/esm/engine/execution/GraphExecutionBackend.js +83 -0
  109. package/lib/esm/engine/execution/GraphExecutionBackend.js.map +1 -0
  110. package/lib/esm/engine/execution/GraphExecutionBackendRegistry.js +102 -0
  111. package/lib/esm/engine/execution/GraphExecutionBackendRegistry.js.map +1 -0
  112. package/lib/esm/engine/execution/GraphExecutionEngine.js +232 -716
  113. package/lib/esm/engine/execution/GraphExecutionEngine.js.map +1 -1
  114. package/lib/esm/engine/execution/LocalGraphExecutionBackend.js +799 -0
  115. package/lib/esm/engine/execution/LocalGraphExecutionBackend.js.map +1 -0
  116. package/lib/esm/engine/execution/index.js +4 -0
  117. package/lib/esm/engine/execution/index.js.map +1 -1
  118. package/lib/esm/engine/index.js +4 -0
  119. package/lib/esm/engine/index.js.map +1 -1
  120. package/lib/esm/engine/runs/GraphRunService.js +62 -1
  121. package/lib/esm/engine/runs/GraphRunService.js.map +1 -1
  122. package/lib/esm/engine/services/GraphWorkflowService.js +33 -14
  123. package/lib/esm/engine/services/GraphWorkflowService.js.map +1 -1
  124. package/lib/esm/mastra/MastraCapabilities.js +164 -0
  125. package/lib/esm/mastra/MastraCapabilities.js.map +1 -0
  126. package/lib/esm/mastra/MastraConditionBridge.js +34 -0
  127. package/lib/esm/mastra/MastraConditionBridge.js.map +1 -0
  128. package/lib/esm/mastra/MastraEventBridge.js +481 -0
  129. package/lib/esm/mastra/MastraEventBridge.js.map +1 -0
  130. package/lib/esm/mastra/MastraGraphExecutionBackend.js +346 -0
  131. package/lib/esm/mastra/MastraGraphExecutionBackend.js.map +1 -0
  132. package/lib/esm/mastra/MastraResumeGuard.js +123 -0
  133. package/lib/esm/mastra/MastraResumeGuard.js.map +1 -0
  134. package/lib/esm/mastra/MastraSchemaConverter.js +119 -0
  135. package/lib/esm/mastra/MastraSchemaConverter.js.map +1 -0
  136. package/lib/esm/mastra/MastraWorkflowCompiler.js +456 -0
  137. package/lib/esm/mastra/MastraWorkflowCompiler.js.map +1 -0
  138. package/lib/esm/mastra/MastraWorkflowManager.js +396 -0
  139. package/lib/esm/mastra/MastraWorkflowManager.js.map +1 -0
  140. package/lib/esm/mastra/index.js +18 -0
  141. package/lib/esm/mastra/index.js.map +1 -0
  142. package/lib/esm/mastra/types.js +30 -0
  143. package/lib/esm/mastra/types.js.map +1 -0
  144. package/lib/esm/nest/graph/GraphEngineCapabilityManifest.js +129 -0
  145. package/lib/esm/nest/graph/GraphEngineCapabilityManifest.js.map +1 -0
  146. package/lib/esm/nest/graph/GraphEngineCapabilityService.js +131 -0
  147. package/lib/esm/nest/graph/GraphEngineCapabilityService.js.map +1 -0
  148. package/lib/esm/nest/graph/GraphEngineController.js +218 -0
  149. package/lib/esm/nest/graph/GraphEngineController.js.map +1 -0
  150. package/lib/esm/nest/graph/GraphExecutionModule.js +30 -2
  151. package/lib/esm/nest/graph/GraphExecutionModule.js.map +1 -1
  152. package/lib/esm/nest/graph/index.js +3 -0
  153. package/lib/esm/nest/graph/index.js.map +1 -1
  154. package/lib/esm/nest/graph/main.js +51 -0
  155. package/lib/esm/nest/graph/main.js.map +1 -0
  156. package/lib/esm/nest/graph/servingErrors.js +3 -0
  157. package/lib/esm/nest/graph/servingErrors.js.map +1 -1
  158. package/lib/esm/node/utility/code/node.js +11 -3
  159. package/lib/esm/node/utility/code/node.js.map +1 -1
  160. package/lib/esm/shared/graph/GraphExecutionStateMapper.js.map +1 -1
  161. package/lib/esm/shared/graph/catalog/GraphManifestCompiler.js +2 -3
  162. package/lib/esm/shared/graph/catalog/GraphManifestCompiler.js.map +1 -1
  163. package/lib/esm/shared/graph/constants.js +8 -0
  164. package/lib/esm/shared/graph/constants.js.map +1 -1
  165. package/lib/esm/shared/graph/index.js +2 -1
  166. package/lib/esm/shared/graph/index.js.map +1 -1
  167. package/lib/esm/shared/graph/layout/GraphWorkflowLayout.js +107 -0
  168. package/lib/esm/shared/graph/layout/GraphWorkflowLayout.js.map +1 -0
  169. package/lib/esm/shared/graph/layout/index.js +6 -0
  170. package/lib/esm/shared/graph/layout/index.js.map +1 -0
  171. package/lib/esm/shared/graph/layout/layout-options.js +96 -0
  172. package/lib/esm/shared/graph/layout/layout-options.js.map +1 -0
  173. package/lib/esm/shared/ui/index.js +8 -10
  174. package/lib/esm/shared/ui/index.js.map +1 -1
  175. package/lib/types/dagster/DagsterGraphEventBridge.d.cts +142 -0
  176. package/lib/types/dagster/DagsterGraphEventBridge.d.mts +142 -0
  177. package/lib/types/dagster/DagsterGraphExecutionBackend.d.cts +323 -0
  178. package/lib/types/dagster/DagsterGraphExecutionBackend.d.mts +323 -0
  179. package/lib/types/dagster/DagsterResultMapper.d.cts +50 -0
  180. package/lib/types/dagster/DagsterResultMapper.d.mts +50 -0
  181. package/lib/types/dagster/DagsterTypes.d.cts +355 -0
  182. package/lib/types/dagster/DagsterTypes.d.mts +355 -0
  183. package/lib/types/dagster/capabilities.d.cts +34 -0
  184. package/lib/types/dagster/capabilities.d.mts +34 -0
  185. package/lib/types/dagster/constants.d.cts +87 -0
  186. package/lib/types/dagster/constants.d.mts +87 -0
  187. package/lib/types/dagster/index.d.cts +14 -0
  188. package/lib/types/dagster/index.d.mts +14 -0
  189. package/lib/types/engine/constants.d.cts +5 -0
  190. package/lib/types/engine/constants.d.mts +5 -0
  191. package/lib/types/engine/execution/GraphCodeMode.d.cts +52 -0
  192. package/lib/types/engine/execution/GraphCodeMode.d.mts +52 -0
  193. package/lib/types/engine/execution/GraphExecutionBackend.d.cts +306 -0
  194. package/lib/types/engine/execution/GraphExecutionBackend.d.mts +306 -0
  195. package/lib/types/engine/execution/GraphExecutionBackendRegistry.d.cts +59 -0
  196. package/lib/types/engine/execution/GraphExecutionBackendRegistry.d.mts +59 -0
  197. package/lib/types/engine/execution/GraphExecutionEngine.d.cts +116 -135
  198. package/lib/types/engine/execution/GraphExecutionEngine.d.mts +116 -135
  199. package/lib/types/engine/execution/LocalGraphExecutionBackend.d.cts +232 -0
  200. package/lib/types/engine/execution/LocalGraphExecutionBackend.d.mts +232 -0
  201. package/lib/types/engine/execution/index.d.cts +4 -0
  202. package/lib/types/engine/execution/index.d.mts +4 -0
  203. package/lib/types/engine/index.d.cts +4 -0
  204. package/lib/types/engine/index.d.mts +4 -0
  205. package/lib/types/engine/runs/GraphRunService.d.cts +19 -0
  206. package/lib/types/engine/runs/GraphRunService.d.mts +19 -0
  207. package/lib/types/engine/services/GraphWorkflowService.d.cts +22 -0
  208. package/lib/types/engine/services/GraphWorkflowService.d.mts +22 -0
  209. package/lib/types/mastra/MastraCapabilities.d.cts +91 -0
  210. package/lib/types/mastra/MastraCapabilities.d.mts +91 -0
  211. package/lib/types/mastra/MastraConditionBridge.d.cts +38 -0
  212. package/lib/types/mastra/MastraConditionBridge.d.mts +38 -0
  213. package/lib/types/mastra/MastraEventBridge.d.cts +189 -0
  214. package/lib/types/mastra/MastraEventBridge.d.mts +189 -0
  215. package/lib/types/mastra/MastraGraphExecutionBackend.d.cts +119 -0
  216. package/lib/types/mastra/MastraGraphExecutionBackend.d.mts +119 -0
  217. package/lib/types/mastra/MastraResumeGuard.d.cts +58 -0
  218. package/lib/types/mastra/MastraResumeGuard.d.mts +58 -0
  219. package/lib/types/mastra/MastraSchemaConverter.d.cts +39 -0
  220. package/lib/types/mastra/MastraSchemaConverter.d.mts +39 -0
  221. package/lib/types/mastra/MastraWorkflowCompiler.d.cts +218 -0
  222. package/lib/types/mastra/MastraWorkflowCompiler.d.mts +218 -0
  223. package/lib/types/mastra/MastraWorkflowManager.d.cts +220 -0
  224. package/lib/types/mastra/MastraWorkflowManager.d.mts +220 -0
  225. package/lib/types/mastra/index.d.cts +17 -0
  226. package/lib/types/mastra/index.d.mts +17 -0
  227. package/lib/types/mastra/types.d.cts +222 -0
  228. package/lib/types/mastra/types.d.mts +222 -0
  229. package/lib/types/nest/graph/GraphEngineCapabilityManifest.d.cts +87 -0
  230. package/lib/types/nest/graph/GraphEngineCapabilityManifest.d.mts +87 -0
  231. package/lib/types/nest/graph/GraphEngineCapabilityService.d.cts +98 -0
  232. package/lib/types/nest/graph/GraphEngineCapabilityService.d.mts +98 -0
  233. package/lib/types/nest/graph/GraphEngineController.d.cts +74 -0
  234. package/lib/types/nest/graph/GraphEngineController.d.mts +74 -0
  235. package/lib/types/nest/graph/GraphExecutionModule.d.cts +8 -0
  236. package/lib/types/nest/graph/GraphExecutionModule.d.mts +8 -0
  237. package/lib/types/nest/graph/index.d.cts +3 -0
  238. package/lib/types/nest/graph/index.d.mts +3 -0
  239. package/lib/types/nest/graph/main.d.cts +1 -0
  240. package/lib/types/nest/graph/main.d.mts +1 -0
  241. package/lib/types/nest/graph/servingErrors.d.cts +3 -1
  242. package/lib/types/nest/graph/servingErrors.d.mts +3 -1
  243. package/lib/types/node/utility/code/node.d.cts +1 -1
  244. package/lib/types/node/utility/code/node.d.mts +1 -1
  245. package/lib/types/shared/graph/GraphExecutionStateMapper.d.cts +5 -5
  246. package/lib/types/shared/graph/GraphExecutionStateMapper.d.mts +5 -5
  247. package/lib/types/shared/graph/constants.d.cts +8 -0
  248. package/lib/types/shared/graph/constants.d.mts +8 -0
  249. package/lib/types/shared/graph/index.d.cts +2 -1
  250. package/lib/types/shared/graph/index.d.mts +2 -1
  251. package/lib/types/shared/graph/layout/GraphWorkflowLayout.d.cts +49 -0
  252. package/lib/types/shared/graph/layout/GraphWorkflowLayout.d.mts +49 -0
  253. package/lib/types/shared/graph/layout/index.d.cts +5 -0
  254. package/lib/types/shared/graph/layout/index.d.mts +5 -0
  255. package/lib/types/shared/graph/layout/layout-options.d.cts +46 -0
  256. package/lib/types/shared/graph/layout/layout-options.d.mts +46 -0
  257. package/lib/types/shared/graph/types.d.cts +4 -3
  258. package/lib/types/shared/graph/types.d.mts +4 -3
  259. package/lib/types/shared/ui/index.d.cts +8 -10
  260. package/lib/types/shared/ui/index.d.mts +8 -10
  261. package/package.json +49 -6
  262. package/lib/cjs/shared/ui/GraphNodeView.cjs +0 -114
  263. package/lib/cjs/shared/ui/GraphNodeView.cjs.map +0 -1
  264. package/lib/cjs/shared/ui/GraphRunView.cjs +0 -96
  265. package/lib/cjs/shared/ui/GraphRunView.cjs.map +0 -1
  266. package/lib/cjs/shared/ui/GraphWorkflowView.cjs +0 -78
  267. package/lib/cjs/shared/ui/GraphWorkflowView.cjs.map +0 -1
  268. package/lib/cjs/shared/ui/types.cjs +0 -4
  269. package/lib/cjs/shared/ui/types.cjs.map +0 -1
  270. package/lib/esm/shared/ui/GraphNodeView.js +0 -107
  271. package/lib/esm/shared/ui/GraphNodeView.js.map +0 -1
  272. package/lib/esm/shared/ui/GraphRunView.js +0 -90
  273. package/lib/esm/shared/ui/GraphRunView.js.map +0 -1
  274. package/lib/esm/shared/ui/GraphWorkflowView.js +0 -72
  275. package/lib/esm/shared/ui/GraphWorkflowView.js.map +0 -1
  276. package/lib/esm/shared/ui/types.js +0 -2
  277. package/lib/esm/shared/ui/types.js.map +0 -1
  278. package/lib/types/shared/ui/GraphNodeView.d.cts +0 -48
  279. package/lib/types/shared/ui/GraphNodeView.d.mts +0 -48
  280. package/lib/types/shared/ui/GraphRunView.d.cts +0 -88
  281. package/lib/types/shared/ui/GraphRunView.d.mts +0 -88
  282. package/lib/types/shared/ui/GraphWorkflowView.d.cts +0 -18
  283. package/lib/types/shared/ui/GraphWorkflowView.d.mts +0 -18
  284. package/lib/types/shared/ui/types.d.cts +0 -200
  285. package/lib/types/shared/ui/types.d.mts +0 -200
@@ -0,0 +1,222 @@
1
+ /**
2
+ * @module as-graph/mastra/types
3
+ * @summary Mastra backend shared types, ports, and error codes (SAA-196).
4
+ * @description Contract surface of the `@mastra/core`-translated execution
5
+ * backend: the registered backend flavour, the fail-closed error codes, the
6
+ * host-provided node step handlers that own `createStep` translation, the
7
+ * backend configuration, and the suspend-state reader port Mastra resume relies
8
+ * on. Mastra owns execution state for suspended runs; these types only describe
9
+ * what the host injects and what resume auditing returns.
10
+ */
11
+ import type { Context, MaybeContextualArg } from "@decaf-ts/core";
12
+ import type { GraphBackendWorkflowStore, GraphBackendWorkflowSummary, GraphExecutionBackend } from "../engine/execution/GraphExecutionBackend.d.mts";
13
+ import type { GraphExecutionValues, GraphRunId } from "../engine/types.d.mts";
14
+ import type { GraphNodeInstance } from "../shared/graph/document/GraphNodeInstance.d.mts";
15
+ import type { MastraWorkflowCompiler } from "./MastraWorkflowCompiler.d.mts";
16
+ /** The flavour id the Mastra backend registers under in the backend registry. */
17
+ export declare const MASTRA_BACKEND_FLAVOUR = "mastra";
18
+ /** A document node kind the Mastra translator cannot represent. */
19
+ export declare const GRAPH_MASTRA_UNSUPPORTED_KIND = "GRAPH_MASTRA_UNSUPPORTED_KIND";
20
+ /** A suspendable step declared a missing or degraded resume schema. */
21
+ export declare const GRAPH_MASTRA_RESUME_SCHEMA_UNSAFE = "GRAPH_MASTRA_RESUME_SCHEMA_UNSAFE";
22
+ /** A resume request failed validation (size, JSON safety, schema, or step). */
23
+ export declare const GRAPH_MASTRA_RESUME_INVALID = "GRAPH_MASTRA_RESUME_INVALID";
24
+ /** The resume step or iteration index is not allowlisted by the document. */
25
+ export declare const GRAPH_MASTRA_RESUME_STEP_UNKNOWN = "GRAPH_MASTRA_RESUME_STEP_UNKNOWN";
26
+ /** The Mastra snapshot is not a suspended run of the current document. */
27
+ export declare const GRAPH_MASTRA_RESUME_STATE_INVALID = "GRAPH_MASTRA_RESUME_STATE_INVALID";
28
+ /** The document translation emitted non-JSON-safe Mastra config. */
29
+ export declare const GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE = "GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE";
30
+ /** No Mastra agent is available for an agent-backed node. */
31
+ export declare const GRAPH_MASTRA_AGENT_UNAVAILABLE = "GRAPH_MASTRA_AGENT_UNAVAILABLE";
32
+ /** The wired Mastra runtime exposes no workflow-management surface. */
33
+ export declare const GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE = "GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE";
34
+ /** A managed workflow id has no workflow registered on the runtime. */
35
+ export declare const GRAPH_MASTRA_WORKFLOW_NOT_FOUND = "GRAPH_MASTRA_WORKFLOW_NOT_FOUND";
36
+ /** Persisting a translated workflow to Mastra storage is not supported. */
37
+ export declare const GRAPH_MASTRA_PERSIST_NOT_SUPPORTED = "GRAPH_MASTRA_PERSIST_NOT_SUPPORTED";
38
+ /** A registered workflow exposes no serializable step graph. */
39
+ export declare const GRAPH_MASTRA_SERIALIZE_NOT_SUPPORTED = "GRAPH_MASTRA_SERIALIZE_NOT_SUPPORTED";
40
+ /**
41
+ * A management mutation targeted a workflow the caller may not write, or a host
42
+ * registration the wrapper did not create (C3 complete-mediation guard).
43
+ */
44
+ export declare const GRAPH_MASTRA_WORKFLOW_FORBIDDEN = "GRAPH_MASTRA_WORKFLOW_FORBIDDEN";
45
+ /**
46
+ * Execution context handed to a Mastra step handler for one node execution.
47
+ * The handler receives everything the document resolved for the node plus the
48
+ * Mastra-native suspension affordances.
49
+ */
50
+ export interface MastraNodeStepContext {
51
+ /** The document node being executed. */
52
+ nodeId: string;
53
+ /** The document node kind. */
54
+ kind: string;
55
+ /** Resolved node input values keyed by input port. */
56
+ inputData: GraphExecutionValues;
57
+ /** The workflow-level state accumulated so far. */
58
+ state: Record<string, unknown>;
59
+ /** Payload offered to a suspending step. */
60
+ suspendPayload?: unknown;
61
+ /** Resume payload supplied when a suspended step continues. */
62
+ resumeData?: unknown;
63
+ /** The Mastra-native runtime handle, when one is available. */
64
+ mastra?: unknown;
65
+ /** Mastra-native suspension callback for human-in-the-loop steps. */
66
+ suspend?: (payload?: unknown) => unknown;
67
+ }
68
+ /**
69
+ * Host-provided translator for one node kind. The backend has no built-in node
70
+ * executors: hosts register one handler per supported kind, and translation
71
+ * fails closed with {@link GRAPH_MASTRA_UNSUPPORTED_KIND} otherwise.
72
+ */
73
+ export interface MastraNodeStepHandler {
74
+ /** The document node kind this handler translates. */
75
+ kind: string;
76
+ /**
77
+ * Builds the Mastra step for one node instance.
78
+ * @param node - The document node instance to translate.
79
+ * @param options - Step options (`stepId` names the Mastra step).
80
+ * @returns The Mastra step object.
81
+ */
82
+ createStep(node: GraphNodeInstance, options: {
83
+ stepId: string;
84
+ }): unknown;
85
+ }
86
+ /**
87
+ * Configuration the host passes to {@link MastraGraphExecutionBackend.initialize}.
88
+ * Everything is host-injected; the backend never constructs Mastra primitives.
89
+ */
90
+ export interface MastraBackendConfig extends Record<string, unknown> {
91
+ /** The Mastra runtime used to create and load runs. */
92
+ mastra?: unknown;
93
+ /** Optional Mastra storage configuration. */
94
+ storage?: unknown;
95
+ /** Optional named agent map used by agent-backed node handlers. */
96
+ agents?: Record<string, unknown>;
97
+ /** Node-kind step handlers; replaces the compiler's default (empty) set. */
98
+ stepHandlers?: MastraNodeStepHandler[];
99
+ /** Optional workflow catalogue port backing list/lookup capabilities. */
100
+ workflowStore?: GraphBackendWorkflowStore;
101
+ /** Reader for Mastra-authoritative suspended-run snapshots (resume port). */
102
+ suspendStateReader?: MastraSuspendStateReader;
103
+ /** Maximum accepted serialised `resumeData` size, in bytes. */
104
+ maxResumeBytes?: number;
105
+ }
106
+ /**
107
+ * Mastra-authoritative snapshot of a suspended run as exposed by the host's
108
+ * suspend-state reader. Fields mirror {@link MastraResumeSnapshot} at the seam
109
+ * where the backend reads run state for resume.
110
+ */
111
+ export interface MastraRunSnapshotState {
112
+ /** Canonical run id. */
113
+ runId: GraphRunId;
114
+ /** Canonical workflow id. */
115
+ workflowId: string;
116
+ /** Fingerprint of the document the run was launched from. */
117
+ documentFingerprint: string;
118
+ /** Mastra run status; resume is only legal from `suspended`. */
119
+ status: string;
120
+ /** Mastra step ids the run suspended on. */
121
+ suspendedSteps: string[];
122
+ /** Per-iteration suspend index, keyed by suspended step id. */
123
+ suspendedForEachIndexes?: Record<string, number>;
124
+ }
125
+ /**
126
+ * Host port that reads the Mastra-authoritative suspended-run snapshot.
127
+ * Mastra owns execution state for suspended runs (gap-1); `GraphRunStore` is
128
+ * never consulted for resume.
129
+ */
130
+ export interface MastraSuspendStateReader {
131
+ /**
132
+ * Reads the suspended-run snapshot for a run.
133
+ * @param runId - The canonical run id.
134
+ * @param args - Optional decaf context arguments.
135
+ * @returns The snapshot, or `undefined` when the run has none.
136
+ */
137
+ readRunState(runId: GraphRunId, ...args: MaybeContextualArg<Context>): Promise<MastraRunSnapshotState | undefined>;
138
+ }
139
+ /** Host request to resume a suspended Mastra run. */
140
+ export interface MastraResumeRequest {
141
+ /** The suspended step to resume; defaults to the first suspended step. */
142
+ step?: string;
143
+ /** Resume payload validated against the suspended step's resume schema. */
144
+ resumeData?: Record<string, unknown>;
145
+ /** Iteration index to resume, for suspensions inside a `foreach`. */
146
+ forEachIndex?: number;
147
+ }
148
+ /**
149
+ * C18 audit record returned by a successful resume. Carries identity and
150
+ * provenance only; the raw `resumeData` is never logged or echoed.
151
+ */
152
+ export interface MastraResumeAudit {
153
+ /** Authenticated caller, when the host provided one. */
154
+ caller?: string | null;
155
+ /** The resumed run id. */
156
+ runId: GraphRunId;
157
+ /** The workflow id of the resumed run. */
158
+ workflowId?: string;
159
+ /** The resumed step id. */
160
+ step?: string;
161
+ /** The resumed iteration index, when the step is inside a `foreach`. */
162
+ forEachIndex?: number;
163
+ /** Stable hash of the accepted `resumeData`. */
164
+ resumeDataHash?: string;
165
+ /** Serialised size, in bytes, of the accepted `resumeData`. */
166
+ resumeDataBytes?: number;
167
+ /** ISO timestamp of the audit entry. */
168
+ at?: string;
169
+ }
170
+ /** How Mastra registered a workflow: declared in code or persisted dynamically. */
171
+ export type MastraWorkflowOrigin = "code" | "dynamic";
172
+ /**
173
+ * Structural port over the real `@mastra/core` `Mastra` workflow-management
174
+ * surface (1.74.0). Every method mirrors a real instance method; the wrapper
175
+ * never synthesizes one and fails closed when the wired runtime omits it.
176
+ */
177
+ export interface MastraWorkflowManagementRuntime {
178
+ /** Registers a committed workflow on the instance (real `addWorkflow`). */
179
+ addWorkflow?(workflow: unknown, key?: string): void;
180
+ /** Removes a registered workflow by key or id (real `removeWorkflow`). */
181
+ removeWorkflow?(keyOrId: string): boolean;
182
+ /** Reads a registered workflow by id (real `getWorkflow`). */
183
+ getWorkflow?(id: string, options?: {
184
+ serialized?: boolean;
185
+ }): unknown;
186
+ /** Lists the registered workflows (real `listWorkflows`). */
187
+ listWorkflows?(options?: {
188
+ serialized?: boolean;
189
+ }): Record<string, unknown>;
190
+ /** Reads how a workflow was registered (real `getWorkflowOrigin`). */
191
+ getWorkflowOrigin?(keyOrId: string): MastraWorkflowOrigin | undefined;
192
+ }
193
+ /** A managed workflow as surfaced by the management surface. */
194
+ export interface MastraWorkflowDescriptor {
195
+ /** Canonical workflow id. */
196
+ id: string;
197
+ /** Display name, when the registered workflow exposes one. */
198
+ name?: string;
199
+ /** How the workflow was registered, when the runtime reports it. */
200
+ origin?: MastraWorkflowOrigin;
201
+ /** Canonical document revision (fingerprint), when the wrapper tracked one. */
202
+ revision?: string;
203
+ }
204
+ /** The JSON-safe serialized form of a registered workflow. */
205
+ export interface MastraSerializedWorkflow {
206
+ /** Canonical workflow id. */
207
+ id: string;
208
+ /** Canonical document revision (fingerprint), when known. */
209
+ revision?: string;
210
+ /** The real Mastra `serializedStepGraph`. */
211
+ steps: unknown;
212
+ }
213
+ /** Options a {@link MastraWorkflowManager} is created with. */
214
+ export interface MastraWorkflowManagerOptions {
215
+ /** The wired real `@mastra/core` runtime (or `undefined` when unwired). */
216
+ runtime?: unknown;
217
+ /** The compiler used to translate canonical documents. */
218
+ compiler?: MastraWorkflowCompiler;
219
+ }
220
+ /** The Mastra backend specialised over its configuration type. */
221
+ export type MastraBackend = GraphExecutionBackend<MastraBackendConfig>;
222
+ export type { GraphBackendWorkflowSummary };
@@ -0,0 +1,87 @@
1
+ /**
2
+ * @module as-graph/nest/graph/GraphEngineCapabilityManifest
3
+ * @summary Server-side engine capability manifest (SAA-197, SAA-193 C20).
4
+ * @description Builds the read-only, statically-derived capability manifest the
5
+ * frontend consumes to toggle per-engine features/buttons. The manifest is derived
6
+ * exclusively from engine metadata — the registered
7
+ * {@link GraphExecutionBackend}s and the capability tables the Dagster/Mastra
8
+ * wrappers export — and is never probed against a remote engine and never read from
9
+ * the environment. Every `detail` is a static, reviewed literal (C20): no secrets,
10
+ * endpoints/DSNs, sandbox internals, infrastructure topology, or authorization
11
+ * internals are exposed.
12
+ */
13
+ import type { GraphBackendCapabilities, GraphExecutionBackend } from "../../engine/execution/GraphExecutionBackend.d.cts";
14
+ /**
15
+ * The normalized per-feature verdict served by the manifest. C20 defines exactly
16
+ * three verdicts; the wrapper tables' source spellings are normalized onto them
17
+ * (`supported`/`SUPPORTED` → `SUPPORTED`, `not_supported`/`NOT-SUPPORTED` →
18
+ * `NOT_SUPPORTED`, `extension_point`/`EXTENSION-POINT` → `EXTENSION_POINT`).
19
+ */
20
+ export type GraphEngineFeatureVerdict = "SUPPORTED" | "NOT_SUPPORTED" | "EXTENSION_POINT";
21
+ /** One engine feature row served by the manifest (C20). */
22
+ export interface GraphEngineFeature {
23
+ /** Feature identifier as declared by the engine's capability metadata. */
24
+ feature: string;
25
+ /** Normalized verdict (C20 three-value vocabulary). */
26
+ verdict: GraphEngineFeatureVerdict;
27
+ /** Static, reviewed human-readable detail; never dynamic engine output. */
28
+ detail?: string;
29
+ }
30
+ /** One engine entry served by the manifest (exact C20 shape). */
31
+ export interface GraphEngineDescriptor {
32
+ /** Allowlisted engine id (the backend flavour). */
33
+ engineId: string;
34
+ /** Human-readable engine name. */
35
+ displayName: string;
36
+ /** Whether the engine executes in-process. */
37
+ local: boolean;
38
+ /** Pinned engine version the wrapper targets. */
39
+ pinnedEngineVersion: string;
40
+ /** Feature/verdict rows derived from the engine's capability metadata. */
41
+ capabilities: GraphEngineFeature[];
42
+ }
43
+ /** The top-level capability manifest served to the frontend (exact C20 shape). */
44
+ export interface GraphEngineCapabilityManifest {
45
+ /** One entry per available (registered) engine. */
46
+ engines: GraphEngineDescriptor[];
47
+ /** Engine id the server defaults to. */
48
+ defaultEngineId: string;
49
+ }
50
+ /**
51
+ * Pinned `@mastra/core` engine version. Kept here because the Mastra wrapper
52
+ * exports only its feature table, not a version constant; the value mirrors the
53
+ * `@mastra/core` dependency pin in `as-graph/package.json` (`1.74.0`).
54
+ */
55
+ export declare const MASTRA_PINNED_VERSION = "1.74.0";
56
+ /**
57
+ * Normalizes a wrapper capability verdict onto the C20 three-value vocabulary.
58
+ * `PARTIAL` is deliberately downgraded to `NOT_SUPPORTED` (fail-closed): a
59
+ * partially-supported feature must never be advertised as a usable toggle.
60
+ *
61
+ * @param verdict - The wrapper table verdict string.
62
+ * @returns The normalized C20 verdict.
63
+ */
64
+ export declare function toGraphEngineFeatureVerdict(verdict: string): GraphEngineFeatureVerdict;
65
+ /**
66
+ * Derives the local engine's feature rows from the engine-agnostic
67
+ * {@link GraphBackendCapabilities} the built-in backend exposes, so the manifest
68
+ * never hand-maintains a separate local table.
69
+ *
70
+ * @param capabilities - The active backend's effective capability metadata.
71
+ * @returns The normalized feature rows for the local engine.
72
+ */
73
+ export declare function localEngineFeatures(capabilities: GraphBackendCapabilities): GraphEngineFeature[];
74
+ /**
75
+ * Builds the capability manifest from the registered backends, statically at boot.
76
+ * Only allowlisted flavours are advertised; the descriptors' `local` flag is read
77
+ * from the registered backend, and no remote engine is ever probed. The returned
78
+ * object is a fresh snapshot so a caller cannot mutate the served manifest.
79
+ *
80
+ * @param registered - The registered flavour/backend entries.
81
+ * @param defaultEngineId - Optional host-preferred default engine id.
82
+ * @returns The C20 capability manifest.
83
+ */
84
+ export declare function buildGraphEngineCapabilityManifest(registered: ReadonlyArray<{
85
+ flavour: string;
86
+ backend: GraphExecutionBackend<any>;
87
+ }>, defaultEngineId?: string): GraphEngineCapabilityManifest;
@@ -0,0 +1,87 @@
1
+ /**
2
+ * @module as-graph/nest/graph/GraphEngineCapabilityManifest
3
+ * @summary Server-side engine capability manifest (SAA-197, SAA-193 C20).
4
+ * @description Builds the read-only, statically-derived capability manifest the
5
+ * frontend consumes to toggle per-engine features/buttons. The manifest is derived
6
+ * exclusively from engine metadata — the registered
7
+ * {@link GraphExecutionBackend}s and the capability tables the Dagster/Mastra
8
+ * wrappers export — and is never probed against a remote engine and never read from
9
+ * the environment. Every `detail` is a static, reviewed literal (C20): no secrets,
10
+ * endpoints/DSNs, sandbox internals, infrastructure topology, or authorization
11
+ * internals are exposed.
12
+ */
13
+ import type { GraphBackendCapabilities, GraphExecutionBackend } from "../../engine/execution/GraphExecutionBackend.d.mts";
14
+ /**
15
+ * The normalized per-feature verdict served by the manifest. C20 defines exactly
16
+ * three verdicts; the wrapper tables' source spellings are normalized onto them
17
+ * (`supported`/`SUPPORTED` → `SUPPORTED`, `not_supported`/`NOT-SUPPORTED` →
18
+ * `NOT_SUPPORTED`, `extension_point`/`EXTENSION-POINT` → `EXTENSION_POINT`).
19
+ */
20
+ export type GraphEngineFeatureVerdict = "SUPPORTED" | "NOT_SUPPORTED" | "EXTENSION_POINT";
21
+ /** One engine feature row served by the manifest (C20). */
22
+ export interface GraphEngineFeature {
23
+ /** Feature identifier as declared by the engine's capability metadata. */
24
+ feature: string;
25
+ /** Normalized verdict (C20 three-value vocabulary). */
26
+ verdict: GraphEngineFeatureVerdict;
27
+ /** Static, reviewed human-readable detail; never dynamic engine output. */
28
+ detail?: string;
29
+ }
30
+ /** One engine entry served by the manifest (exact C20 shape). */
31
+ export interface GraphEngineDescriptor {
32
+ /** Allowlisted engine id (the backend flavour). */
33
+ engineId: string;
34
+ /** Human-readable engine name. */
35
+ displayName: string;
36
+ /** Whether the engine executes in-process. */
37
+ local: boolean;
38
+ /** Pinned engine version the wrapper targets. */
39
+ pinnedEngineVersion: string;
40
+ /** Feature/verdict rows derived from the engine's capability metadata. */
41
+ capabilities: GraphEngineFeature[];
42
+ }
43
+ /** The top-level capability manifest served to the frontend (exact C20 shape). */
44
+ export interface GraphEngineCapabilityManifest {
45
+ /** One entry per available (registered) engine. */
46
+ engines: GraphEngineDescriptor[];
47
+ /** Engine id the server defaults to. */
48
+ defaultEngineId: string;
49
+ }
50
+ /**
51
+ * Pinned `@mastra/core` engine version. Kept here because the Mastra wrapper
52
+ * exports only its feature table, not a version constant; the value mirrors the
53
+ * `@mastra/core` dependency pin in `as-graph/package.json` (`1.74.0`).
54
+ */
55
+ export declare const MASTRA_PINNED_VERSION = "1.74.0";
56
+ /**
57
+ * Normalizes a wrapper capability verdict onto the C20 three-value vocabulary.
58
+ * `PARTIAL` is deliberately downgraded to `NOT_SUPPORTED` (fail-closed): a
59
+ * partially-supported feature must never be advertised as a usable toggle.
60
+ *
61
+ * @param verdict - The wrapper table verdict string.
62
+ * @returns The normalized C20 verdict.
63
+ */
64
+ export declare function toGraphEngineFeatureVerdict(verdict: string): GraphEngineFeatureVerdict;
65
+ /**
66
+ * Derives the local engine's feature rows from the engine-agnostic
67
+ * {@link GraphBackendCapabilities} the built-in backend exposes, so the manifest
68
+ * never hand-maintains a separate local table.
69
+ *
70
+ * @param capabilities - The active backend's effective capability metadata.
71
+ * @returns The normalized feature rows for the local engine.
72
+ */
73
+ export declare function localEngineFeatures(capabilities: GraphBackendCapabilities): GraphEngineFeature[];
74
+ /**
75
+ * Builds the capability manifest from the registered backends, statically at boot.
76
+ * Only allowlisted flavours are advertised; the descriptors' `local` flag is read
77
+ * from the registered backend, and no remote engine is ever probed. The returned
78
+ * object is a fresh snapshot so a caller cannot mutate the served manifest.
79
+ *
80
+ * @param registered - The registered flavour/backend entries.
81
+ * @param defaultEngineId - Optional host-preferred default engine id.
82
+ * @returns The C20 capability manifest.
83
+ */
84
+ export declare function buildGraphEngineCapabilityManifest(registered: ReadonlyArray<{
85
+ flavour: string;
86
+ backend: GraphExecutionBackend<any>;
87
+ }>, defaultEngineId?: string): GraphEngineCapabilityManifest;
@@ -0,0 +1,98 @@
1
+ import type { Context, MaybeContextualArg } from "@decaf-ts/core";
2
+ import type { GraphBackendWorkflowSummary } from "../../engine/execution/GraphExecutionBackend.d.cts";
3
+ import type { GraphExecutionEngine } from "../../engine/execution/GraphExecutionEngine.d.cts";
4
+ import type { GraphWorkflowDocument } from "../../shared/graph/index.d.cts";
5
+ import { type GraphEngineCapabilityManifest, type GraphEngineDescriptor } from "./GraphEngineCapabilityManifest.d.cts";
6
+ /** DI token for {@link GraphEngineCapabilityOptions}. */
7
+ export declare const GRAPH_ENGINE_CAPABILITY_OPTIONS = "GRAPH_ENGINE_CAPABILITY_OPTIONS";
8
+ /** Rate-limit configuration for the engine capability routes: window and request cap. */
9
+ export interface GraphEngineRateLimitOptions {
10
+ windowMs?: number;
11
+ maxRequests?: number;
12
+ }
13
+ /**
14
+ * Default rate limit for the engine capability routes: 120 requests per 60-second
15
+ * window, applied by the `@nestjs/throttler` guard on the `engines` bucket.
16
+ */
17
+ export declare const DEFAULT_GRAPH_ENGINE_RATE_LIMIT: Required<GraphEngineRateLimitOptions>;
18
+ /**
19
+ * Options for the engine capability HTTP API (SAA-193 C20/C21): authentication
20
+ * mode, the host-preferred default engine id, and the engine-route rate limit.
21
+ */
22
+ export interface GraphEngineCapabilityOptions {
23
+ /**
24
+ * `"required"` (default) rejects a request with no request context, or with a
25
+ * context that carries no resolved owner user, with `401`, matching the other
26
+ * graph read routes; `"optional"` tolerates anonymous/system callers for
27
+ * standalone module runs.
28
+ */
29
+ auth?: "required" | "optional";
30
+ /**
31
+ * Engine id the manifest advertises as the default. Ignored when it is not one of
32
+ * the registered, allowlisted engine ids; the current backend flavour is used
33
+ * instead.
34
+ */
35
+ defaultEngineId?: string;
36
+ /** Rate limit for the engine capability routes (the `engines` throttler bucket). */
37
+ rateLimit?: GraphEngineRateLimitOptions;
38
+ }
39
+ /**
40
+ * Owns the boot-time capability manifest and resolves engine-scoped workflow
41
+ * listing/lookup. The manifest is built once in the constructor from the
42
+ * registered backends; request handling never mutates it and never probes a remote
43
+ * engine.
44
+ */
45
+ export declare class GraphEngineCapabilityService {
46
+ private readonly engine?;
47
+ private readonly manifest;
48
+ private readonly engineIds;
49
+ /**
50
+ * @param options - Controller options (auth, default engine id, rate limit).
51
+ * @param engine - The engine facade resolving flavour-scoped listing/lookup.
52
+ */
53
+ constructor(options?: GraphEngineCapabilityOptions, engine?: GraphExecutionEngine | undefined);
54
+ /**
55
+ * Returns a defensive copy of the statically-derived capability manifest.
56
+ *
57
+ * @returns The C20 capability manifest snapshot.
58
+ */
59
+ manifestSnapshot(): GraphEngineCapabilityManifest;
60
+ /**
61
+ * Returns a defensive copy of a single allowlisted engine descriptor.
62
+ *
63
+ * @param engineId - The engine id to look up.
64
+ * @returns The engine descriptor, or `undefined` when not allowlisted.
65
+ */
66
+ descriptor(engineId: string): GraphEngineDescriptor | undefined;
67
+ /**
68
+ * Whether the engine id is registered and allowlisted.
69
+ *
70
+ * @param engineId - The engine id to check.
71
+ * @returns `true` when the id is an available engine.
72
+ */
73
+ isKnownEngine(engineId: string): boolean;
74
+ /**
75
+ * Lists the workflows a registered engine can surface through the engine-agnostic
76
+ * facade, which applies the fail-closed capability gate and the
77
+ * `GRAPH_BACKEND_WORKFLOWS_NOT_SUPPORTED` error code.
78
+ *
79
+ * @param engineId - The allowlisted engine id to list for.
80
+ * @param args - Optional decaf contextual arguments forwarded to the backend.
81
+ * @returns Workflow summaries.
82
+ * @throws {GraphExecutionError} when the engine declares no listing support.
83
+ */
84
+ listWorkflows(engineId: string, ...args: MaybeContextualArg<Context>): Promise<GraphBackendWorkflowSummary[]>;
85
+ /**
86
+ * Looks up a single canonical workflow document on a registered engine through
87
+ * the engine-agnostic facade.
88
+ *
89
+ * @param engineId - The allowlisted engine id to read from.
90
+ * @param workflowId - The canonical workflow id to read.
91
+ * @param args - Optional decaf contextual arguments forwarded to the backend.
92
+ * @returns The canonical workflow document.
93
+ * @throws {GraphExecutionError} when the engine declares no lookup support.
94
+ */
95
+ getWorkflow(engineId: string, workflowId: string, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowDocument>;
96
+ /** Resolves the engine facade, failing closed when it is not wired. */
97
+ private requireEngine;
98
+ }
@@ -0,0 +1,98 @@
1
+ import type { Context, MaybeContextualArg } from "@decaf-ts/core";
2
+ import type { GraphBackendWorkflowSummary } from "../../engine/execution/GraphExecutionBackend.d.mts";
3
+ import type { GraphExecutionEngine } from "../../engine/execution/GraphExecutionEngine.d.mts";
4
+ import type { GraphWorkflowDocument } from "../../shared/graph/index.d.mts";
5
+ import { type GraphEngineCapabilityManifest, type GraphEngineDescriptor } from "./GraphEngineCapabilityManifest.d.mts";
6
+ /** DI token for {@link GraphEngineCapabilityOptions}. */
7
+ export declare const GRAPH_ENGINE_CAPABILITY_OPTIONS = "GRAPH_ENGINE_CAPABILITY_OPTIONS";
8
+ /** Rate-limit configuration for the engine capability routes: window and request cap. */
9
+ export interface GraphEngineRateLimitOptions {
10
+ windowMs?: number;
11
+ maxRequests?: number;
12
+ }
13
+ /**
14
+ * Default rate limit for the engine capability routes: 120 requests per 60-second
15
+ * window, applied by the `@nestjs/throttler` guard on the `engines` bucket.
16
+ */
17
+ export declare const DEFAULT_GRAPH_ENGINE_RATE_LIMIT: Required<GraphEngineRateLimitOptions>;
18
+ /**
19
+ * Options for the engine capability HTTP API (SAA-193 C20/C21): authentication
20
+ * mode, the host-preferred default engine id, and the engine-route rate limit.
21
+ */
22
+ export interface GraphEngineCapabilityOptions {
23
+ /**
24
+ * `"required"` (default) rejects a request with no request context, or with a
25
+ * context that carries no resolved owner user, with `401`, matching the other
26
+ * graph read routes; `"optional"` tolerates anonymous/system callers for
27
+ * standalone module runs.
28
+ */
29
+ auth?: "required" | "optional";
30
+ /**
31
+ * Engine id the manifest advertises as the default. Ignored when it is not one of
32
+ * the registered, allowlisted engine ids; the current backend flavour is used
33
+ * instead.
34
+ */
35
+ defaultEngineId?: string;
36
+ /** Rate limit for the engine capability routes (the `engines` throttler bucket). */
37
+ rateLimit?: GraphEngineRateLimitOptions;
38
+ }
39
+ /**
40
+ * Owns the boot-time capability manifest and resolves engine-scoped workflow
41
+ * listing/lookup. The manifest is built once in the constructor from the
42
+ * registered backends; request handling never mutates it and never probes a remote
43
+ * engine.
44
+ */
45
+ export declare class GraphEngineCapabilityService {
46
+ private readonly engine?;
47
+ private readonly manifest;
48
+ private readonly engineIds;
49
+ /**
50
+ * @param options - Controller options (auth, default engine id, rate limit).
51
+ * @param engine - The engine facade resolving flavour-scoped listing/lookup.
52
+ */
53
+ constructor(options?: GraphEngineCapabilityOptions, engine?: GraphExecutionEngine | undefined);
54
+ /**
55
+ * Returns a defensive copy of the statically-derived capability manifest.
56
+ *
57
+ * @returns The C20 capability manifest snapshot.
58
+ */
59
+ manifestSnapshot(): GraphEngineCapabilityManifest;
60
+ /**
61
+ * Returns a defensive copy of a single allowlisted engine descriptor.
62
+ *
63
+ * @param engineId - The engine id to look up.
64
+ * @returns The engine descriptor, or `undefined` when not allowlisted.
65
+ */
66
+ descriptor(engineId: string): GraphEngineDescriptor | undefined;
67
+ /**
68
+ * Whether the engine id is registered and allowlisted.
69
+ *
70
+ * @param engineId - The engine id to check.
71
+ * @returns `true` when the id is an available engine.
72
+ */
73
+ isKnownEngine(engineId: string): boolean;
74
+ /**
75
+ * Lists the workflows a registered engine can surface through the engine-agnostic
76
+ * facade, which applies the fail-closed capability gate and the
77
+ * `GRAPH_BACKEND_WORKFLOWS_NOT_SUPPORTED` error code.
78
+ *
79
+ * @param engineId - The allowlisted engine id to list for.
80
+ * @param args - Optional decaf contextual arguments forwarded to the backend.
81
+ * @returns Workflow summaries.
82
+ * @throws {GraphExecutionError} when the engine declares no listing support.
83
+ */
84
+ listWorkflows(engineId: string, ...args: MaybeContextualArg<Context>): Promise<GraphBackendWorkflowSummary[]>;
85
+ /**
86
+ * Looks up a single canonical workflow document on a registered engine through
87
+ * the engine-agnostic facade.
88
+ *
89
+ * @param engineId - The allowlisted engine id to read from.
90
+ * @param workflowId - The canonical workflow id to read.
91
+ * @param args - Optional decaf contextual arguments forwarded to the backend.
92
+ * @returns The canonical workflow document.
93
+ * @throws {GraphExecutionError} when the engine declares no lookup support.
94
+ */
95
+ getWorkflow(engineId: string, workflowId: string, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowDocument>;
96
+ /** Resolves the engine facade, failing closed when it is not wired. */
97
+ private requireEngine;
98
+ }
@@ -0,0 +1,74 @@
1
+ import { DecafRequestContext } from "@decaf-ts/for-nest";
2
+ import type { GraphWorkflowDocument } from "../../shared/graph/index.d.cts";
3
+ import type { GraphEngineCapabilityManifest, GraphEngineDescriptor } from "./GraphEngineCapabilityManifest.d.cts";
4
+ import { GraphEngineCapabilityService, type GraphEngineCapabilityOptions } from "./GraphEngineCapabilityService.d.cts";
5
+ /** One row of the engine workflow list: the serving summary a list binds to. */
6
+ export interface GraphEngineWorkflowSummary {
7
+ /** Canonical workflow id. */
8
+ workflowId: string;
9
+ /** Display name mirrored from the document, when present. */
10
+ name?: string;
11
+ /** ISO timestamp of the last update, when the backend exposes one. */
12
+ updatedAt?: string;
13
+ }
14
+ /**
15
+ * Engine capability manifest and engine-scoped workflow catalogue endpoints:
16
+ *
17
+ * - `GET /graph/engines` — the C20 capability manifest for every available
18
+ * (registered, allowlisted) engine.
19
+ * - `GET /graph/engines/{engineId}` — one engine descriptor.
20
+ * - `GET /graph/engines/{engineId}/workflows` — the workflows that engine
21
+ * surfaces through the engine-agnostic facade.
22
+ * - `GET /graph/engines/{engineId}/workflows/{workflowId}` — one canonical
23
+ * workflow document from that engine.
24
+ *
25
+ * All routes are read-only `GET`s, select engines by allowlisted id only, and
26
+ * never reflect arbitrary query input.
27
+ */
28
+ export declare class GraphEngineController {
29
+ private readonly capabilityService;
30
+ private readonly requestContext?;
31
+ private readonly options;
32
+ constructor(capabilityService: GraphEngineCapabilityService, requestContext?: DecafRequestContext | undefined, options?: GraphEngineCapabilityOptions);
33
+ /**
34
+ * Enforces the configured authentication mode: `auth` defaults to `"required"`
35
+ * and rejects a request with no request context, or with a context that carries
36
+ * no resolved owner user, with `401`; `"optional"` admits anonymous requests.
37
+ */
38
+ private requireAuthenticatedContext;
39
+ private assertKnownEngine;
40
+ /**
41
+ * Returns the capability manifest for every available engine.
42
+ *
43
+ * @return {Promise<GraphEngineCapabilityManifest>} The C20 capability manifest.
44
+ * @throws {HttpException} 401 without an authenticated caller.
45
+ */
46
+ getManifest(): Promise<GraphEngineCapabilityManifest>;
47
+ /**
48
+ * Returns one allowlisted engine's capability descriptor.
49
+ *
50
+ * @param {string} engineId - Allowlisted engine id path parameter.
51
+ * @return {Promise<GraphEngineDescriptor>} The engine descriptor.
52
+ * @throws {HttpException} 404 when the engine id is not available.
53
+ */
54
+ getEngine(engineId: string): Promise<GraphEngineDescriptor>;
55
+ /**
56
+ * Lists the workflows the selected engine surfaces through the
57
+ * engine-agnostic facade.
58
+ *
59
+ * @param {string} engineId - Allowlisted engine id path parameter.
60
+ * @return {Promise<GraphEngineWorkflowSummary[]>} Workflow summaries.
61
+ * @throws {HttpException} 404 for an unknown engine id, 501 when the engine declares no listing support.
62
+ */
63
+ listWorkflows(engineId: string): Promise<GraphEngineWorkflowSummary[]>;
64
+ /**
65
+ * Returns one canonical workflow document from the selected engine through the
66
+ * engine-agnostic facade.
67
+ *
68
+ * @param {string} engineId - Allowlisted engine id path parameter.
69
+ * @param {string} workflowId - Canonical workflow id path parameter.
70
+ * @return {Promise<GraphWorkflowDocument>} The canonical workflow document.
71
+ * @throws {HttpException} 404 for an unknown engine id, 501 when the engine declares no lookup support.
72
+ */
73
+ getWorkflow(engineId: string, workflowId: string): Promise<GraphWorkflowDocument>;
74
+ }