@decaf-ts/as-graph 0.6.0 → 0.7.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 (919) hide show
  1. package/README.md +776 -26
  2. package/assets/i18n/en.json +2527 -32
  3. package/dist/as-graph.cjs +1 -1
  4. package/dist/as-graph.cjs.map +1 -1
  5. package/dist/as-graph.js +1 -1
  6. package/dist/as-graph.js.map +1 -1
  7. package/lib/cjs/engine/auth/GraphAuthValidator.cjs +19 -0
  8. package/lib/cjs/engine/auth/GraphAuthValidator.cjs.map +1 -1
  9. package/lib/cjs/engine/constants.cjs +61 -1
  10. package/lib/cjs/engine/constants.cjs.map +1 -1
  11. package/lib/cjs/engine/credentials/GraphNodeCredentials.cjs +158 -0
  12. package/lib/cjs/engine/credentials/GraphNodeCredentials.cjs.map +1 -0
  13. package/lib/cjs/engine/execution/GraphExecutionEngine.cjs +228 -67
  14. package/lib/cjs/engine/execution/GraphExecutionEngine.cjs.map +1 -1
  15. package/lib/cjs/engine/execution/GraphNodeEngineRequirements.cjs +33 -0
  16. package/lib/cjs/engine/execution/GraphNodeEngineRequirements.cjs.map +1 -0
  17. package/lib/cjs/engine/execution/GraphWebhookResponseRegistry.cjs +108 -0
  18. package/lib/cjs/engine/execution/GraphWebhookResponseRegistry.cjs.map +1 -0
  19. package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs +53 -1
  20. package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs.map +1 -1
  21. package/lib/cjs/engine/execution/index.cjs +1 -0
  22. package/lib/cjs/engine/execution/index.cjs.map +1 -1
  23. package/lib/cjs/engine/index.cjs +4 -0
  24. package/lib/cjs/engine/index.cjs.map +1 -1
  25. package/lib/cjs/engine/store/GraphDataTableModel.cjs +76 -0
  26. package/lib/cjs/engine/store/GraphDataTableModel.cjs.map +1 -0
  27. package/lib/cjs/engine/store/GraphDataTableRepository.cjs +324 -0
  28. package/lib/cjs/engine/store/GraphDataTableRepository.cjs.map +1 -0
  29. package/lib/cjs/engine/store/index.cjs +2 -0
  30. package/lib/cjs/engine/store/index.cjs.map +1 -1
  31. package/lib/cjs/engine/validation/GraphConnectionPolicyValidator.cjs +28 -0
  32. package/lib/cjs/engine/validation/GraphConnectionPolicyValidator.cjs.map +1 -1
  33. package/lib/cjs/engine/validation/GraphCredentialReferenceValidator.cjs +4 -2
  34. package/lib/cjs/engine/validation/GraphCredentialReferenceValidator.cjs.map +1 -1
  35. package/lib/cjs/engine/validation/GraphParameterValidator.cjs +6 -0
  36. package/lib/cjs/engine/validation/GraphParameterValidator.cjs.map +1 -1
  37. package/lib/cjs/mastra/MastraAgeVectorDriver.cjs +298 -0
  38. package/lib/cjs/mastra/MastraAgeVectorDriver.cjs.map +1 -0
  39. package/lib/cjs/mastra/MastraAgentBuilder.cjs +249 -0
  40. package/lib/cjs/mastra/MastraAgentBuilder.cjs.map +1 -0
  41. package/lib/cjs/mastra/MastraAgentModelAdapter.cjs +65 -0
  42. package/lib/cjs/mastra/MastraAgentModelAdapter.cjs.map +1 -0
  43. package/lib/cjs/mastra/MastraAgentProcessors.cjs +397 -0
  44. package/lib/cjs/mastra/MastraAgentProcessors.cjs.map +1 -0
  45. package/lib/cjs/mastra/MastraAgentStepHandler.cjs +332 -0
  46. package/lib/cjs/mastra/MastraAgentStepHandler.cjs.map +1 -0
  47. package/lib/cjs/mastra/MastraCapabilities.cjs +115 -0
  48. package/lib/cjs/mastra/MastraCapabilities.cjs.map +1 -1
  49. package/lib/cjs/mastra/MastraChannelResponse.cjs +162 -0
  50. package/lib/cjs/mastra/MastraChannelResponse.cjs.map +1 -0
  51. package/lib/cjs/mastra/MastraChannelTrigger.cjs +124 -0
  52. package/lib/cjs/mastra/MastraChannelTrigger.cjs.map +1 -0
  53. package/lib/cjs/mastra/MastraDefaultStepHandlers.cjs +240 -22
  54. package/lib/cjs/mastra/MastraDefaultStepHandlers.cjs.map +1 -1
  55. package/lib/cjs/mastra/MastraEnvironment.cjs +297 -0
  56. package/lib/cjs/mastra/MastraEnvironment.cjs.map +1 -0
  57. package/lib/cjs/mastra/MastraEvalModels.cjs +546 -0
  58. package/lib/cjs/mastra/MastraEvalModels.cjs.map +1 -0
  59. package/lib/cjs/mastra/MastraEventBridge.cjs +21 -1
  60. package/lib/cjs/mastra/MastraEventBridge.cjs.map +1 -1
  61. package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs +414 -19
  62. package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs.map +1 -1
  63. package/lib/cjs/mastra/MastraGraphExecutionModule.cjs +148 -0
  64. package/lib/cjs/mastra/MastraGraphExecutionModule.cjs.map +1 -0
  65. package/lib/cjs/mastra/MastraHitlStepHandler.cjs +67 -0
  66. package/lib/cjs/mastra/MastraHitlStepHandler.cjs.map +1 -0
  67. package/lib/cjs/mastra/MastraMcpTrigger.cjs +254 -0
  68. package/lib/cjs/mastra/MastraMcpTrigger.cjs.map +1 -0
  69. package/lib/cjs/mastra/MastraMemory.cjs +467 -0
  70. package/lib/cjs/mastra/MastraMemory.cjs.map +1 -0
  71. package/lib/cjs/mastra/MastraMetricsAdapter.cjs +279 -0
  72. package/lib/cjs/mastra/MastraMetricsAdapter.cjs.map +1 -0
  73. package/lib/cjs/mastra/MastraMetricsGateway.cjs +404 -0
  74. package/lib/cjs/mastra/MastraMetricsGateway.cjs.map +1 -0
  75. package/lib/cjs/mastra/MastraMetricsModels.cjs +498 -0
  76. package/lib/cjs/mastra/MastraMetricsModels.cjs.map +1 -0
  77. package/lib/cjs/mastra/MastraMetricsStatement.cjs +220 -0
  78. package/lib/cjs/mastra/MastraMetricsStatement.cjs.map +1 -0
  79. package/lib/cjs/mastra/MastraModelSchemaConverter.cjs +84 -0
  80. package/lib/cjs/mastra/MastraModelSchemaConverter.cjs.map +1 -0
  81. package/lib/cjs/mastra/MastraObservability.cjs +335 -0
  82. package/lib/cjs/mastra/MastraObservability.cjs.map +1 -0
  83. package/lib/cjs/mastra/MastraPersistence.cjs +545 -0
  84. package/lib/cjs/mastra/MastraPersistence.cjs.map +1 -0
  85. package/lib/cjs/mastra/MastraRagStepHandlers.cjs +927 -0
  86. package/lib/cjs/mastra/MastraRagStepHandlers.cjs.map +1 -0
  87. package/lib/cjs/mastra/MastraRunMetricsEndpoint.cjs +153 -0
  88. package/lib/cjs/mastra/MastraRunMetricsEndpoint.cjs.map +1 -0
  89. package/lib/cjs/mastra/MastraRunRecovery.cjs +94 -0
  90. package/lib/cjs/mastra/MastraRunRecovery.cjs.map +1 -0
  91. package/lib/cjs/mastra/MastraScheduleTrigger.cjs +115 -0
  92. package/lib/cjs/mastra/MastraScheduleTrigger.cjs.map +1 -0
  93. package/lib/cjs/mastra/MastraStorageWiring.cjs +125 -0
  94. package/lib/cjs/mastra/MastraStorageWiring.cjs.map +1 -0
  95. package/lib/cjs/mastra/MastraStructuredOutput.cjs +152 -0
  96. package/lib/cjs/mastra/MastraStructuredOutput.cjs.map +1 -0
  97. package/lib/cjs/mastra/MastraToolBuilder.cjs +73 -0
  98. package/lib/cjs/mastra/MastraToolBuilder.cjs.map +1 -0
  99. package/lib/cjs/mastra/MastraToolConfig.cjs +42 -0
  100. package/lib/cjs/mastra/MastraToolConfig.cjs.map +1 -0
  101. package/lib/cjs/mastra/MastraToolDecorator.cjs +99 -0
  102. package/lib/cjs/mastra/MastraToolDecorator.cjs.map +1 -0
  103. package/lib/cjs/mastra/MastraVectorStore.cjs +618 -0
  104. package/lib/cjs/mastra/MastraVectorStore.cjs.map +1 -0
  105. package/lib/cjs/mastra/MastraVoiceStepHandler.cjs +90 -0
  106. package/lib/cjs/mastra/MastraVoiceStepHandler.cjs.map +1 -0
  107. package/lib/cjs/mastra/MastraWorkflowCompiler.cjs +38 -6
  108. package/lib/cjs/mastra/MastraWorkflowCompiler.cjs.map +1 -1
  109. package/lib/cjs/mastra/MastraWorkflowManager.cjs +100 -50
  110. package/lib/cjs/mastra/MastraWorkflowManager.cjs.map +1 -1
  111. package/lib/cjs/mastra/index.cjs +40 -1
  112. package/lib/cjs/mastra/index.cjs.map +1 -1
  113. package/lib/cjs/mastra/nodes/MastraNodeRegistry.cjs +232 -0
  114. package/lib/cjs/mastra/nodes/MastraNodeRegistry.cjs.map +1 -0
  115. package/lib/cjs/mastra/nodes/index.cjs +29 -0
  116. package/lib/cjs/mastra/nodes/index.cjs.map +1 -0
  117. package/lib/cjs/mastra/nodes/types.cjs +4 -0
  118. package/lib/cjs/mastra/nodes/types.cjs.map +1 -0
  119. package/lib/cjs/mastra/types.cjs +126 -1
  120. package/lib/cjs/mastra/types.cjs.map +1 -1
  121. package/lib/cjs/nest/graph/GraphBackendHost.cjs +12 -4
  122. package/lib/cjs/nest/graph/GraphBackendHost.cjs.map +1 -1
  123. package/lib/cjs/nest/graph/GraphExecutionModule.cjs +35 -1
  124. package/lib/cjs/nest/graph/GraphExecutionModule.cjs.map +1 -1
  125. package/lib/cjs/nest/graph/GraphRunController.cjs +47 -6
  126. package/lib/cjs/nest/graph/GraphRunController.cjs.map +1 -1
  127. package/lib/cjs/nest/graph/main.cjs +83 -1
  128. package/lib/cjs/nest/graph/main.cjs.map +1 -1
  129. package/lib/cjs/node/agents/agent/node.cjs +189 -31
  130. package/lib/cjs/node/agents/agent/node.cjs.map +1 -1
  131. package/lib/cjs/node/agents/hitl/node.cjs +115 -0
  132. package/lib/cjs/node/agents/hitl/node.cjs.map +1 -0
  133. package/lib/cjs/node/agents/hooks/delegation/node.cjs +122 -0
  134. package/lib/cjs/node/agents/hooks/delegation/node.cjs.map +1 -0
  135. package/lib/cjs/node/agents/hooks/hook/node.cjs +120 -0
  136. package/lib/cjs/node/agents/hooks/hook/node.cjs.map +1 -0
  137. package/lib/cjs/node/agents/hooks/tool-deny/node.cjs +104 -0
  138. package/lib/cjs/node/agents/hooks/tool-deny/node.cjs.map +1 -0
  139. package/lib/cjs/node/agents/memory/memory/node.cjs +231 -0
  140. package/lib/cjs/node/agents/memory/memory/node.cjs.map +1 -0
  141. package/lib/cjs/node/agents/memory/memory-selector/node.cjs +101 -0
  142. package/lib/cjs/node/agents/memory/memory-selector/node.cjs.map +1 -0
  143. package/lib/cjs/node/agents/processors/guardrail/node.cjs +126 -0
  144. package/lib/cjs/node/agents/processors/guardrail/node.cjs.map +1 -0
  145. package/lib/cjs/node/agents/processors/input-processor/node.cjs +118 -0
  146. package/lib/cjs/node/agents/processors/input-processor/node.cjs.map +1 -0
  147. package/lib/cjs/node/agents/processors/output-processor/node.cjs +108 -0
  148. package/lib/cjs/node/agents/processors/output-processor/node.cjs.map +1 -0
  149. package/lib/cjs/node/agents/processors/types.cjs +68 -0
  150. package/lib/cjs/node/agents/processors/types.cjs.map +1 -0
  151. package/lib/cjs/node/agents/rag/chains/basic/node.cjs +103 -0
  152. package/lib/cjs/node/agents/rag/chains/basic/node.cjs.map +1 -0
  153. package/lib/cjs/node/agents/rag/chains/qa/node.cjs +124 -0
  154. package/lib/cjs/node/agents/rag/chains/qa/node.cjs.map +1 -0
  155. package/lib/cjs/node/agents/rag/chains/summarization/node.cjs +116 -0
  156. package/lib/cjs/node/agents/rag/chains/summarization/node.cjs.map +1 -0
  157. package/lib/cjs/node/agents/rag/chunking/node.cjs +222 -0
  158. package/lib/cjs/node/agents/rag/chunking/node.cjs.map +1 -0
  159. package/lib/cjs/node/agents/rag/embedding/node.cjs +110 -0
  160. package/lib/cjs/node/agents/rag/embedding/node.cjs.map +1 -0
  161. package/lib/cjs/node/agents/rag/information-extractor/node.cjs +115 -0
  162. package/lib/cjs/node/agents/rag/information-extractor/node.cjs.map +1 -0
  163. package/lib/cjs/node/agents/rag/langchain-code/node.cjs +113 -0
  164. package/lib/cjs/node/agents/rag/langchain-code/node.cjs.map +1 -0
  165. package/lib/cjs/node/agents/rag/rerank/node.cjs +112 -0
  166. package/lib/cjs/node/agents/rag/rerank/node.cjs.map +1 -0
  167. package/lib/cjs/node/agents/rag/retriever/node.cjs +120 -0
  168. package/lib/cjs/node/agents/rag/retriever/node.cjs.map +1 -0
  169. package/lib/cjs/node/agents/rag/structured-output-parser/node.cjs +121 -0
  170. package/lib/cjs/node/agents/rag/structured-output-parser/node.cjs.map +1 -0
  171. package/lib/cjs/node/agents/rag/vector-store/node.cjs +187 -0
  172. package/lib/cjs/node/agents/rag/vector-store/node.cjs.map +1 -0
  173. package/lib/cjs/node/agents/responses/discord/node.cjs +101 -0
  174. package/lib/cjs/node/agents/responses/discord/node.cjs.map +1 -0
  175. package/lib/cjs/node/agents/responses/slack/node.cjs +101 -0
  176. package/lib/cjs/node/agents/responses/slack/node.cjs.map +1 -0
  177. package/lib/cjs/node/agents/responses/teams/node.cjs +101 -0
  178. package/lib/cjs/node/agents/responses/teams/node.cjs.map +1 -0
  179. package/lib/cjs/node/agents/responses/telegram/node.cjs +101 -0
  180. package/lib/cjs/node/agents/responses/telegram/node.cjs.map +1 -0
  181. package/lib/cjs/node/agents/sandbox/node.cjs +135 -0
  182. package/lib/cjs/node/agents/sandbox/node.cjs.map +1 -0
  183. package/lib/cjs/node/agents/scorers/scorer/node.cjs +107 -0
  184. package/lib/cjs/node/agents/scorers/scorer/node.cjs.map +1 -0
  185. package/lib/cjs/node/agents/scorers/scorer-selector/node.cjs +100 -0
  186. package/lib/cjs/node/agents/scorers/scorer-selector/node.cjs.map +1 -0
  187. package/lib/cjs/node/agents/skills/skill/node.cjs +105 -0
  188. package/lib/cjs/node/agents/skills/skill/node.cjs.map +1 -0
  189. package/lib/cjs/node/agents/skills/skill-selector/node.cjs +98 -0
  190. package/lib/cjs/node/agents/skills/skill-selector/node.cjs.map +1 -0
  191. package/lib/cjs/node/agents/tools/tool/node.cjs +100 -0
  192. package/lib/cjs/node/agents/tools/tool/node.cjs.map +1 -0
  193. package/lib/cjs/node/agents/tools/tool-selector/node.cjs +99 -0
  194. package/lib/cjs/node/agents/tools/tool-selector/node.cjs.map +1 -0
  195. package/lib/cjs/node/agents/triggers/discord/node.cjs +101 -0
  196. package/lib/cjs/node/agents/triggers/discord/node.cjs.map +1 -0
  197. package/lib/cjs/node/agents/triggers/mcp-server/node.cjs +147 -0
  198. package/lib/cjs/node/agents/triggers/mcp-server/node.cjs.map +1 -0
  199. package/lib/cjs/node/agents/triggers/slack/node.cjs +101 -0
  200. package/lib/cjs/node/agents/triggers/slack/node.cjs.map +1 -0
  201. package/lib/cjs/node/agents/triggers/teams/node.cjs +101 -0
  202. package/lib/cjs/node/agents/triggers/teams/node.cjs.map +1 -0
  203. package/lib/cjs/node/agents/triggers/telegram/node.cjs +101 -0
  204. package/lib/cjs/node/agents/triggers/telegram/node.cjs.map +1 -0
  205. package/lib/cjs/node/agents/voice/node.cjs +107 -0
  206. package/lib/cjs/node/agents/voice/node.cjs.map +1 -0
  207. package/lib/cjs/node/agents/zones.cjs +43 -0
  208. package/lib/cjs/node/agents/zones.cjs.map +1 -0
  209. package/lib/cjs/node/comms/email-send/node.cjs +340 -0
  210. package/lib/cjs/node/comms/email-send/node.cjs.map +1 -0
  211. package/lib/cjs/node/comms/gmail/node.cjs +287 -0
  212. package/lib/cjs/node/comms/gmail/node.cjs.map +1 -0
  213. package/lib/cjs/node/comms/slack/node.cjs +276 -0
  214. package/lib/cjs/node/comms/slack/node.cjs.map +1 -0
  215. package/lib/cjs/node/comms/teams/node.cjs +231 -0
  216. package/lib/cjs/node/comms/teams/node.cjs.map +1 -0
  217. package/lib/cjs/node/comms/telegram/node.cjs +260 -0
  218. package/lib/cjs/node/comms/telegram/node.cjs.map +1 -0
  219. package/lib/cjs/node/credentials.cjs +103 -0
  220. package/lib/cjs/node/credentials.cjs.map +1 -0
  221. package/lib/cjs/node/data/data-table/node.cjs +265 -0
  222. package/lib/cjs/node/data/data-table/node.cjs.map +1 -0
  223. package/lib/cjs/node/data/date-time/node.cjs +180 -0
  224. package/lib/cjs/node/data/date-time/node.cjs.map +1 -0
  225. package/lib/cjs/node/data/filter/node.cjs +134 -0
  226. package/lib/cjs/node/data/filter/node.cjs.map +1 -0
  227. package/lib/cjs/node/data/limit/node.cjs +104 -0
  228. package/lib/cjs/node/data/limit/node.cjs.map +1 -0
  229. package/lib/cjs/node/data/merge/node.cjs +251 -0
  230. package/lib/cjs/node/data/merge/node.cjs.map +1 -0
  231. package/lib/cjs/node/data/rename-keys/node.cjs +139 -0
  232. package/lib/cjs/node/data/rename-keys/node.cjs.map +1 -0
  233. package/lib/cjs/node/data/set/node.cjs +148 -0
  234. package/lib/cjs/node/data/set/node.cjs.map +1 -0
  235. package/lib/cjs/node/data/sort/node.cjs +125 -0
  236. package/lib/cjs/node/data/sort/node.cjs.map +1 -0
  237. package/lib/cjs/node/data/split-out/node.cjs +140 -0
  238. package/lib/cjs/node/data/split-out/node.cjs.map +1 -0
  239. package/lib/cjs/node/data/support.cjs +398 -0
  240. package/lib/cjs/node/data/support.cjs.map +1 -0
  241. package/lib/cjs/node/devops/crypto/node.cjs +364 -0
  242. package/lib/cjs/node/devops/crypto/node.cjs.map +1 -0
  243. package/lib/cjs/node/devops/execute-command/node.cjs +201 -0
  244. package/lib/cjs/node/devops/execute-command/node.cjs.map +1 -0
  245. package/lib/cjs/node/devops/ftp/node.cjs +241 -0
  246. package/lib/cjs/node/devops/ftp/node.cjs.map +1 -0
  247. package/lib/cjs/node/devops/github/node.cjs +282 -0
  248. package/lib/cjs/node/devops/github/node.cjs.map +1 -0
  249. package/lib/cjs/node/devops/gitlab/node.cjs +273 -0
  250. package/lib/cjs/node/devops/gitlab/node.cjs.map +1 -0
  251. package/lib/cjs/node/devops/jwt/node.cjs +204 -0
  252. package/lib/cjs/node/devops/jwt/node.cjs.map +1 -0
  253. package/lib/cjs/node/flow/execute-sub-workflow/node.cjs +223 -0
  254. package/lib/cjs/node/flow/execute-sub-workflow/node.cjs.map +1 -0
  255. package/lib/cjs/node/index.cjs +402 -66
  256. package/lib/cjs/node/index.cjs.map +1 -1
  257. package/lib/cjs/node/io/airtable/node.cjs +318 -0
  258. package/lib/cjs/node/io/airtable/node.cjs.map +1 -0
  259. package/lib/cjs/node/io/extract-from-file/node.cjs +269 -0
  260. package/lib/cjs/node/io/extract-from-file/node.cjs.map +1 -0
  261. package/lib/cjs/node/io/google-sheets/node.cjs +267 -0
  262. package/lib/cjs/node/io/google-sheets/node.cjs.map +1 -0
  263. package/lib/cjs/node/io/graphql/node.cjs +169 -0
  264. package/lib/cjs/node/io/graphql/node.cjs.map +1 -0
  265. package/lib/cjs/node/io/http-request/node.cjs +415 -0
  266. package/lib/cjs/node/io/http-request/node.cjs.map +1 -0
  267. package/lib/cjs/node/io/read-pdf/node.cjs +206 -0
  268. package/lib/cjs/node/io/read-pdf/node.cjs.map +1 -0
  269. package/lib/cjs/node/io/read-write-file/node.cjs +314 -0
  270. package/lib/cjs/node/io/read-write-file/node.cjs.map +1 -0
  271. package/lib/cjs/node/io/respond-to-webhook/node.cjs +183 -0
  272. package/lib/cjs/node/io/respond-to-webhook/node.cjs.map +1 -0
  273. package/lib/cjs/node/io/spreadsheet-file/node.cjs +192 -0
  274. package/lib/cjs/node/io/spreadsheet-file/node.cjs.map +1 -0
  275. package/lib/cjs/node/manifests.cjs +264 -36
  276. package/lib/cjs/node/manifests.cjs.map +1 -1
  277. package/lib/cjs/node/storage/blob/azure/node.cjs +138 -0
  278. package/lib/cjs/node/storage/blob/azure/node.cjs.map +1 -0
  279. package/lib/cjs/node/storage/blob/base.cjs +321 -0
  280. package/lib/cjs/node/storage/blob/base.cjs.map +1 -0
  281. package/lib/cjs/node/storage/blob/gcs/node.cjs +126 -0
  282. package/lib/cjs/node/storage/blob/gcs/node.cjs.map +1 -0
  283. package/lib/cjs/node/storage/blob/s3/node.cjs +186 -0
  284. package/lib/cjs/node/storage/blob/s3/node.cjs.map +1 -0
  285. package/lib/cjs/node/storage/database/base.cjs +301 -0
  286. package/lib/cjs/node/storage/database/base.cjs.map +1 -0
  287. package/lib/cjs/node/storage/database/mssql/node.cjs +50 -0
  288. package/lib/cjs/node/storage/database/mssql/node.cjs.map +1 -0
  289. package/lib/cjs/node/storage/database/mysql/node.cjs +50 -0
  290. package/lib/cjs/node/storage/database/mysql/node.cjs.map +1 -0
  291. package/lib/cjs/node/storage/database/postgres/node.cjs +50 -0
  292. package/lib/cjs/node/storage/database/postgres/node.cjs.map +1 -0
  293. package/lib/cjs/node/storage/redis/node.cjs +340 -0
  294. package/lib/cjs/node/storage/redis/node.cjs.map +1 -0
  295. package/lib/cjs/node/storage/support.cjs +81 -0
  296. package/lib/cjs/node/storage/support.cjs.map +1 -0
  297. package/lib/cjs/node/triggers/execute-workflow/node.cjs +94 -0
  298. package/lib/cjs/node/triggers/execute-workflow/node.cjs.map +1 -0
  299. package/lib/cjs/ram/GraphRunEventModel.cjs +4 -0
  300. package/lib/cjs/ram/GraphRunEventModel.cjs.map +1 -1
  301. package/lib/cjs/shared/graph/GraphNodeModel.cjs +4 -0
  302. package/lib/cjs/shared/graph/GraphNodeModel.cjs.map +1 -1
  303. package/lib/cjs/shared/graph/GraphWorkflowModel.cjs +4 -0
  304. package/lib/cjs/shared/graph/GraphWorkflowModel.cjs.map +1 -1
  305. package/lib/cjs/shared/graph/catalog/GraphManifestCompiler.cjs +40 -0
  306. package/lib/cjs/shared/graph/catalog/GraphManifestCompiler.cjs.map +1 -1
  307. package/lib/cjs/shared/graph/category-styles.cjs +12 -0
  308. package/lib/cjs/shared/graph/category-styles.cjs.map +1 -1
  309. package/lib/cjs/typeorm/TypeormGraphAdapter.cjs +250 -0
  310. package/lib/cjs/typeorm/TypeormGraphAdapter.cjs.map +1 -0
  311. package/lib/cjs/typeorm/index.cjs +29 -0
  312. package/lib/cjs/typeorm/index.cjs.map +1 -0
  313. package/lib/esm/engine/auth/GraphAuthValidator.js +19 -0
  314. package/lib/esm/engine/auth/GraphAuthValidator.js.map +1 -1
  315. package/lib/esm/engine/constants.js +60 -0
  316. package/lib/esm/engine/constants.js.map +1 -1
  317. package/lib/esm/engine/credentials/GraphNodeCredentials.js +152 -0
  318. package/lib/esm/engine/credentials/GraphNodeCredentials.js.map +1 -0
  319. package/lib/esm/engine/execution/GraphExecutionEngine.js +229 -68
  320. package/lib/esm/engine/execution/GraphExecutionEngine.js.map +1 -1
  321. package/lib/esm/engine/execution/GraphNodeEngineRequirements.js +28 -0
  322. package/lib/esm/engine/execution/GraphNodeEngineRequirements.js.map +1 -0
  323. package/lib/esm/engine/execution/GraphWebhookResponseRegistry.js +103 -0
  324. package/lib/esm/engine/execution/GraphWebhookResponseRegistry.js.map +1 -0
  325. package/lib/esm/engine/execution/LocalGraphExecutionBackend.js +54 -2
  326. package/lib/esm/engine/execution/LocalGraphExecutionBackend.js.map +1 -1
  327. package/lib/esm/engine/execution/index.js +1 -0
  328. package/lib/esm/engine/execution/index.js.map +1 -1
  329. package/lib/esm/engine/index.js +4 -0
  330. package/lib/esm/engine/index.js.map +1 -1
  331. package/lib/esm/engine/store/GraphDataTableModel.js +67 -0
  332. package/lib/esm/engine/store/GraphDataTableModel.js.map +1 -0
  333. package/lib/esm/engine/store/GraphDataTableRepository.js +314 -0
  334. package/lib/esm/engine/store/GraphDataTableRepository.js.map +1 -0
  335. package/lib/esm/engine/store/index.js +2 -0
  336. package/lib/esm/engine/store/index.js.map +1 -1
  337. package/lib/esm/engine/validation/GraphConnectionPolicyValidator.js +28 -0
  338. package/lib/esm/engine/validation/GraphConnectionPolicyValidator.js.map +1 -1
  339. package/lib/esm/engine/validation/GraphCredentialReferenceValidator.js +4 -2
  340. package/lib/esm/engine/validation/GraphCredentialReferenceValidator.js.map +1 -1
  341. package/lib/esm/engine/validation/GraphParameterValidator.js +6 -0
  342. package/lib/esm/engine/validation/GraphParameterValidator.js.map +1 -1
  343. package/lib/esm/mastra/MastraAgeVectorDriver.js +294 -0
  344. package/lib/esm/mastra/MastraAgeVectorDriver.js.map +1 -0
  345. package/lib/esm/mastra/MastraAgentBuilder.js +244 -0
  346. package/lib/esm/mastra/MastraAgentBuilder.js.map +1 -0
  347. package/lib/esm/mastra/MastraAgentModelAdapter.js +59 -0
  348. package/lib/esm/mastra/MastraAgentModelAdapter.js.map +1 -0
  349. package/lib/esm/mastra/MastraAgentProcessors.js +391 -0
  350. package/lib/esm/mastra/MastraAgentProcessors.js.map +1 -0
  351. package/lib/esm/mastra/MastraAgentStepHandler.js +327 -0
  352. package/lib/esm/mastra/MastraAgentStepHandler.js.map +1 -0
  353. package/lib/esm/mastra/MastraCapabilities.js +115 -0
  354. package/lib/esm/mastra/MastraCapabilities.js.map +1 -1
  355. package/lib/esm/mastra/MastraChannelResponse.js +154 -0
  356. package/lib/esm/mastra/MastraChannelResponse.js.map +1 -0
  357. package/lib/esm/mastra/MastraChannelTrigger.js +116 -0
  358. package/lib/esm/mastra/MastraChannelTrigger.js.map +1 -0
  359. package/lib/esm/mastra/MastraDefaultStepHandlers.js +240 -22
  360. package/lib/esm/mastra/MastraDefaultStepHandlers.js.map +1 -1
  361. package/lib/esm/mastra/MastraEnvironment.js +287 -0
  362. package/lib/esm/mastra/MastraEnvironment.js.map +1 -0
  363. package/lib/esm/mastra/MastraEvalModels.js +535 -0
  364. package/lib/esm/mastra/MastraEvalModels.js.map +1 -0
  365. package/lib/esm/mastra/MastraEventBridge.js +21 -1
  366. package/lib/esm/mastra/MastraEventBridge.js.map +1 -1
  367. package/lib/esm/mastra/MastraGraphExecutionBackend.js +414 -19
  368. package/lib/esm/mastra/MastraGraphExecutionBackend.js.map +1 -1
  369. package/lib/esm/mastra/MastraGraphExecutionModule.js +139 -0
  370. package/lib/esm/mastra/MastraGraphExecutionModule.js.map +1 -0
  371. package/lib/esm/mastra/MastraHitlStepHandler.js +62 -0
  372. package/lib/esm/mastra/MastraHitlStepHandler.js.map +1 -0
  373. package/lib/esm/mastra/MastraMcpTrigger.js +246 -0
  374. package/lib/esm/mastra/MastraMcpTrigger.js.map +1 -0
  375. package/lib/esm/mastra/MastraMemory.js +455 -0
  376. package/lib/esm/mastra/MastraMemory.js.map +1 -0
  377. package/lib/esm/mastra/MastraMetricsAdapter.js +273 -0
  378. package/lib/esm/mastra/MastraMetricsAdapter.js.map +1 -0
  379. package/lib/esm/mastra/MastraMetricsGateway.js +394 -0
  380. package/lib/esm/mastra/MastraMetricsGateway.js.map +1 -0
  381. package/lib/esm/mastra/MastraMetricsModels.js +486 -0
  382. package/lib/esm/mastra/MastraMetricsModels.js.map +1 -0
  383. package/lib/esm/mastra/MastraMetricsStatement.js +213 -0
  384. package/lib/esm/mastra/MastraMetricsStatement.js.map +1 -0
  385. package/lib/esm/mastra/MastraModelSchemaConverter.js +78 -0
  386. package/lib/esm/mastra/MastraModelSchemaConverter.js.map +1 -0
  387. package/lib/esm/mastra/MastraObservability.js +327 -0
  388. package/lib/esm/mastra/MastraObservability.js.map +1 -0
  389. package/lib/esm/mastra/MastraPersistence.js +530 -0
  390. package/lib/esm/mastra/MastraPersistence.js.map +1 -0
  391. package/lib/esm/mastra/MastraRagStepHandlers.js +920 -0
  392. package/lib/esm/mastra/MastraRagStepHandlers.js.map +1 -0
  393. package/lib/esm/mastra/MastraRunMetricsEndpoint.js +147 -0
  394. package/lib/esm/mastra/MastraRunMetricsEndpoint.js.map +1 -0
  395. package/lib/esm/mastra/MastraRunRecovery.js +89 -0
  396. package/lib/esm/mastra/MastraRunRecovery.js.map +1 -0
  397. package/lib/esm/mastra/MastraScheduleTrigger.js +110 -0
  398. package/lib/esm/mastra/MastraScheduleTrigger.js.map +1 -0
  399. package/lib/esm/mastra/MastraStorageWiring.js +119 -0
  400. package/lib/esm/mastra/MastraStorageWiring.js.map +1 -0
  401. package/lib/esm/mastra/MastraStructuredOutput.js +144 -0
  402. package/lib/esm/mastra/MastraStructuredOutput.js.map +1 -0
  403. package/lib/esm/mastra/MastraToolBuilder.js +68 -0
  404. package/lib/esm/mastra/MastraToolBuilder.js.map +1 -0
  405. package/lib/esm/mastra/MastraToolConfig.js +37 -0
  406. package/lib/esm/mastra/MastraToolConfig.js.map +1 -0
  407. package/lib/esm/mastra/MastraToolDecorator.js +92 -0
  408. package/lib/esm/mastra/MastraToolDecorator.js.map +1 -0
  409. package/lib/esm/mastra/MastraVectorStore.js +605 -0
  410. package/lib/esm/mastra/MastraVectorStore.js.map +1 -0
  411. package/lib/esm/mastra/MastraVoiceStepHandler.js +84 -0
  412. package/lib/esm/mastra/MastraVoiceStepHandler.js.map +1 -0
  413. package/lib/esm/mastra/MastraWorkflowCompiler.js +38 -6
  414. package/lib/esm/mastra/MastraWorkflowCompiler.js.map +1 -1
  415. package/lib/esm/mastra/MastraWorkflowManager.js +101 -51
  416. package/lib/esm/mastra/MastraWorkflowManager.js.map +1 -1
  417. package/lib/esm/mastra/index.js +40 -1
  418. package/lib/esm/mastra/index.js.map +1 -1
  419. package/lib/esm/mastra/nodes/MastraNodeRegistry.js +225 -0
  420. package/lib/esm/mastra/nodes/MastraNodeRegistry.js.map +1 -0
  421. package/lib/esm/mastra/nodes/index.js +12 -0
  422. package/lib/esm/mastra/nodes/index.js.map +1 -0
  423. package/lib/esm/mastra/nodes/types.js +2 -0
  424. package/lib/esm/mastra/nodes/types.js.map +1 -0
  425. package/lib/esm/mastra/types.js +125 -0
  426. package/lib/esm/mastra/types.js.map +1 -1
  427. package/lib/esm/nest/graph/GraphBackendHost.js +10 -2
  428. package/lib/esm/nest/graph/GraphBackendHost.js.map +1 -1
  429. package/lib/esm/nest/graph/GraphExecutionModule.js +35 -1
  430. package/lib/esm/nest/graph/GraphExecutionModule.js.map +1 -1
  431. package/lib/esm/nest/graph/GraphRunController.js +47 -6
  432. package/lib/esm/nest/graph/GraphRunController.js.map +1 -1
  433. package/lib/esm/nest/graph/main.js +83 -1
  434. package/lib/esm/nest/graph/main.js.map +1 -1
  435. package/lib/esm/node/agents/agent/node.js +189 -31
  436. package/lib/esm/node/agents/agent/node.js.map +1 -1
  437. package/lib/esm/node/agents/hitl/node.js +106 -0
  438. package/lib/esm/node/agents/hitl/node.js.map +1 -0
  439. package/lib/esm/node/agents/hooks/delegation/node.js +113 -0
  440. package/lib/esm/node/agents/hooks/delegation/node.js.map +1 -0
  441. package/lib/esm/node/agents/hooks/hook/node.js +111 -0
  442. package/lib/esm/node/agents/hooks/hook/node.js.map +1 -0
  443. package/lib/esm/node/agents/hooks/tool-deny/node.js +95 -0
  444. package/lib/esm/node/agents/hooks/tool-deny/node.js.map +1 -0
  445. package/lib/esm/node/agents/memory/memory/node.js +222 -0
  446. package/lib/esm/node/agents/memory/memory/node.js.map +1 -0
  447. package/lib/esm/node/agents/memory/memory-selector/node.js +92 -0
  448. package/lib/esm/node/agents/memory/memory-selector/node.js.map +1 -0
  449. package/lib/esm/node/agents/processors/guardrail/node.js +117 -0
  450. package/lib/esm/node/agents/processors/guardrail/node.js.map +1 -0
  451. package/lib/esm/node/agents/processors/input-processor/node.js +109 -0
  452. package/lib/esm/node/agents/processors/input-processor/node.js.map +1 -0
  453. package/lib/esm/node/agents/processors/output-processor/node.js +99 -0
  454. package/lib/esm/node/agents/processors/output-processor/node.js.map +1 -0
  455. package/lib/esm/node/agents/processors/types.js +64 -0
  456. package/lib/esm/node/agents/processors/types.js.map +1 -0
  457. package/lib/esm/node/agents/rag/chains/basic/node.js +94 -0
  458. package/lib/esm/node/agents/rag/chains/basic/node.js.map +1 -0
  459. package/lib/esm/node/agents/rag/chains/qa/node.js +115 -0
  460. package/lib/esm/node/agents/rag/chains/qa/node.js.map +1 -0
  461. package/lib/esm/node/agents/rag/chains/summarization/node.js +107 -0
  462. package/lib/esm/node/agents/rag/chains/summarization/node.js.map +1 -0
  463. package/lib/esm/node/agents/rag/chunking/node.js +211 -0
  464. package/lib/esm/node/agents/rag/chunking/node.js.map +1 -0
  465. package/lib/esm/node/agents/rag/embedding/node.js +101 -0
  466. package/lib/esm/node/agents/rag/embedding/node.js.map +1 -0
  467. package/lib/esm/node/agents/rag/information-extractor/node.js +106 -0
  468. package/lib/esm/node/agents/rag/information-extractor/node.js.map +1 -0
  469. package/lib/esm/node/agents/rag/langchain-code/node.js +104 -0
  470. package/lib/esm/node/agents/rag/langchain-code/node.js.map +1 -0
  471. package/lib/esm/node/agents/rag/rerank/node.js +103 -0
  472. package/lib/esm/node/agents/rag/rerank/node.js.map +1 -0
  473. package/lib/esm/node/agents/rag/retriever/node.js +111 -0
  474. package/lib/esm/node/agents/rag/retriever/node.js.map +1 -0
  475. package/lib/esm/node/agents/rag/structured-output-parser/node.js +112 -0
  476. package/lib/esm/node/agents/rag/structured-output-parser/node.js.map +1 -0
  477. package/lib/esm/node/agents/rag/vector-store/node.js +178 -0
  478. package/lib/esm/node/agents/rag/vector-store/node.js.map +1 -0
  479. package/lib/esm/node/agents/responses/discord/node.js +92 -0
  480. package/lib/esm/node/agents/responses/discord/node.js.map +1 -0
  481. package/lib/esm/node/agents/responses/slack/node.js +92 -0
  482. package/lib/esm/node/agents/responses/slack/node.js.map +1 -0
  483. package/lib/esm/node/agents/responses/teams/node.js +92 -0
  484. package/lib/esm/node/agents/responses/teams/node.js.map +1 -0
  485. package/lib/esm/node/agents/responses/telegram/node.js +92 -0
  486. package/lib/esm/node/agents/responses/telegram/node.js.map +1 -0
  487. package/lib/esm/node/agents/sandbox/node.js +125 -0
  488. package/lib/esm/node/agents/sandbox/node.js.map +1 -0
  489. package/lib/esm/node/agents/scorers/scorer/node.js +98 -0
  490. package/lib/esm/node/agents/scorers/scorer/node.js.map +1 -0
  491. package/lib/esm/node/agents/scorers/scorer-selector/node.js +91 -0
  492. package/lib/esm/node/agents/scorers/scorer-selector/node.js.map +1 -0
  493. package/lib/esm/node/agents/skills/skill/node.js +96 -0
  494. package/lib/esm/node/agents/skills/skill/node.js.map +1 -0
  495. package/lib/esm/node/agents/skills/skill-selector/node.js +89 -0
  496. package/lib/esm/node/agents/skills/skill-selector/node.js.map +1 -0
  497. package/lib/esm/node/agents/tools/tool/node.js +91 -0
  498. package/lib/esm/node/agents/tools/tool/node.js.map +1 -0
  499. package/lib/esm/node/agents/tools/tool-selector/node.js +90 -0
  500. package/lib/esm/node/agents/tools/tool-selector/node.js.map +1 -0
  501. package/lib/esm/node/agents/triggers/discord/node.js +92 -0
  502. package/lib/esm/node/agents/triggers/discord/node.js.map +1 -0
  503. package/lib/esm/node/agents/triggers/mcp-server/node.js +138 -0
  504. package/lib/esm/node/agents/triggers/mcp-server/node.js.map +1 -0
  505. package/lib/esm/node/agents/triggers/slack/node.js +92 -0
  506. package/lib/esm/node/agents/triggers/slack/node.js.map +1 -0
  507. package/lib/esm/node/agents/triggers/teams/node.js +92 -0
  508. package/lib/esm/node/agents/triggers/teams/node.js.map +1 -0
  509. package/lib/esm/node/agents/triggers/telegram/node.js +92 -0
  510. package/lib/esm/node/agents/triggers/telegram/node.js.map +1 -0
  511. package/lib/esm/node/agents/voice/node.js +98 -0
  512. package/lib/esm/node/agents/voice/node.js.map +1 -0
  513. package/lib/esm/node/agents/zones.js +39 -0
  514. package/lib/esm/node/agents/zones.js.map +1 -0
  515. package/lib/esm/node/comms/email-send/node.js +331 -0
  516. package/lib/esm/node/comms/email-send/node.js.map +1 -0
  517. package/lib/esm/node/comms/gmail/node.js +278 -0
  518. package/lib/esm/node/comms/gmail/node.js.map +1 -0
  519. package/lib/esm/node/comms/slack/node.js +267 -0
  520. package/lib/esm/node/comms/slack/node.js.map +1 -0
  521. package/lib/esm/node/comms/teams/node.js +222 -0
  522. package/lib/esm/node/comms/teams/node.js.map +1 -0
  523. package/lib/esm/node/comms/telegram/node.js +251 -0
  524. package/lib/esm/node/comms/telegram/node.js.map +1 -0
  525. package/lib/esm/node/credentials.js +96 -0
  526. package/lib/esm/node/credentials.js.map +1 -0
  527. package/lib/esm/node/data/data-table/node.js +256 -0
  528. package/lib/esm/node/data/data-table/node.js.map +1 -0
  529. package/lib/esm/node/data/date-time/node.js +171 -0
  530. package/lib/esm/node/data/date-time/node.js.map +1 -0
  531. package/lib/esm/node/data/filter/node.js +125 -0
  532. package/lib/esm/node/data/filter/node.js.map +1 -0
  533. package/lib/esm/node/data/limit/node.js +95 -0
  534. package/lib/esm/node/data/limit/node.js.map +1 -0
  535. package/lib/esm/node/data/merge/node.js +242 -0
  536. package/lib/esm/node/data/merge/node.js.map +1 -0
  537. package/lib/esm/node/data/rename-keys/node.js +130 -0
  538. package/lib/esm/node/data/rename-keys/node.js.map +1 -0
  539. package/lib/esm/node/data/set/node.js +139 -0
  540. package/lib/esm/node/data/set/node.js.map +1 -0
  541. package/lib/esm/node/data/sort/node.js +116 -0
  542. package/lib/esm/node/data/sort/node.js.map +1 -0
  543. package/lib/esm/node/data/split-out/node.js +131 -0
  544. package/lib/esm/node/data/split-out/node.js.map +1 -0
  545. package/lib/esm/node/data/support.js +382 -0
  546. package/lib/esm/node/data/support.js.map +1 -0
  547. package/lib/esm/node/devops/crypto/node.js +355 -0
  548. package/lib/esm/node/devops/crypto/node.js.map +1 -0
  549. package/lib/esm/node/devops/execute-command/node.js +192 -0
  550. package/lib/esm/node/devops/execute-command/node.js.map +1 -0
  551. package/lib/esm/node/devops/ftp/node.js +232 -0
  552. package/lib/esm/node/devops/ftp/node.js.map +1 -0
  553. package/lib/esm/node/devops/github/node.js +273 -0
  554. package/lib/esm/node/devops/github/node.js.map +1 -0
  555. package/lib/esm/node/devops/gitlab/node.js +264 -0
  556. package/lib/esm/node/devops/gitlab/node.js.map +1 -0
  557. package/lib/esm/node/devops/jwt/node.js +195 -0
  558. package/lib/esm/node/devops/jwt/node.js.map +1 -0
  559. package/lib/esm/node/flow/execute-sub-workflow/node.js +214 -0
  560. package/lib/esm/node/flow/execute-sub-workflow/node.js.map +1 -0
  561. package/lib/esm/node/index.js +338 -2
  562. package/lib/esm/node/index.js.map +1 -1
  563. package/lib/esm/node/io/airtable/node.js +309 -0
  564. package/lib/esm/node/io/airtable/node.js.map +1 -0
  565. package/lib/esm/node/io/extract-from-file/node.js +260 -0
  566. package/lib/esm/node/io/extract-from-file/node.js.map +1 -0
  567. package/lib/esm/node/io/google-sheets/node.js +258 -0
  568. package/lib/esm/node/io/google-sheets/node.js.map +1 -0
  569. package/lib/esm/node/io/graphql/node.js +160 -0
  570. package/lib/esm/node/io/graphql/node.js.map +1 -0
  571. package/lib/esm/node/io/http-request/node.js +406 -0
  572. package/lib/esm/node/io/http-request/node.js.map +1 -0
  573. package/lib/esm/node/io/read-pdf/node.js +164 -0
  574. package/lib/esm/node/io/read-pdf/node.js.map +1 -0
  575. package/lib/esm/node/io/read-write-file/node.js +305 -0
  576. package/lib/esm/node/io/read-write-file/node.js.map +1 -0
  577. package/lib/esm/node/io/respond-to-webhook/node.js +174 -0
  578. package/lib/esm/node/io/respond-to-webhook/node.js.map +1 -0
  579. package/lib/esm/node/io/spreadsheet-file/node.js +183 -0
  580. package/lib/esm/node/io/spreadsheet-file/node.js.map +1 -0
  581. package/lib/esm/node/manifests.js +228 -0
  582. package/lib/esm/node/manifests.js.map +1 -1
  583. package/lib/esm/node/storage/blob/azure/node.js +129 -0
  584. package/lib/esm/node/storage/blob/azure/node.js.map +1 -0
  585. package/lib/esm/node/storage/blob/base.js +311 -0
  586. package/lib/esm/node/storage/blob/base.js.map +1 -0
  587. package/lib/esm/node/storage/blob/gcs/node.js +117 -0
  588. package/lib/esm/node/storage/blob/gcs/node.js.map +1 -0
  589. package/lib/esm/node/storage/blob/s3/node.js +176 -0
  590. package/lib/esm/node/storage/blob/s3/node.js.map +1 -0
  591. package/lib/esm/node/storage/database/base.js +291 -0
  592. package/lib/esm/node/storage/database/base.js.map +1 -0
  593. package/lib/esm/node/storage/database/mssql/node.js +42 -0
  594. package/lib/esm/node/storage/database/mssql/node.js.map +1 -0
  595. package/lib/esm/node/storage/database/mysql/node.js +42 -0
  596. package/lib/esm/node/storage/database/mysql/node.js.map +1 -0
  597. package/lib/esm/node/storage/database/postgres/node.js +42 -0
  598. package/lib/esm/node/storage/database/postgres/node.js.map +1 -0
  599. package/lib/esm/node/storage/redis/node.js +331 -0
  600. package/lib/esm/node/storage/redis/node.js.map +1 -0
  601. package/lib/esm/node/storage/support.js +69 -0
  602. package/lib/esm/node/storage/support.js.map +1 -0
  603. package/lib/esm/node/triggers/execute-workflow/node.js +85 -0
  604. package/lib/esm/node/triggers/execute-workflow/node.js.map +1 -0
  605. package/lib/esm/ram/GraphRunEventModel.js +5 -1
  606. package/lib/esm/ram/GraphRunEventModel.js.map +1 -1
  607. package/lib/esm/shared/graph/GraphNodeModel.js +5 -1
  608. package/lib/esm/shared/graph/GraphNodeModel.js.map +1 -1
  609. package/lib/esm/shared/graph/GraphWorkflowModel.js +5 -1
  610. package/lib/esm/shared/graph/GraphWorkflowModel.js.map +1 -1
  611. package/lib/esm/shared/graph/catalog/GraphManifestCompiler.js +40 -0
  612. package/lib/esm/shared/graph/catalog/GraphManifestCompiler.js.map +1 -1
  613. package/lib/esm/shared/graph/catalog/GraphPortManifest.js.map +1 -1
  614. package/lib/esm/shared/graph/category-styles.js +12 -0
  615. package/lib/esm/shared/graph/category-styles.js.map +1 -1
  616. package/lib/esm/shared/graph/constants.js.map +1 -1
  617. package/lib/esm/typeorm/TypeormGraphAdapter.js +213 -0
  618. package/lib/esm/typeorm/TypeormGraphAdapter.js.map +1 -0
  619. package/lib/esm/typeorm/index.js +12 -0
  620. package/lib/esm/typeorm/index.js.map +1 -0
  621. package/lib/types/engine/auth/GraphAuthValidator.d.cts +13 -0
  622. package/lib/types/engine/auth/GraphAuthValidator.d.mts +13 -0
  623. package/lib/types/engine/constants.d.cts +60 -0
  624. package/lib/types/engine/constants.d.mts +60 -0
  625. package/lib/types/engine/credentials/GraphNodeCredentials.d.cts +145 -0
  626. package/lib/types/engine/credentials/GraphNodeCredentials.d.mts +145 -0
  627. package/lib/types/engine/execution/GraphExecutionEngine.d.cts +88 -1
  628. package/lib/types/engine/execution/GraphExecutionEngine.d.mts +88 -1
  629. package/lib/types/engine/execution/GraphNodeEngineRequirements.d.cts +24 -0
  630. package/lib/types/engine/execution/GraphNodeEngineRequirements.d.mts +24 -0
  631. package/lib/types/engine/execution/GraphWebhookResponseRegistry.d.cts +67 -0
  632. package/lib/types/engine/execution/GraphWebhookResponseRegistry.d.mts +67 -0
  633. package/lib/types/engine/execution/LocalGraphExecutionBackend.d.cts +12 -3
  634. package/lib/types/engine/execution/LocalGraphExecutionBackend.d.mts +12 -3
  635. package/lib/types/engine/execution/index.d.cts +1 -0
  636. package/lib/types/engine/execution/index.d.mts +1 -0
  637. package/lib/types/engine/index.d.cts +4 -0
  638. package/lib/types/engine/index.d.mts +4 -0
  639. package/lib/types/engine/store/GraphDataTableModel.d.cts +24 -0
  640. package/lib/types/engine/store/GraphDataTableModel.d.mts +24 -0
  641. package/lib/types/engine/store/GraphDataTableRepository.d.cts +136 -0
  642. package/lib/types/engine/store/GraphDataTableRepository.d.mts +136 -0
  643. package/lib/types/engine/store/index.d.cts +2 -0
  644. package/lib/types/engine/store/index.d.mts +2 -0
  645. package/lib/types/engine/types.d.cts +12 -0
  646. package/lib/types/engine/types.d.mts +12 -0
  647. package/lib/types/engine/validation/GraphConnectionPolicyValidator.d.cts +10 -0
  648. package/lib/types/engine/validation/GraphConnectionPolicyValidator.d.mts +10 -0
  649. package/lib/types/engine/validation/GraphParameterValidator.d.cts +1 -1
  650. package/lib/types/engine/validation/GraphParameterValidator.d.mts +1 -1
  651. package/lib/types/mastra/MastraAgeVectorDriver.d.cts +55 -0
  652. package/lib/types/mastra/MastraAgeVectorDriver.d.mts +55 -0
  653. package/lib/types/mastra/MastraAgentBuilder.d.cts +188 -0
  654. package/lib/types/mastra/MastraAgentBuilder.d.mts +188 -0
  655. package/lib/types/mastra/MastraAgentModelAdapter.d.cts +76 -0
  656. package/lib/types/mastra/MastraAgentModelAdapter.d.mts +76 -0
  657. package/lib/types/mastra/MastraAgentProcessors.d.cts +50 -0
  658. package/lib/types/mastra/MastraAgentProcessors.d.mts +50 -0
  659. package/lib/types/mastra/MastraAgentStepHandler.d.cts +128 -0
  660. package/lib/types/mastra/MastraAgentStepHandler.d.mts +128 -0
  661. package/lib/types/mastra/MastraCapabilities.d.cts +20 -0
  662. package/lib/types/mastra/MastraCapabilities.d.mts +20 -0
  663. package/lib/types/mastra/MastraChannelResponse.d.cts +64 -0
  664. package/lib/types/mastra/MastraChannelResponse.d.mts +64 -0
  665. package/lib/types/mastra/MastraChannelTrigger.d.cts +57 -0
  666. package/lib/types/mastra/MastraChannelTrigger.d.mts +57 -0
  667. package/lib/types/mastra/MastraDefaultStepHandlers.d.cts +53 -6
  668. package/lib/types/mastra/MastraDefaultStepHandlers.d.mts +53 -6
  669. package/lib/types/mastra/MastraEnvironment.d.cts +270 -0
  670. package/lib/types/mastra/MastraEnvironment.d.mts +270 -0
  671. package/lib/types/mastra/MastraEvalModels.d.cts +191 -0
  672. package/lib/types/mastra/MastraEvalModels.d.mts +191 -0
  673. package/lib/types/mastra/MastraEventBridge.d.cts +17 -0
  674. package/lib/types/mastra/MastraEventBridge.d.mts +17 -0
  675. package/lib/types/mastra/MastraGraphExecutionBackend.d.cts +108 -1
  676. package/lib/types/mastra/MastraGraphExecutionBackend.d.mts +108 -1
  677. package/lib/types/mastra/MastraGraphExecutionModule.d.cts +114 -0
  678. package/lib/types/mastra/MastraGraphExecutionModule.d.mts +114 -0
  679. package/lib/types/mastra/MastraHitlStepHandler.d.cts +18 -0
  680. package/lib/types/mastra/MastraHitlStepHandler.d.mts +18 -0
  681. package/lib/types/mastra/MastraMcpTrigger.d.cts +133 -0
  682. package/lib/types/mastra/MastraMcpTrigger.d.mts +133 -0
  683. package/lib/types/mastra/MastraMemory.d.cts +362 -0
  684. package/lib/types/mastra/MastraMemory.d.mts +362 -0
  685. package/lib/types/mastra/MastraMetricsAdapter.d.cts +216 -0
  686. package/lib/types/mastra/MastraMetricsAdapter.d.mts +216 -0
  687. package/lib/types/mastra/MastraMetricsGateway.d.cts +265 -0
  688. package/lib/types/mastra/MastraMetricsGateway.d.mts +265 -0
  689. package/lib/types/mastra/MastraMetricsModels.d.cts +175 -0
  690. package/lib/types/mastra/MastraMetricsModels.d.mts +175 -0
  691. package/lib/types/mastra/MastraMetricsStatement.d.cts +116 -0
  692. package/lib/types/mastra/MastraMetricsStatement.d.mts +116 -0
  693. package/lib/types/mastra/MastraModelSchemaConverter.d.cts +45 -0
  694. package/lib/types/mastra/MastraModelSchemaConverter.d.mts +45 -0
  695. package/lib/types/mastra/MastraObservability.d.cts +197 -0
  696. package/lib/types/mastra/MastraObservability.d.mts +197 -0
  697. package/lib/types/mastra/MastraPersistence.d.cts +241 -0
  698. package/lib/types/mastra/MastraPersistence.d.mts +241 -0
  699. package/lib/types/mastra/MastraRagStepHandlers.d.cts +137 -0
  700. package/lib/types/mastra/MastraRagStepHandlers.d.mts +137 -0
  701. package/lib/types/mastra/MastraRunMetricsEndpoint.d.cts +53 -0
  702. package/lib/types/mastra/MastraRunMetricsEndpoint.d.mts +53 -0
  703. package/lib/types/mastra/MastraRunRecovery.d.cts +26 -0
  704. package/lib/types/mastra/MastraRunRecovery.d.mts +26 -0
  705. package/lib/types/mastra/MastraScheduleTrigger.d.cts +20 -0
  706. package/lib/types/mastra/MastraScheduleTrigger.d.mts +20 -0
  707. package/lib/types/mastra/MastraStorageWiring.d.cts +71 -0
  708. package/lib/types/mastra/MastraStorageWiring.d.mts +71 -0
  709. package/lib/types/mastra/MastraStructuredOutput.d.cts +165 -0
  710. package/lib/types/mastra/MastraStructuredOutput.d.mts +165 -0
  711. package/lib/types/mastra/MastraToolBuilder.d.cts +70 -0
  712. package/lib/types/mastra/MastraToolBuilder.d.mts +70 -0
  713. package/lib/types/mastra/MastraToolConfig.d.cts +136 -0
  714. package/lib/types/mastra/MastraToolConfig.d.mts +136 -0
  715. package/lib/types/mastra/MastraToolDecorator.d.cts +47 -0
  716. package/lib/types/mastra/MastraToolDecorator.d.mts +47 -0
  717. package/lib/types/mastra/MastraVectorStore.d.cts +383 -0
  718. package/lib/types/mastra/MastraVectorStore.d.mts +383 -0
  719. package/lib/types/mastra/MastraVoiceStepHandler.d.cts +40 -0
  720. package/lib/types/mastra/MastraVoiceStepHandler.d.mts +40 -0
  721. package/lib/types/mastra/MastraWorkflowManager.d.cts +36 -28
  722. package/lib/types/mastra/MastraWorkflowManager.d.mts +36 -28
  723. package/lib/types/mastra/index.d.cts +40 -1
  724. package/lib/types/mastra/index.d.mts +40 -1
  725. package/lib/types/mastra/nodes/MastraNodeRegistry.d.cts +41 -0
  726. package/lib/types/mastra/nodes/MastraNodeRegistry.d.mts +41 -0
  727. package/lib/types/mastra/nodes/index.d.cts +11 -0
  728. package/lib/types/mastra/nodes/index.d.mts +11 -0
  729. package/lib/types/mastra/nodes/types.d.cts +57 -0
  730. package/lib/types/mastra/nodes/types.d.mts +57 -0
  731. package/lib/types/mastra/types.d.cts +365 -6
  732. package/lib/types/mastra/types.d.mts +365 -6
  733. package/lib/types/nest/graph/GraphExecutionModule.d.cts +17 -0
  734. package/lib/types/nest/graph/GraphExecutionModule.d.mts +17 -0
  735. package/lib/types/nest/graph/GraphRunController.d.cts +24 -4
  736. package/lib/types/nest/graph/GraphRunController.d.mts +24 -4
  737. package/lib/types/node/agents/agent/node.d.cts +72 -16
  738. package/lib/types/node/agents/agent/node.d.mts +72 -16
  739. package/lib/types/node/agents/hitl/node.d.cts +45 -0
  740. package/lib/types/node/agents/hitl/node.d.mts +45 -0
  741. package/lib/types/node/agents/hooks/delegation/node.d.cts +48 -0
  742. package/lib/types/node/agents/hooks/delegation/node.d.mts +48 -0
  743. package/lib/types/node/agents/hooks/hook/node.d.cts +45 -0
  744. package/lib/types/node/agents/hooks/hook/node.d.mts +45 -0
  745. package/lib/types/node/agents/hooks/tool-deny/node.d.cts +39 -0
  746. package/lib/types/node/agents/hooks/tool-deny/node.d.mts +39 -0
  747. package/lib/types/node/agents/memory/memory/node.d.cts +73 -0
  748. package/lib/types/node/agents/memory/memory/node.d.mts +73 -0
  749. package/lib/types/node/agents/memory/memory-selector/node.d.cts +34 -0
  750. package/lib/types/node/agents/memory/memory-selector/node.d.mts +34 -0
  751. package/lib/types/node/agents/processors/guardrail/node.d.cts +47 -0
  752. package/lib/types/node/agents/processors/guardrail/node.d.mts +47 -0
  753. package/lib/types/node/agents/processors/input-processor/node.d.cts +40 -0
  754. package/lib/types/node/agents/processors/input-processor/node.d.mts +40 -0
  755. package/lib/types/node/agents/processors/output-processor/node.d.cts +34 -0
  756. package/lib/types/node/agents/processors/output-processor/node.d.mts +34 -0
  757. package/lib/types/node/agents/processors/types.d.cts +45 -0
  758. package/lib/types/node/agents/processors/types.d.mts +45 -0
  759. package/lib/types/node/agents/rag/chains/basic/node.d.cts +36 -0
  760. package/lib/types/node/agents/rag/chains/basic/node.d.mts +36 -0
  761. package/lib/types/node/agents/rag/chains/qa/node.d.cts +44 -0
  762. package/lib/types/node/agents/rag/chains/qa/node.d.mts +44 -0
  763. package/lib/types/node/agents/rag/chains/summarization/node.d.cts +39 -0
  764. package/lib/types/node/agents/rag/chains/summarization/node.d.mts +39 -0
  765. package/lib/types/node/agents/rag/chunking/node.d.cts +73 -0
  766. package/lib/types/node/agents/rag/chunking/node.d.mts +73 -0
  767. package/lib/types/node/agents/rag/embedding/node.d.cts +37 -0
  768. package/lib/types/node/agents/rag/embedding/node.d.mts +37 -0
  769. package/lib/types/node/agents/rag/information-extractor/node.d.cts +39 -0
  770. package/lib/types/node/agents/rag/information-extractor/node.d.mts +39 -0
  771. package/lib/types/node/agents/rag/langchain-code/node.d.cts +36 -0
  772. package/lib/types/node/agents/rag/langchain-code/node.d.mts +36 -0
  773. package/lib/types/node/agents/rag/rerank/node.d.cts +39 -0
  774. package/lib/types/node/agents/rag/rerank/node.d.mts +39 -0
  775. package/lib/types/node/agents/rag/retriever/node.d.cts +42 -0
  776. package/lib/types/node/agents/rag/retriever/node.d.mts +42 -0
  777. package/lib/types/node/agents/rag/structured-output-parser/node.d.cts +35 -0
  778. package/lib/types/node/agents/rag/structured-output-parser/node.d.mts +35 -0
  779. package/lib/types/node/agents/rag/vector-store/node.d.cts +59 -0
  780. package/lib/types/node/agents/rag/vector-store/node.d.mts +59 -0
  781. package/lib/types/node/agents/responses/discord/node.d.cts +34 -0
  782. package/lib/types/node/agents/responses/discord/node.d.mts +34 -0
  783. package/lib/types/node/agents/responses/slack/node.d.cts +34 -0
  784. package/lib/types/node/agents/responses/slack/node.d.mts +34 -0
  785. package/lib/types/node/agents/responses/teams/node.d.cts +34 -0
  786. package/lib/types/node/agents/responses/teams/node.d.mts +34 -0
  787. package/lib/types/node/agents/responses/telegram/node.d.cts +34 -0
  788. package/lib/types/node/agents/responses/telegram/node.d.mts +34 -0
  789. package/lib/types/node/agents/sandbox/node.d.cts +47 -0
  790. package/lib/types/node/agents/sandbox/node.d.mts +47 -0
  791. package/lib/types/node/agents/scorers/scorer/node.d.cts +33 -0
  792. package/lib/types/node/agents/scorers/scorer/node.d.mts +33 -0
  793. package/lib/types/node/agents/scorers/scorer-selector/node.d.cts +33 -0
  794. package/lib/types/node/agents/scorers/scorer-selector/node.d.mts +33 -0
  795. package/lib/types/node/agents/skills/skill/node.d.cts +32 -0
  796. package/lib/types/node/agents/skills/skill/node.d.mts +32 -0
  797. package/lib/types/node/agents/skills/skill-selector/node.d.cts +33 -0
  798. package/lib/types/node/agents/skills/skill-selector/node.d.mts +33 -0
  799. package/lib/types/node/agents/tools/tool/node.d.cts +33 -0
  800. package/lib/types/node/agents/tools/tool/node.d.mts +33 -0
  801. package/lib/types/node/agents/tools/tool-selector/node.d.cts +33 -0
  802. package/lib/types/node/agents/tools/tool-selector/node.d.mts +33 -0
  803. package/lib/types/node/agents/triggers/discord/node.d.cts +40 -0
  804. package/lib/types/node/agents/triggers/discord/node.d.mts +40 -0
  805. package/lib/types/node/agents/triggers/mcp-server/node.d.cts +51 -0
  806. package/lib/types/node/agents/triggers/mcp-server/node.d.mts +51 -0
  807. package/lib/types/node/agents/triggers/slack/node.d.cts +40 -0
  808. package/lib/types/node/agents/triggers/slack/node.d.mts +40 -0
  809. package/lib/types/node/agents/triggers/teams/node.d.cts +40 -0
  810. package/lib/types/node/agents/triggers/teams/node.d.mts +40 -0
  811. package/lib/types/node/agents/triggers/telegram/node.d.cts +40 -0
  812. package/lib/types/node/agents/triggers/telegram/node.d.mts +40 -0
  813. package/lib/types/node/agents/voice/node.d.cts +34 -0
  814. package/lib/types/node/agents/voice/node.d.mts +34 -0
  815. package/lib/types/node/agents/zones.d.cts +30 -0
  816. package/lib/types/node/agents/zones.d.mts +30 -0
  817. package/lib/types/node/comms/email-send/node.d.cts +85 -0
  818. package/lib/types/node/comms/email-send/node.d.mts +85 -0
  819. package/lib/types/node/comms/gmail/node.d.cts +67 -0
  820. package/lib/types/node/comms/gmail/node.d.mts +67 -0
  821. package/lib/types/node/comms/slack/node.d.cts +65 -0
  822. package/lib/types/node/comms/slack/node.d.mts +65 -0
  823. package/lib/types/node/comms/teams/node.d.cts +49 -0
  824. package/lib/types/node/comms/teams/node.d.mts +49 -0
  825. package/lib/types/node/comms/telegram/node.d.cts +61 -0
  826. package/lib/types/node/comms/telegram/node.d.mts +61 -0
  827. package/lib/types/node/credentials.d.cts +43 -0
  828. package/lib/types/node/credentials.d.mts +43 -0
  829. package/lib/types/node/data/data-table/node.d.cts +86 -0
  830. package/lib/types/node/data/data-table/node.d.mts +86 -0
  831. package/lib/types/node/data/date-time/node.d.cts +49 -0
  832. package/lib/types/node/data/date-time/node.d.mts +49 -0
  833. package/lib/types/node/data/filter/node.d.cts +31 -0
  834. package/lib/types/node/data/filter/node.d.mts +31 -0
  835. package/lib/types/node/data/limit/node.d.cts +28 -0
  836. package/lib/types/node/data/limit/node.d.mts +28 -0
  837. package/lib/types/node/data/merge/node.d.cts +63 -0
  838. package/lib/types/node/data/merge/node.d.mts +63 -0
  839. package/lib/types/node/data/rename-keys/node.d.cts +35 -0
  840. package/lib/types/node/data/rename-keys/node.d.mts +35 -0
  841. package/lib/types/node/data/set/node.d.cts +52 -0
  842. package/lib/types/node/data/set/node.d.mts +52 -0
  843. package/lib/types/node/data/sort/node.d.cts +40 -0
  844. package/lib/types/node/data/sort/node.d.mts +40 -0
  845. package/lib/types/node/data/split-out/node.d.cts +30 -0
  846. package/lib/types/node/data/split-out/node.d.mts +30 -0
  847. package/lib/types/node/data/support.d.cts +164 -0
  848. package/lib/types/node/data/support.d.mts +164 -0
  849. package/lib/types/node/devops/crypto/node.d.cts +65 -0
  850. package/lib/types/node/devops/crypto/node.d.mts +65 -0
  851. package/lib/types/node/devops/execute-command/node.d.cts +55 -0
  852. package/lib/types/node/devops/execute-command/node.d.mts +55 -0
  853. package/lib/types/node/devops/ftp/node.d.cts +55 -0
  854. package/lib/types/node/devops/ftp/node.d.mts +55 -0
  855. package/lib/types/node/devops/github/node.d.cts +61 -0
  856. package/lib/types/node/devops/github/node.d.mts +61 -0
  857. package/lib/types/node/devops/gitlab/node.d.cts +61 -0
  858. package/lib/types/node/devops/gitlab/node.d.mts +61 -0
  859. package/lib/types/node/devops/jwt/node.d.cts +53 -0
  860. package/lib/types/node/devops/jwt/node.d.mts +53 -0
  861. package/lib/types/node/flow/execute-sub-workflow/node.d.cts +63 -0
  862. package/lib/types/node/flow/execute-sub-workflow/node.d.mts +63 -0
  863. package/lib/types/node/index.d.cts +182 -2
  864. package/lib/types/node/index.d.mts +182 -2
  865. package/lib/types/node/io/airtable/node.d.cts +73 -0
  866. package/lib/types/node/io/airtable/node.d.mts +73 -0
  867. package/lib/types/node/io/extract-from-file/node.d.cts +38 -0
  868. package/lib/types/node/io/extract-from-file/node.d.mts +38 -0
  869. package/lib/types/node/io/google-sheets/node.d.cts +77 -0
  870. package/lib/types/node/io/google-sheets/node.d.mts +77 -0
  871. package/lib/types/node/io/graphql/node.d.cts +46 -0
  872. package/lib/types/node/io/graphql/node.d.mts +46 -0
  873. package/lib/types/node/io/http-request/node.d.cts +107 -0
  874. package/lib/types/node/io/http-request/node.d.mts +107 -0
  875. package/lib/types/node/io/read-pdf/node.d.cts +40 -0
  876. package/lib/types/node/io/read-pdf/node.d.mts +40 -0
  877. package/lib/types/node/io/read-write-file/node.d.cts +41 -0
  878. package/lib/types/node/io/read-write-file/node.d.mts +41 -0
  879. package/lib/types/node/io/respond-to-webhook/node.d.cts +45 -0
  880. package/lib/types/node/io/respond-to-webhook/node.d.mts +45 -0
  881. package/lib/types/node/io/spreadsheet-file/node.d.cts +51 -0
  882. package/lib/types/node/io/spreadsheet-file/node.d.mts +51 -0
  883. package/lib/types/node/storage/blob/azure/node.d.cts +27 -0
  884. package/lib/types/node/storage/blob/azure/node.d.mts +27 -0
  885. package/lib/types/node/storage/blob/base.d.cts +83 -0
  886. package/lib/types/node/storage/blob/base.d.mts +83 -0
  887. package/lib/types/node/storage/blob/gcs/node.d.cts +27 -0
  888. package/lib/types/node/storage/blob/gcs/node.d.mts +27 -0
  889. package/lib/types/node/storage/blob/s3/node.d.cts +39 -0
  890. package/lib/types/node/storage/blob/s3/node.d.mts +39 -0
  891. package/lib/types/node/storage/database/base.d.cts +97 -0
  892. package/lib/types/node/storage/database/base.d.mts +97 -0
  893. package/lib/types/node/storage/database/mssql/node.d.cts +8 -0
  894. package/lib/types/node/storage/database/mssql/node.d.mts +8 -0
  895. package/lib/types/node/storage/database/mysql/node.d.cts +8 -0
  896. package/lib/types/node/storage/database/mysql/node.d.mts +8 -0
  897. package/lib/types/node/storage/database/postgres/node.d.cts +8 -0
  898. package/lib/types/node/storage/database/postgres/node.d.mts +8 -0
  899. package/lib/types/node/storage/redis/node.d.cts +68 -0
  900. package/lib/types/node/storage/redis/node.d.mts +68 -0
  901. package/lib/types/node/storage/support.d.cts +36 -0
  902. package/lib/types/node/storage/support.d.mts +36 -0
  903. package/lib/types/node/triggers/execute-workflow/node.d.cts +25 -0
  904. package/lib/types/node/triggers/execute-workflow/node.d.mts +25 -0
  905. package/lib/types/ram/GraphRunEventModel.d.cts +6 -0
  906. package/lib/types/ram/GraphRunEventModel.d.mts +6 -0
  907. package/lib/types/shared/graph/GraphNodeModel.d.cts +6 -0
  908. package/lib/types/shared/graph/GraphNodeModel.d.mts +6 -0
  909. package/lib/types/shared/graph/GraphWorkflowModel.d.cts +6 -0
  910. package/lib/types/shared/graph/GraphWorkflowModel.d.mts +6 -0
  911. package/lib/types/shared/graph/catalog/GraphPortManifest.d.cts +7 -0
  912. package/lib/types/shared/graph/catalog/GraphPortManifest.d.mts +7 -0
  913. package/lib/types/shared/graph/constants.d.cts +39 -0
  914. package/lib/types/shared/graph/constants.d.mts +39 -0
  915. package/lib/types/typeorm/TypeormGraphAdapter.d.cts +32 -0
  916. package/lib/types/typeorm/TypeormGraphAdapter.d.mts +32 -0
  917. package/lib/types/typeorm/index.d.cts +11 -0
  918. package/lib/types/typeorm/index.d.mts +11 -0
  919. package/package.json +51 -11
