@decaf-ts/as-graph 0.4.0 → 0.5.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 (39) hide show
  1. package/README.md +116 -0
  2. package/lib/cjs/dagster/DagsterGraphQLClient.cjs +738 -0
  3. package/lib/cjs/dagster/DagsterGraphQLClient.cjs.map +1 -0
  4. package/lib/cjs/dagster/index.cjs +1 -0
  5. package/lib/cjs/dagster/index.cjs.map +1 -1
  6. package/lib/cjs/nest/graph/GraphBackendHost.cjs +146 -0
  7. package/lib/cjs/nest/graph/GraphBackendHost.cjs.map +1 -0
  8. package/lib/cjs/nest/graph/GraphExecutionModule.cjs +1 -0
  9. package/lib/cjs/nest/graph/GraphExecutionModule.cjs.map +1 -1
  10. package/lib/cjs/nest/graph/index.cjs +1 -0
  11. package/lib/cjs/nest/graph/index.cjs.map +1 -1
  12. package/lib/cjs/nest/graph/main.cjs +97 -12
  13. package/lib/cjs/nest/graph/main.cjs.map +1 -1
  14. package/lib/esm/dagster/DagsterGraphQLClient.js +733 -0
  15. package/lib/esm/dagster/DagsterGraphQLClient.js.map +1 -0
  16. package/lib/esm/dagster/index.js +1 -0
  17. package/lib/esm/dagster/index.js.map +1 -1
  18. package/lib/esm/mastra/MastraCapabilities.js.map +1 -1
  19. package/lib/esm/nest/graph/GraphBackendHost.js +138 -0
  20. package/lib/esm/nest/graph/GraphBackendHost.js.map +1 -0
  21. package/lib/esm/nest/graph/GraphExecutionModule.js +1 -0
  22. package/lib/esm/nest/graph/GraphExecutionModule.js.map +1 -1
  23. package/lib/esm/nest/graph/index.js +1 -0
  24. package/lib/esm/nest/graph/index.js.map +1 -1
  25. package/lib/esm/nest/graph/main.js +64 -12
  26. package/lib/esm/nest/graph/main.js.map +1 -1
  27. package/lib/types/dagster/DagsterGraphQLClient.d.cts +231 -0
  28. package/lib/types/dagster/DagsterGraphQLClient.d.mts +231 -0
  29. package/lib/types/dagster/index.d.cts +1 -0
  30. package/lib/types/dagster/index.d.mts +1 -0
  31. package/lib/types/mastra/MastraCapabilities.d.cts +0 -5
  32. package/lib/types/mastra/MastraCapabilities.d.mts +0 -5
  33. package/lib/types/nest/graph/GraphBackendHost.d.cts +100 -0
  34. package/lib/types/nest/graph/GraphBackendHost.d.mts +100 -0
  35. package/lib/types/nest/graph/GraphExecutionModule.d.cts +12 -0
  36. package/lib/types/nest/graph/GraphExecutionModule.d.mts +12 -0
  37. package/lib/types/nest/graph/index.d.cts +1 -0
  38. package/lib/types/nest/graph/index.d.mts +1 -0
  39. package/package.json +7 -1
