@decaf-ts/integrations 0.3.10 → 0.3.12

package/lib/types/graph/engine/execution/IsolatedVmCodeSandboxEvaluator.d.mts

@@ -0,0 +1,63 @@
+import type { CodeSandboxEvaluator, CodeSandboxContext } from "./CodeSandboxEvaluator.d.mts";
+/**
+ * `isolated-vm`-backed {@link CodeSandboxEvaluator} (ALFRED-5 §7.18).
+ *
+ * This evaluator provides a truly isolated V8 sandbox — the code runs in a
+ * separate isolate with its own heap, separate from the host process. The
+ * sandbox context exposes only the data variables (`$input`, `$vars`, `$item`,
+ * `$index`, `$node`, `$output`); no host globals are available.
+ *
+ * Execution pipeline:
+ * 1. **Transpile** — TypeScript code is transpiled to JavaScript via
+ *    `typescript.transpileModule` (ALFRED-5 §7.4).
+ * 2. **Validate** — the JavaScript code is parsed with `acorn` and walked with
+ *    `acorn-walk` to reject imports, exports, blocked identifiers, `eval()`,
+ *    and `new Function()` (ALFRED-5 §7.11).
+ * 3. **Isolate** — a new `isolated-vm` `Isolate` is created with a memory
+ *    limit. A context is created and the data variables are copied into the
+ *    isolate's heap via `ExternalCopy`.
+ * 4. **Compile & run** — the wrapped code is compiled and executed with a
+ *    timeout. The result is copied back to the host heap.
+ * 5. **Dispose** — the isolate is always disposed in a `finally` block.
+ *
+ * The user code is wrapped in a strict-mode async function:
+ *
+ * ```js
+ * "use strict";
+ * async function __userFunction($input, $vars, $item, $index, $node, $output) {
+ *   <user code>
+ * }
+ * __userFunction($input, $vars, $item, $index, $node, $output);
+ * ```
+ *
+ * When the code has no `return` statement it is treated as a single expression
+ * and wrapped in `return (...)`.
+ */
+export declare class IsolatedVmCodeSandboxEvaluator implements CodeSandboxEvaluator {
+    private readonly defaultTimeoutMs;
+    private readonly defaultMemoryMb;
+    /**
+     * @param defaultTimeoutMs - Default execution timeout in milliseconds.
+     * @param defaultMemoryMb - Default isolate memory limit in MB.
+     */
+    constructor(defaultTimeoutMs?: number, defaultMemoryMb?: number);
+    evaluate(ctx: CodeSandboxContext): Promise<unknown>;
+    /**
+     * Injects a `console` object into the isolate whose methods forward to the
+     * Context logger (bound to `runId`).
+     *
+     * Every standard `console.*` method is supported:
+     * `log`, `info`, `warn`, `error`, `debug`, `trace`, `dir`, `dirxml`,
+     * `table`, `group`, `groupCollapsed`, `groupEnd`, `time`, `timeEnd`,
+     * `timeLog`, `assert`, `count`, `countReset`, `clear`.
+     *
+     * Arguments are serialised inside the isolate (via `JSON.stringify` with a
+     * safe fallback) before being passed across the isolate boundary, because
+     * `isolated-vm` cannot copy arbitrary host objects.
+     *
+     * @param jail - The isolate's global object.
+     * @param logger - The Context logger that receives the forwarded calls.
+     * @param context - The isolate context (for running the init script).
+     */
+    private injectConsole;
+}

package/lib/types/graph/engine/execution/LogGraphNodeExecutor.d.cts