package/README.md CHANGED
@@ -80,10 +80,13 @@ src/
80
80
  │ │ └── snapshot.ts # frontend-safe execution snapshots
81
81
  │ └── ui/ # framework-neutral view models for the graph UI
82
82
  ├── node/ # built-in @node classes, one folder per node: node/<category>/<sub>/<node>/node.ts
83
- │ # (triggers, flow, utility, loops, agents, boundary input/output value nodes)
84
- ├── engine/ # execution engine (planning, validation, auth, loops, pinning, runs, store, catalog)
83
+ │ # (triggers, flow, data, io, storage, devops, comms, utility, agents, boundary)
84
+ ├── engine/ # execution engine (planning, validation, auth, credentials, loops, pinning, runs, store, catalog)
85
85
  ├── nest/ # NestJS HTTP/SSE wiring for the engine
86
86
  ├── ram/ # adapter-backed run/run-event persistence (RamGraphRunStore, RamGraphRunEventStore)
87
+ ├── mastra/ # Mastra execution backend (mastra/nodes/: the mastra-only node-kind registry)
88
+ ├── typeorm/ # durable Postgres adapter factory for the as-graph decaf tables
89
+ ├── dagster/ # Dagster execution backend (host-injected DagsterClient port)
87
90
  ├── assets/ # locale JSON for @uielement strings (i18n/en.json, shipped via package files)
