@decaf-ts/integrations 0.3.8 → 0.3.10

package/lib/types/graph/{types.d.mts → engine/types.d.mts}

@@ -1,10 +1,17 @@
 /**
- * @module integrations/graph/types
+ * @module integrations/graph/engine/types
  * @summary Graph execution engine core types.
- * @description Type aliases and interfaces shared across the graph execution engine.
- */
-import type { GraphNodeDefinition, GraphPortDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionEventType, GraphExecutionStatus } from "./constants.d.mts";
+ * @description Engine-private type aliases and interfaces. Frontend-safe
+ * types (`ExprValue`, `ConditionExpression`, `CodeCondition`,
+ * `SwitchCaseCondition`, `SwitchCase`, `SwitchNodeMetadata`,
+ * `NodeMetadataChange`, `GraphExecutionEvent`, `GraphExecutionErrorPayload`)
+ * live in `../shared/types`; engine modules import shared symbols from there
+ * and engine-private symbols from here.
+ */
+import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionStatus } from "../shared/constants.d.mts";
+import type { GraphExecutionErrorPayload, GraphExecutionEvent } from "../shared/types.d.mts";
+export type { GraphExecutionErrorPayload, GraphExecutionEvent, } from "../shared/types.d.mts";
 /**
  * Unique identifier for a single graph execution run.
  */
@@ -43,37 +50,6 @@ export interface GraphExecutionOptions {
     writeThroughCache?: boolean;
     metadata?: Record<string, unknown>;
 }
-/**
- * Serialized error payload included in execution events and results.
- */
-export interface GraphExecutionErrorPayload {
-    name: string;
-    message: string;
-    stack?: string;
-    code?: string;
-    details?: unknown;
-}
-/**
- * A single event emitted during graph execution.
- */
-export interface GraphExecutionEvent {
-    id: string;
-    sequence: number;
-    runId: GraphRunId;
-    parentRunId?: GraphRunId;
-    workflowId: GraphWorkflowId;
-    type: GraphExecutionEventType;
-    timestamp: Date;
-    nodeId?: GraphNodeId;
-    edgeId?: string;
-    port?: GraphPortName;
-    iteration?: number;
-    path: string[];
-    status?: GraphExecutionStatus;
-    payload?: unknown;
-    error?: GraphExecutionErrorPayload;
-    metadata?: Record<string, unknown>;
-}
 /**
  * Result of executing a single node.
  */
@@ -146,118 +122,6 @@ export interface GraphConditionDefinition {
     evaluator?: string;
     metadata?: Record<string, unknown>;
 }