@@ -0,0 +1,19 @@
+/**
+ * @module integrations/graph/execution/LogGraphNodeExecutor
+ * @summary Executor for the Log flow-control node.
+ * @description Logs the input value via the execution context's logger and
+ * forwards it unchanged on the `logged` output port. Useful for debugging,
+ * audit trails, and discard/side-effect branches in a workflow.
+ */
+import type { GraphNodeExecutor } from "./GraphNodeExecutor.d.cts";
+import type { GraphExecutionContext } from "./GraphExecutionContext.d.cts";
+import type { GraphExecutionValues } from "../types.d.cts";
+/**
+ * Executor for `core.flow.log` nodes.
+ *
+ * Reads the `value` input port, logs it through `context.log()`, and returns
+ * it unchanged on the `logged` output port.
+ */
+export declare class LogGraphNodeExecutor implements GraphNodeExecutor {
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+}

package/lib/types/graph/engine/execution/LogGraphNodeExecutor.d.mts

@@ -0,0 +1,19 @@
+/**
+ * @module integrations/graph/execution/LogGraphNodeExecutor
+ * @summary Executor for the Log flow-control node.
+ * @description Logs the input value via the execution context's logger and
+ * forwards it unchanged on the `logged` output port. Useful for debugging,
+ * audit trails, and discard/side-effect branches in a workflow.
+ */
+import type { GraphNodeExecutor } from "./GraphNodeExecutor.d.mts";
+import type { GraphExecutionContext } from "./GraphExecutionContext.d.mts";
+import type { GraphExecutionValues } from "../types.d.mts";
+/**
+ * Executor for `core.flow.log` nodes.
+ *
+ * Reads the `value` input port, logs it through `context.log()`, and returns
+ * it unchanged on the `logged` output port.
+ */
+export declare class LogGraphNodeExecutor implements GraphNodeExecutor {
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+}

package/lib/types/graph/engine/execution/SwitchGraphNodeExecutor.d.cts

@@ -15,8 +15,9 @@ import type { CodeSandboxEvaluator } from "./CodeSandboxEvaluator.d.cts";
  * Executor for `core.flow.switch` nodes.
  *
  * Evaluates each case's condition in order and routes the input to the
- * first matching case's output port. When no case matches, routes to the
- * `default` output port.
+ * first matching case's output port. When no case matches:
+ * - If `hasDefault` is `true` (or omitted), routes to the `default` output port.
+ * - If `hasDefault` is `false`, returns an empty output (the input is dropped).
  *
  * Condition evaluation:
  * - `ConditionExpression` — evaluated via {@link ConditionExpressionEvaluator}.

package/lib/types/graph/engine/execution/SwitchGraphNodeExecutor.d.mts

@@ -15,8 +15,9 @@ import type { CodeSandboxEvaluator } from "./CodeSandboxEvaluator.d.mts";
  * Executor for `core.flow.switch` nodes.
  *
  * Evaluates each case's condition in order and routes the input to the
- * first matching case's output port. When no case matches, routes to the
- * `default` output port.
+ * first matching case's output port. When no case matches:
+ * - If `hasDefault` is `true` (or omitted), routes to the `default` output port.
+ * - If `hasDefault` is `false`, returns an empty output (the input is dropped).
  *
  * Condition evaluation:
  * - `ConditionExpression` — evaluated via {@link ConditionExpressionEvaluator}.

package/lib/types/graph/engine/execution/index.d.cts

@@ -10,3 +10,6 @@ export * from "./GraphExecutionFrame.d.cts";
 export * from "./GraphExecutionEngine.d.cts";
 export * from "./CodeSandboxEvaluator.d.cts";
 export * from "./SwitchGraphNodeExecutor.d.cts";
+export * from "./CodeGraphNodeExecutor.d.cts";
+export * from "./LogGraphNodeExecutor.d.cts";
+export * from "./IsolatedVmCodeSandboxEvaluator.d.cts";

package/lib/types/graph/engine/execution/index.d.mts

@@ -10,3 +10,6 @@ export * from "./GraphExecutionFrame.d.mts";
 export * from "./GraphExecutionEngine.d.mts";
 export * from "./CodeSandboxEvaluator.d.mts";
 export * from "./SwitchGraphNodeExecutor.d.mts";
+export * from "./CodeGraphNodeExecutor.d.mts";
+export * from "./LogGraphNodeExecutor.d.mts";
+export * from "./IsolatedVmCodeSandboxEvaluator.d.mts";