88
91
  └── log/ # run-log channel
89
92
  ```
@@ -96,7 +99,8 @@ compiled into a canonical `GraphWorkflowDocument` (`GraphDecoratedWorkflowCompil
96
99
 
97
100
  The document topology **is** the concurrency model: multiple `data` connections out of one output port
98
101
  fan out and execute concurrently, and multiple connections into one input port fan in and are joined
99
- before the target node runs. There are no dedicated `parallel` or `merge` node kinds. Node classes
102
+ before the target node runs. There is no dedicated `parallel` node kind (`core.data.merge` is a data-transform node, not an
103
+ execution branch merge). Node classes
100
104
  carry their behaviour on the **instance** `execute` method (parameters are hydrated onto the instance
101
105
  before it runs), and each kind is described by a `GraphNodeManifest` compiled from `@node`/`@input`/
102
106
  `@output` metadata.
@@ -148,7 +152,9 @@ npm install @decaf-ts/as-graph
148
152
  | `@decaf-ts/as-graph/shared` | UI-known contracts: `@node`/`@graph`/`@port` decorators, the canonical `GraphWorkflowDocument` and its builder/reader/serializer, manifest catalogue types, the persistable `GraphNodeModel` catalogue row with its manifest converters, constants, and frontend-safe execution-state projections |