-/**
- * A value reference inside a {@link ConditionExpression}.
- *
- * - `{ const: x }` — a literal constant.
- * - `{ path: "a.b" }` — a dotted path resolved against the current loop state.
- * - `{ step: "nodeId", path: "out" }` — a cross-node reference (resolved from
- *   the execution state in v1; reserved for future multi-step evaluation).
- */
-export type ExprValue = {
-    const: unknown;
-} | {
-    path: string;
-} | {
-    step: string;
-    path: string;
-};
-/**
- * Declarative, serializable condition expression DSL (ALFRED-5 §8 / DECAF-32 §22.3).
- *
- * The engine's {@link GraphConditionEvaluator} recognises this DSL when the
- * condition object carries an `op` field and dispatches to the
- * {@link ConditionExpressionEvaluator}.
- */
-export type ConditionExpression = {
-    op: "eq";
-    left: ExprValue;
-    right: ExprValue;
-} | {
-    op: "neq";
-    left: ExprValue;
-    right: ExprValue;
-} | {
-    op: "gt";
-    left: ExprValue;
-    right: ExprValue;
-} | {
-    op: "gte";
-    left: ExprValue;
-    right: ExprValue;
-} | {
-    op: "lt";
-    left: ExprValue;
-    right: ExprValue;
-} | {
-    op: "lte";
-    left: ExprValue;
-    right: ExprValue;
-} | {
-    op: "and";
-    conditions: ConditionExpression[];
-} | {
-    op: "or";
-    conditions: ConditionExpression[];
-} | {
-    op: "not";
-    condition: ConditionExpression;
-} | {
-    op: "exists";
-    value: ExprValue;
-};
-/**
- * A code-based condition evaluated in a restricted VM sandbox (§22.4).
- *
- * The engine does NOT implement the sandbox directly — a pluggable
- * {@link CodeSandboxEvaluator} must be registered for code conditions to work.
- * The code must follow the same restrictions as the Code Node (§22.4):
- * no system API access, placeholder syntax for workflow data references.
- */
-export interface CodeCondition {
-    type: "code";
-    code: string;
-    language?: "javascript" | "typescript";
-}
-/**
- * A condition on a Switch case — either a declarative
- * {@link ConditionExpression} (graphical mode) or a {@link CodeCondition}
- * (code mode).
- */
-export type SwitchCaseCondition = ConditionExpression | CodeCondition;
-/**
- * A single case in a Switch node.
- *
- * Each case pairs a condition with a dedicated output port. When the
- * condition evaluates to `true`, the input is routed to `outputPort`.
- */
-export interface SwitchCase {
-    id: string;
-    label: string;
-    condition: SwitchCaseCondition;
-    outputPort: string;
-}
-/**
- * Metadata for a Switch node, stored in `metadata.switch`.
- */
-export interface SwitchNodeMetadata {
-    cases: SwitchCase[];
-    defaultPort?: string;
-}
-/**
- * The result of applying a metadata change to a node. Each concrete node
- * class that overrides `GraphNode.applyMetadata()` returns this so the
- * renderer can update the diagram model — the node owns its ports, its
- * size, and any data patches.
- */
-export interface NodeMetadataChange {
-    ports: GraphPortDefinition[];
-    size: {
-        width: number;
-        height: number;
-    };
-    dataPatch: Record<string, unknown>;
-}
 /**
  * Pinning metadata attached to a node via `@pinnable()`.
  */

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

@@ -1,56 +1,11 @@
 /**
  * @module integrations/graph
- * @summary Decaf Graph Execution Engine.
- * @description Reference interpreter for Decaf graph workflows. Executes workflows declared with `@decaf-ts/ui-decorators/graph`, emits events through Decaf's Observable pipeline, supports structured loops, configurable value stores, and pinnable/cacheable nodes.
+ * @summary Decaf Graph Execution Engine (backend convenience export).
+ * @description Re-exports `./engine`, which in turn re-exports `./shared`
+ * (frontend-safe declarations) plus all engine modules. Backend consumers
+ * import from `@decaf-ts/integrations/graph` and get a single unified surface.
+ *
+ * Frontend bundles MUST import from `@decaf-ts/integrations/graph/shared`
+ * instead to avoid pulling in the execution engine.
  */
-export * from "./constants.d.cts";
-export * from "./types.d.cts";
-export * from "./decorators.d.cts";
-export * from "./errors/GraphExecutionError.d.cts";
-export * from "./errors/GraphCycleError.d.cts";
-export * from "./errors/GraphInputError.d.cts";
-export * from "./errors/GraphLoopLimitError.d.cts";
-export * from "./errors/GraphPinningError.d.cts";
-export * from "./errors/GraphPortError.d.cts";
-export * from "./errors/GraphStoreError.d.cts";
-export * from "./errors/GraphTopologyError.d.cts";
-export * from "./events/GraphExecutionEvent.d.cts";
-export * from "./events/GraphExecutionObserver.d.cts";
-export * from "./events/GraphExecutionEventEmitter.d.cts";
-export * from "./events/GraphExecutionEventFactory.d.cts";
-export * from "./execution/GraphExecutionContext.d.cts";
-export * from "./execution/GraphNodeExecutor.d.cts";
-export * from "./execution/GraphExecutionFrame.d.cts";
-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 "./registry/GraphNodeExecutorRegistry.d.cts";
-export * from "./registry/GraphNodeExecutorResolver.d.cts";
-export * from "./store/GraphValueKey.d.cts";
-export * from "./store/GraphCachedValue.d.cts";
-export * from "./store/GraphValueStoreAdapter.d.cts";
-export * from "./store/InMemoryGraphValueStoreAdapter.d.cts";
-export * from "./store/GraphValueStore.d.cts";
-export * from "./planning/GraphExecutionPlanNode.d.cts";
-export * from "./planning/GraphExecutionPlanEdge.d.cts";
-export * from "./planning/GraphExecutionPlanLayer.d.cts";
-export * from "./planning/GraphExecutionPlan.d.cts";
-export * from "./planning/GraphRelationResolver.d.cts";
-export * from "./planning/GraphExecutionPlanner.d.cts";
-export * from "./planning/GraphTopology.d.cts";
-export * from "./validation/GraphDefinitionValidator.d.cts";
-export * from "./validation/GraphPortSchemaResolver.d.cts";
-export * from "./validation/GraphValueValidator.d.cts";
-export * from "./loops/GraphConditionEvaluator.d.cts";
-export * from "./loops/ConditionExpressionEvaluator.d.cts";
-export * from "./loops/GraphLoopExecutionContext.d.cts";
-export * from "./loops/ForeachGraphNodeExecutor.d.cts";
-export * from "./loops/WhileGraphNodeExecutor.d.cts";
-export * from "./loops/UntilGraphNodeExecutor.d.cts";
-export * from "./pinning/GraphPinningMetadata.d.cts";
-export * from "./pinning/GraphPinningPolicy.d.cts";
-export * from "./pinning/GraphPinningDependencyResolver.d.cts";
-export * from "./pinning/GraphPinningService.d.cts";
-export * from "./snapshots/GraphExecutionSnapshotMapper.d.cts";
-export * from "./nodes/index.d.cts";
+export * from "./engine/index.d.cts";

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