package/lib/types/graph/engine/index.d.cts

@@ -31,6 +31,9 @@ export * from "./execution/GraphExecutionResult.d.cts";
 export * from "./execution/GraphExecutionEngine.d.cts";
 export * from "./execution/CodeSandboxEvaluator.d.cts";
 export * from "./execution/SwitchGraphNodeExecutor.d.cts";
+export * from "./execution/CodeGraphNodeExecutor.d.cts";
+export * from "./execution/LogGraphNodeExecutor.d.cts";
+export * from "./execution/IsolatedVmCodeSandboxEvaluator.d.cts";
 export * from "./registry/GraphNodeExecutorRegistry.d.cts";
 export * from "./registry/GraphNodeExecutorResolver.d.cts";
 export * from "./store/GraphValueKey.d.cts";

package/lib/types/graph/engine/index.d.mts

@@ -31,6 +31,9 @@ export * from "./execution/GraphExecutionResult.d.mts";
 export * from "./execution/GraphExecutionEngine.d.mts";
 export * from "./execution/CodeSandboxEvaluator.d.mts";
 export * from "./execution/SwitchGraphNodeExecutor.d.mts";
+export * from "./execution/CodeGraphNodeExecutor.d.mts";
+export * from "./execution/LogGraphNodeExecutor.d.mts";
+export * from "./execution/IsolatedVmCodeSandboxEvaluator.d.mts";
 export * from "./registry/GraphNodeExecutorRegistry.d.mts";
 export * from "./registry/GraphNodeExecutorResolver.d.mts";
 export * from "./store/GraphValueKey.d.mts";

package/lib/types/graph/shared/nodes/flow-control.d.cts

@@ -38,7 +38,9 @@ export declare class SwitchFlowNode extends GraphNode {
     /**
      * Computes the node's ports, size, and data patch from the given switch
      * metadata. Each case gets its own output port on the right side; the
-     * node grows in height as cases are added.
+     * `default` port always renders **last** (DECAF-32 §21 port-ordering rule,
+     * DECAF-34 §6.2). When `hasDefault` is `false`, the `default` output port
+     * is omitted entirely. The node grows in height as cases are added.
      */
     static applyMetadata(meta: SwitchNodeMetadata): NodeMetadataChange;
 }
@@ -94,19 +96,44 @@ export declare class ReturnFlowNode extends Model {
     result: unknown;
 }
 /**
- * Code — sandboxed JS/TS code execution (ALFRED-5 §7).
+ * Code — sandboxed JS/TS code execution (ALFRED-5 §7, DECAF-32 §22.4).
  *
- * The engine does not implement the sandbox directly (§22.4). A future
- * executor may wrap the `CodeSandbox` contract (ALFRED-5 §7.17) as a
- * pluggable executor. The placeholder syntax (`{{ $input }}`, `{{ $item }}`,
- * `{{ $index }}`, `{{ $vars }}`, `{{ $node["Name"].output }}`) is Mastra-
- * agnostic and lives in the downstream project's `modules/core` (ALFRED-6).
+ * The engine's {@link CodeGraphNodeExecutor} delegates to the pluggable
+ * {@link CodeSandboxEvaluator}. The default
+ * `IsolatedVmCodeSandboxEvaluator` (backed by `isolated-vm`) enforces the
+ * Code Node restrictions: no imports, no requires, pure functions only. The
+ * sandbox context exposes `$input`, `$vars`, `$item`, `$index`, `$node`, and
+ * `$output` as data variables. TypeScript is supported via transpilation.
  */