149
153
  | `@decaf-ts/as-graph/nest` | NestJS HTTP/SSE wiring: catalogue, workflow persistence and run-lifecycle controllers |
150
154
  | `@decaf-ts/as-graph/ram` | Adapter-backed persistence: `GraphRunModel`/`GraphRunEventModel`/`GraphValueModel` and their `@repository()` classes, the `GraphNodeRepository` node-kind rows, the `RamGraphRunStore`/`RamGraphRunEventStore` stores, and the `createRamGraphAdapter` helper |
151
- | `@decaf-ts/as-graph/mastra` | Mastra execution backend: `MastraGraphExecutionBackend`, the workflow compiler, condition/event bridges, schema converter, resume guard, and the Mastra capability table. Runs canonical documents on a host-injected `@mastra/core` runtime (pinned `1.74.0`) |
155
+ | `@decaf-ts/as-graph/typeorm` | Durable production persistence: `createTypeormGraphAdapter({ dataSource })` — a `@decaf-ts/for-typeorm` Postgres adapter factory for the five as-graph decaf tables plus the mastra-layer decaf models (flavoured for the durable lane, `jsonb`-pinned structured columns, `synchronize: false`, bootstrap-owned DDL). See [Durable Postgres lane](#durable-postgres-lane-decaf-tsas-graphtypeorm) |
156
+ | `@decaf-ts/as-graph/mastra` | Mastra execution backend: `MastraGraphExecutionBackend`, the workflow compiler, condition/event bridges, schema converter, resume guard, and the Mastra capability table — plus the backend contract: `MastraModelSchemaConverter` (`mastraSchemaFromModel`/`mastraModelFromSchema`, the single decaf↔mastra schema conversion path over `@decaf-ts/as-zod`), `MastraStructuredOutput` (the JSON-safe structured-output definition/resolution contract), and `MastraEnvironment` (the `MASTRA__*` engine environment with the credential fail-closed gate). Runs canonical documents on a host-injected `@mastra/core` runtime (peer dependency `^1.77.0`; the capability manifest separately pins `MASTRA_PINNED_VERSION = "1.74.0"` as the reviewed engine contract), executing the RAG/sandbox kinds for real through `MastraRagStepHandlers` (fail-closed `GRAPH_MASTRA_RAG_UNAVAILABLE`/`GRAPH_MASTRA_EMBEDDING_UNAVAILABLE`/`GRAPH_MASTRA_SANDBOX_UNAVAILABLE`) and serving MCP deliveries behind the run-scoped C6 `MastraMcpDeliveryGuard` |
157
+ | `@decaf-ts/as-graph/mastra/nodes` | Mastra-only node-kind registry (SAA-1141): the authoritative list of `core.agent[.*]` kinds, each paired with its declaration class and the step-handler factory that owns it. `createMastraNodeStepHandlers` composes the backend's registered handler set from the host extension points; `auditMastraNodeCoverage` / `assertMastraNodeCoverage` prove zero missing implementations |
152
158
  | `@decaf-ts/as-graph/dagster` | Dagster execution backend: `DagsterGraphExecutionBackend`, the workflow translator, event bridge, result mapper, capability table (`DAGSTER_CAPABILITY_TABLE`), and Dagster identifier/condition-grammar helpers. Driven through a host-injected `DagsterClient` port against the pinned engine contract (`1.13.25`; Dagster is Python-side, there is no JavaScript runtime dependency) |
153
159
 
154
160
  The `exports` map in `package.json` is:
@@ -176,11 +182,21 @@ The `exports` map in `package.json` is:
176
182
  "require": { "types": "./lib/types/ram/index.d.cts", "default": "./lib/cjs/ram/index.cjs" },
177
183
  "default": "./lib/esm/ram/index.js"
178
184
  },
