@decaf-ts/as-graph 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/README.md +59 -13
  2. package/dist/as-graph.cjs +1 -1
  3. package/dist/as-graph.cjs.map +1 -1
  4. package/dist/as-graph.js +1 -1
  5. package/dist/as-graph.js.map +1 -1
  6. package/lib/cjs/dagster/DagsterGraphExecutionBackend.cjs +102 -11
  7. package/lib/cjs/dagster/DagsterGraphExecutionBackend.cjs.map +1 -1
  8. package/lib/cjs/engine/execution/GraphExecutionEngine.cjs +7 -0
  9. package/lib/cjs/engine/execution/GraphExecutionEngine.cjs.map +1 -1
  10. package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs +39 -0
  11. package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs.map +1 -1
  12. package/lib/cjs/engine/index.cjs +1 -0
  13. package/lib/cjs/engine/index.cjs.map +1 -1
  14. package/lib/cjs/engine/services/GraphNodeModelService.cjs +129 -0
  15. package/lib/cjs/engine/services/GraphNodeModelService.cjs.map +1 -0
  16. package/lib/cjs/engine/services/GraphWorkflowService.cjs +33 -0
  17. package/lib/cjs/engine/services/GraphWorkflowService.cjs.map +1 -1
  18. package/lib/cjs/mastra/MastraDefaultStepHandlers.cjs +217 -0
  19. package/lib/cjs/mastra/MastraDefaultStepHandlers.cjs.map +1 -0
  20. package/lib/cjs/mastra/MastraEventBridge.cjs +10 -3
  21. package/lib/cjs/mastra/MastraEventBridge.cjs.map +1 -1
  22. package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs +111 -13
  23. package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs.map +1 -1
  24. package/lib/cjs/mastra/MastraWorkflowCompiler.cjs +3 -3
  25. package/lib/cjs/mastra/MastraWorkflowCompiler.cjs.map +1 -1
  26. package/lib/cjs/mastra/index.cjs +1 -0
  27. package/lib/cjs/mastra/index.cjs.map +1 -1
  28. package/lib/cjs/mastra/types.cjs +5 -1
  29. package/lib/cjs/mastra/types.cjs.map +1 -1
  30. package/lib/cjs/nest/graph/GraphBackendHost.cjs +105 -19
  31. package/lib/cjs/nest/graph/GraphBackendHost.cjs.map +1 -1
  32. package/lib/cjs/nest/graph/GraphExecutionModule.cjs +37 -1
  33. package/lib/cjs/nest/graph/GraphExecutionModule.cjs.map +1 -1
  34. package/lib/cjs/nest/graph/main.cjs +16 -1
  35. package/lib/cjs/nest/graph/main.cjs.map +1 -1
  36. package/lib/cjs/ram/GraphNodeRepository.cjs +40 -0
  37. package/lib/cjs/ram/GraphNodeRepository.cjs.map +1 -0
  38. package/lib/cjs/ram/index.cjs +1 -0
  39. package/lib/cjs/ram/index.cjs.map +1 -1
  40. package/lib/cjs/shared/graph/GraphNodeConverters.cjs +43 -0
  41. package/lib/cjs/shared/graph/GraphNodeConverters.cjs.map +1 -0
  42. package/lib/cjs/shared/graph/GraphNodeModel.cjs +74 -0
  43. package/lib/cjs/shared/graph/GraphNodeModel.cjs.map +1 -0
  44. package/lib/cjs/shared/graph/index.cjs +2 -0
  45. package/lib/cjs/shared/graph/index.cjs.map +1 -1
  46. package/lib/esm/dagster/DagsterGraphExecutionBackend.js +102 -11
  47. package/lib/esm/dagster/DagsterGraphExecutionBackend.js.map +1 -1
  48. package/lib/esm/engine/execution/GraphExecutionBackend.js.map +1 -1
  49. package/lib/esm/engine/execution/GraphExecutionEngine.js +7 -0
  50. package/lib/esm/engine/execution/GraphExecutionEngine.js.map +1 -1
  51. package/lib/esm/engine/execution/LocalGraphExecutionBackend.js +39 -0
  52. package/lib/esm/engine/execution/LocalGraphExecutionBackend.js.map +1 -1
  53. package/lib/esm/engine/index.js +1 -0
  54. package/lib/esm/engine/index.js.map +1 -1
  55. package/lib/esm/engine/services/GraphNodeModelService.js +120 -0
  56. package/lib/esm/engine/services/GraphNodeModelService.js.map +1 -0
  57. package/lib/esm/engine/services/GraphWorkflowService.js +34 -1
  58. package/lib/esm/engine/services/GraphWorkflowService.js.map +1 -1
  59. package/lib/esm/mastra/MastraDefaultStepHandlers.js +212 -0
  60. package/lib/esm/mastra/MastraDefaultStepHandlers.js.map +1 -0
  61. package/lib/esm/mastra/MastraEventBridge.js +10 -3
  62. package/lib/esm/mastra/MastraEventBridge.js.map +1 -1
  63. package/lib/esm/mastra/MastraGraphExecutionBackend.js +112 -14
  64. package/lib/esm/mastra/MastraGraphExecutionBackend.js.map +1 -1
  65. package/lib/esm/mastra/MastraWorkflowCompiler.js +3 -3
  66. package/lib/esm/mastra/MastraWorkflowCompiler.js.map +1 -1
  67. package/lib/esm/mastra/index.js +1 -0
  68. package/lib/esm/mastra/index.js.map +1 -1
  69. package/lib/esm/mastra/types.js +4 -0
  70. package/lib/esm/mastra/types.js.map +1 -1
  71. package/lib/esm/nest/graph/GraphBackendHost.js +69 -18
  72. package/lib/esm/nest/graph/GraphBackendHost.js.map +1 -1
  73. package/lib/esm/nest/graph/GraphExecutionModule.js +38 -2
  74. package/lib/esm/nest/graph/GraphExecutionModule.js.map +1 -1
  75. package/lib/esm/nest/graph/main.js +17 -2
  76. package/lib/esm/nest/graph/main.js.map +1 -1
  77. package/lib/esm/ram/GraphNodeRepository.js +31 -0
  78. package/lib/esm/ram/GraphNodeRepository.js.map +1 -0
  79. package/lib/esm/ram/index.js +1 -0
  80. package/lib/esm/ram/index.js.map +1 -1
  81. package/lib/esm/shared/graph/GraphNodeConverters.js +38 -0
  82. package/lib/esm/shared/graph/GraphNodeConverters.js.map +1 -0
  83. package/lib/esm/shared/graph/GraphNodeModel.js +65 -0
  84. package/lib/esm/shared/graph/GraphNodeModel.js.map +1 -0
  85. package/lib/esm/shared/graph/index.js +2 -0
  86. package/lib/esm/shared/graph/index.js.map +1 -1
  87. package/lib/types/dagster/DagsterGraphExecutionBackend.d.cts +40 -4
  88. package/lib/types/dagster/DagsterGraphExecutionBackend.d.mts +40 -4
  89. package/lib/types/engine/execution/GraphExecutionBackend.d.cts +27 -0
  90. package/lib/types/engine/execution/GraphExecutionBackend.d.mts +27 -0
  91. package/lib/types/engine/execution/GraphExecutionEngine.d.cts +9 -0
  92. package/lib/types/engine/execution/GraphExecutionEngine.d.mts +9 -0
  93. package/lib/types/engine/execution/LocalGraphExecutionBackend.d.cts +14 -0
  94. package/lib/types/engine/execution/LocalGraphExecutionBackend.d.mts +14 -0
  95. package/lib/types/engine/index.d.cts +1 -0
  96. package/lib/types/engine/index.d.mts +1 -0
  97. package/lib/types/engine/services/GraphNodeModelService.d.cts +54 -0
  98. package/lib/types/engine/services/GraphNodeModelService.d.mts +54 -0
  99. package/lib/types/engine/services/GraphWorkflowService.d.cts +21 -0
  100. package/lib/types/engine/services/GraphWorkflowService.d.mts +21 -0
  101. package/lib/types/mastra/MastraDefaultStepHandlers.d.cts +74 -0
  102. package/lib/types/mastra/MastraDefaultStepHandlers.d.mts +74 -0
  103. package/lib/types/mastra/MastraGraphExecutionBackend.d.cts +29 -0
  104. package/lib/types/mastra/MastraGraphExecutionBackend.d.mts +29 -0
  105. package/lib/types/mastra/MastraWorkflowCompiler.d.cts +3 -3
  106. package/lib/types/mastra/MastraWorkflowCompiler.d.mts +3 -3
  107. package/lib/types/mastra/index.d.cts +1 -0
  108. package/lib/types/mastra/index.d.mts +1 -0
  109. package/lib/types/mastra/types.d.cts +12 -0
  110. package/lib/types/mastra/types.d.mts +12 -0
  111. package/lib/types/nest/graph/GraphBackendHost.d.cts +52 -0
  112. package/lib/types/nest/graph/GraphBackendHost.d.mts +52 -0
  113. package/lib/types/nest/graph/GraphExecutionModule.d.cts +11 -0
  114. package/lib/types/nest/graph/GraphExecutionModule.d.mts +11 -0
  115. package/lib/types/ram/GraphNodeRepository.d.cts +13 -0
  116. package/lib/types/ram/GraphNodeRepository.d.mts +13 -0
  117. package/lib/types/ram/index.d.cts +1 -0
  118. package/lib/types/ram/index.d.mts +1 -0
  119. package/lib/types/shared/graph/GraphNodeConverters.d.cts +15 -0
  120. package/lib/types/shared/graph/GraphNodeConverters.d.mts +15 -0
  121. package/lib/types/shared/graph/GraphNodeModel.d.cts +24 -0
  122. package/lib/types/shared/graph/GraphNodeModel.d.mts +24 -0
  123. package/lib/types/shared/graph/index.d.cts +2 -0
  124. package/lib/types/shared/graph/index.d.mts +2 -0
  125. package/package.json +9 -3