+/**
+ * Input schema for the Code node. The `@input` on `CodeFlowNode.input` is a
+ * schema group — the nested model's `@input` ports are spliced into the
+ * parent unprefixed. `code` has `@input` + `@uielement("code-editor")`, so it
+ * appears as a port AND in the CRUD modal (the only visible field). `data`
+ * has `@input` + `@hidden()` but no `@uielement`, so it is a canvas-only port
+ * (for edge connections from workflow input badges) but never appears in the
+ * CRUD modal. `language` has no `@input` and no `@uielement`, so it is
+ * neither a port nor rendered — it defaults to `"javascript"`.
+ */
+export declare class CodeInputSchema extends Model {
+    language: string;
+    code: string;
+    data?: unknown;
+}
 export declare class CodeFlowNode extends Model {
-    input: unknown;
+    input: CodeInputSchema;
     result: unknown;
 }
+/**
+ * Log — logs the input value and forwards it unchanged on the `logged`
+ * output port. Useful for debugging, audit trails, and discard/side-effect
+ * branches in a workflow.
+ */
+export declare class LogFlowNode extends Model {
+    value: unknown;
+    logged: unknown;
+}
 /**
  * All built-in flow-control node constructors.
  */
-export declare const GRAPH_FLOW_CONTROL_NODES: readonly [typeof IfFlowNode, typeof SwitchFlowNode, typeof ParallelFlowNode, typeof MergeFlowNode, typeof MapFlowNode, typeof DelayFlowNode, typeof ErrorBoundaryFlowNode, typeof HumanApprovalFlowNode, typeof ReturnFlowNode, typeof CodeFlowNode];
+export declare const GRAPH_FLOW_CONTROL_NODES: readonly [typeof IfFlowNode, typeof SwitchFlowNode, typeof ParallelFlowNode, typeof MergeFlowNode, typeof MapFlowNode, typeof DelayFlowNode, typeof ErrorBoundaryFlowNode, typeof HumanApprovalFlowNode, typeof ReturnFlowNode, typeof CodeFlowNode, typeof LogFlowNode];

package/lib/types/graph/shared/nodes/flow-control.d.mts

@@ -38,7 +38,9 @@ export declare class SwitchFlowNode extends GraphNode {
     /**
      * Computes the node's ports, size, and data patch from the given switch
      * metadata. Each case gets its own output port on the right side; the
-     * node grows in height as cases are added.
+     * `default` port always renders **last** (DECAF-32 §21 port-ordering rule,
+     * DECAF-34 §6.2). When `hasDefault` is `false`, the `default` output port
+     * is omitted entirely. The node grows in height as cases are added.
      */
     static applyMetadata(meta: SwitchNodeMetadata): NodeMetadataChange;
 }
@@ -94,19 +96,44 @@ export declare class ReturnFlowNode extends Model {
     result: unknown;
 }
 /**
- * Code — sandboxed JS/TS code execution (ALFRED-5 §7).
+ * Code — sandboxed JS/TS code execution (ALFRED-5 §7, DECAF-32 §22.4).
  *
- * The engine does not implement the sandbox directly (§22.4). A future
- * executor may wrap the `CodeSandbox` contract (ALFRED-5 §7.17) as a
- * pluggable executor. The placeholder syntax (`{{ $input }}`, `{{ $item }}`,
- * `{{ $index }}`, `{{ $vars }}`, `{{ $node["Name"].output }}`) is Mastra-
- * agnostic and lives in the downstream project's `modules/core` (ALFRED-6).
+ * The engine's {@link CodeGraphNodeExecutor} delegates to the pluggable
+ * {@link CodeSandboxEvaluator}. The default
+ * `IsolatedVmCodeSandboxEvaluator` (backed by `isolated-vm`) enforces the
+ * Code Node restrictions: no imports, no requires, pure functions only. The
+ * sandbox context exposes `$input`, `$vars`, `$item`, `$index`, `$node`, and
+ * `$output` as data variables. TypeScript is supported via transpilation.
  */