185
+ "./typeorm": {
186
+ "import": { "types": "./lib/types/typeorm/index.d.mts", "default": "./lib/esm/typeorm/index.js" },
187
+ "require": { "types": "./lib/types/typeorm/index.d.cts", "default": "./lib/cjs/typeorm/index.cjs" },
188
+ "default": "./lib/esm/typeorm/index.js"
189
+ },
179
190
  "./mastra": {
180
191
  "import": { "types": "./lib/types/mastra/index.d.mts", "default": "./lib/esm/mastra/index.js" },
181
192
  "require": { "types": "./lib/types/mastra/index.d.cts", "default": "./lib/cjs/mastra/index.cjs" },
182
193
  "default": "./lib/esm/mastra/index.js"
183
194
  },
195
+ "./mastra/nodes": {
196
+ "import": { "types": "./lib/types/mastra/nodes/index.d.mts", "default": "./lib/esm/mastra/nodes/index.js" },
197
+ "require": { "types": "./lib/types/mastra/nodes/index.d.cts", "default": "./lib/cjs/mastra/nodes/index.cjs" },
198
+ "default": "./lib/esm/mastra/nodes/index.js"
199
+ },
184
200
  "./dagster": {
185
201
  "import": { "types": "./lib/types/dagster/index.d.mts", "default": "./lib/esm/dagster/index.js" },
186
202
  "require": { "types": "./lib/types/dagster/index.d.cts", "default": "./lib/cjs/dagster/index.cjs" },
@@ -282,24 +298,55 @@ The built-in kinds are declared one folder per node under
282
298
 
283
299
  | Group | Kinds |
284
300
  | --- | --- |
285
- | Triggers | `core.trigger.manual`, `core.trigger.webhook`, `core.trigger.schedule`, `core.trigger.event`, `core.trigger.form`, `core.trigger.chat` |
286
- | Flow | `core.flow.if`, `core.flow.switch`, `core.flow.delay`, `core.flow.errorBoundary`, `core.flow.humanApproval`, `core.flow.log`, `core.flow.break` |
301
+ | Triggers | `core.trigger.manual`, `core.trigger.webhook`, `core.trigger.schedule`, `core.trigger.event`, `core.trigger.form`, `core.trigger.chat`, `core.trigger.executeWorkflow` |
302
+ | Flow | `core.flow.if`, `core.flow.switch`, `core.flow.delay`, `core.flow.errorBoundary`, `core.flow.humanApproval`, `core.flow.log`, `core.flow.break`, `core.flow.executeSubWorkflow` |
303
+ | Data | `core.data.set`, `core.data.merge`, `core.data.filter`, `core.data.splitOut`, `core.data.dateTime`, `core.data.dataTable`, `core.data.limit`, `core.data.sort`, `core.data.renameKeys` |
304
+ | IO | `core.io.httpRequest`, `core.io.respondToWebhook`, `core.io.extractFromFile`, `core.io.readPDF`, `core.io.readWriteFile`, `core.io.googleSheets`, `core.io.airtable`, `core.io.spreadsheetFile`, `core.io.graphql` |
305
+ | Storage | `core.storage.postgres`, `core.storage.mySql`, `core.storage.microsoftSql`, `core.storage.redis`, `core.storage.s3`, `core.storage.awsS3`, `core.storage.googleCloudStorage`, `core.storage.azureStorage` |
306
+ | DevOps | `core.devops.crypto`, `core.devops.jwt`, `core.devops.executeCommand`, `core.devops.ftp`, `core.devops.github`, `core.devops.gitlab` |
307
+ | Comms | `core.comms.slack`, `core.comms.telegram`, `core.comms.teams`, `core.comms.gmail`, `core.comms.emailSend` |
287
308
  | Utility | `core.utility.code`, `core.utility.map`, `core.utility.log` |
288
309
  | Loops | `core.loop.foreach`, `core.loop.while`, `core.loop.until` |
289
- | Agent | `core.agent` |
310
+ | Agent | `core.agent` (the agent node) and its `core.agent.*` family kinds: `core.agent.tool|toolSelector` (tools), `core.agent.hook|toolDeny|delegationHook` (hooks), `core.agent.skill|skillSelector` (skills), `core.agent.sandbox` (sandbox), `core.agent.scorer|scorerSelector` (scorers), `core.agent.memory|memorySelector` (memory), `core.agent.embedding|vectorStore|retriever|rerank|chunking` (RAG), `core.agent.chain.basic|qa|summarization` (RAG chains), `core.agent.inputProcessor|outputProcessor|guardrail|structuredOutputParser|informationExtractor|langchainCode` (processors), `core.agent.hitl` (human-in-the-loop), `core.agent.voice` (voice), `core.agent.trigger.mcp|slack|discord|telegram|teams` (triggers), `core.agent.response.slack|discord|telegram|teams` (channel responses). Every `core.agent[.*]` kind requires the mastra engine — the general (local) engine fails closed with `GRAPH_LOCAL_UNSUPPORTED_NODE_KIND` |
290
311
  | Boundary | `graph-input-value-node` (`GraphNode<void, …>` — reusable value node whose single `value` output may feed multiple targets), `graph-output-value-node` (`GraphNode<…, void>` — terminal sink whose `value` input receives the workflow result; it has **no output port** — the engine captures workflow outputs from the `$workflow` boundary edges into it) |
291
312
 
292
- There are no `parallel` or `merge` node kinds: the graph itself parallelizes on multiple connections
313
+ Storage, DevOps, Comms, and credential-bearing IO kinds resolve their credentials at execution time through the engine's ctx-bound
314
+ `GraphNodeCredentialResolver` (`GraphExecutionEngine.nodeCredentials`), backed by the `@decaf-ts/integrations` credential and
315
+ secret services. A node's `credentialRef` parameter holds a `{ credentialId, credentialType }` reference; the resolver loads the
316
+ credential record, validates its type, enabled state and expiry, then retrieves the secret by `secretName` through the model-backed
317
+ or filesystem-backed secret service. A missing/unconfigured resolver fails closed with `GRAPH_CREDENTIAL_SERVICE_UNAVAILABLE` and an
318
+ unsupported provider with `GRAPH_CREDENTIAL_PROVIDER_UNSUPPORTED`; secrets are never stored in workflow documents. The
319
+ PostgreSQL, MySQL, and Microsoft SQL kinds require the matching TypeORM driver (`pg`, `mysql2`, `mssql`), all three declared as optional dependencies. The Comms, DevOps, and IO kinds delegate to the service classes in `@decaf-ts/integrations` where applicable (`comms/{slack,telegram,teams,gmail,email}`, `devops/{github,gitlab}`, `core.devops.ftp` via `@decaf-ts/integrations/sftp`, `io/{google-sheets,airtable,graphql}`); `core.devops.crypto` and `core.devops.jwt` use `@decaf-ts/crypto`, `core.devops.executeCommand` runs a local `child_process`, and `core.io.spreadsheetFile` is local parsing/writing with no network service.
320
+
321
+ There is no structural `parallel` node kind: the graph itself parallelizes on multiple connections
293
322
  to an output port (native fan-out) and syncs on multiple connections into an input port (native
294
- fan-in). Notable per-node properties:
323
+ fan-in). `core.data.merge` is a data-transform node for joining value arrays, not an execution
324
+ branch merge. Data nodes use array-in/array-out values (no n8n item model); `core.data.dataTable`
325
+ persists cross-run rows through the engine's data-table repository, and
326
+ `core.io.respondToWebhook` correlates responses by `runId`. Notable per-node properties:
295
327
 
296
328
  - `core.utility.code` — `timeoutMs` (node property forwarded to the code sandbox evaluator) and the
297
329
  `code` editor field (`@uielement("code-editor", …)`).
330
+ - `core.flow.executeSubWorkflow` — `workflowId` or an inline `workflow` document; child runs inherit
331
+ `parentRunId` and return the child `result`, `outputs`, and `childRunId`.
332
+ - `core.io.readPDF` — requires the `pdf-parse` dependency; returns extracted text plus per-page text.
333
+ - `core.data.dataTable` — operations `insert|upsert|get|list|delete|clear` over a named table.
298
334
  - `core.trigger.schedule` — `cron`, mapped to the for-angular Cron input
299
335
  (`@uielement("app-cron-selector-field", …)`), with timezone support.
300
336
  - `core.trigger.form` / `core.trigger.webhook` — `schema`, a `ModelBuilder`-produced model rendered
301
337
  with the for-angular model-builder webcomponent (`@uielement("ngx-decaf-model-builder", …)`); the
302
338
  resulting `payload` output is a plain data port.
339
+ - `core.agent` — the mastra agent node. Every mastra agent option is a first-class CRUD field
340
+ (`name`, `description`, `instructions`, `skillsFormat`, `maxRetries`, `structuredOutput`, and the
341
+ advanced `agentOptions` passthrough), the `prompt` input accepts placeholder expressions like
342
+ `{{ $input.brief }}`, and the LLM is carried as **config** via the `modelAdapter` parameter
343
+ (`provider`, `modelId`, optional `credentialRef` credential reference — resolved by document
344
+ validation stage 8 — plus optional `modelSettings`); there is no model-provider node kind, and the
345
+ bottom `model`/`workspace` connections stay for explicit wiring only. Its structural dependencies
346
+ are dedicated connection zones — `memory` bottom-left, `scorers` top-right, `embedding`
347
+ bottom-right, `hooks`/`sandbox` top-middle, `tools`/`skill` bottom-middle, and the processor
348
+ zones `inputProcessors`/`outputProcessors` — each accepting only
349
+ the matching family node's connection (same-category rule).
303
350
 
304
351
  `@uielement` labels and placeholders are locale keys, not hardcoded strings: the strings live in
305
352
  `assets/i18n/en.json`, shipped in the published package.
@@ -443,9 +490,19 @@ with `GRAPH_BACKEND_SEED_NOT_SUPPORTED` when the backend does not implement it.
443
490
  ##### Mastra backend (`@decaf-ts/as-graph/mastra`)
444
491
 
445
492
  `MastraGraphExecutionBackend` translates the canonical document into a Mastra
446
- workflow, runs it on the injected `@mastra/core` runtime (pinned `1.74.0`),
493
+ workflow, runs it on the injected `@mastra/core` runtime (peer dependency
494
+ `^1.77.0`; the capability manifest pins `MASTRA_PINNED_VERSION = "1.74.0"` as
495
+ the reviewed engine contract),
447
496
  bridges Mastra's `fullStream` onto the facade event sink, and enforces the
448
- schema-safe resume guard on every resume payload. It reports `codeMode:
497
+ schema-safe resume guard on every resume payload. The returned
498
+ `GraphExecutionResult.status` is derived from the run's terminal outcome, never
499
+ assumed from the bare fact that the run resolved: the event bridge records the
500
+ terminal `workflow-finish` status (`failed`/`tripwire` → `failed`,
501
+ `canceled`/`cancelled` → `cancelled`, `success`/`succeeded` → `succeeded`), with
502
+ the run result's/stream's raw status as fallback when the stream was not
503
+ observed — so a failed or guardrail-tripped run reports `failed` and a
504
+ cancelled run reports `cancelled` instead of a false `succeeded`. It reports
505
+ `codeMode:
449
506
  "unsupported"` (code-mode surfaces currently fail closed) and surfaces
450
507
  `workflowList`/`workflowLookup` over its compiled-workflow cache. Its full
451
508
  per-feature capability table (`MASTRA_FEATURE_CAPABILITIES`) declares, per
@@ -459,19 +516,583 @@ import { MastraGraphExecutionBackend } from "@decaf-ts/as-graph/mastra";
459
516
 
460
517
  const backend = new MastraGraphExecutionBackend(); // self-registers under the "mastra" flavour
461
518
  await backend.initialize({
462
- mastra, // the host's @mastra/core runtime instance
463
- agents, // optional agent map for agent/LLM nodes
464
- stepHandlers, // optional MastraNodeStepHandler[] for custom node kinds
465
- suspendStateReader, // optional, for suspend/resume runs
466
- maxResumeBytes, // optional resume payload byte cap
519
+ mastra, // the host's @mastra/core runtime instance
520
+ agents, // optional agent map for `core.agent` nodes, keyed by `<provider>/<modelId>`, model id, or node id
521
+ createAgent, // optional factory building an agent from a node's model-adapter config (fallback after `agents`)
522
+ agentRuntime, // optional pre-built agent runtime (takes precedence over both)
523
+ memories, createMemory, // optional memory wiring for `core.agent.memory` nodes
524
+ stepHandlers, // optional MastraNodeStepHandler[] for custom node kinds
525
+ resolveProcessorModel, // optional model resolver for input/output processors and guardrails
526
+ resolveStructuredOutputModel, // optional model resolver for structured-output parsing
527
+ createMcpServer, // optional MCP server factory — receives `(descriptor, guard)` where `guard` is the run-scoped C6 delivery guard; omitting the factory makes `core.agent.trigger.mcp` fail closed (`GRAPH_MASTRA_MCP_UNAVAILABLE`)
528
+ resolveChannelAdapter, sendChannelResponse, // optional channel wiring — omitting them makes `core.agent.trigger.*`/`response.*` fail closed (`GRAPH_MASTRA_CHANNEL_UNAVAILABLE`)
529
+ resolveVoice, // optional voice wiring — omitting it makes `core.agent.voice` fail closed (`GRAPH_MASTRA_VOICE_UNAVAILABLE`)
530
+ embedText, generateText, runSandboxedCode, // optional RAG/sandbox host ports — see "Real RAG & sandbox execution (SAA-747 Stage 2)" below
531
+ embedding, // optional backend-wide embedding config used when a RAG document carries none
532
+ vectorStoreBindings, vectorStoreDrivers, resolveVectorStore, // optional mastra-native vector-store wiring for the RAG steps (Stage 4 provider matrix)
533
+ memoryStorageBindings, memoryVectorStore, memoryEmbedder, // optional memory-matrix wiring — see "Stage 4 mastra breadth" below
534
+ persistence, // optional per-layer persistence surface (replays/cache/pins), overriding the `MASTRA__PERSISTENCE__*` env defaults
535
+ storage, // optional Mastra storage for the runtime — applied and verified back; see storage wiring below
536
+ suspendStateReader, // optional, for suspend/resume runs
537
+ maxResumeBytes, // optional resume payload byte cap
538
+ terminalTimeoutMs, // optional run-level terminal timeout
467
539
  });
468
540
  // pass `backend` via GraphExecutionEngineConfig.backend
469
541
  ```
470
542
 