@@ -0,0 +1,231 @@
1
+ /**
2
+ * @module as-graph/dagster/DagsterGraphQLClient
3
+ * @summary Real, read-only Dagster GraphQL client implementing the driver's
4
+ * `DagsterClient` port (SAA-306, SAA-706).
5
+ * @description A thin transport that implements the production `DagsterClient`
6
+ * port against a real `dagster-webserver` GraphQL endpoint. It is the only piece
7
+ * of the host that talks to Dagster, so a bootable Dagster host (see
8
+ * `@decaf-ts/as-graph/nest`) can list and inspect an already-deployed deployment.
9
+ * It exposes **no authoring method**: it
10
+ * never emits Python and never registers a job/op. It does implement the port's
11
+ * gated execution surface (`launchRun` of an already-deployed job and
12
+ * `replayRun` of an existing run via Dagster's `launchRunReexecution`), exactly as
13
+ * a host would wire its own transport; the production driver only calls those when
14
+ * its explicit `executionEnabled` gate is on.
15
+ *
16
+ * The client maps the raw GraphQL event vocabulary onto the driver's documented
17
+ * `DagsterEventRecord` contract. Dagster emits far more step-scoped telemetry
18
+ * (`STEP_WORKER_STARTING`, `RESOURCE_INIT_STARTED`, `LOADED_INPUT`, ...) than
19
+ * the canonical event map the driver consumes; those non-graph-transition events
20
+ * are engine telemetry and are intentionally not forwarded, matching the driver's
21
+ * allowlist posture. Only the documented graph-transition event types
22
+ * (`STEP_START`/`STEP_SUCCESS`/`STEP_FAILURE`/`STEP_SKIPPED`/`STEP_OUTPUT` and
23
+ * the run-level terminal events) are surfaced.
24
+ */
25
+ import type { DagsterClient, DagsterEventRecord, DagsterJobRecord, DagsterJobSummary, DagsterLaunchedRun, DagsterLaunchRunRequest, DagsterReplayRunRequest, DagsterRunRecord, DagsterRunSubscription, DagsterRunSubscriptionOptions } from "./DagsterTypes.d.mts";
26
+ /**
27
+ * The fetch implementation a {@link DagsterGraphQLClient} transport is constructed
28
+ * with: the global `fetch` signature. It is named so the type is expressible in
29
+ * JSDoc — a bare `typeof fetch` member type is not parseable — and so a host can
30
+ * inject a stub in tests without changing the transport.
31
+ */
32
+ export type FetchImpl = typeof fetch;
33
+ /** Options for constructing a {@link DagsterGraphQLClient}. */
34
+ export interface DagsterGraphQLClientOptions {
35
+ /** Absolute GraphQL endpoint URL, e.g. `http://127.0.0.1:3300/graphql`. */
36
+ url: string;
37
+ /** Fetch implementation; defaults to the global `fetch`. */
38
+ fetchImpl?: FetchImpl;
39
+ /** Per-request timeout in milliseconds. Defaults to `15000`. */
40
+ requestTimeoutMs?: number;
41
+ /** Repository (code location) selector name. Defaults to `__repository__`. */
42
+ repositoryName?: string;
43
+ /** Repository location name. Defaults to `definitions.py`. */
44
+ repositoryLocationName?: string;
45
+ }
46
+ /**
47
+ * Real, read-only Dagster GraphQL client implementing the production
48
+ * `DagsterClient` port. It never authors a workflow or launches a run.
49
+ */
50
+ export declare class DagsterGraphQLClient implements DagsterClient {
51
+ private readonly url;
52
+ private readonly fetchImpl;
53
+ private readonly requestTimeoutMs;
54
+ private readonly repositoryName;
55
+ private readonly repositoryLocationName;
56
+ /**
57
+ * @param options - Endpoint URL, fetch implementation, timeout, and repository
58
+ * selector.
59
+ */
60
+ constructor(options: DagsterGraphQLClientOptions);
61
+ /**
62
+ * Sends a GraphQL operation and unwraps the `data` envelope, failing loudly
63
+ * on transport, HTTP, or GraphQL errors.
64
+ *
65
+ * @typeParam T - The expected `data` shape.
66
+ * @param query - The GraphQL document.
67
+ * @param variables - Optional operation variables.
68
+ * @param signal - Optional caller signal composed with the request timeout.
69
+ * @returns The response `data`.
70
+ */
71
+ private request;
72
+ /**
73
+ * Lists every already-deployed Dagster job across the served repositories.
74
+ *
75
+ * @returns The deployed job summaries.
76
+ */
77
+ listJobs(): Promise<DagsterJobSummary[]>;
78
+ /**
79
+ * Reads a single already-deployed Dagster job, including its real graph
80
+ * structure (ops, dependencies, asset keys, schedules, sensors).
81
+ *
82
+ * @param jobName - The Dagster job name.
83
+ * @returns The inspected job record.
84
+ */
85
+ getJob(jobName: string): Promise<DagsterJobRecord>;
86
+ /**
87
+ * Replays the recorded event stream of an EXISTING Dagster run and invokes the
88
+ * handler for every documented graph-transition event. The client never launches
89
+ * a run; it only reads a run that already exists.
90
+ *
91
+ * @param runId - The Dagster run id.
92
+ * @param handler - The per-event callback.
93
+ * @param options - Optional signal/event/page bounds.
94
+ * @returns A subscription handle.
95
+ * @throws {GraphExecutionError} `GRAPH_DAGSTER_OBSERVE_ABORTED` when the signal
96
+ * is already aborted before or during the event replay,
97
+ * `GRAPH_DAGSTER_PAGE_LIMIT_EXCEEDED` when the page cap is hit, or
98
+ * `GRAPH_DAGSTER_EVENT_LIMIT_EXCEEDED` when the event cap is hit.
99
+ */
100
+ subscribeRun(runId: string, handler: (event: DagsterEventRecord) => void, options?: DagsterRunSubscriptionOptions): Promise<DagsterRunSubscription>;
101
+ /**
102
+ * Terminates an EXISTING Dagster run through the GraphQL mutation.
103
+ *
104
+ * @param runId - The Dagster run id.
105
+ * @param reason - Optional termination reason (unused by Dagster).
106
+ */
107
+ terminateRun(runId: string, reason?: string): Promise<void>;
108
+ /**
109
+ * Launches a run of an ALREADY-DEPLOYED Dagster job through the real GraphQL
110
+ * `launchRun` mutation. The job must already exist in the deployment; no job or
111
+ * op is authored and no Python is emitted.
112
+ *
113
+ * @param request - The job name, optional raw run config, and optional tags.
114
+ * @returns The launched run's id and initial status.
115
+ */
116
+ launchRun(request: DagsterLaunchRunRequest): Promise<DagsterLaunchedRun>;
117
+ /**
118
+ * Re-executes an EXISTING Dagster run from its run id through the real GraphQL
119
+ * `launchRunReexecution` mutation (Dagster's re-execution surface). The parent
120
+ * run must already exist; no job or op is authored and no Python is emitted.
121
+ *
122
+ * @param request - The parent run id, its job name, and optional tags.
123
+ * @returns The re-executed run's id and initial status.
124
+ */
125
+ replayRun(request: DagsterReplayRunRequest): Promise<DagsterLaunchedRun>;
126
+ /**
127
+ * Builds the GraphQL `ExecutionParams` for a launch/re-execution: the job
128
+ * selector, optional raw run config, and optional run tags.
129
+ *
130
+ * @param jobName - The already-deployed job name.
131
+ * @param runConfig - Optional raw Dagster run config (forwarded verbatim).
132
+ * @param tags - Optional run tags.
133
+ * @returns The `ExecutionParams` input object.
134
+ */
135
+ private executionParams;
136
+ /**
137
+ * Unwraps a launch/re-execution result union into a run handle, failing loudly
138
+ * on a launch error.
139
+ *
140
+ * @param result - The raw launch result union.
141
+ * @param jobName - The job name, for error context.
142
+ * @returns The launched run's id and initial status.
143
+ */
144
+ private toLaunchedRun;
145
+ /**
146
+ * Reads an EXISTING Dagster run's terminal record.
147
+ *
148
+ * @param runId - The Dagster run id.
149
+ * @returns The terminal run record.
150
+ */
151
+ getRun(runId: string): Promise<DagsterRunRecord>;
152
+ /**
153
+ * Harness-only helper: lists the runs for a job (or every run when no job name
154
+ * is given) with their raw Dagster status. Not part of the `DagsterClient` port;
155
+ * it exists so the suite can discover a pre-existing terminal run (e.g. the
156
+ * `etl_pipeline` run materialized at startup) without launching one, and can
157
+ * count runs before/after an operation to prove no run was created.
158
+ *
159
+ * @param jobName - Optional Dagster job name filter.
160
+ * @returns The runs, with raw Dagster run status.
161
+ */
162
+ listRuns(jobName?: string): Promise<{
163
+ runId: string;
164
+ jobName: string;
165
+ status: string;
166
+ }[]>;
167
+ /**
168
+ * Harness-only helper: lists the ids of runs for a job (or every run when no
169
+ * job name is given). Not part of the `DagsterClient` port; it exists so the
170
+ * suite can discover a pre-existing run without launching one.
171
+ *
172
+ * @param jobName - Optional Dagster job name filter.
173
+ * @returns The run ids.
174
+ */
175
+ listRunIds(jobName?: string): Promise<string[]>;
176
+ /** Disposes the client; the fetch transport holds no resources. */
177
+ dispose(): void;
178
+ /**
179
+ * Paginates the run's recorded event stream, bounded by `maxPages` and
180
+ * `maxEvents` so a gateway whose `eventConnection` never reports
181
+ * `hasMore: false` cannot page or buffer without limit.
182
+ *
183
+ * @param runId - The Dagster run id.
184
+ * @param options - Optional signal/event/page bounds.
185
+ * @returns The raw events, in order.
186
+ * @throws {GraphExecutionError} `GRAPH_DAGSTER_PAGE_LIMIT_EXCEEDED` when the
187
+ * page cap is hit, or `GRAPH_DAGSTER_EVENT_LIMIT_EXCEEDED` when the event cap
188
+ * is hit.
189
+ */
190
+ private fetchRunEvents;
191
+ /**
192
+ * Maps a raw Dagster event onto the driver's documented `DagsterEventRecord`
193
+ * contract, filtering out non-graph-transition telemetry.
194
+ *
195
+ * @param event - The raw event.
196
+ * @returns The driver event record, or `undefined` when the event is engine
197
+ * telemetry the read-only driver does not consume.
198
+ */
199
+ private toEventRecord;
200
+ /**
201
+ * Maps a raw `Run` onto the driver's `DagsterRunRecord` contract.
202
+ *
203
+ * @param run - The raw run.
204
+ * @returns The driver run record.
205
+ */
206
+ private toRunRecord;
207
+ /**
208
+ * Maps a Dagster `RunStatus` onto the driver's terminal run status.
209
+ *
210
+ * @param status - The raw Dagster run status.
211
+ * @returns The driver run status.
212
+ */
213
+ private toRunStatus;
214
+ /**
215
+ * Maps a raw job plus its repository context onto the driver's
216
+ * `DagsterJobRecord` contract.
217
+ *
218
+ * @param job - The raw job.
219
+ * @param repository - The raw repository the job belongs to.
220
+ * @returns The inspected job record.
221
+ */
222
+ private toJobRecord;
223
+ /**
224
+ * Resolves the asset keys a job produces from the repository's asset nodes.
225
+ *
226
+ * @param jobName - The Dagster job name.
227
+ * @param assetNodes - The repository asset nodes.
228
+ * @returns The dotted asset keys.
229
+ */
230
+ private assetKeysFor;
231
+ }
@@ -9,6 +9,7 @@
9
9
  export * from "./constants.d.cts";