@@ -0,0 +1,54 @@
1
+ import { ModelService, type Context, type MaybeContextualArg } from "@decaf-ts/core";
2
+ import { GraphNodeModel } from "../../shared/graph/index.d.cts";
3
+ import type { GraphNodeManifest } from "../../shared/graph/index.d.cts";
4
+ import type { GraphNodeCatalogue } from "../catalog/GraphNodeCatalogue.d.cts";
5
+ /**
6
+ * Model-backed node catalogue: persists {@link GraphNodeManifest} rows as
7
+ * {@link GraphNodeModel} via the Decaf {@link ModelService}.
8
+ */
9
+ export declare class GraphNodeModelService extends ModelService<GraphNodeModel> {
10
+ constructor();
11
+ /**
12
+ * Upserts a single node-kind manifest as a {@link GraphNodeModel} row,
13
+ * updating the mirror columns and manifest when the row already exists.
14
+ *
15
+ * @param {GraphNodeManifest} manifest - Node-kind manifest to persist.
16
+ * @param args - An optional decaf `Context` forwarded to the model service.
17
+ * @return {Promise<GraphNodeModel>} The persisted row.
18
+ */
19
+ upsertManifest(manifest: GraphNodeManifest, ...args: MaybeContextualArg<Context>): Promise<GraphNodeModel>;
20
+ /**
21
+ * Synchronises the whole catalogue into persistence, upserting every listed
22
+ * manifest so listing/CRUD works out of the box for the engine driver.
23
+ *
24
+ * @param {GraphNodeCatalogue} catalogue - Catalogue to mirror into persistence.
25
+ * @param args - An optional decaf `Context` forwarded to the model service.
26
+ * @return {Promise<GraphNodeModel[]>} The persisted rows, in catalogue order.
27
+ */
28
+ syncFromCatalogue(catalogue: GraphNodeCatalogue, ...args: MaybeContextualArg<Context>): Promise<GraphNodeModel[]>;
29
+ /**
30
+ * Lists every persisted node-kind row, ordered by kind.
31
+ *
32
+ * A store failure propagates instead of being swallowed as `[]` (SAA-93 F4).
33
+ *
34
+ * @param args - An optional decaf `Context` forwarded to the model service.
35
+ * @return {Promise<GraphNodeModel[]>} The persisted rows.
36
+ */
37
+ listNodes(...args: MaybeContextualArg<Context>): Promise<GraphNodeModel[]>;
38
+ /**
39
+ * Lists every persisted node-kind manifest, ordered by kind.
40
+ *
41
+ * @param args - An optional decaf `Context` forwarded to the model service.
42
+ * @return {Promise<GraphNodeManifest[]>} The persisted manifests.
43
+ */
44
+ listManifests(...args: MaybeContextualArg<Context>): Promise<GraphNodeManifest[]>;
45
+ /**
46
+ * Reads the persisted row for a node kind.
47
+ *
48
+ * @param {string} kind - Registered node kind to read.
49
+ * @param args - An optional decaf `Context` forwarded to the model service.
50
+ * @return {Promise<GraphNodeModel>} The persisted row.
51
+ * @throws {NotFoundError} When no row exists for `kind`.
52
+ */
53
+ getNode(kind: string, ...args: MaybeContextualArg<Context>): Promise<GraphNodeModel>;
54
+ }
@@ -0,0 +1,54 @@
1
+ import { ModelService, type Context, type MaybeContextualArg } from "@decaf-ts/core";
2
+ import { GraphNodeModel } from "../../shared/graph/index.d.mts";
3
+ import type { GraphNodeManifest } from "../../shared/graph/index.d.mts";
4
+ import type { GraphNodeCatalogue } from "../catalog/GraphNodeCatalogue.d.mts";
5
+ /**
6
+ * Model-backed node catalogue: persists {@link GraphNodeManifest} rows as
7
+ * {@link GraphNodeModel} via the Decaf {@link ModelService}.
8
+ */
9
+ export declare class GraphNodeModelService extends ModelService<GraphNodeModel> {
10
+ constructor();
11
+ /**
12
+ * Upserts a single node-kind manifest as a {@link GraphNodeModel} row,
13
+ * updating the mirror columns and manifest when the row already exists.
14
+ *
15
+ * @param {GraphNodeManifest} manifest - Node-kind manifest to persist.
16
+ * @param args - An optional decaf `Context` forwarded to the model service.
17
+ * @return {Promise<GraphNodeModel>} The persisted row.
18
+ */
19
+ upsertManifest(manifest: GraphNodeManifest, ...args: MaybeContextualArg<Context>): Promise<GraphNodeModel>;
20
+ /**
21
+ * Synchronises the whole catalogue into persistence, upserting every listed
22
+ * manifest so listing/CRUD works out of the box for the engine driver.
23
+ *
24
+ * @param {GraphNodeCatalogue} catalogue - Catalogue to mirror into persistence.
25
+ * @param args - An optional decaf `Context` forwarded to the model service.
26
+ * @return {Promise<GraphNodeModel[]>} The persisted rows, in catalogue order.
27
+ */
28
+ syncFromCatalogue(catalogue: GraphNodeCatalogue, ...args: MaybeContextualArg<Context>): Promise<GraphNodeModel[]>;
29
+ /**
30
+ * Lists every persisted node-kind row, ordered by kind.
31
+ *
32
+ * A store failure propagates instead of being swallowed as `[]` (SAA-93 F4).
33
+ *
34
+ * @param args - An optional decaf `Context` forwarded to the model service.
35
+ * @return {Promise<GraphNodeModel[]>} The persisted rows.
36
+ */
37
+ listNodes(...args: MaybeContextualArg<Context>): Promise<GraphNodeModel[]>;
38
+ /**
39
+ * Lists every persisted node-kind manifest, ordered by kind.
40
+ *
41
+ * @param args - An optional decaf `Context` forwarded to the model service.
42
+ * @return {Promise<GraphNodeManifest[]>} The persisted manifests.
43
+ */
44
+ listManifests(...args: MaybeContextualArg<Context>): Promise<GraphNodeManifest[]>;
45
+ /**
46
+ * Reads the persisted row for a node kind.
47
+ *
48
+ * @param {string} kind - Registered node kind to read.
49
+ * @param args - An optional decaf `Context` forwarded to the model service.
50
+ * @return {Promise<GraphNodeModel>} The persisted row.
51
+ * @throws {NotFoundError} When no row exists for `kind`.
52
+ */
53
+ getNode(kind: string, ...args: MaybeContextualArg<Context>): Promise<GraphNodeModel>;
54
+ }
@@ -69,6 +69,27 @@ export declare class GraphWorkflowService extends ModelService<GraphWorkflowMode
69
69
  * @throws {GraphWorkflowDocumentRejectedError} When boundary validation fails.