543
+ **Explicit storage wiring (SAA-926 §6.2).** The optional `storage` config
544
+ member is applied to the wired `@mastra/core` runtime through its
545
+ `setStorage` surface and then verified back through `getStorage()`:
546
+ the wiring fails closed with `GRAPH_MASTRA_STORAGE_UNWIRED` when the runtime
547
+ is not a Mastra instance or exposes no `setStorage` surface (a silently
548
+ ignored declared storage would fall back to in-memory persistence), and with
549
+ `GRAPH_MASTRA_STORAGE_DOMAIN_INMEMORY` when the resolved workflows domain is
550
+ absent or silently in-memory — a composite storage that misses the workflows
551
+ domain loses suspend/resume snapshots on restart. The only accepted path to
552
+ an in-memory workflows domain is the host explicitly declaring an
553
+ `InMemoryStore`. `backend.storageStatus` exposes the resolved outcome
554
+ (`{ wired, explicitInMemory, domains: { workflows: "durable" | "in-memory" |
555
+ "absent" } }`; `undefined` when no storage config was declared): production
556
+ hosts must configure Mastra storage explicitly and durably, i.e.
557
+ `storageStatus.domains.workflows === "durable"`.
558
+
559
+ **Resume run recovery (SAA-926 §6.3).** `@mastra/core` 1.77.0 exposes no
560
+ public `getRun` on the `Mastra` class, so resume on a plain runtime used to
561
+ fail closed. The backend's run loading now falls back to
562
+ `recoverMastraRunHandle` — mastra's own restart-recovery pattern: resolve the
563
+ persisted run record from the configured storage's workflows domain
564
+ (`getWorkflowRunById`) to learn the workflow name, then rebind the run id
565
+ onto the live workflow via `createRun({ runId })`. Hosts can wrap their own
566
+ `getRun` with `createMastraGetRunWrapper(runtime)`, which delegates to a
567
+ runtime-provided `getRun` when present and otherwise recovers the handle the
568
+ same way.
569
+
570
+ `core.agent` executes as a real mastra agent step (no degraded echo): the backend builds the agent
571
+ step handler from an explicit `agentRuntime`, or from `createAgent`/`agents` (consulted in that
572
+ order), invokes the resolved agent with the node's `prompt` input, and projects the result onto the
573
+ node's `response`/`actions` outputs. When none of the three is configured the step fails closed with
574
+ `GRAPH_MASTRA_AGENT_UNAVAILABLE` instead of returning a fabricated result; the `core.agent.*` family
575
+ kinds resolve their configuration into resource descriptors through the default handler set,
576
+ overridden for the RAG and sandbox kinds by the real execution handlers below. Every mastra-only
577
+ step handler is composed through the `@decaf-ts/as-graph/mastra/nodes` registry
578
+ (`createMastraNodeStepHandlers`), which filters the host options to the mastra-only kinds and
579
+ proves zero missing implementations with `auditMastraNodeCoverage` / `assertMastraNodeCoverage`. The
580
+ general (local) engine never runs the mastra AI family: any `core.agent[.*]` node reaching it fails
581
+ closed with `GRAPH_LOCAL_UNSUPPORTED_NODE_KIND`.
582
+
471
583
  The flavour constant is `MASTRA_BACKEND_FLAVOUR` (`"mastra"`); unsupported node
472
584
  kinds and unsafe/invalid resume payloads fail loudly with
473
585
  `GRAPH_MASTRA_UNSUPPORTED_KIND` / `GRAPH_MASTRA_RESUME_*` errors.
474
586
 