@@ -1,56 +1,11 @@
 /**
  * @module integrations/graph
- * @summary Decaf Graph Execution Engine.
- * @description Reference interpreter for Decaf graph workflows. Executes workflows declared with `@decaf-ts/ui-decorators/graph`, emits events through Decaf's Observable pipeline, supports structured loops, configurable value stores, and pinnable/cacheable nodes.
+ * @summary Decaf Graph Execution Engine (backend convenience export).
+ * @description Re-exports `./engine`, which in turn re-exports `./shared`
+ * (frontend-safe declarations) plus all engine modules. Backend consumers
+ * import from `@decaf-ts/integrations/graph` and get a single unified surface.
+ *
+ * Frontend bundles MUST import from `@decaf-ts/integrations/graph/shared`
+ * instead to avoid pulling in the execution engine.
  */
-export * from "./constants.d.mts";
-export * from "./types.d.mts";
-export * from "./decorators.d.mts";
-export * from "./errors/GraphExecutionError.d.mts";
-export * from "./errors/GraphCycleError.d.mts";
-export * from "./errors/GraphInputError.d.mts";
-export * from "./errors/GraphLoopLimitError.d.mts";
-export * from "./errors/GraphPinningError.d.mts";
-export * from "./errors/GraphPortError.d.mts";
-export * from "./errors/GraphStoreError.d.mts";
-export * from "./errors/GraphTopologyError.d.mts";
-export * from "./events/GraphExecutionEvent.d.mts";
-export * from "./events/GraphExecutionObserver.d.mts";
-export * from "./events/GraphExecutionEventEmitter.d.mts";
-export * from "./events/GraphExecutionEventFactory.d.mts";
-export * from "./execution/GraphExecutionContext.d.mts";
-export * from "./execution/GraphNodeExecutor.d.mts";
-export * from "./execution/GraphExecutionFrame.d.mts";
-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 "./registry/GraphNodeExecutorRegistry.d.mts";
-export * from "./registry/GraphNodeExecutorResolver.d.mts";
-export * from "./store/GraphValueKey.d.mts";
-export * from "./store/GraphCachedValue.d.mts";
-export * from "./store/GraphValueStoreAdapter.d.mts";
-export * from "./store/InMemoryGraphValueStoreAdapter.d.mts";
-export * from "./store/GraphValueStore.d.mts";
-export * from "./planning/GraphExecutionPlanNode.d.mts";
-export * from "./planning/GraphExecutionPlanEdge.d.mts";
-export * from "./planning/GraphExecutionPlanLayer.d.mts";
-export * from "./planning/GraphExecutionPlan.d.mts";
-export * from "./planning/GraphRelationResolver.d.mts";
-export * from "./planning/GraphExecutionPlanner.d.mts";
-export * from "./planning/GraphTopology.d.mts";
-export * from "./validation/GraphDefinitionValidator.d.mts";
-export * from "./validation/GraphPortSchemaResolver.d.mts";
-export * from "./validation/GraphValueValidator.d.mts";
-export * from "./loops/GraphConditionEvaluator.d.mts";
-export * from "./loops/ConditionExpressionEvaluator.d.mts";
-export * from "./loops/GraphLoopExecutionContext.d.mts";
-export * from "./loops/ForeachGraphNodeExecutor.d.mts";
-export * from "./loops/WhileGraphNodeExecutor.d.mts";
-export * from "./loops/UntilGraphNodeExecutor.d.mts";
-export * from "./pinning/GraphPinningMetadata.d.mts";
-export * from "./pinning/GraphPinningPolicy.d.mts";
-export * from "./pinning/GraphPinningDependencyResolver.d.mts";
-export * from "./pinning/GraphPinningService.d.mts";
-export * from "./snapshots/GraphExecutionSnapshotMapper.d.mts";
-export * from "./nodes/index.d.mts";
+export * from "./engine/index.d.mts";

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