+/**
+ * Input schema for the Code node. The `@input` on `CodeFlowNode.input` is a
+ * schema group — the nested model's `@input` ports are spliced into the
+ * parent unprefixed. `code` has `@input` + `@uielement("code-editor")`, so it
+ * appears as a port AND in the CRUD modal (the only visible field). `data`
+ * has `@input` + `@hidden()` but no `@uielement`, so it is a canvas-only port
+ * (for edge connections from workflow input badges) but never appears in the
+ * CRUD modal. `language` has no `@input` and no `@uielement`, so it is
+ * neither a port nor rendered — it defaults to `"javascript"`.
+ */
+export declare class CodeInputSchema extends Model {
+    language: string;
+    code: string;
+    data?: unknown;
+}
 export declare class CodeFlowNode extends Model {
-    input: unknown;
+    input: CodeInputSchema;
     result: unknown;
 }
+/**
+ * Log — logs the input value and forwards it unchanged on the `logged`
+ * output port. Useful for debugging, audit trails, and discard/side-effect
+ * branches in a workflow.
+ */
+export declare class LogFlowNode extends Model {
+    value: unknown;
+    logged: unknown;
+}
 /**
  * All built-in flow-control node constructors.
  */
-export declare const GRAPH_FLOW_CONTROL_NODES: readonly [typeof IfFlowNode, typeof SwitchFlowNode, typeof ParallelFlowNode, typeof MergeFlowNode, typeof MapFlowNode, typeof DelayFlowNode, typeof ErrorBoundaryFlowNode, typeof HumanApprovalFlowNode, typeof ReturnFlowNode, typeof CodeFlowNode];
+export declare const GRAPH_FLOW_CONTROL_NODES: readonly [typeof IfFlowNode, typeof SwitchFlowNode, typeof ParallelFlowNode, typeof MergeFlowNode, typeof MapFlowNode, typeof DelayFlowNode, typeof ErrorBoundaryFlowNode, typeof HumanApprovalFlowNode, typeof ReturnFlowNode, typeof CodeFlowNode, typeof LogFlowNode];

package/lib/types/graph/shared/types.d.cts

@@ -102,10 +102,16 @@ export interface SwitchCase {
 }
 /**
  * Metadata for a Switch node, stored in `metadata.switch`.
+ *
+ * When `hasDefault` is `false`, the `default` output port is hidden and the
+ * executor returns an empty output (no port) when no case matches. When
+ * `hasDefault` is `true` (or omitted), the `default` output port is visible
+ * and receives the input when no case matches (DECAF-34 §6.2).
  */
 export interface SwitchNodeMetadata {
     cases: SwitchCase[];
     defaultPort?: string;
+    hasDefault?: boolean;
 }
 /**
  * The result of applying a metadata change to a node. Each concrete node

package/lib/types/graph/shared/types.d.mts

@@ -102,10 +102,16 @@ export interface SwitchCase {
 }
 /**
  * Metadata for a Switch node, stored in `metadata.switch`.
+ *
+ * When `hasDefault` is `false`, the `default` output port is hidden and the
+ * executor returns an empty output (no port) when no case matches. When
+ * `hasDefault` is `true` (or omitted), the `default` output port is visible
+ * and receives the input when no case matches (DECAF-34 §6.2).
  */
 export interface SwitchNodeMetadata {
     cases: SwitchCase[];
     defaultPort?: string;
+    hasDefault?: boolean;
 }
 /**
  * The result of applying a metadata change to a node. Each concrete node

package/lib/types/index.d.cts

@@ -6,6 +6,6 @@
 export * from "./utils.d.cts";
 export * from "./namespaces/index.d.cts";
 export declare const VERSION: string;
-export declare const COMMIT = "1deb3bb";
-export declare const FULL_VERSION = "0.3.9-1deb3bb";
+export declare const COMMIT = "e2c4409";
+export declare const FULL_VERSION = "0.3.11-e2c4409";
 export declare const PACKAGE_NAME: string;

package/lib/types/index.d.mts

@@ -6,6 +6,6 @@
 export * from "./utils.d.mts";
 export * from "./namespaces/index.d.mts";
 export declare const VERSION: string;
-export declare const COMMIT = "1deb3bb";
-export declare const FULL_VERSION = "0.3.9-1deb3bb";
+export declare const COMMIT = "e2c4409";
+export declare const FULL_VERSION = "0.3.11-e2c4409";
 export declare const PACKAGE_NAME: string;

package/lib/types/nest/graph/GraphExecutionController.d.cts

@@ -1,62 +1,31 @@
-/**
- * @module integrations/nest/graph/GraphExecutionController
- * @summary NestJS controller bridging the graph execution engine to REST + SSE.
- * @description Exposes three endpoints:
- * - `POST /graph/execute` — triggers {@link GraphExecutionEngine.execute}, persists the result via a Decaf repository, and returns `{ runId, status, outputs }`.
- * - `GET /graph/events` — SSE endpoint streaming {@link GraphExecutionEvent}s as `[modelName, operation, id, payload]` tuples (compatible with for-http's `ServerEventConnector`).
- * - `GET /graph/results/:runId` — retrieves a persisted {@link GraphExecutionResultModel} from the repository.
- *
- * This is the production pattern: for-nest hosts the engine, for-angular consumes events over the network via SSE and fetches persisted results via REST.
- */
 import { MessageEvent } from "@nestjs/common";
 import { Observable } from "rxjs";
 import { GraphExecutionEngine, type GraphExecutionValues } from "../../graph/index.d.cts";
 import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