587
+ **Single schema conversion path (as-zod).** Every decaf↔mastra schema
588
+ conversion goes through `@decaf-ts/as-zod` — `mastraSchemaFromModel` converts
589
+ a decaf Model constructor into the mastra Zod object schema, and
590
+ `mastraModelFromSchema` converts back. There is no second metadata walker;
591
+ both directions fail closed with `GRAPH_MASTRA_MODEL_SCHEMA_UNAVAILABLE` when
592
+ the conversion cannot produce a usable schema instead of handing the engine a
593
+ degraded schema (only a Zod object schema with a non-empty declared shape can
594
+ drive structured output).
595
+
596
+ **Structured output.** A graph document authors structured output as a plain,
597
+ JSON-safe definition on a node's `structuredOutput` parameter: a decaf model
598
+ **name** resolved through the host-supplied model registry
599
+ (`MastraDecafModelResolver` — the host owns the model catalogue; the backend
600
+ never invents one), or a host-carried, already-converted Zod schema (takes
601
+ precedence), plus optional `instructions`, `jsonPromptInjection`, and
602
+ `providerOptions` forwarded to mastra verbatim.
603
+ `mastraStructuredOutputOf` resolves it into mastra's `structuredOutput`
604
+ generate option; an unresolvable definition fails closed with
605
+ `GRAPH_MASTRA_STRUCTURED_OUTPUT_UNRESOLVED` rather than silently degrading to
606
+ unstructured output, and an absent definition leaves the agent unstructured
607
+ (mastra's default). The definition never carries a secret and never carries
608
+ raw JSON Schema — mastra consumes Zod. The model-builder UI (SAA-836 U1)
609
+ consumes this same contract.
610
+
611
+ ```typescript
612
+ import {
613
+ mastraSchemaFromModel,
614
+ mastraStructuredOutputOf,
615
+ } from "@decaf-ts/as-graph/mastra";
616
+
617
+ const zodSchema = mastraSchemaFromModel(MyDecafModel); // via @decaf-ts/as-zod
618
+ const structuredOutput = mastraStructuredOutputOf(node, (name) => models[name]);
619
+ // → { schema, instructions?, jsonPromptInjection?, providerOptions? } | undefined
620
+ ```
621
+
622
+ **Real RAG & sandbox execution (SAA-747 Stage 2).** The RAG/sandbox data-flow
623
+ family is no longer config-only in the mastra engine:
624
+ `createMastraRagStepHandlers` registers real steps **after** the host default
625
+ set for `core.agent.embedding`, `core.agent.vectorStore`,
626
+ `core.agent.retriever`, `core.agent.chain.basic|qa|summarization`,
627
+ `core.agent.structuredOutputParser`, `core.agent.informationExtractor`,
628
+ `core.agent.sandbox`, and `core.agent.langchainCode`
629
+ (`MASTRA_RAG_EXECUTION_KINDS` / `MASTRA_SANDBOX_EXECUTION_KINDS`). Insert
630
+ steps embed the input documents — the node's embedding config, falling back
631
+ to the backend-wide `embedding` config when the document carries none, run
632
+ through the host `embedText` port or mastra's `ModelRouterEmbeddingModel` by
633
+ default — create the index, and upsert into the mastra-native `MastraVector`
634
+ resolved through `MastraVectorStore` (a shared store cache, so the retriever
635
+ reads the same in-memory instance the insert wrote); retriever steps embed the
636
+ query and read the store wired on the `store` data edge, with a `queryVector`
637
+ bypass; chain/extractor steps generate through the host `generateText` port or
638
+ a mastra `Agent` built from the node's `modelAdapter` config and emit
639
+ `text`/`sourceDocuments`/`data`; the parser parses JSON on the real `text`
640
+ input. Vector-store wiring is mastra-native: `vectorStoreBindings` (the nine
641
+ mastra-native providers), custom `vectorStoreDrivers` (`age`, `graph`), and an
642
+ optional `resolveVectorStore` override — see the
643
+ [Stage 4 mastra breadth](#stage-4-mastra-breadth-saa-749-vector-store-matrix-memory-matrix-processor-variants)
644
+ section for the full provider/credential matrix and the RAG walkthrough. Every step selects real execution only
645
+ when the document wires the work the kind needs (documents, query, model
646
+ config, or code); otherwise it emits the same JSON-safe descriptor fallback
647
+ (R9) the default set emits, so a config-only node never makes a model or
648
+ database call by accident. Missing embedding config, an invalid vector batch,
649
+ or a failed generation fails closed with
650
+ `GRAPH_MASTRA_EMBEDDING_UNAVAILABLE` / `GRAPH_MASTRA_RAG_UNAVAILABLE` — no
651
+ vector, answer, or extraction is ever fabricated. The `core.agent.sandbox`
652
+ node stays config-only when no host `runSandboxedCode` runner is wired, while
653
+ `core.agent.langchainCode` carrying code without a runner fails closed with
654
+ `GRAPH_MASTRA_SANDBOX_UNAVAILABLE` — never executing code outside a sandbox —
655
+ and both reuse `GRAPH_CODE_SANDBOX_TIMEOUT` (exported as
656
+ `GRAPH_MASTRA_SANDBOX_TIMEOUT`) when the runner exceeds the ceiling-clamped
657
+ `timeoutMs`.
658
+
659
+ ```typescript
660
+ import { createMastraRagStepHandlers } from "@decaf-ts/as-graph/mastra";
661
+
662
+ // The backend registers these handlers automatically; hosts pass the backend
663
+ // config members above to override the mastra-native defaults
664
+ // (ModelRouterEmbeddingModel embeddings / Agent.generate text).
665
+ const ragHandlers = createMastraRagStepHandlers({
666
+ vectorStoreBindings: myVectorStoreBindings, // all nine mastra-native providers (Stage 4)
667
+ embedText: async ({ values, config }) => myEmbedder(values, config),
668
+ generateText: async ({ prompt, instructions }) => ({
669
+ text: await myLlm(prompt, instructions),
670
+ }),
671
+ runSandboxedCode: async ({ code, timeoutMs }) =>
672
+ mySandbox.run(code, timeoutMs),
673
+ });
674
+ ```
675
+
676
+ ##### Stage 4 mastra breadth (SAA-749): vector-store matrix, memory matrix, processor variants
677
+
678
+ Stage 4 completes the mastra AI breadth behind the same patterns as the
679
+ earlier stages: every provider is selected by node **config**, every backend
680
+ package stays host-bound (as-graph never imports an optional backend package),
681
+ every missing binding/driver/model fails closed instead of fabricating a
682
+ resource, and only JSON-safe, secret-free descriptors (R9) are ever persisted.
683
+
684
+ ###### Vector-store matrix (`core.agent.vectorStore`)
685
+
686
+ The vector-store node's `vectorStore` parameter carries a
687
+ `MastraVectorStoreConfig`; `resolveMastraVectorStore` turns it into a live
688
+ mastra `MastraVector` at execution time. Providers, in palette order:
689
+
690
+ | Provider | Backing | Host wiring |
691
+ | --- | --- | --- |
692
+ | `memory` | built-in `InMemoryVectorStore` (dependency-free, offline-capable) | none |
693
+ | `pgvector`, `redis`, `upstash`, `qdrant`, `pinecone`, `supabase`, `mongodb`, `libsql`, `chroma` | mastra-native `MastraVector` constructors (e.g. `@mastra/pg`'s `PGVector`, `@mastra/libsql`'s `LibSQLVector`) | `vectorStoreBindings`, keyed by provider |
694
+ | `age`, `graph` | custom `MastraVector` stores (`DriverBackedVectorStore`) over a host `MastraVectorDriver` | `vectorStoreDrivers`, keyed by provider |
695
+
696
+ Config members:
697
+
698
+ | Member | Meaning |
699
+ | --- | --- |
700
+ | `provider` | One of the twelve providers above; anything else fails with `GRAPH_MASTRA_VECTOR_PROVIDER_UNKNOWN`. |
701
+ | `id` | Optional store id; defaults to `indexName`, then `provider`. |
702
+ | `indexName` / `dimension` / `metric` | The index to create; `metric` is `cosine` (default), `euclidean`, or `dotproduct`. |
703
+ | `embedding` | The embedding adapter carried **in config** (R1): `provider`, `modelId`, optional `credentialRef`, `dimension`, `batchSize`. There is no embedding-provider node kind. |
704
+ | `connection` | Provider connection options. **Never carries credential material** — plaintext credential members (e.g. `password`, `connectionString`) are refused outright — never stripped — with `GRAPH_MASTRA_PLAIN_CREDENTIAL_REFUSED`. |
705
+ | `credentialKey` | The `connection` member the resolved credential populates; defaults to the provider's native option name (table below). Only used with `credentialRef`. |
706
+ | `credentialRef` | `{ credentialId, credentialType }` naming the environment variable (a `MASTRA_*` name is required) in the git-ignored `.env.secret` that carries the credential. Required for `pgvector` (PostgreSQL authenticates every connection); optional elsewhere — a passwordless local `redis` stays usable. |
707
+
708
+ Default credential-injection members (the `credentialKey` when unset):
709
+
710
+ | Provider | Default `credentialKey` |
711
+ | --- | --- |
712
+ | `pgvector`, `redis`, `mongodb` | `password` |
713
+ | `upstash` | `token` |
714
+ | `qdrant`, `pinecone`, `chroma` | `apiKey` |
715
+ | `supabase` | `serviceRoleKey` |
716
+ | `libsql` | `authToken` |
717
+
718
+ Fail-closed behaviour (C6): an unbound mastra-native provider fails with
719
+ `GRAPH_MASTRA_VECTOR_UNAVAILABLE` (the message names the exact binding to
720
+ supply, e.g. `@mastra/qdrant QdrantVector`), an unknown provider with
721
+ `GRAPH_MASTRA_VECTOR_PROVIDER_UNKNOWN`, and an absent or unresolvable
722
+ credential with `GRAPH_MASTRA_CREDENTIALS_UNAVAILABLE`. A resolved store emits
723
+ the JSON-safe descriptor `{ type: "mastra.vectorStore", provider, id, … }`
724
+ (R9) — the live `MastraVector` is never persisted, only the descriptor is.
725
+
726
+ ###### The AGE custom driver (`MastraAgeVectorDriver`)
727
+
728
+ Apache AGE has no stock mastra binding, so the `age` provider resolves through
729
+ a host driver. `createMastraAgeVectorDriver({ client, graphName?, tablePrefix? })`
730
+ is the reference driver exported from `@decaf-ts/as-graph/mastra`:
731
+
732
+ - `client` is a `MastraVectorSqlClient` (`query(sql, params)`) — the host owns
733
+ the Postgres connection (typically `pg`'s `Pool`/`Client`) and its
734
+ credentials; as-graph never imports a Postgres client package.
735
+ - On first use the driver idempotently verifies the `age` extension, creates
736
+ the graph (`ag_catalog.create_graph`, default `as_graph_age_vectors`) when
737
+ absent, and creates the `<prefix>_indexes`/`<prefix>_vectors` tables inside
738
+ the graph schema; a missing extension or a failed setup fails closed with
739
+ `GRAPH_MASTRA_VECTOR_UNAVAILABLE` — never a silent fallback to another
740
+ backend.
741
+ - Vectors are stored as `double precision[]` and metadata as `jsonb`; the
742
+ cosine/euclidean/dotproduct scores are computed in-process, so the driver
743
+ works on any AGE-enabled PostgreSQL without the `pgvector` extension. Every
744
+ value is bound as a query parameter, and `graphName`/`tablePrefix` must be
745
+ plain SQL identifiers.
746
+ - The `graph` provider is the same custom-store pattern with a host-injected
747
+ driver: implement `MastraVectorDriver` over your own store and pass it as
748
+ `vectorStoreDrivers.graph`.
749
+
750
+ ###### Memory matrix (`core.agent.memory`)
751
+
752
+ The memory node resolves a `MastraMemoryConfig` into mastra's own `Memory`
753
+ (`@mastra/memory`) over a config-selected storage backend:
754
+
755
+ | Provider | Backing | Host wiring |
756
+ | --- | --- | --- |
757
+ | `memory` | mastra's `InMemoryStore` baseline | none |
758
+ | `libsql`, `pg` | mastra-native `LibSQLStore` / `PostgresStore` | none (statically imported peer packages) |
759
+ | `mongodb`, `upstash`, `cloud`, `d1`, `dynamodb`, `convex`, `astra`, `redis` | mastra-native storage stores (`MongoStore`, `UpstashStore`, …) | `memoryStorageBindings`, keyed by provider |
760
+
761
+ Config members: `id`, `threadId`, `resourceId`, `lastMessages`,
762
+ `semanticRecall`, `workingMemoryTemplate` (enables mastra working memory with
763
+ that template), `generateTitle`, and the advanced `memoryOptions` passthrough
764
+ (named fields override the same key), plus the same credential gate as vector
765
+ stores (`connection` never carries plaintext credentials; `credentialRef`
766
+ names a `MASTRA_*` environment variable; `credentialKey` overrides the
767
+ injection member). Provider-specific requirements, both fail-closed with
768
+ `GRAPH_MASTRA_MEMORY_UNAVAILABLE`: `pg` needs a complete non-secret host
769
+ config (`host`, `port`, `database`, `user`) **plus** its `credentialRef` (a
770
+ `connectionString` is not an accepted alternative), and `libsql` needs a
771
+ `connection.url` (e.g. `file:./agent-memory.db`). An unknown provider fails
772
+ with `GRAPH_MASTRA_MEMORY_PROVIDER_UNKNOWN`.
773
+
774
+ **Semantic-recall host seam.** A `semanticRecall` memory needs a live mastra
775
+ vector store, which the host supplies through the backend config's
776
+ `memoryVectorStore` (and `memoryEmbedder` when the store does not generate
777
+ embeddings itself — mastra's `isSelfEmbedding`). A semantic-recall memory
778
+ without the vector seam fails closed with
779
+ `GRAPH_MASTRA_MEMORY_VECTOR_REQUIRED`; a non-self-embedding store without an
780
+ embedder fails with `GRAPH_MASTRA_MEMORY_EMBEDDER_REQUIRED`. Memory nodes wire
781
+ to agents through the agent node's `memory` zone; the invocation binds to the
782
+ first wired config's `threadId` (fail-closed when no wired memory declares a
783
+ thread). Memory nodes may also carry `memoryId`, which maps onto the config
784
+ `id` so descriptors and host memory maps resolve by the configured id.
785
+
786
+ ###### Processor / guardrail variants
787
+
788
+ Processor and guardrail nodes wire onto the agent node's
789
+ `inputProcessors`/`outputProcessors` zones and resolve to real
790
+ `@mastra/core/processors` instances; guardrails compose with the
791
+ output-processor pipeline, and resolution follows document edge order, so the
792
+ pipeline order is deterministic:
793
+
794
+ | Zone | `processorType` / `guardrailType` values |
795
+ | --- | --- |
796
+ | Input | `unicodeNormalizer`, `languageDetector`*, `piiDetector`*, `promptInjectionDetector`*, `systemPromptScrubber`*, `tokenCostControl`, `modelSelection` |
797
+ | Output | `tokenLimiter`, `toolCallFilter`, `regexFilter`, `responseCache`, `batchParts`, `providerHistoryCompat`, `cyberRefusalHandler`, `prefillErrorHandler`, `streamErrorRetry`, `unsupportedFileHandler` |
798
+ | Guardrail | `moderation`*, `piiDetector`*, `promptInjectionDetector`*, `regexFilter` |
799
+
800
+ \* Model-carrying variants take their classifier as `modelAdapter` config
801
+ (R1): the host `resolveProcessorModel` hook resolves it to a live model,
802
+ otherwise the composed `<provider>/<modelId>` id is used; without either, the
803
+ node fails closed with `GRAPH_MASTRA_PROCESSOR_UNAVAILABLE`.
804
+
805
+ JSON-config-only constraints (the node vocabulary carries no live objects):
806
+
807
+ - `tokenCostControl` requires a positive numeric `options.maxCost`.
808
+ - `modelSelection` requires at least two `choices`, each with non-empty
809
+ `criteria` and a valid `modelAdapter`; its classifier **decision model**
810
+ must come from the host `resolveProcessorModel` hook (mastra validates the
811
+ classifier structurally — a language-model id cannot serve as one),
812
+ otherwise the node fails closed with `GRAPH_MASTRA_PROCESSOR_UNAVAILABLE`.
813
+ - `regexFilter` rule `pattern`s may be given as strings (documents are JSON)
814
+ and are compiled into `RegExp`s with the optional rule `flags`; a pattern
815
+ that is neither a `RegExp` nor a compiling string fails closed.
816
+ - `providerHistoryCompat` refuses `additionalRules` and all options
817
+ (compatibility rules contain functions/regexes that are not
818
+ JSON-serializable; the built-in mastra rules stay active);
819
+ `cyberRefusalHandler`, `prefillErrorHandler`, and `unsupportedFileHandler`
820
+ take no options at all; `streamErrorRetry` refuses `matchers` (predicates
821
+ are not JSON-serializable — only its numeric/boolean retry knobs are
822
+ supported).
823
+
824
+ ###### Node descriptors and capability rows
825
+
826
+ - `core.agent.vectorStore` gains the `embedding` (object) and `credentialKey`
827
+ (text) CRUD fields alongside its existing provider/index fields.
828
+ - `core.agent.memory` gains the `credentialKey` field, its `provider` select
829
+ lists the full storage matrix, and an unknown provider now fails closed
830
+ with `GRAPH_MASTRA_MEMORY_PROVIDER_UNKNOWN` instead of silently defaulting
831
+ to `memory`.
832
+ - The Mastra capability table (`MASTRA_FEATURE_CAPABILITIES`) gained the
833
+ `memoryStorage` and `processorVariants` rows (both `SUPPORTED`), and the
834
+ `vectorStores` row now names all twelve providers.
835
+
836
+ ###### Walkthrough: a RAG graph against PGVector / Redis / AGE / Graph via config
837
+
838
+ The acceptance criterion is "a RAG graph runs against PGVector, Redis, AGE and
839
+ Graph stores via config-selected bindings". Everything below is config — the
840
+ same document shape works for every provider; only the store wiring changes.
841
+
842
+ 1. **Stand up the backend fixture** (the live-test Docker precedent):
843
+
844
+ ```bash
845
+ # PGVector (pgvector extension image; publishes :5432 on the Docker host)
846
+ docker run -d --name asgraph-pgvector -p 55441:5432 \
847
+ -e POSTGRES_PASSWORD=postgres pgvector/pgvector:pg17
848
+ # Apache AGE (AGE extension image; publishes :5432 on the Docker host)
849
+ docker run -d --name asgraph-age -p 55442:5432 \
850
+ -e POSTGRES_PASSWORD=postgres apache/age:release_PG17_1.7.0
851
+ # From a containerized host the endpoints are the Docker bridge gateway
852
+ # (172.17.0.1); from a normal host they are 127.0.0.1.
853
+ ```
854
+
855
+ 2. **Reference credentials by name**, never in the document — put the value
856
+ in the git-ignored `.env.secret`:
857
+
858
+ ```bash
859
+ MASTRA_PGVECTOR_PASSWORD=postgres # or your own MASTRA_* variable name
860
+ ```
861
+
862
+ 3. **Author the vector-store config** on a `core.agent.vectorStore` node
863
+ (the same config the retriever/chain steps consume through the store's
864
+ `resource` port):
865
+
866
+ ```jsonc
867
+ {
868
+ "provider": "pgvector",
869
+ "indexName": "docs",
870
+ "dimension": 1536,
871
+ "metric": "cosine",
872
+ "embedding": { "provider": "openai", "modelId": "text-embedding-3-small" },
873
+ "connection": { "host": "172.17.0.1", "port": 55441, "database": "test", "user": "postgres", "schemaName": "public" },
874
+ "credentialRef": { "credentialId": "MASTRA_PGVECTOR_PASSWORD", "credentialType": "password" }
875
+ }
876
+ ```
877
+
878
+ Switching to `redis`, `age`, or `graph` changes `provider` and
879
+ `connection` only; `age` needs no `pgvector` extension — only the AGE
880
+ extension and its graph (see the driver section above).
881
+
882
+ 4. **Wire the host bindings** once at backend initialization:
883
+
884
+ ```typescript
885
+ import { PgVector } from "@mastra/pg"; // the host installs backend packages
886
+ import { createMastraAgeVectorDriver } from "@decaf-ts/as-graph/mastra";
887
+
888
+ await backend.initialize({
889
+ // …mastra runtime, agents, RAG ports (see "Real RAG & sandbox execution")…
890
+ vectorStoreBindings: {
891
+ pgvector: PgVector,
892
+ // redis/upstash/qdrant/pinecone/supabase/mongodb/libsql/chroma likewise
893
+ },
894
+ vectorStoreDrivers: {
895
+ age: createMastraAgeVectorDriver({ client: myPgPool }),
896
+ graph: myGraphVectorDriver,
897
+ },
898
+ // memory matrix: non-built-in storage + the semantic-recall seam
899
+ memoryStorageBindings: { mongodb: MongoStore /* … */ },
900
+ memoryVectorStore: myMastraVector, // required by semanticRecall memories
901
+ memoryEmbedder: myEmbeddingModel, // when the vector store doesn't embed itself
902
+ });
903
+ ```
904
+
905
+ 5. **Run the live driver tests** (the suites skip honestly when the
906
+ endpoints are unset):
907
+
908
+ ```bash
909
+ GRAPH_IT_PGVECTOR_HOST=172.17.0.1 GRAPH_IT_AGE_HOST=172.17.0.1 \
910
+ npm run test:integration:mastra
911
+ ```
912
+
913
+ The resolution flow these steps exercise:
914
+
915
+ ```mermaid
916
+ sequenceDiagram
917
+ autonumber
918
+ participant Doc as Graph document
919
+ participant Res as resolveMastraVectorStore
920
+ participant Bind as Host bindings
921
+ participant Store as Live MastraVector
922
+
923
+ activate Doc
924
+ Doc->>Res: vectorStore config (provider, embedding, credentialRef)
925
+ activate Res
926
+ Res->>Bind: binding/driver lookup
927
+ activate Bind
928
+ Bind-->>Res: constructor | driver | undefined
929
+ deactivate Bind
930
+ alt binding or driver missing
931
+ Res-->>Doc: fail-closed GraphExecutionError
932
+ else resolved
933
+ Res->>Store: construct (connection, resolved credential)
934
+ activate Store
935
+ Store-->>Res: live store
936
+ deactivate Store
937
+ Res-->>Doc: store + secret-free descriptor (R9)
938
+ end
939
+ deactivate Res
940
+ deactivate Doc
941
+ ```
942
+
943
+ ##### Mastra compatibility surface (SAA-836)
944
+
945
+ Beyond the backend itself, the `@decaf-ts/as-graph/mastra` entrypoint exports
946
+ the full compatibility surface built across the SAA-836 slices:
947
+
948
+ - **Authoring builders** — `MastraAgentBuilder` (fluent facade over
949
+ `GraphWorkflowDocumentBuilder` producing valid `core.agent` documents, wiring
950
+ the agent zones: `tools`, `memory`, `skill`, `scorers`, `hooks`, `sandbox`,
951
+ `embedding`, `inputProcessors`, `outputProcessors`) and `MastraToolBuilder`
952
+ (the same contract for `core.agent.tool` documents), plus
953
+ `MastraToolConfig`/`MastraToolDecorator` for tool authoring.
954
+ - **Memory and vector layers** — `MastraMemory` (mastra memory wiring over
955
+ `@mastra/memory`, including the `memorySelector` decision sub-flow; the
956
+ Stage 4 storage matrix resolves every mastra-native backend, with the host
957
+ `memoryVectorStore`/`memoryEmbedder` seam for semantic recall) and
958
+ `MastraVectorStore` (the Stage 4 twelve-provider matrix: the built-in
959
+ `InMemoryVectorStore` baseline, host-bound mastra-native constructors, and
960
+ `DriverBackedVectorStore`/`MastraAgeVectorDriver` for the custom
961
+ `age`/`graph` stores — see the
962
+ [Stage 4 mastra breadth](#stage-4-mastra-breadth-saa-749-vector-store-matrix-memory-matrix-processor-variants)
963
+ section). Backend configs never carry
964
+ credential values (SAA-911 F4, gate C): plaintext credential members in a
965
+ config's `connection` options are refused outright — never stripped — with
966
+ `GRAPH_MASTRA_PLAIN_CREDENTIAL_REFUSED`, and `pg`/`pgvector` (and a
967
+ credentialed `redis`) resolve their password only through a `credentialRef`
968
+ whose `credentialId` names the `.env.secret` variable carrying it (see the
969
+ Mastra engine environment section below); the value is resolved from the
970
+ host environment only at backend-construction time.
971
+ - **Real RAG/sandbox execution (SAA-747 Stage 2)** — `MastraRagStepHandlers`
972
+ (`createMastraRagStepHandlers`, the `MASTRA_RAG_EXECUTION_KINDS` /
973
+ `MASTRA_SANDBOX_EXECUTION_KINDS` kind tables, the host
974
+ `MastraRagEmbedder`/`MastraRagTextGenerator`/`MastraSandboxRunner` ports,
975
+ and `mastraEmbeddingConfigOf`) — see "Real RAG & sandbox execution
976
+ (SAA-747 Stage 2)" above for the execution contract and the fail-closed
977
+ `GRAPH_MASTRA_RAG_UNAVAILABLE` / `GRAPH_MASTRA_EMBEDDING_UNAVAILABLE` /
978
+ `GRAPH_MASTRA_SANDBOX_UNAVAILABLE` / `GRAPH_CODE_SANDBOX_TIMEOUT` codes.
979
+ - **Processors** — `MastraAgentProcessors` (input/output processor and
980
+ guardrail wiring, with the host-supplied `resolveProcessorModel` model hook;
981
+ the Stage 4 variant vocabularies add `tokenCostControl`/`modelSelection` on
982
+ input and the JSON-config-safe output variants — see the
983
+ [Stage 4 mastra breadth](#stage-4-mastra-breadth-saa-749-vector-store-matrix-memory-matrix-processor-variants)
984
+ section for the per-variant constraints).
985
+ - **Human-in-the-loop and voice** — `MastraHitlStepHandler` (the
986
+ `core.agent.hitl` suspend/resume handler) and `MastraVoiceStepHandler`
987
+ (`core.agent.voice`, failing closed with `GRAPH_MASTRA_VOICE_UNAVAILABLE`
988
+ when no voice wiring is supplied).
989
+ - **Triggers and channel responses** — `MastraMcpTrigger` (MCP server trigger,
990
+ fail-closed `GRAPH_MASTRA_MCP_UNAVAILABLE`, with the run-scoped
991
+ `MastraMcpDeliveryGuard` (C6, SAA-747 Stage 2) handed to
992
+ `createMcpServer(descriptor, guard)`: timing-safe token or HMAC-SHA256
993
+ delivery auth (`MastraMcpAuthMode`, read by `mastraMcpAuthConfigOf` from the
994
+ node's `authMode`/`authCredentialRef` fields — the credential reference
995
+ names a `MASTRA_*` environment variable and never carries the secret; when
996
+ the node names no credential the run generates a scoped secret the host
997
+ publishes to its clients), a concurrent pending-delivery cap (`pendingCap`,
998
+ default 256) with age pruning (`pendingTimeoutMs`, default 60000) — excess
999
+ refusals fail closed with `GRAPH_MASTRA_MCP_UNAVAILABLE` — and an exposed
1000
+ run-scoped server id that is never the document-carried `serverId`),
1001
+ `MastraScheduleTrigger`,
1002
+ `MastraChannelTrigger`/`MastraChannelResponse` (Slack/Discord/Telegram/Teams,
1003
+ fail-closed `GRAPH_MASTRA_CHANNEL_UNAVAILABLE` without channel wiring). A
1004
+ channel response delivers to the node's **configured** conversation
1005
+ binding; a wired `threadId` may never override it — a mismatch fails
1006
+ closed with `GRAPH_MASTRA_CHANNEL_THREAD_MISMATCH` (SAA-911 F5).
1007
+ - **Run metrics (S2)** — the read-only metrics layer:
1008
+ `MastraMetricsModels` (run/score/trace rows), `MastraMetricsAdapter`
1009
+ (read-only adapter over the mastra storage), `MastraMetricsStatement` +
1010
+ paginator, `MastraMetricsGateway` (owner-scoped serving), and
1011
+ `MastraRunMetricsEndpoint` (the editor-endpoint delegation behind
1012
+ `GET /graph/workflows/:workflowId/runs`).
1013
+ - **Eval models (O1)** — `MastraEvalModels` (read-only experiments/results
1014
+ models for eval pipelines).
1015
+ - **Observability and persistence** — `MastraObservability` (langfuse exporter
1016
+ wiring; enabled by default and fail-closed without credentials) and
1017
+ `MastraPersistence` (per-layer replay/cache/pin repositories with the
1018
+ `MASTRA__PERSISTENCE__*` adapter routing). Replay snapshots are **versioned
1019
+ and restorable** (row id `${runId}::v${version}`), backing mastra's own
1020
+ time-travel replay; a recording failure never fails a run, while restoring
1021
+ a missing snapshot fails closed. Workflows persist through the as-graph
1022
+ adapter only, versioned with restore.
1023
+ - **Nest wiring** — `MastraGraphExecutionModule` (the mastra `forRoot` module
1024
+ variant of `GraphExecutionModule`).
1025
+
1026
+ The agent-family node kinds themselves (memory, RAG, processors, HITL, voice,
1027
+ triggers, channel responses) are declared under
1028
+ `src/node/agents/**` and registered from their `@node` metadata — see the
1029
+ Agent row of the built-in node-kind table above.
1030
+
1031
+ ##### Mastra engine environment (`.env` / `.env.secret`)
1032
+
1033
+ The mastra engine reads its configuration from the accumulated
1034
+ `@decaf-ts/logging` environment (`MastraEnvironment`), overridable through
1035
+ `MASTRA__*` keys:
1036
+
1037
+ | Key | Default | Purpose |
1038
+ |:----|:--------|:--------|
1039
+ | `MASTRA__ENGINE__ENABLED` | `true` | Enables the mastra engine lane; `false` makes `MastraGraphExecutionBackend.initialize()` fail closed with `GRAPH_MASTRA_ENGINE_DISABLED`. |
1040
+ | `MASTRA__ENGINE__TERMINAL_TIMEOUT_MS` | `300000` | Default run-level terminal timeout for mastra runs (used when the backend config sets no positive `terminalTimeoutMs`). |
1041
+ | `MASTRA__PROVIDER__ENDPOINT` | `""` | Reserved provider config (declared in `MastraEnvironment`; not yet consumed — agents take their model from the node's `modelAdapter` parameter). |
1042
+ | `MASTRA__PROVIDER__MODEL` | `""` | Reserved provider config (declared in `MastraEnvironment`; not yet consumed — agents take their model from the node's `modelAdapter` parameter). |
1043
+ | `MASTRA__CREDENTIALS__API_KEY_ENV` | `MASTRA_PROVIDER_API_KEY` | The **name** of the environment variable that carries the provider credential. |
1044
+ | `MASTRA__OBSERVABILITY__ENABLED` | `true` | Enables the langfuse observability lane; it **fails closed** when enabled and the langfuse credentials are missing, so a mastra boot without `.env.secret` langfuse keys requires `false`. |
1045
+ | `MASTRA__OBSERVABILITY__SERVICE_NAME` | `as-graph-mastra` | Service name attached to observability exports. |
1046
+ | `MASTRA__OBSERVABILITY__ENVIRONMENT` | `""` | Environment label attached to observability exports. |
1047
+ | `MASTRA__OBSERVABILITY__LANGFUSE__ENDPOINT` | `https://cloud.langfuse.com` | Langfuse web/API base URL traces are exported to. |
1048
+ | `MASTRA__OBSERVABILITY__LANGFUSE__PUBLIC_KEY_ENV` / `MASTRA__OBSERVABILITY__LANGFUSE__SECRET_KEY_ENV` | `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` | The **names** of the environment variables carrying the langfuse keys (values live in `.env.secret` and are read only at exporter construction). |
1049
+ | `MASTRA__PERSISTENCE__REPLAYS__ADAPTER` | `fs` | Storage adapter for the replay-snapshot layer (`ram` \| `fs` \| `host`). |
1050
+ | `MASTRA__PERSISTENCE__CACHE__ADAPTER` | `ram` | Storage adapter for the compiled-workflow cache layer. |
1051
+ | `MASTRA__PERSISTENCE__PINS__ADAPTER` | `fs` | Storage adapter for the pinned-values layer. |
1052
+ | `MASTRA__PERSISTENCE__FS__ROOT` | `var/as-graph-mastra` | Base directory for the filesystem adapter's persisted data (a per-adapter-alias sub-directory is created automatically). |
1053
+
1054
+ Host-operator workflow (gate C):
1055
+
1056
+ - **Non-secret config goes in `.env`** — the engine flags and observability /
1057
+ persistence routing. (The `MASTRA__PROVIDER__ENDPOINT` / `MASTRA__PROVIDER__MODEL`
1058
+ keys are declared but reserved — agents take their model from the node's
1059
+ `modelAdapter` parameter.) `.env` is git-ignored and must never be committed.
1060
+ - **The credential value goes in `.env.secret`** — copy the tracked
1061
+ `.env.secret.template` (placeholders only) to `.env.secret`, fill in
1062
+ `MASTRA_PROVIDER_API_KEY` (or point `MASTRA__CREDENTIALS__API_KEY_ENV` at
1063
+ another variable name), and never commit it; `.env.secret` is git-ignored.
1064
+ - **Backend connection credentials are name-referenced too (SAA-911 F4,
1065
+ gate C)** — a `pg` memory provider, a `pgvector` vector store, or a
1066
+ credentialed `redis` vector store declares a `credentialRef` whose
1067
+ `credentialId` NAMES the environment variable carrying the password
1068
+ (placeholders `MASTRA_PG_PASSWORD` / `MASTRA_PGVECTOR_PASSWORD` /
1069
+ `MASTRA_REDIS_PASSWORD` in `.env.secret.template`); the value is resolved
1070
+ from the host environment only at backend-construction time. Plaintext
1071
+ credential members in a config's `connection` options (e.g. `password`,
1072
+ `connectionString`) are refused outright — never stripped — with
1073
+ `GRAPH_MASTRA_PLAIN_CREDENTIAL_REFUSED`. The `pg` memory provider requires
1074
+ a complete non-secret host config (`host`, `port`, `database`, `user`)
1075
+ plus its `credentialRef` — a `connectionString` is no longer an accepted
1076
+ alternative.
1077
+ - **Secrets are referenced by name only.** The graph layer reads the
1078
+ credential by environment-variable name and asserts only its presence —
1079
+ `assertMastraProviderCredentials()` throws
1080
+ `GRAPH_MASTRA_CREDENTIALS_UNAVAILABLE` when the referenced variable is
1081
+ unset or empty (no unauthenticated model traffic is ever attempted), and
1082
+ `hasMastraProviderCredentials()` reports availability without throwing. A
1083
+ secret value is never read into, held by, or persisted in the graph layer.
1084
+
1085
+ ```typescript
1086
+ import {
1087
+ assertMastraProviderCredentials,
1088
+ MastraEnvironment,
1089
+ } from "@decaf-ts/as-graph/mastra";
1090
+
1091
+ MastraEnvironment.mastra.engine.enabled; // MASTRA__ENGINE__ENABLED
1092
+ MastraEnvironment.mastra.provider.endpoint; // MASTRA__PROVIDER__ENDPOINT
1093
+ assertMastraProviderCredentials(); // fails closed without a resolvable credential
1094
+ ```
1095
+
475
1096
  ##### Dagster backend (`@decaf-ts/as-graph/dagster`)
476
1097
 
477
1098
  `DagsterGraphExecutionBackend` translates the canonical document into Dagster
@@ -518,7 +1139,7 @@ Run lifecycle and cached/pinned-value persistence always flows through Decaf rep
518
1139
  | `GraphValueModel` / `GraphValueRepository` | Cached/pinned graph values (must survive restarts for pinning), persisted as `graph_value` rows; per-execution runtime values are not persisted |
519
1140
  | `GraphNodeRepository` | Node-kind catalogue rows (one row per registered kind, persisted as `graph_node`); the `GraphNodeModel` row class lives in `./shared` so backend stores and UI listing/forms share it |
520
1141
  | `RamGraphRunStore` / `RamGraphRunEventStore` | Adapter-backed `GraphRunStore`/`GraphRunEventStore` implementations; construct with an initialized adapter |
521
- | `createRamGraphAdapter(alias?)` | Creates and initializes a `RamAdapter` (tests); production passes a durable adapter (e.g. TypeORM) |
1142
+ | `createRamGraphAdapter(alias?)` | Creates and initializes a `RamAdapter` (tests); production passes a durable adapter — see [Durable Postgres lane](#durable-postgres-lane-decaf-tsas-graphtypeorm) |
522
1143
  | `createGraphValueRepository(adapter)` | Factory for a fresh `GraphValueRepository` instance over the provided adapter |
523
1144
 
524
1145
  ```typescript
@@ -534,6 +1155,50 @@ and must not be used as production persistence. In a NestJS host,
534
1155
  `GraphExecutionModule.forRoot({ valueAdapter, runAdapter })` wires these adapter-backed stores
535
1156
  automatically (see [NestJS](#nestjs)).
536
1157
 
1158
+ #### Durable Postgres lane (`@decaf-ts/as-graph/typeorm`)
1159
+
1160
+ The stores never create an adapter implicitly: development boots persist through the built-in
1161
+ `RamAdapter` (`./ram`), while production hosts must supply a durable adapter for the five as-graph
1162
+ decaf tables (`graph_workflow`, `graph_run`, `graph_run_event`, `graph_node`, `graph_value`) plus the
1163
+ mastra-layer decaf models. The `./typeorm` export is the durable production path (SAA-926 §6.4):
1164
+ `createTypeormGraphAdapter({ dataSource })` builds and initializes a `@decaf-ts/for-typeorm` Postgres
1165
+ adapter and registers it as the current decaf adapter, so the engine's repositories resolve the
1166
+ flavoured entities.
1167
+
1168
+ The factory enforces the production contract on the host config (fail-closed):
1169
+
1170
+ - `type: "postgres"` only — the durable as-graph production path is Postgres.
1171
+ - `synchronize: false` only — the `asgraph` schema is owned by the stack's bootstrap migrations
1172
+ (executed by the `db-migrate` one-shot service as the `mastra_migrator` role); the least-privilege
1173
+ `mastra_app` runtime role must never mutate it, and the factory force-sets the flag regardless.
1174
+ - Credentials are resolved by the host from its environment or Docker secrets — never hard-coded.
1175
+ - The as-graph decaf models are flavoured for TypeORM explicitly, their model modules are imported
1176
+ lazily (importing `./typeorm` never flips a development RAM boot sharing the process), structured
1177
+ Object/Array decaf columns are pinned to `jsonb` so the runtime shape matches the bootstrap DDL 1:1,
1178
+ and the model class is canonicalized before TypeORM entity resolution.
1179
+
1180
+ ```typescript
1181
+ import { createTypeormGraphAdapter } from "@decaf-ts/as-graph/typeorm";
1182
+
1183
+ const adapter = await createTypeormGraphAdapter({
1184
+ dataSource: {
1185
+ type: "postgres",
1186
+ host: "db.internal",
1187
+ port: 5432,
1188
+ username: "mastra_app",
1189
+ password: /* resolved by the host from its environment or Docker secrets */,
1190
+ database: "mastra",
1191
+ schema: "asgraph",
1192
+ synchronize: false,
1193
+ },
1194
+ });
1195
+ ```
1196
+
1197
+ The standalone host selects this lane with `GRAPH_DB_DRIVER=postgres` — the connection is resolved
1198
+ from the environment/Docker secrets (`GRAPH_DB_URL`, or `GRAPH_DB_HOST`/`GRAPH_DB_PORT`/
1199
+ `GRAPH_DB_USER`/`GRAPH_DB_DATABASE` plus `GRAPH_DB_PASSWORD_FILE`; see the standalone-host
1200
+ environment table under [Running each backend + UI combination](#running-each-backend--ui-combination)).
1201
+
537
1202
  #### Consuming `shared` from a UI
538
1203
 
539
1204
  A UI bundle imports only from `@decaf-ts/as-graph/shared` and stays engine-free:
@@ -567,7 +1232,12 @@ manifests, documents and engine run results into DOM-free render inputs.
567
1232
  (`GET /graph/node-types`, `GET /graph/node-types/:kind`, `POST /graph/node-types/:kind/resolve`), canonical
568
1233
  workflow persistence (`PUT|GET /graph/workflows/:workflowId`, `GET /graph/workflows` ownership-filtered
569
1234
  summaries, `POST /graph/workflows/validate`), the asynchronous run lifecycle (`POST /graph/runs` → `202`,
570
- `GET /graph/workflows/:workflowId/runs` per-workflow run listing, `GET /graph/runs/:runId/events` SSE,
1235
+ `GET /graph/workflows/:workflowId/runs` per-workflow run listing — with optional
1236
+ `page`/`perPage` query params (`400` on non-integer or `< 1` values), and,
1237
+ when the active backend is mastra and the workflow is mastra-owned, serving the
1238
+ owner-scoped agent run-metrics page envelope `{ data, current, total, count }`
1239
+ through the metrics gateway instead of local run rows,
1240
+ `GET /graph/runs/:runId/events` SSE,
571
1241
  `DELETE /graph/runs/:runId`), and the read-only engine capability API (`GET /graph/engines`,
572
1242
  `GET /graph/engines/:engineId`, `GET /graph/engines/:engineId/workflows`,
573
1243
  `GET /graph/engines/:engineId/workflows/:workflowId`).
@@ -593,7 +1263,7 @@ dynamic engine output. The manifest shape:
593
1263
  engineId: "local", // backend flavour (allowlisted id)
594
1264
  displayName: "Local (built-in)",
595
1265
  local: true,
596
- pinnedEngineVersion: "built-in", // "1.13.25" for dagster, "1.74.0" for mastra
1266
+ pinnedEngineVersion: "built-in", // "1.13.25" for dagster, MASTRA_PINNED_VERSION ("1.74.0") for mastra — the peer dependency contract is @mastra/core ^1.77.0
597
1267
  capabilities: [
598
1268
  { feature: "codeMode", verdict: "SUPPORTED", detail?: "…" },
599
1269
  { feature: "workflowList", verdict: "NOT_SUPPORTED" },
@@ -679,6 +1349,11 @@ the backend and the UI together with `concurrently`.
679
1349
  | `GRAPH_BACKEND_PORT` | `3000` | Backend HTTP port (the standalone binary also accepts the port as its first argument) |
680
1350
  | `DAGSTER_GRAPHQL_URL` | unset | Read-only Dagster client target. Without it the dagster backend still boots and serves the manifest, but the catalogue reports `NOT_SUPPORTED` (`501`) |
681
1351
  | `DAGSTER_EXECUTION_ENABLED` | `false` | Opt-in gate for launching/replaying existing Dagster runs |
1352
+ | `GRAPH_DB_DRIVER` | unset | `postgres` boots the durable TypeORM/Postgres adapter (SAA-926 §6.4); anything else keeps the development `RamAdapter` posture |
1353
+ | `GRAPH_DB_URL` | unset | Full Postgres DSN for the durable lane — an alternative to the parts below plus the password file |
1354
+ | `GRAPH_DB_HOST` / `GRAPH_DB_PORT` / `GRAPH_DB_USER` / `GRAPH_DB_DATABASE` | — / `5432` | Durable-lane connection parts used when `GRAPH_DB_URL` is unset; an incomplete set fails closed at boot |
1355
+ | `GRAPH_DB_PASSWORD_FILE` | `/run/secrets/postgres_app_password` | Docker secret file carrying the `mastra_app` runtime password (the value is never logged) |
1356
+ | `GRAPH_DB_SCHEMA` | `asgraph` | Postgres schema owning the as-graph decaf tables |
682
1357
  | `GRAPH_BACKEND_URL` | `http://localhost:3000` | for-angular injection token for the backend base URL (a provider override, not an env var) |
683
1358
 
684
1359
  The host binds to `127.0.0.1` and only admits `http://localhost`/`http://127.0.0.1` CORS origins
@@ -690,7 +1365,10 @@ The standalone host seeds the demo workflow fixture registry into whichever
690
1365
  engine it boots: `loadGraphDemoWorkflows()` (exported from
691
1366
  `@decaf-ts/as-graph/nest`) imports the `graphWorkflowFixtures` registry from
692
1367
  `src/workflows` and passes its canonical documents as `seedWorkflows`, so each
693
- driver's catalogue lists the full fixture set out of the box. The registry is
1368
+ driver's catalogue lists the full fixture set out of the box. Operators can
1369
+ suppress boot-time seeding with `GRAPH_SEED_DEMO=off` (also
1370
+ `false`/`0`/`no`/`disabled`) — any other value (or an unset variable) keeps the
1371
+ default on. The registry is
694
1372
  test-only content — `npm pack` excludes `lib/**/workflows` — so a
695
1373
  release-packaged host boots with an empty seed set and its catalogues behave
696
1374
  exactly as before (the mastra catalogue starts empty; the dagster catalogue
@@ -718,8 +1396,19 @@ workflows persisted in the backend's local engine store, including the seeded de
718
1396
 
719
1397
  ##### Mastra
720
1398
 
721
- In-process; the only prerequisite is the `@mastra/core` peer dependency (pinned `^1.77.0`),
722
- resolved by `npm install` in `as-graph`. The host lazily builds a real `@mastra/core` runtime.
1399
+ In-process; the prerequisites are the `@mastra/core` peer dependency (`^1.77.0`,
1400
+ resolved by `npm install` in `as-graph`, alongside the optional `@mastra/memory`,
1401
+ `@mastra/libsql`, and `@mastra/pg` peers consumed by the memory/vector-store
1402
+ layers) and the langfuse credentials (`LANGFUSE_PUBLIC_KEY` /
1403
+ `LANGFUSE_SECRET_KEY` in `.env.secret`) — the observability lane is on by
1404
+ default and fails closed without them; disable it with
1405
+ `MASTRA__OBSERVABILITY__ENABLED=false`. The host lazily builds a real
1406
+ `@mastra/core` runtime. The standalone host's mastra wiring declares an
1407
+ explicit `InMemoryStore` (development posture); a production host must
1408
+ configure Mastra storage explicitly and durably through
1409
+ `MastraBackendConfig.storage` and verify
1410
+ `backend.storageStatus.domains.workflows === "durable"` (see the
1411
+ [Mastra backend](#mastra-backend-decaf-tsas-graphmastra) section).
723
1412
 
724
1413
  ```bash
725
1414
  npm run start:backend:mastra # engine: mastra, still on :3000
@@ -737,7 +1426,7 @@ host-injected `DagsterClient` built from `DAGSTER_GRAPHQL_URL`. Provision the pi
737
1426
  (Docker; Dagster `1.13.25`) with the integration harness:
738
1427
 
739
1428
  ```bash
740
- # as-graph: boot + seed the pinned gateway and persist its GraphQL URL
1429
+ # as-graph: boot the integration service matrix + the pinned gateway (its GraphQL URL is persisted to the it-env file)
741
1430
  npm run prepare-it-tests # publishes the gateway at http://127.0.0.1:3300/graphql
742
1431
  DAGSTER_GRAPHQL_URL=http://127.0.0.1:3300/graphql npm run start:backend:dagster
743
1432
  npm run teardown-it-tests # when done
@@ -774,7 +1463,9 @@ with an empty seed set answers `501` (`NOT_SUPPORTED`). To run against an alread
774
1463
 
775
1464
  The dagster suite needs the gateway fixture (`prepare-it-tests`) and Docker; it skips honestly when
776
1465
  no gateway is prepared. The standalone-binary boot test needs the `lib/cjs` build and skips when it
777
- is absent.
1466
+ is absent. All integration suites resolve their live endpoints from the service matrix booted by
1467
+ `npm run prepare-it-tests` (see [Integration service matrix](#integration-service-matrix)); absent
1468
+ infra is skipped honestly rather than faked.
778
1469
 
779
1470
  #### Scripts
780
1471
 
@@ -786,9 +1477,11 @@ is absent.
786
1477
  | `npm run start:backend:dagster` | Boot the standalone host with the Dagster engine (`GRAPH_BACKEND_ENGINE=dagster`) |
787
1478
  | `npm run test:integration:standard` / `:mastra` / `:dagster` | Run one engine variant's integration suite |
788
1479
  | `npm run test:integration:backend` | Run the host-boot integration suite (all variants + standalone binary) |
789
- | `npm run prepare-it-tests` / `teardown-it-tests` | Provision / stop the pinned Dagster gateway fixture |
1480
+ | `npm run prepare-it-tests` / `teardown-it-tests` | Boot / stop the integration service matrix (`docker/tests-compose.yml`, 11 services), the pinned Dagster gateway fixture, and — when the sibling `integrations` checkout is present — its Postgres harness on `:55435` — see [Integration service matrix](#integration-service-matrix) |
790
1481
  | `npm run test:unit` / `test:integration` / `test:e2e` | Run the Jest unit / integration / e2e suites |
791
- | `npm run test:all` | Run the entire Jest suite (unit, integration, e2e) |
1482
+ | `npm run test:unit:pdf` | Run the `ReadPDFNode` unit suite through `jest.pdf.config.cjs`; `pdf-parse`'s `pdfjs-dist` fake worker needs the Node `--experimental-vm-modules` runtime, so the file stays excluded from the default Jest config and runs first in `test:all` (and therefore in `test`, `test:dist`, `coverage`, `prepare-pr`, and `prepare-release`) |
1483
+ | `npm run test:evals` | Run the standalone eval suite (`jest -c jest.eval.config.cjs` over `tests/evals/*.eval.ts`; never picked up by the main Jest config) |
1484
+ | `npm run test:all` | Run the entire Jest suite (unit, integration, e2e) plus the `test:unit:pdf` lane |
792
1485
  | `npm run test:dist` | Re-run the full suite against the compiled `lib` and `dist` outputs |
793
1486
  | `npm run test:circular` | Check the source for circular dependencies |
794
1487
  | `npm run coverage` | Test run with coverage into `workdocs/reports/coverage` |
@@ -797,6 +1490,63 @@ is absent.
797
1490
  | `npm run uml` / `drawings` | Render `workdocs/uml/*.puml` and `workdocs/drawings/*.drawio` into `workdocs/resources` |
798
1491
  | `repo:readme` | Regenerate `README.md` from `workdocs/Readme.md` |
799
1492
 
1493
+ #### Integration service matrix
1494
+
1495
+ The integration suites and `npm run coverage` run against the
1496
+ production-grade service matrix booted by `npm run prepare-it-tests`
1497
+ (SAA-1142):
1498
+
1499
+ - **Compose file:** `docker/tests-compose.yml` (compose project
1500
+ `as-graph-it`), 11 services — Postgres 16, PGVector (pg 17), Apache AGE
1501
+ (pg 17), MySQL 8, SQL Server 2022, Redis, MinIO (S3), fake-gcs-server
1502
+ (GCS), Azurite (Azure Blob), SFTP (atmoz/sftp), and Mailpit (SMTP sink) —
1503
+ plus the pinned Dagster gateway fixture built by `tests/integration/dagster`
1504
+ and, when the sibling `integrations` checkout is present, its Postgres
1505
+ harness (`decaf-postgres-integration`, published on `:55435`; required by
1506
+ the RLS credential suites, skipped gracefully when the checkout is absent).
1507
+ - **Contract:** every endpoint is probed before the script succeeds, and the
1508
+ resolved endpoints are written to the git-ignored
1509
+ `var/as-graph-it/.it-env.json`, which `tests/integration/it-env.setup.cjs`
1510
+ loads for every Jest run (without overriding a value the caller already
1511
+ exported). The Dagster gateway is published at
1512
+ `http://127.0.0.1:3300/graphql` on a plain host
1513
+ (`http://127.0.0.1:3000/graphql` inside a containerized runner).
1514
+ - **Knobs:** `AS_GRAPH_IT_HOST` overrides the service host (a containerized
1515
+ runner defaults to the Docker bridge gateway `172.17.0.1`, a plain host to
1516
+ `127.0.0.1`), `AS_GRAPH_IT_SKIP_BUILD=1` reuses an existing `lib` build
1517
+ for a fast infra-only re-prepare, and `INTEGRATIONS_DIR` overrides the
1518
+ location of the sibling `integrations` checkout whose Postgres harness
1519
+ `prepare-it-tests` boots (default: `../integrations`).
1520
+ - **Teardown:** `npm run teardown-it-tests` stops the gateway, the service
1521
+ matrix, and the sibling integrations Postgres harness (when its checkout is
1522
+ present), keeping the named volumes so the next prepare is fast; pass
1523
+ `--volumes` for a full reset of service state.
1524
+ - **Honest skips:** without the booted matrix the live suites skip honestly.
1525
+ Suites needing a real external SaaS credential (GitHub, GitLab, Airtable,
1526
+ Gmail, Slack, Teams, Telegram, Google Sheets) stay skipped until that
1527
+ credential is configured — the harness never fabricates one and never
1528
+ starts a vendor stub in place of live infrastructure, and each skip title
1529
+ names the exact missing env var.
1530
+
1531
+ Docker (with a reachable daemon) and devDependencies are the only
1532
+ prerequisites.
1533
+
1534
+ #### Test environment prerequisites
1535
+
1536
+ The test and documentation lanes need the declared `devDependencies` present in `node_modules`. An
1537
+ install made under `NODE_ENV=production` (where npm defaults to `--omit=dev`) leaves them out and
1538
+ produces module-resolution failures that are install gaps, not product regressions:
1539
+
1540
+ - `@nestjs/testing` missing — `tests/unit/graph/mastra/MastraCatalogueOwnership.test.ts` and
1541
+ `tests/unit/graph/GraphPortManifestElement.test.ts` cannot load.
1542
+ - `eslint` missing — `tests/unit/graph/boundary-wall.test.ts` cannot spawn
1543
+ `node_modules/.bin/eslint`.
1544
+ - `@decaf-ts/utils` missing — `npm run docs` fails with `build-scripts: not found` (and the
1545
+ JSDoc/README toolchain cannot run).
1546
+
1547
+ Run the install with devDependencies enabled (`NODE_ENV=development npm install`) before treating
1548
+ those failures as defects.
1549
+
800
1550
 
801
1551
  ### Related
802
1552