@@ -0,0 +1,53 @@
+/**
+ * @module integrations/graph/shared/constants
+ * @summary Frontend-safe graph constants and enums.
+ * @description Constants and enumerations that are safe to import from a
+ * frontend bundle (no engine runtime dependency). The execution-status and
+ * event-type enums live here because the frontend renders status badges and
+ * event timelines and must not pull in the execution engine.
+ */
+/**
+ * Execution status for a workflow or individual node.
+ */
+export declare enum GraphExecutionStatus {
+    PENDING = "pending",
+    PLANNING = "planning",
+    RUNNING = "running",
+    SUCCEEDED = "succeeded",
+    FAILED = "failed",
+    SKIPPED = "skipped",
+    CANCELLED = "cancelled",
+    CACHED = "cached"
+}
+/**
+ * Event types emitted through the graph execution observer pipeline.
+ */
+export declare enum GraphExecutionEventType {
+    WORKFLOW_STARTED = "workflow.started",
+    WORKFLOW_PLANNED = "workflow.planned",
+    WORKFLOW_COMPLETED = "workflow.completed",
+    WORKFLOW_FAILED = "workflow.failed",
+    WORKFLOW_CANCELLED = "workflow.cancelled",
+    NODE_QUEUED = "node.queued",
+    NODE_STARTED = "node.started",
+    NODE_OUTPUT = "node.output",
+    NODE_COMPLETED = "node.completed",
+    NODE_FAILED = "node.failed",
+    NODE_SKIPPED = "node.skipped",
+    NODE_CACHE_HIT = "node.cacheHit",
+    NODE_PINNED = "node.pinned",
+    NODE_UNPINNED = "node.unpinned",
+    EDGE_VALUE_ROUTED = "edge.valueRouted",
+    LOOP_STARTED = "loop.started",
+    LOOP_ITERATION_STARTED = "loop.iteration.started",
+    LOOP_ITERATION_COMPLETED = "loop.iteration.completed",
+    LOOP_CONDITION_EVALUATED = "loop.condition.evaluated",
+    LOOP_COMPLETED = "loop.completed",
+    LOOP_LIMIT_REACHED = "loop.limitReached",
+    VALIDATION_STARTED = "validation.started",
+    VALIDATION_FAILED = "validation.failed",
+    VALIDATION_COMPLETED = "validation.completed",
+    STORE_READ = "store.read",
+    STORE_WRITE = "store.write",
+    STORE_DELETE = "store.delete"
+}

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