-import { type GraphExecutionResultRepositoryInstance } from "./GraphExecutionResultRepository.d.cts";
-/**
- * NestJS injection token for the graph execution result repository.
- */
-export declare const GRAPH_RESULT_REPOSITORY = "GRAPH_RESULT_REPOSITORY";
-/**
- * Payload for the `POST /graph/execute` endpoint.
- */
+import { DecafRequestContext } from "@decaf-ts/for-nest";
+import { GraphResultService } from "./GraphResultService.d.cts";
+import { GraphWorkflowService } from "./GraphWorkflowService.d.cts";
 export interface GraphExecutePayload {
     workflow: GraphWorkflowDefinition;
     inputs: GraphExecutionValues;
 }
-/**
- * Response shape for the `POST /graph/execute` endpoint.
- */
 export interface GraphExecuteResponse {
     runId: string;
     status: string;
     outputs: Record<string, unknown>;
 }
-/**
- * NestJS controller that hosts the graph execution engine server-side,
- * streams events via SSE, and persists results for later retrieval.
- */
 export declare class GraphExecutionController {
     private readonly engine;
-    private readonly resultRepository;
+    private readonly resultService;
+    private readonly workflowService;
+    private readonly requestContext?;
     private readonly eventSubject;
-    constructor(engine: GraphExecutionEngine, resultRepository: GraphExecutionResultRepositoryInstance);
-    /**
-     * Triggers graph execution server-side, persists the result, and returns
-     * a summary containing the `runId`, `status`, and `outputs`.
-     */
+    constructor(engine: GraphExecutionEngine, resultService: GraphResultService, workflowService: GraphWorkflowService, requestContext?: DecafRequestContext | undefined);
     execute(body: GraphExecutePayload): Promise<GraphExecuteResponse>;
-    /**
-     * SSE endpoint that streams graph execution events.
-     *
-     * Events are serialized as `[modelName, operation, id, payload]` to match
-     * the format expected by for-http's `ServerEventConnector`.
-     */
     events(): Observable<MessageEvent>;
-    /**
-     * Retrieves a persisted graph execution result by its `runId`.
-     *
-     * @throws {NotFoundException} when no result is stored for the given `runId`.
-     */
     getResult(runId: string): Promise<unknown>;
+    saveWorkflow(id: string, snapshot: Record<string, unknown>): Promise<{
+        workflowId: string;
+        savedAt: string;
+    }>;
 }

package/lib/types/nest/graph/GraphExecutionController.d.mts