10
10
  export * from "./DagsterTypes.d.cts";
11
11
  export * from "./capabilities.d.cts";
12
+ export * from "./DagsterGraphQLClient.d.cts";
12
13
  export * from "./DagsterGraphEventBridge.d.cts";
13
14
  export * from "./DagsterResultMapper.d.cts";
14
15
  export * from "./DagsterGraphExecutionBackend.d.cts";
@@ -9,6 +9,7 @@
9
9
  export * from "./constants.d.mts";
10
10
  export * from "./DagsterTypes.d.mts";
11
11
  export * from "./capabilities.d.mts";
12
+ export * from "./DagsterGraphQLClient.d.mts";
12
13
  export * from "./DagsterGraphEventBridge.d.mts";
13
14
  export * from "./DagsterResultMapper.d.mts";
14
15
  export * from "./DagsterGraphExecutionBackend.d.mts";
@@ -56,11 +56,6 @@ export interface MastraWorkflowManagementCapabilities {
56
56
  /** Native workflow versioning support. */
57
57
  version: MastraWorkflowCapabilityStatus;
58
58
  }
59
- /**
60
- * The full Mastra backend capability projection: the engine-agnostic
61
- * {@link GraphBackendCapabilities} plus the Mastra-specific workflow-management
62
- * statuses.
63
- */
64
59
  export interface MastraBackendCapabilities extends GraphBackendCapabilities {
65
60
  /** Workflow list/lookup plus the management statuses. */
66
61
  workflows: GraphBackendCapabilities["workflows"] & MastraWorkflowManagementCapabilities;
@@ -56,11 +56,6 @@ export interface MastraWorkflowManagementCapabilities {
56
56
  /** Native workflow versioning support. */
57
57
  version: MastraWorkflowCapabilityStatus;
58
58
  }
59
- /**
60
- * The full Mastra backend capability projection: the engine-agnostic
61
- * {@link GraphBackendCapabilities} plus the Mastra-specific workflow-management
62
- * statuses.
63
- */
64
59
  export interface MastraBackendCapabilities extends GraphBackendCapabilities {
65
60
  /** Workflow list/lookup plus the management statuses. */
66
61
  workflows: GraphBackendCapabilities["workflows"] & MastraWorkflowManagementCapabilities;
@@ -0,0 +1,100 @@
1
+ import type { GraphExecutionBackend } from "../../engine/execution/GraphExecutionBackend.d.cts";
2
+ import { type MastraBackendConfig } from "../../mastra/types.d.cts";
3
+ import type { DagsterClient } from "../../dagster/DagsterTypes.d.cts";
4
+ import type { GraphExecutionModuleOptions } from "./GraphExecutionModule.d.cts";
5
+ /**
6
+ * The graph engine variants a host can boot. Each maps one-to-one onto the
7
+ * backend flavour it registers, which is also the allowlisted engine id the C20
8
+ * manifest advertises.
9
+ */
10
+ export type GraphEngineVariant = "local" | "mastra" | "dagster";
11
+ /** Every bootable engine variant, in manifest order. */
12
+ export declare const GRAPH_ENGINE_VARIANTS: readonly GraphEngineVariant[];
13
+ /** Environment variable selecting the engine variant the host boots. */
14
+ export declare const GRAPH_BACKEND_ENGINE_ENV = "GRAPH_BACKEND_ENGINE";
15
+ /** The engine variant a host boots when none is configured. */
16
+ export declare const DEFAULT_GRAPH_ENGINE_VARIANT: GraphEngineVariant;
17
+ /**
18
+ * Parses a configured engine variant, failing closed on an unknown value so a
19
+ * typo never silently boots the wrong engine.
20
+ *
21
+ * @param value - The raw configured value (`undefined`/empty selects the fallback).
22
+ * @param fallback - The variant to use when no value is configured.
23
+ * @returns The resolved engine variant.
24
+ * @throws {GraphExecutionError} when the value names no known variant.
25
+ */
26
+ export declare function parseGraphEngineVariant(value: string | undefined, fallback?: GraphEngineVariant): GraphEngineVariant;
27
+ /**
28
+ * Reads the engine variant from an environment bag (defaults to `process.env`),
29
+ * applying {@link parseGraphEngineVariant}.
30
+ *
31
+ * @param env - The environment to read from.
32
+ * @returns The resolved engine variant.
33
+ */
34
+ export declare function graphEngineVariantFromEnv(env?: NodeJS.ProcessEnv): GraphEngineVariant;
35
+ /** Host wiring for the Dagster variant: the client port plus its gate options. */
36
+ export interface GraphDagsterHostOptions {
37
+ /**
38
+ * The read-only Dagster client port. When omitted the backend still boots and
39
+ * serves the manifest, but its catalogue reports `NOT_SUPPORTED` because no
40
+ * deployment transport is wired.
41
+ */
42
+ client?: DagsterClient;
43
+ /** Opt-in gate for launching/replaying EXISTING workflows. Defaults to off. */
44
+ executionEnabled?: boolean;
45
+ /** Host-supplied default run tags. */
46
+ tags?: Record<string, string>;
47
+ }
48
+ /**
49
+ * Options for {@link createGraphBackendHost}: the selected variant plus the
50
+ * per-variant host wiring. Unused wiring for the unselected variant is ignored.
51
+ */
52
+ export interface GraphBackendHostOptions {
53
+ /** The engine variant to boot. */
54
+ variant: GraphEngineVariant;
55
+ /**
56
+ * Host wiring for the Mastra variant: the real `@mastra/core` runtime and the
57
+ * node-kind step handlers. Absent wiring boots a catalogue-less Mastra host.
58
+ */
59
+ mastra?: MastraBackendConfig;
60
+ /** Host wiring for the Dagster variant. */
61
+ dagster?: GraphDagsterHostOptions;
62
+ /**
63
+ * Existing module options to extend. The host overrides only `backend` and
64
+ * `engines.defaultEngineId`, so a caller keeps its auth, limits, adapter, and
65
+ * rate-limit configuration.
66
+ */
67
+ base?: GraphExecutionModuleOptions;
68
+ }
69
+ /**
70
+ * The result of {@link createGraphBackendHost}: the resolved variant, the
71
+ * allowlisted engine id it advertises, the constructed backend (absent for the
72
+ * local variant, which the engine constructs itself), and the assembled module
73
+ * options ready for `GraphExecutionModule.forRoot`.
74
+ */
75
+ export interface GraphBackendHost {
76
+ /** The resolved engine variant. */
77
+ variant: GraphEngineVariant;
78
+ /** The allowlisted engine id the manifest advertises for this variant. */
79
+ engineId: string;
80
+ /**
81
+ * The constructed backend the host selected, or `undefined` for the local
82
+ * variant (the engine constructs the built-in backend itself).
83
+ */
84
+ backend?: GraphExecutionBackend;
85
+ /** Module options carrying the selected backend and default engine id. */
86
+ moduleOptions: GraphExecutionModuleOptions;
87
+ }
88
+ /**
89
+ * Builds the bootable graph backend host for one engine variant: constructs and
90
+ * registers the selected backend, selects it as the registry current so the
91
+ * engine facade's default engine follows the variant, and assembles the
92
+ * {@link GraphExecutionModule} options that advertise that engine's capability
93
+ * manifest and per-engine workflow catalogue.
94
+ *
95
+ * @param options - The host options (variant, per-variant wiring, base options).
96
+ * @returns The resolved host, including the module options to boot.
97
+ */
98
+ export declare function createGraphBackendHost(options: GraphBackendHostOptions): Promise<GraphBackendHost>;
99
+ /** The allowlisted engine id for a variant (the backend flavour). */
100
+ export declare function graphEngineIdOf(variant: GraphEngineVariant): string;
@@ -0,0 +1,100 @@
1
+ import type { GraphExecutionBackend } from "../../engine/execution/GraphExecutionBackend.d.mts";
2
+ import { type MastraBackendConfig } from "../../mastra/types.d.mts";
3
+ import type { DagsterClient } from "../../dagster/DagsterTypes.d.mts";
4
+ import type { GraphExecutionModuleOptions } from "./GraphExecutionModule.d.mts";
5
+ /**
6
+ * The graph engine variants a host can boot. Each maps one-to-one onto the
7
+ * backend flavour it registers, which is also the allowlisted engine id the C20
8
+ * manifest advertises.
9
+ */
10
+ export type GraphEngineVariant = "local" | "mastra" | "dagster";
11
+ /** Every bootable engine variant, in manifest order. */
12
+ export declare const GRAPH_ENGINE_VARIANTS: readonly GraphEngineVariant[];
13
+ /** Environment variable selecting the engine variant the host boots. */
14
+ export declare const GRAPH_BACKEND_ENGINE_ENV = "GRAPH_BACKEND_ENGINE";
15
+ /** The engine variant a host boots when none is configured. */
16
+ export declare const DEFAULT_GRAPH_ENGINE_VARIANT: GraphEngineVariant;
17
+ /**
18
+ * Parses a configured engine variant, failing closed on an unknown value so a
19
+ * typo never silently boots the wrong engine.
20
+ *
21
+ * @param value - The raw configured value (`undefined`/empty selects the fallback).
22
+ * @param fallback - The variant to use when no value is configured.
23
+ * @returns The resolved engine variant.
24
+ * @throws {GraphExecutionError} when the value names no known variant.
25
+ */
26
+ export declare function parseGraphEngineVariant(value: string | undefined, fallback?: GraphEngineVariant): GraphEngineVariant;
27
+ /**
28
+ * Reads the engine variant from an environment bag (defaults to `process.env`),
29
+ * applying {@link parseGraphEngineVariant}.
30
+ *
31
+ * @param env - The environment to read from.
32
+ * @returns The resolved engine variant.
33
+ */
34
+ export declare function graphEngineVariantFromEnv(env?: NodeJS.ProcessEnv): GraphEngineVariant;
35
+ /** Host wiring for the Dagster variant: the client port plus its gate options. */
36
+ export interface GraphDagsterHostOptions {
37
+ /**
38
+ * The read-only Dagster client port. When omitted the backend still boots and
39
+ * serves the manifest, but its catalogue reports `NOT_SUPPORTED` because no
40
+ * deployment transport is wired.
41
+ */
42
+ client?: DagsterClient;
43
+ /** Opt-in gate for launching/replaying EXISTING workflows. Defaults to off. */
44
+ executionEnabled?: boolean;
45
+ /** Host-supplied default run tags. */
46
+ tags?: Record<string, string>;
47
+ }
48
+ /**
49
+ * Options for {@link createGraphBackendHost}: the selected variant plus the
50
+ * per-variant host wiring. Unused wiring for the unselected variant is ignored.
51
+ */
52
+ export interface GraphBackendHostOptions {
53
+ /** The engine variant to boot. */
54
+ variant: GraphEngineVariant;
55
+ /**
56
+ * Host wiring for the Mastra variant: the real `@mastra/core` runtime and the
57
+ * node-kind step handlers. Absent wiring boots a catalogue-less Mastra host.
58
+ */
59
+ mastra?: MastraBackendConfig;
60
+ /** Host wiring for the Dagster variant. */
61
+ dagster?: GraphDagsterHostOptions;
62
+ /**
63
+ * Existing module options to extend. The host overrides only `backend` and
64
+ * `engines.defaultEngineId`, so a caller keeps its auth, limits, adapter, and
65
+ * rate-limit configuration.
66
+ */
67
+ base?: GraphExecutionModuleOptions;
68
+ }
69
+ /**
70
+ * The result of {@link createGraphBackendHost}: the resolved variant, the
71
+ * allowlisted engine id it advertises, the constructed backend (absent for the
72
+ * local variant, which the engine constructs itself), and the assembled module
73
+ * options ready for `GraphExecutionModule.forRoot`.
74
+ */
75
+ export interface GraphBackendHost {
76
+ /** The resolved engine variant. */
77
+ variant: GraphEngineVariant;
78
+ /** The allowlisted engine id the manifest advertises for this variant. */
79
+ engineId: string;
80
+ /**
81
+ * The constructed backend the host selected, or `undefined` for the local
82
+ * variant (the engine constructs the built-in backend itself).
83
+ */
84
+ backend?: GraphExecutionBackend;
85
+ /** Module options carrying the selected backend and default engine id. */
86
+ moduleOptions: GraphExecutionModuleOptions;
87
+ }
88
+ /**
89
+ * Builds the bootable graph backend host for one engine variant: constructs and
90
+ * registers the selected backend, selects it as the registry current so the
91
+ * engine facade's default engine follows the variant, and assembles the
92
+ * {@link GraphExecutionModule} options that advertise that engine's capability
93
+ * manifest and per-engine workflow catalogue.
94
+ *
95
+ * @param options - The host options (variant, per-variant wiring, base options).
96
+ * @returns The resolved host, including the module options to boot.
97
+ */
98
+ export declare function createGraphBackendHost(options: GraphBackendHostOptions): Promise<GraphBackendHost>;
99
+ /** The allowlisted engine id for a variant (the backend flavour). */
100
+ export declare function graphEngineIdOf(variant: GraphEngineVariant): string;
@@ -11,6 +11,7 @@
11
11
  import { DynamicModule, Type } from "@nestjs/common";
12
12
  import type { AuthHandler } from "@decaf-ts/for-http/server";
13
13
  import { Adapter } from "@decaf-ts/core";
14
+ import type { GraphExecutionBackend } from "../../engine/execution/GraphExecutionBackend.d.cts";
14
15
  import { type GraphCredentialAuthorizer, type GraphNamespaceMatchOptions } from "../..//index.d.cts";
15
16
  import { type GraphCatalogueControllerOptions } from "./GraphNodeCatalogueController.d.cts";
16
17
  import { type GraphRunControllerOptions } from "./GraphRunController.d.cts";
@@ -66,6 +67,17 @@ export interface GraphExecutionModuleOptions {
66
67
  * registered backends and never read from the environment or a remote engine.
67
68
  */
68
69
  engines?: GraphEngineCapabilityOptions;
70
+ /**
71
+ * Pluggable execution backend the host selects as the engine's active backend
72
+ * (SAA-706). When omitted the engine falls back to the registry's current
73
+ * backend and then to the built-in {@link LocalGraphExecutionBackend}, so the
74
+ * standard local host needs no wiring. A host that boots a translated/remote
75
+ * engine (Mastra, Dagster) constructs its backend, registers it, and passes it
76
+ * here; the capability manifest then advertises that engine's flavour. The
77
+ * backend must already be registered under its flavour (constructing the
78
+ * wrapper does this) so the manifest and the per-engine catalogue agree.
79
+ */
80
+ backend?: GraphExecutionBackend<any>;
69
81
  /**
70
82
  * Production hosts MUST wire a {@link GraphCredentialAuthorizer} backed by
71
83
  * their credential store (DECAF-50 §4.8 stage 8). Without it, stage-8
@@ -11,6 +11,7 @@
11
11
  import { DynamicModule, Type } from "@nestjs/common";
12
12
  import type { AuthHandler } from "@decaf-ts/for-http/server";
13
13
  import { Adapter } from "@decaf-ts/core";
14
+ import type { GraphExecutionBackend } from "../../engine/execution/GraphExecutionBackend.d.mts";
14
15
  import { type GraphCredentialAuthorizer, type GraphNamespaceMatchOptions } from "../..//index.d.mts";
15
16
  import { type GraphCatalogueControllerOptions } from "./GraphNodeCatalogueController.d.mts";
16
17
  import { type GraphRunControllerOptions } from "./GraphRunController.d.mts";
@@ -66,6 +67,17 @@ export interface GraphExecutionModuleOptions {
66
67
  * registered backends and never read from the environment or a remote engine.
67
68
  */
68
69
  engines?: GraphEngineCapabilityOptions;
70
+ /**
71
+ * Pluggable execution backend the host selects as the engine's active backend
72
+ * (SAA-706). When omitted the engine falls back to the registry's current
73
+ * backend and then to the built-in {@link LocalGraphExecutionBackend}, so the
74
+ * standard local host needs no wiring. A host that boots a translated/remote
75
+ * engine (Mastra, Dagster) constructs its backend, registers it, and passes it
76
+ * here; the capability manifest then advertises that engine's flavour. The
77
+ * backend must already be registered under its flavour (constructing the
78
+ * wrapper does this) so the manifest and the per-engine catalogue agree.
79
+ */
80
+ backend?: GraphExecutionBackend<any>;
69
81
  /**
70
82
  * Production hosts MUST wire a {@link GraphCredentialAuthorizer} backed by
71
83
  * their credential store (DECAF-50 §4.8 stage 8). Without it, stage-8
@@ -13,3 +13,4 @@ export * from "./GraphEngineCapabilityManifest.d.cts";
13
13
  export * from "./GraphEngineCapabilityService.d.cts";
14
14
  export * from "./GraphEngineController.d.cts";
15
15
  export * from "./GraphExecutionModule.d.cts";
16
+ export * from "./GraphBackendHost.d.cts";
@@ -13,3 +13,4 @@ export * from "./GraphEngineCapabilityManifest.d.mts";
13
13
  export * from "./GraphEngineCapabilityService.d.mts";
14
14
  export * from "./GraphEngineController.d.mts";
15
15
  export * from "./GraphExecutionModule.d.mts";
16
+ export * from "./GraphBackendHost.d.mts";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@decaf-ts/as-graph",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Workflow document model, node catalogue and reference execution engine for Decaf graph workflows",
5
5
  "type": "module",
6
6
  "exports": {
@@ -91,9 +91,15 @@
91
91
  "reset": "rm -rf * && git checkout . && git pull && npm run do-install",
92
92
  "build": "build-scripts --dev",
93
93
  "build:prod": "build-scripts --prod",
94
+ "start:backend": "node ./lib/cjs/nest/graph/main.cjs",
95
+ "start:backend:local": "GRAPH_BACKEND_ENGINE=local node ./lib/cjs/nest/graph/main.cjs",
96
+ "start:backend:mastra": "GRAPH_BACKEND_ENGINE=mastra node ./lib/cjs/nest/graph/main.cjs",
97
+ "start:backend:dagster": "GRAPH_BACKEND_ENGINE=dagster node ./lib/cjs/nest/graph/main.cjs",
94
98
  "test": "npm run test:all",
95
99
  "test:unit": "jest --testPathPatterns=\"/tests/unit\" --passWithNoTests --detectOpenHandles",
96
100
  "test:integration": "jest --testPathPatterns=\"/tests/(integration)\" --passWithNoTests --detectOpenHandles",
101
+ "test:integration:standard": "jest --testPathPatterns=\"/tests/integration/graph\" --passWithNoTests --detectOpenHandles",
102
+ "test:integration:backend": "jest --testPathPatterns=\"/tests/integration/nest\" --passWithNoTests --detectOpenHandles",
97
103
  "test:integration:mastra": "jest --testPathPatterns=\"/tests/integration/mastra\" --passWithNoTests --detectOpenHandles",
98
104
  "test:integration:dagster": "bash tests/integration/dagster/run.sh",
99
105
  "test:e2e": "jest --testPathPatterns=\"/tests/(e2e)\" --passWithNoTests --detectOpenHandles",