@@ -0,0 +1,53 @@
+/**
+ * @module integrations/graph/shared/constants
+ * @summary Frontend-safe graph constants and enums.
+ * @description Constants and enumerations that are safe to import from a
+ * frontend bundle (no engine runtime dependency). The execution-status and
+ * event-type enums live here because the frontend renders status badges and
+ * event timelines and must not pull in the execution engine.
+ */
+/**
+ * Execution status for a workflow or individual node.
+ */
+export declare enum GraphExecutionStatus {
+    PENDING = "pending",
+    PLANNING = "planning",
+    RUNNING = "running",
+    SUCCEEDED = "succeeded",
+    FAILED = "failed",
+    SKIPPED = "skipped",
+    CANCELLED = "cancelled",
+    CACHED = "cached"
+}
+/**
+ * Event types emitted through the graph execution observer pipeline.
+ */
+export declare enum GraphExecutionEventType {
+    WORKFLOW_STARTED = "workflow.started",
+    WORKFLOW_PLANNED = "workflow.planned",
+    WORKFLOW_COMPLETED = "workflow.completed",
+    WORKFLOW_FAILED = "workflow.failed",
+    WORKFLOW_CANCELLED = "workflow.cancelled",
+    NODE_QUEUED = "node.queued",
+    NODE_STARTED = "node.started",
+    NODE_OUTPUT = "node.output",
+    NODE_COMPLETED = "node.completed",
+    NODE_FAILED = "node.failed",
+    NODE_SKIPPED = "node.skipped",
+    NODE_CACHE_HIT = "node.cacheHit",
+    NODE_PINNED = "node.pinned",
+    NODE_UNPINNED = "node.unpinned",
+    EDGE_VALUE_ROUTED = "edge.valueRouted",
+    LOOP_STARTED = "loop.started",
+    LOOP_ITERATION_STARTED = "loop.iteration.started",
+    LOOP_ITERATION_COMPLETED = "loop.iteration.completed",
+    LOOP_CONDITION_EVALUATED = "loop.condition.evaluated",
+    LOOP_COMPLETED = "loop.completed",
+    LOOP_LIMIT_REACHED = "loop.limitReached",
+    VALIDATION_STARTED = "validation.started",
+    VALIDATION_FAILED = "validation.failed",
+    VALIDATION_COMPLETED = "validation.completed",
+    STORE_READ = "store.read",
+    STORE_WRITE = "store.write",
+    STORE_DELETE = "store.delete"
+}

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

@@ -0,0 +1,18 @@
+/**
+ * @module integrations/graph/shared
+ * @summary Frontend-safe graph declarations.
+ * @description Subpath export for frontend bundles. Re-exports the node kind
+ * declarations, shared types, and shared constants — no engine runtime
+ * dependency. Also re-exports `Metadata` from `@decaf-ts/ui-decorators` so
+ * consumers get the `Metadata.nodes()` / `Metadata.workflows()` accessors
+ * (attached via the graph overrides side-effect import).
+ *
+ * Importing anything from this module triggers the `ui-decorators/graph`
+ * overrides side-effect, which attaches `nodes()` / `workflows()` to the
+ * `Metadata` class.
+ */
+import "@decaf-ts/ui-decorators/graph";
+export { Metadata } from "@decaf-ts/decoration";
+export * from "./constants.d.cts";
+export * from "./types.d.cts";
+export * from "./nodes/index.d.cts";

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

@@ -0,0 +1,18 @@
+/**
+ * @module integrations/graph/shared
+ * @summary Frontend-safe graph declarations.
+ * @description Subpath export for frontend bundles. Re-exports the node kind
+ * declarations, shared types, and shared constants — no engine runtime
+ * dependency. Also re-exports `Metadata` from `@decaf-ts/ui-decorators` so
+ * consumers get the `Metadata.nodes()` / `Metadata.workflows()` accessors
+ * (attached via the graph overrides side-effect import).
+ *
+ * Importing anything from this module triggers the `ui-decorators/graph`
+ * overrides side-effect, which attaches `nodes()` / `workflows()` to the
+ * `Metadata` class.
+ */
+import "@decaf-ts/ui-decorators/graph";
+export { Metadata } from "@decaf-ts/decoration";
+export * from "./constants.d.mts";
+export * from "./types.d.mts";
+export * from "./nodes/index.d.mts";

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