@@ -1,62 +1,31 @@
-/**
- * @module integrations/nest/graph/GraphExecutionController
- * @summary NestJS controller bridging the graph execution engine to REST + SSE.
- * @description Exposes three endpoints:
- * - `POST /graph/execute` — triggers {@link GraphExecutionEngine.execute}, persists the result via a Decaf repository, and returns `{ runId, status, outputs }`.
- * - `GET /graph/events` — SSE endpoint streaming {@link GraphExecutionEvent}s as `[modelName, operation, id, payload]` tuples (compatible with for-http's `ServerEventConnector`).
- * - `GET /graph/results/:runId` — retrieves a persisted {@link GraphExecutionResultModel} from the repository.
- *
- * This is the production pattern: for-nest hosts the engine, for-angular consumes events over the network via SSE and fetches persisted results via REST.
- */
 import { MessageEvent } from "@nestjs/common";
 import { Observable } from "rxjs";
 import { GraphExecutionEngine, type GraphExecutionValues } from "../../graph/index.d.mts";
 import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
-import { type GraphExecutionResultRepositoryInstance } from "./GraphExecutionResultRepository.d.mts";
-/**
- * NestJS injection token for the graph execution result repository.
- */
-export declare const GRAPH_RESULT_REPOSITORY = "GRAPH_RESULT_REPOSITORY";
-/**
- * Payload for the `POST /graph/execute` endpoint.
- */
+import { DecafRequestContext } from "@decaf-ts/for-nest";
+import { GraphResultService } from "./GraphResultService.d.mts";
+import { GraphWorkflowService } from "./GraphWorkflowService.d.mts";
 export interface GraphExecutePayload {
     workflow: GraphWorkflowDefinition;
     inputs: GraphExecutionValues;
 }
-/**
- * Response shape for the `POST /graph/execute` endpoint.
- */
 export interface GraphExecuteResponse {
     runId: string;
     status: string;
     outputs: Record<string, unknown>;
 }
-/**
- * NestJS controller that hosts the graph execution engine server-side,
- * streams events via SSE, and persists results for later retrieval.
- */
 export declare class GraphExecutionController {
     private readonly engine;
-    private readonly resultRepository;
+    private readonly resultService;
+    private readonly workflowService;
+    private readonly requestContext?;
     private readonly eventSubject;
-    constructor(engine: GraphExecutionEngine, resultRepository: GraphExecutionResultRepositoryInstance);
-    /**
-     * Triggers graph execution server-side, persists the result, and returns
-     * a summary containing the `runId`, `status`, and `outputs`.
-     */
+    constructor(engine: GraphExecutionEngine, resultService: GraphResultService, workflowService: GraphWorkflowService, requestContext?: DecafRequestContext | undefined);
     execute(body: GraphExecutePayload): Promise<GraphExecuteResponse>;
-    /**
-     * SSE endpoint that streams graph execution events.
-     *
-     * Events are serialized as `[modelName, operation, id, payload]` to match
-     * the format expected by for-http's `ServerEventConnector`.
-     */
     events(): Observable<MessageEvent>;
-    /**
-     * Retrieves a persisted graph execution result by its `runId`.
-     *
-     * @throws {NotFoundException} when no result is stored for the given `runId`.
-     */
     getResult(runId: string): Promise<unknown>;
+    saveWorkflow(id: string, snapshot: Record<string, unknown>): Promise<{
+        workflowId: string;
+        savedAt: string;
+    }>;
 }

package/lib/types/nest/graph/GraphExecutionModule.d.cts

@@ -1,39 +1,19 @@
-/**
- * @module integrations/nest/graph/GraphExecutionModule
- * @summary NestJS DynamicModule hosting the graph execution engine.
- * @description Wires the {@link GraphExecutionEngine}, a demo executor registry, a RamAdapter-backed result repository, and the {@link GraphExecutionController} into a single NestJS module. Use `GraphExecutionModule.forRoot()` to register it in the application.
- */
 import { DynamicModule } from "@nestjs/common";