70
70
  */
71
71
  saveDocument(workflowId: string, document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel>;
72
+ /**
73
+ * Boot-seed write of a canonical workflow document (F2 availability fix):
74
+ * behaves exactly like {@link saveDocument} except that an ownership conflict
75
+ * on an existing foreign-owned row is treated as a skip-and-log instead of a
76
+ * hard failure. A durable store that already holds a user-owned row for a
77
+ * fixture id therefore cannot fail host bootstrap, while the security posture
78
+ * is unchanged: the foreign-owned row is never overwritten and the engine's own
79
+ * catalogue seed still serves the fixture.
80
+ *
81
+ * This is the boot seeding surface only. Request-path writes MUST keep using
82
+ * {@link saveDocument} / {@link saveSnapshot}, which stay fail-closed on a
83
+ * foreign-owned overwrite (SAA-105 R3).
84
+ *
85
+ * @param {string} workflowId - Workflow id from the fixture registry.
86
+ * @param {GraphWorkflowDocument} document - Canonical document to seed (its `id` must equal `workflowId`).
87
+ * @param args - An optional decaf `Context` carrying the owning principal.
88
+ * @return {Promise<GraphWorkflowModel | null>} The persisted row, or `null` when the seed was skipped because the existing row is owned by another user.
89
+ * @throws {ValidationError} When the payload shape or the document/path id match is invalid.
90
+ * @throws {GraphWorkflowDocumentRejectedError} When boundary validation fails.
91
+ */
92
+ seedDocument(workflowId: string, document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel | null>;
72
93
  /**
73
94
  * Reads a workflow's canonical document, enforcing the DECAF-48 ownership
74
95
  * tuple. Legacy definition/state snapshots are no longer served.
@@ -69,6 +69,27 @@ export declare class GraphWorkflowService extends ModelService<GraphWorkflowMode
69
69
  * @throws {GraphWorkflowDocumentRejectedError} When boundary validation fails.
70
70
  */
71
71
  saveDocument(workflowId: string, document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel>;
72
+ /**
73
+ * Boot-seed write of a canonical workflow document (F2 availability fix):
74
+ * behaves exactly like {@link saveDocument} except that an ownership conflict
75
+ * on an existing foreign-owned row is treated as a skip-and-log instead of a
76
+ * hard failure. A durable store that already holds a user-owned row for a
77
+ * fixture id therefore cannot fail host bootstrap, while the security posture
78
+ * is unchanged: the foreign-owned row is never overwritten and the engine's own
79
+ * catalogue seed still serves the fixture.
80
+ *
81
+ * This is the boot seeding surface only. Request-path writes MUST keep using
82
+ * {@link saveDocument} / {@link saveSnapshot}, which stay fail-closed on a
83
+ * foreign-owned overwrite (SAA-105 R3).
84
+ *
85
+ * @param {string} workflowId - Workflow id from the fixture registry.
86
+ * @param {GraphWorkflowDocument} document - Canonical document to seed (its `id` must equal `workflowId`).
87
+ * @param args - An optional decaf `Context` carrying the owning principal.
88
+ * @return {Promise<GraphWorkflowModel | null>} The persisted row, or `null` when the seed was skipped because the existing row is owned by another user.
89
+ * @throws {ValidationError} When the payload shape or the document/path id match is invalid.
90
+ * @throws {GraphWorkflowDocumentRejectedError} When boundary validation fails.
91
+ */
92
+ seedDocument(workflowId: string, document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel | null>;
72
93
  /**
73
94
  * Reads a workflow's canonical document, enforcing the DECAF-48 ownership
74
95
  * tuple. Legacy definition/state snapshots are no longer served.
@@ -0,0 +1,74 @@
1
+ import { type MastraNodeStepHandler } from "./types.d.cts";
2
+ /**
3
+ * The built-in leaf node kinds covered by the default handler set: the
4
+ * plain-data, flow-utility, trigger, and utility kinds that compile as opaque
5
+ * steps. Structural kinds (`core.flow.if`/`core.flow.switch`, the
6
+ * `core.loop.*` loops, and `core.flow.humanApproval`) are translated by the
7
+ * compiler itself and are deliberately absent.
8
+ */
9
+ export declare const MASTRA_DEFAULT_STEP_HANDLER_KINDS: readonly ["value", "result", "core.agent", "core.flow.break", "core.flow.delay", "core.flow.errorBoundary", "core.flow.log", "core.trigger.chat", "core.trigger.event", "core.trigger.form", "core.trigger.manual", "core.trigger.schedule", "core.trigger.webhook", "core.utility.code", "core.utility.log", "core.utility.map"];
10
+ /** Any built-in leaf node kind covered by {@link MASTRA_DEFAULT_STEP_HANDLER_KINDS}. */
11
+ export type MastraDefaultStepHandlerKind = (typeof MASTRA_DEFAULT_STEP_HANDLER_KINDS)[number];
12
+ /**
13
+ * Largest delay `setTimeout` accepts before Node overflows and collapses the
14
+ * wait to ~1ms (`2^31 - 1`). {@link createMastraDefaultStepHandlers} clamps a
15
+ * delay node's `timeoutMs` to this value *before* scheduling, so a hostile or
16
+ * oversized declared delay can never hit the overflow degenerate path.
17
+ */
18
+ export declare const MASTRA_MAX_SET_TIMEOUT_MS = 2147483647;
19
+ /**
20
+ * Default host-configurable ceiling, in milliseconds, for a `core.flow.delay`
21
+ * node's `timeoutMs` (60s). The declared value is clamped to this ceiling, never
22
+ * rejected, so an oversized document cannot pin a run slot for up to
23
+ * `MASTRA_MAX_SET_TIMEOUT_MS` (~24.8 days) per node.
24
+ */
25
+ export declare const DEFAULT_MASTRA_DELAY_MAX_MS = 60000;
26
+ /**
27
+ * Reserved key under which a default-handler result records that the node was
28
+ * not fully executed. `core.agent` returns its forwarded input plus this key so
29
+ * a caller can tell a declared-but-inert agent step apart from a real one; the
30
+ * key never collides with a canonical data port.
31
+ */
32
+ export declare const MASTRA_DEGRADED_OUTPUT_KEY = "__mastraDegraded";
33
+ /** Details recorded under {@link MASTRA_DEGRADED_OUTPUT_KEY}. */
34
+ export interface MastraDegradedOutput {
35
+ /** The node kind whose declared capability was not executed. */
36
+ kind: string;
37
+ /** The node id the degraded result belongs to. */
38
+ nodeId: string;
39
+ /** Human-readable reason the node degraded to a pass-through. */
40
+ reason: string;
41
+ }
42
+ /** Options {@link createMastraDefaultStepHandlers} is created with. */
43
+ export interface MastraDefaultStepHandlerOptions {
44
+ /**
45
+ * Optional sink for the log kinds' messages (the default is silent).
46
+ *
47
+ * The sink receives **untrusted** data: `message` is the document's
48
+ * `node.parameters.message` verbatim and `meta` carries in-flight node data. A
49
+ * logger implementation must treat both arguments as untrusted, JSON-serialize
50
+ * `meta`, and never interpolate either into a line-oriented log (the pattern
51
+ * `nest/graph/servingErrors.ts` already mandates) — otherwise a crafted
52
+ * document enables log forging or CRLF injection.
53
+ */
54
+ logger?: (message: string, meta?: Record<string, unknown>) => void;
55
+ /**
56
+ * Host-configurable ceiling, in milliseconds, for a `core.flow.delay` node's
57
+ * `timeoutMs`. The declared value is clamped to this ceiling (never rejected)
58
+ * and additionally bounded by {@link MASTRA_MAX_SET_TIMEOUT_MS}; defaults to
59
+ * {@link DEFAULT_MASTRA_DELAY_MAX_MS}.
60
+ */
61
+ maxDelayMs?: number;
62
+ }
63
+ /**
64
+ * Builds the default {@link MastraNodeStepHandler} set: one handler per
65
+ * {@link MastraDefaultStepHandlerKind}. Each handler creates a
66
+ * schema-agnostic Mastra step (`z.any()` input and output schemas) whose
67
+ * execution coerces the runtime's input data to a record and delegates to the
68
+ * kind's executor, so untyped document parameters never break the runtime.
69
+ *
70
+ * @param options - Optional handler-set options (logger and delay ceiling).
71
+ * @returns One {@link MastraNodeStepHandler} per entry of
72
+ * {@link MASTRA_DEFAULT_STEP_HANDLER_KINDS}.
73
+ */
74
+ export declare function createMastraDefaultStepHandlers(options?: MastraDefaultStepHandlerOptions): MastraNodeStepHandler[];
@@ -0,0 +1,74 @@
1
+ import { type MastraNodeStepHandler } from "./types.d.mts";
2
+ /**
3
+ * The built-in leaf node kinds covered by the default handler set: the
4
+ * plain-data, flow-utility, trigger, and utility kinds that compile as opaque
5
+ * steps. Structural kinds (`core.flow.if`/`core.flow.switch`, the
6
+ * `core.loop.*` loops, and `core.flow.humanApproval`) are translated by the
7
+ * compiler itself and are deliberately absent.
8
+ */
9
+ export declare const MASTRA_DEFAULT_STEP_HANDLER_KINDS: readonly ["value", "result", "core.agent", "core.flow.break", "core.flow.delay", "core.flow.errorBoundary", "core.flow.log", "core.trigger.chat", "core.trigger.event", "core.trigger.form", "core.trigger.manual", "core.trigger.schedule", "core.trigger.webhook", "core.utility.code", "core.utility.log", "core.utility.map"];
10
+ /** Any built-in leaf node kind covered by {@link MASTRA_DEFAULT_STEP_HANDLER_KINDS}. */
11
+ export type MastraDefaultStepHandlerKind = (typeof MASTRA_DEFAULT_STEP_HANDLER_KINDS)[number];
12
+ /**
13
+ * Largest delay `setTimeout` accepts before Node overflows and collapses the
14
+ * wait to ~1ms (`2^31 - 1`). {@link createMastraDefaultStepHandlers} clamps a
15
+ * delay node's `timeoutMs` to this value *before* scheduling, so a hostile or
16
+ * oversized declared delay can never hit the overflow degenerate path.
17
+ */
18
+ export declare const MASTRA_MAX_SET_TIMEOUT_MS = 2147483647;
19
+ /**
20
+ * Default host-configurable ceiling, in milliseconds, for a `core.flow.delay`
21
+ * node's `timeoutMs` (60s). The declared value is clamped to this ceiling, never
22
+ * rejected, so an oversized document cannot pin a run slot for up to
23
+ * `MASTRA_MAX_SET_TIMEOUT_MS` (~24.8 days) per node.
24
+ */
25
+ export declare const DEFAULT_MASTRA_DELAY_MAX_MS = 60000;
26
+ /**
27
+ * Reserved key under which a default-handler result records that the node was
28
+ * not fully executed. `core.agent` returns its forwarded input plus this key so
29
+ * a caller can tell a declared-but-inert agent step apart from a real one; the
30
+ * key never collides with a canonical data port.
31
+ */
32
+ export declare const MASTRA_DEGRADED_OUTPUT_KEY = "__mastraDegraded";
33
+ /** Details recorded under {@link MASTRA_DEGRADED_OUTPUT_KEY}. */
34
+ export interface MastraDegradedOutput {
35
+ /** The node kind whose declared capability was not executed. */
36
+ kind: string;
37
+ /** The node id the degraded result belongs to. */
38
+ nodeId: string;
39
+ /** Human-readable reason the node degraded to a pass-through. */
40
+ reason: string;
41
+ }
42
+ /** Options {@link createMastraDefaultStepHandlers} is created with. */
43
+ export interface MastraDefaultStepHandlerOptions {
44
+ /**
45
+ * Optional sink for the log kinds' messages (the default is silent).
46
+ *
47
+ * The sink receives **untrusted** data: `message` is the document's
48
+ * `node.parameters.message` verbatim and `meta` carries in-flight node data. A
49
+ * logger implementation must treat both arguments as untrusted, JSON-serialize
50
+ * `meta`, and never interpolate either into a line-oriented log (the pattern
51
+ * `nest/graph/servingErrors.ts` already mandates) — otherwise a crafted
52
+ * document enables log forging or CRLF injection.
53
+ */
54
+ logger?: (message: string, meta?: Record<string, unknown>) => void;
55
+ /**
56
+ * Host-configurable ceiling, in milliseconds, for a `core.flow.delay` node's
57
+ * `timeoutMs`. The declared value is clamped to this ceiling (never rejected)
58
+ * and additionally bounded by {@link MASTRA_MAX_SET_TIMEOUT_MS}; defaults to
59
+ * {@link DEFAULT_MASTRA_DELAY_MAX_MS}.
60
+ */
61
+ maxDelayMs?: number;
62
+ }
63
+ /**
64
+ * Builds the default {@link MastraNodeStepHandler} set: one handler per
65
+ * {@link MastraDefaultStepHandlerKind}. Each handler creates a
66
+ * schema-agnostic Mastra step (`z.any()` input and output schemas) whose
67
+ * execution coerces the runtime's input data to a record and delegates to the
68
+ * kind's executor, so untyped document parameters never break the runtime.
69
+ *
70
+ * @param options - Optional handler-set options (logger and delay ceiling).
71
+ * @returns One {@link MastraNodeStepHandler} per entry of
72
+ * {@link MASTRA_DEFAULT_STEP_HANDLER_KINDS}.
73
+ */
74
+ export declare function createMastraDefaultStepHandlers(options?: MastraDefaultStepHandlerOptions): MastraNodeStepHandler[];
@@ -34,6 +34,7 @@ export declare class MastraGraphExecutionBackend implements GraphExecutionBacken
34
34
  private managementManager?;
35
35
  private suspendStateReader?;
36
36
  private maxResumeBytes;
37
+ private terminalTimeoutMs;
37
38
  private initialized;
38
39
  private _config?;
39
40
  constructor();
@@ -75,7 +76,35 @@ export declare class MastraGraphExecutionBackend implements GraphExecutionBacken
75
76
  * @throws {NotFoundError} when the workflow is owned by another user.
76
77
  */
77
78
  getWorkflow(workflowId: string, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowDocument>;
79
+ /**
80
+ * Seeds canonical workflow documents into the translated-workflow catalogue so
81
+ * they are served by {@link listWorkflows}/{@link getWorkflow} exactly like a
82
+ * document recorded by {@link execute}. Seeded entries are owner-less, so the
83
+ * C23 filter keeps them visible to every caller (the owner-less visibility
84
+ * rule). Fails closed when the backend has not been initialized.
85
+ *
86
+ * @param documents - The canonical documents to register.
87
+ * @returns The seeded workflow summaries.
88
+ * @throws {GraphExecutionError} when the backend is not initialized.
89
+ */
90
+ seedWorkflows(documents: readonly GraphWorkflowDocument[]): Promise<GraphBackendWorkflowSummary[]>;
78
91
  execute(request: GraphBackendExecutionRequest, ...args: MaybeContextualArg<Context>): Promise<GraphExecutionResult>;
92
+ /**
93
+ * Bounds the translated run's terminal wait by the backend's run-level
94
+ * `terminalTimeoutMs` and the caller's cancellation signal, mirroring the
95
+ * Dagster observation bound. Exceeding the timeout fails closed with
96
+ * {@link GRAPH_MASTRA_EXECUTE_TIMEOUT}; an abort fails closed with
97
+ * {@link GRAPH_MASTRA_EXECUTE_ABORTED}. The underlying run is not force-killed
98
+ * (Mastra owns run lifecycle), but the backend stops awaiting it so the run
99
+ * slot and event bridge are released and the run cannot pin the process.
100
+ *
101
+ * @param execution - The in-flight run/stream/result promise.
102
+ * @param signal - The caller's cancellation signal, when supplied.
103
+ * @param workflowId - The workflow id the run belongs to (for error details).
104
+ * @returns Resolves once the run terminates normally.
105
+ * @throws {GraphExecutionError} on timeout or abort.
106
+ */
107
+ private awaitTerminal;
79
108
  /**
80
109
  * Resumes a suspended Mastra run after enforcing the SAA-193 resume guard
81
110
  * (C13/C15/C16/C17/C18). The Mastra run snapshot is authoritative for the
@@ -34,6 +34,7 @@ export declare class MastraGraphExecutionBackend implements GraphExecutionBacken
34
34
  private managementManager?;
35
35
  private suspendStateReader?;
36
36
  private maxResumeBytes;
37
+ private terminalTimeoutMs;
37
38
  private initialized;
38
39
  private _config?;
39
40
  constructor();
@@ -75,7 +76,35 @@ export declare class MastraGraphExecutionBackend implements GraphExecutionBacken
75
76
  * @throws {NotFoundError} when the workflow is owned by another user.
76
77
  */
77
78
  getWorkflow(workflowId: string, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowDocument>;
79
+ /**
80
+ * Seeds canonical workflow documents into the translated-workflow catalogue so
81
+ * they are served by {@link listWorkflows}/{@link getWorkflow} exactly like a
82
+ * document recorded by {@link execute}. Seeded entries are owner-less, so the
83
+ * C23 filter keeps them visible to every caller (the owner-less visibility
84
+ * rule). Fails closed when the backend has not been initialized.
85
+ *
86
+ * @param documents - The canonical documents to register.
87
+ * @returns The seeded workflow summaries.
88
+ * @throws {GraphExecutionError} when the backend is not initialized.
89
+ */
90
+ seedWorkflows(documents: readonly GraphWorkflowDocument[]): Promise<GraphBackendWorkflowSummary[]>;
78
91
  execute(request: GraphBackendExecutionRequest, ...args: MaybeContextualArg<Context>): Promise<GraphExecutionResult>;
92
+ /**
93
+ * Bounds the translated run's terminal wait by the backend's run-level
94
+ * `terminalTimeoutMs` and the caller's cancellation signal, mirroring the
95
+ * Dagster observation bound. Exceeding the timeout fails closed with
96
+ * {@link GRAPH_MASTRA_EXECUTE_TIMEOUT}; an abort fails closed with
97
+ * {@link GRAPH_MASTRA_EXECUTE_ABORTED}. The underlying run is not force-killed
98
+ * (Mastra owns run lifecycle), but the backend stops awaiting it so the run
99
+ * slot and event bridge are released and the run cannot pin the process.
100
+ *
101
+ * @param execution - The in-flight run/stream/result promise.
102
+ * @param signal - The caller's cancellation signal, when supplied.
103
+ * @param workflowId - The workflow id the run belongs to (for error details).
104
+ * @returns Resolves once the run terminates normally.
105
+ * @throws {GraphExecutionError} on timeout or abort.
106
+ */
107
+ private awaitTerminal;
79
108
  /**
80
109
  * Resumes a suspended Mastra run after enforcing the SAA-193 resume guard
81
110
  * (C13/C15/C16/C17/C18). The Mastra run snapshot is authoritative for the
@@ -18,11 +18,11 @@ export declare const GRAPH_MASTRA_IF_KIND = "core.flow.if";
18
18
  /** Document kind translated into a Mastra `switch` branch set. */
19
19
  export declare const GRAPH_MASTRA_SWITCH_KIND = "core.flow.switch";
20
20
  /** Document kind translated into a Mastra `foreach` loop. */
21
- export declare const GRAPH_MASTRA_FOREACH_KIND = "graph-foreach-loop-node";
21
+ export declare const GRAPH_MASTRA_FOREACH_KIND = "core.loop.foreach";
22
22
  /** Document kind translated into a Mastra `do-while` loop. */
23
- export declare const GRAPH_MASTRA_WHILE_KIND = "graph-while-loop-node";
23
+ export declare const GRAPH_MASTRA_WHILE_KIND = "core.loop.while";
24
24
  /** Document kind translated into a Mastra `do-until` loop. */
25
- export declare const GRAPH_MASTRA_UNTIL_KIND = "graph-until-loop-node";
25
+ export declare const GRAPH_MASTRA_UNTIL_KIND = "core.loop.until";
26
26
  /** Document kind translated into a Mastra suspending approval step. */
27
27
  export declare const GRAPH_MASTRA_HUMAN_APPROVAL_KIND = "core.flow.humanApproval";
28
28
  /**
@@ -18,11 +18,11 @@ export declare const GRAPH_MASTRA_IF_KIND = "core.flow.if";
18
18
  /** Document kind translated into a Mastra `switch` branch set. */
19
19
  export declare const GRAPH_MASTRA_SWITCH_KIND = "core.flow.switch";
20
20
  /** Document kind translated into a Mastra `foreach` loop. */
21
- export declare const GRAPH_MASTRA_FOREACH_KIND = "graph-foreach-loop-node";
21
+ export declare const GRAPH_MASTRA_FOREACH_KIND = "core.loop.foreach";
22
22
  /** Document kind translated into a Mastra `do-while` loop. */
23
- export declare const GRAPH_MASTRA_WHILE_KIND = "graph-while-loop-node";
23
+ export declare const GRAPH_MASTRA_WHILE_KIND = "core.loop.while";
24
24
  /** Document kind translated into a Mastra `do-until` loop. */
25
- export declare const GRAPH_MASTRA_UNTIL_KIND = "graph-until-loop-node";
25
+ export declare const GRAPH_MASTRA_UNTIL_KIND = "core.loop.until";
26
26
  /** Document kind translated into a Mastra suspending approval step. */
27
27
  export declare const GRAPH_MASTRA_HUMAN_APPROVAL_KIND = "core.flow.humanApproval";
28
28
  /**
@@ -12,6 +12,7 @@ export * from "./MastraSchemaConverter.d.cts";
12
12
  export * from "./MastraConditionBridge.d.cts";
13
13
  export * from "./MastraEventBridge.d.cts";
14
14
  export * from "./MastraWorkflowCompiler.d.cts";
15
+ export * from "./MastraDefaultStepHandlers.d.cts";
15
16
  export * from "./MastraWorkflowManager.d.cts";
16
17
  export * from "./MastraResumeGuard.d.cts";
17
18
  export * from "./MastraGraphExecutionBackend.d.cts";
@@ -12,6 +12,7 @@ export * from "./MastraSchemaConverter.d.mts";
12
12
  export * from "./MastraConditionBridge.d.mts";
13
13
  export * from "./MastraEventBridge.d.mts";
14
14
  export * from "./MastraWorkflowCompiler.d.mts";
15
+ export * from "./MastraDefaultStepHandlers.d.mts";
15
16
  export * from "./MastraWorkflowManager.d.mts";
16
17
  export * from "./MastraResumeGuard.d.mts";
17
18
  export * from "./MastraGraphExecutionBackend.d.mts";
@@ -29,6 +29,10 @@ export declare const GRAPH_MASTRA_RESUME_STATE_INVALID = "GRAPH_MASTRA_RESUME_ST
29
29
  export declare const GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE = "GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE";
30
30
  /** No Mastra agent is available for an agent-backed node. */
31
31
  export declare const GRAPH_MASTRA_AGENT_UNAVAILABLE = "GRAPH_MASTRA_AGENT_UNAVAILABLE";
32
+ /** The Mastra execute path did not terminate within its run-level timeout. */
33
+ export declare const GRAPH_MASTRA_EXECUTE_TIMEOUT = "GRAPH_MASTRA_EXECUTE_TIMEOUT";
34
+ /** The Mastra execute path was aborted by the caller's cancellation signal. */
35
+ export declare const GRAPH_MASTRA_EXECUTE_ABORTED = "GRAPH_MASTRA_EXECUTE_ABORTED";
32
36
  /** The wired Mastra runtime exposes no workflow-management surface. */
33
37
  export declare const GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE = "GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE";
34
38
  /** A managed workflow id has no workflow registered on the runtime. */
@@ -102,6 +106,14 @@ export interface MastraBackendConfig extends Record<string, unknown> {
102
106
  suspendStateReader?: MastraSuspendStateReader;
103
107
  /** Maximum accepted serialised `resumeData` size, in bytes. */
104
108
  maxResumeBytes?: number;
109
+ /**
110
+ * Run-level terminal timeout, in milliseconds, for {@link MastraGraphExecutionBackend.execute}.
111
+ * A translated run that has not terminated within this bound fails closed with
112
+ * {@link GRAPH_MASTRA_EXECUTE_TIMEOUT} instead of pinning the run slot and event
113
+ * stream indefinitely; mirrors the Dagster `terminalTimeoutMs` bound. Defaults
114
+ * to five minutes when omitted.
115
+ */
116
+ terminalTimeoutMs?: number;
105
117
  }
106
118
  /**
107
119
  * Mastra-authoritative snapshot of a suspended run as exposed by the host's
@@ -29,6 +29,10 @@ export declare const GRAPH_MASTRA_RESUME_STATE_INVALID = "GRAPH_MASTRA_RESUME_ST
29
29
  export declare const GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE = "GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE";
30
30
  /** No Mastra agent is available for an agent-backed node. */
31
31
  export declare const GRAPH_MASTRA_AGENT_UNAVAILABLE = "GRAPH_MASTRA_AGENT_UNAVAILABLE";
32
+ /** The Mastra execute path did not terminate within its run-level timeout. */
33
+ export declare const GRAPH_MASTRA_EXECUTE_TIMEOUT = "GRAPH_MASTRA_EXECUTE_TIMEOUT";
34
+ /** The Mastra execute path was aborted by the caller's cancellation signal. */
35
+ export declare const GRAPH_MASTRA_EXECUTE_ABORTED = "GRAPH_MASTRA_EXECUTE_ABORTED";
32
36
  /** The wired Mastra runtime exposes no workflow-management surface. */
33
37
  export declare const GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE = "GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE";
34
38
  /** A managed workflow id has no workflow registered on the runtime. */
@@ -102,6 +106,14 @@ export interface MastraBackendConfig extends Record<string, unknown> {
102
106
  suspendStateReader?: MastraSuspendStateReader;
103
107
  /** Maximum accepted serialised `resumeData` size, in bytes. */
104
108
  maxResumeBytes?: number;
109
+ /**
110
+ * Run-level terminal timeout, in milliseconds, for {@link MastraGraphExecutionBackend.execute}.
111
+ * A translated run that has not terminated within this bound fails closed with
112
+ * {@link GRAPH_MASTRA_EXECUTE_TIMEOUT} instead of pinning the run slot and event
113
+ * stream indefinitely; mirrors the Dagster `terminalTimeoutMs` bound. Defaults
114
+ * to five minutes when omitted.
115
+ */
116
+ terminalTimeoutMs?: number;
105
117
  }
106
118
  /**
107
119
  * Mastra-authoritative snapshot of a suspended run as exposed by the host's
@@ -1,3 +1,22 @@
1
+ /**
2
+ * @module as-graph/nest/graph/GraphBackendHost
3
+ * @summary Boot-time engine-variant selection for the graph backend host (SAA-706).
4
+ * @description Resolves which of the three pluggable graph engines — the built-in
5
+ * local reference interpreter, the `@mastra/core` translated backend, or the
6
+ * read-only Dagster backend — a host boots, constructs and registers that
7
+ * backend, and assembles the {@link GraphExecutionModule} options that make the
8
+ * Nest host serve the matching C20 capability manifest (`graph/engines`) and the
9
+ * per-engine workflow catalogue (`graph/engines/{engineId}/workflows`).
10
+ *
11
+ * The host never stubs an engine: each variant constructs the real backend. A
12
+ * translated/remote backend whose host wiring is absent (no Mastra runtime, no
13
+ * Dagster client) still boots and serves the manifest; its catalogue then reports
14
+ * the engine's honest `NOT_SUPPORTED` verdict through the engine facade, exactly
15
+ * as `GraphEngineController` maps it to `501`. The variant is chosen at boot by
16
+ * the `GRAPH_BACKEND_ENGINE` environment variable, so switching engines is a
17
+ * configuration change, never a code change.
18
+ */
19
+ import type { GraphWorkflowDocument } from "../../shared/graph/index.d.cts";
1
20
  import type { GraphExecutionBackend } from "../../engine/execution/GraphExecutionBackend.d.cts";
2
21
  import { type MastraBackendConfig } from "../../mastra/types.d.cts";
3
22
  import type { DagsterClient } from "../../dagster/DagsterTypes.d.cts";
@@ -32,6 +51,20 @@ export declare function parseGraphEngineVariant(value: string | undefined, fallb
32
51
  * @returns The resolved engine variant.
33
52
  */
34
53
  export declare function graphEngineVariantFromEnv(env?: NodeJS.ProcessEnv): GraphEngineVariant;
54
+ /** Environment variable gating boot-time demo-workflow seeding (F5 hardening). */
55
+ export declare const GRAPH_SEED_DEMO_ENV = "GRAPH_SEED_DEMO";
56
+ /**
57
+ * Resolves whether the standalone host seeds the demo workflow fixture registry
58
+ * at boot (F5 hardening). Seeding is enabled by default so a source checkout
59
+ * keeps its fixtures; a production host sets `GRAPH_SEED_DEMO=off` (also accepts
60
+ * `false` / `0` / `no` / `disabled`, case-insensitive) to suppress owner-less
61
+ * demo seeding without a code change. An unset or empty value keeps the default
62
+ * (enabled), so existing hosts are unaffected.
63
+ *
64
+ * @param env - The environment to read from (defaults to `process.env`).
65
+ * @returns `true` when boot-time demo seeding is enabled.
66
+ */
67
+ export declare function graphDemoSeedEnabledFromEnv(env?: NodeJS.ProcessEnv): boolean;
35
68
  /** Host wiring for the Dagster variant: the client port plus its gate options. */
36
69
  export interface GraphDagsterHostOptions {
37
70
  /**
@@ -59,6 +92,13 @@ export interface GraphBackendHostOptions {
59
92
  mastra?: MastraBackendConfig;
60
93
  /** Host wiring for the Dagster variant. */
61
94
  dagster?: GraphDagsterHostOptions;
95
+ /**
96
+ * Canonical workflow documents seeded into the selected engine's catalogue at
97
+ * boot (the host's fixture registry). Forwarded to the module options so the
98
+ * per-engine workflow catalogue serves the fixture set for whichever variant
99
+ * the host booted. The seed stays engine-dependent and read-only for Dagster.
100
+ */
101
+ seedWorkflows?: readonly GraphWorkflowDocument[];
62
102
  /**
63
103
  * Existing module options to extend. The host overrides only `backend` and
64
104
  * `engines.defaultEngineId`, so a caller keeps its auth, limits, adapter, and
@@ -96,5 +136,17 @@ export interface GraphBackendHost {
96
136
  * @returns The resolved host, including the module options to boot.
97
137
  */
98
138
  export declare function createGraphBackendHost(options: GraphBackendHostOptions): Promise<GraphBackendHost>;
139
+ /**
140
+ * Loads the host's demo workflow fixture registry for boot-time seeding. This is
141
+ * the engine driver's seeding path (R4): the fixture registry is imported only
142
+ * by tests and by this loader. Because the registry is excluded from release
143
+ * packaging, the loader is best-effort — it returns the fixture documents when
144
+ * the registry is present (a source checkout or development install) and an
145
+ * empty set when it is absent (a published package), never failing the boot.
146
+ *
147
+ * @returns The canonical documents to seed, or an empty array when the registry
148
+ * is unavailable.
149
+ */
150
+ export declare function loadGraphDemoWorkflows(): Promise<readonly GraphWorkflowDocument[]>;
99
151
  /** The allowlisted engine id for a variant (the backend flavour). */
100
152
  export declare function graphEngineIdOf(variant: GraphEngineVariant): string;