@@ -0,0 +1,162 @@
+/**
+ * @module integrations/graph/shared/types
+ * @summary Frontend-safe graph type declarations.
+ * @description Type aliases and interfaces that are safe to import from a
+ * frontend bundle. These types describe declarative graph metadata (loop
+ * condition DSL, switch cases, node metadata patches) and the execution-event
+ * data contract consumed by the frontend via SSE — no engine runtime
+ * dependency.
+ */
+import type { GraphPortDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionEventType, GraphExecutionStatus } from "./constants.d.cts";
+/**
+ * A value reference inside a {@link ConditionExpression}.
+ *
+ * - `{ const: x }` — a literal constant.
+ * - `{ path: "a.b" }` — a dotted path resolved against the current loop state.
+ * - `{ step: "nodeId", path: "out" }` — a cross-node reference (resolved from
+ *   the execution state in v1; reserved for future multi-step evaluation).
+ */
+export type ExprValue = {
+    const: unknown;
+} | {
+    path: string;
+} | {
+    step: string;
+    path: string;
+};
+/**
+ * Declarative, serializable condition expression DSL (ALFRED-5 §8 / DECAF-32 §22.3).
+ *
+ * The engine's `GraphConditionEvaluator` recognises this DSL when the
+ * condition object carries an `op` field and dispatches to the
+ * `ConditionExpressionEvaluator`.
+ */
+export type ConditionExpression = {
+    op: "eq";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "neq";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "gt";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "gte";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "lt";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "lte";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "and";
+    conditions: ConditionExpression[];
+} | {
+    op: "or";
+    conditions: ConditionExpression[];
+} | {
+    op: "not";
+    condition: ConditionExpression;
+} | {
+    op: "exists";
+    value: ExprValue;
+};
+/**
+ * A code-based condition evaluated in a restricted VM sandbox (§22.4).
+ *
+ * The engine does NOT implement the sandbox directly — a pluggable
+ * `CodeSandboxEvaluator` must be registered for code conditions to work.
+ * The code must follow the same restrictions as the Code Node (§22.4):
+ * no system API access, placeholder syntax for workflow data references.
+ */
+export interface CodeCondition {
+    type: "code";
+    code: string;
+    language?: "javascript" | "typescript";
+}
+/**
+ * A condition on a Switch case — either a declarative
+ * {@link ConditionExpression} (graphical mode) or a {@link CodeCondition}
+ * (code mode).
+ */
+export type SwitchCaseCondition = ConditionExpression | CodeCondition;
+/**
+ * A single case in a Switch node.
+ *
+ * Each case pairs a condition with a dedicated output port. When the
+ * condition evaluates to `true`, the input is routed to `outputPort`.
+ */
+export interface SwitchCase {
+    id: string;
+    label: string;
+    condition: SwitchCaseCondition;
+    outputPort: string;
+}
+/**
+ * Metadata for a Switch node, stored in `metadata.switch`.
+ */
+export interface SwitchNodeMetadata {
+    cases: SwitchCase[];
+    defaultPort?: string;
+}
+/**
+ * The result of applying a metadata change to a node. Each concrete node
+ * class that overrides `GraphNode.applyMetadata()` returns this so the
+ * renderer can update the diagram model — the node owns its ports, its
+ * size, and any data patches.
+ */
+export interface NodeMetadataChange {
+    ports: GraphPortDefinition[];
+    size: {
+        width: number;
+        height: number;
+    };
+    dataPatch: Record<string, unknown>;
+}
+/**
+ * Serialized error payload included in execution events and results.
+ *
+ * Frontend-safe: the frontend receives this over SSE when a node or workflow
+ * fails and needs to render the error details.
+ */
+export interface GraphExecutionErrorPayload {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string;
+    details?: unknown;
+}
+/**
+ * A single event emitted during graph execution.
+ *
+ * Frontend-safe: the frontend consumes these events over the SSE endpoint
+ * (`GET /graph/events`) and maps them to UI state updates via
+ * `GraphExecutionStateMapper`. The `timestamp` is serialised as an ISO string
+ * over the wire; the frontend deserialises it back to a `Date` when mapping.
+ */
+export interface GraphExecutionEvent {
+    id: string;
+    sequence: number;
+    runId: string;
+    parentRunId?: string;
+    workflowId: string;
+    type: GraphExecutionEventType;
+    timestamp: Date;
+    nodeId?: string;
+    edgeId?: string;
+    port?: string;
+    iteration?: number;
+    path: string[];
+    status?: GraphExecutionStatus;
+    payload?: unknown;
+    error?: GraphExecutionErrorPayload;
+    metadata?: Record<string, unknown>;
+}