-/**
- * Options for {@link GraphExecutionModule.forRoot}.
- */
 export interface GraphExecutionModuleOptions {
     /**
-     * User identifier passed to the RamAdapter. Defaults to `"graph-engine"`.
+     * When `true`, the module bootstraps a default RamAdapter for standalone
+     * development. When `false`, the host application is expected to have
+     * already configured a Decaf adapter via `DecafModule.forRoot(...)`.
+     * Defaults to `true` for backwards compatibility.
      */
-    adapterUser?: string;
+    initAdapter?: boolean;
     /**
-     * When `true`, calls `RamAdapter.decoration()` and
-     * `Adapter.setCurrent(RamFlavour)` during module initialisation. Defaults to
-     * `true`. Set to `false` when the host application has already configured a
-     * RamAdapter.
+     * Adapter user identifier passed to `RamAdapter` when `initAdapter` is
+     * `true`. Ignored when `initAdapter` is `false`.
+     * Defaults to `"graph-engine"`.
      */
-    initAdapter?: boolean;
+    adapterUser?: string;
 }
-/**
- * NestJS module that hosts the graph execution engine server-side.
- *
- * Provides:
- * - {@link GraphExecutionEngine} — singleton engine with a demo executor registry.
- * - `GRAPH_RESULT_REPOSITORY` — Decaf repository for {@link GraphExecutionResultModel} backed by RamAdapter.
- * - {@link GraphExecutionController} — REST + SSE controller.
- */
 export declare class GraphExecutionModule {
-    /**
-     * Creates a configured {@link DynamicModule} for the graph execution backend.
-     *
-     * @param options - Module configuration options.
-     * @returns A NestJS `DynamicModule` ready for import.
-     */
     static forRoot(options?: GraphExecutionModuleOptions): DynamicModule;
 }

package/lib/types/nest/graph/GraphExecutionModule.d.mts

@@ -1,39 +1,19 @@
-/**
- * @module integrations/nest/graph/GraphExecutionModule
- * @summary NestJS DynamicModule hosting the graph execution engine.
- * @description Wires the {@link GraphExecutionEngine}, a demo executor registry, a RamAdapter-backed result repository, and the {@link GraphExecutionController} into a single NestJS module. Use `GraphExecutionModule.forRoot()` to register it in the application.
- */
 import { DynamicModule } from "@nestjs/common";
-/**
- * Options for {@link GraphExecutionModule.forRoot}.
- */
 export interface GraphExecutionModuleOptions {
     /**
-     * User identifier passed to the RamAdapter. Defaults to `"graph-engine"`.
+     * When `true`, the module bootstraps a default RamAdapter for standalone
+     * development. When `false`, the host application is expected to have
+     * already configured a Decaf adapter via `DecafModule.forRoot(...)`.
+     * Defaults to `true` for backwards compatibility.
      */
-    adapterUser?: string;
+    initAdapter?: boolean;
     /**
-     * When `true`, calls `RamAdapter.decoration()` and
-     * `Adapter.setCurrent(RamFlavour)` during module initialisation. Defaults to
-     * `true`. Set to `false` when the host application has already configured a
-     * RamAdapter.
+     * Adapter user identifier passed to `RamAdapter` when `initAdapter` is
+     * `true`. Ignored when `initAdapter` is `false`.
+     * Defaults to `"graph-engine"`.
      */
-    initAdapter?: boolean;
+    adapterUser?: string;
 }
-/**
- * NestJS module that hosts the graph execution engine server-side.
- *
- * Provides:
- * - {@link GraphExecutionEngine} — singleton engine with a demo executor registry.
- * - `GRAPH_RESULT_REPOSITORY` — Decaf repository for {@link GraphExecutionResultModel} backed by RamAdapter.
- * - {@link GraphExecutionController} — REST + SSE controller.
- */
 export declare class GraphExecutionModule {
-    /**
-     * Creates a configured {@link DynamicModule} for the graph execution backend.
-     *
-     * @param options - Module configuration options.
-     * @returns A NestJS `DynamicModule` ready for import.
-     */
     static forRoot(options?: GraphExecutionModuleOptions): DynamicModule;
 }