@decaf-ts/integrations 0.6.2 → 0.7.0

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

@@ -0,0 +1,66 @@
+/**
+ * @module integrations/graph/shared/GraphExecutionStateMapper
+ * @summary Maps engine state to the frontend-safe visual-state contract.
+ * @description Pure, engine-agnostic helpers that derive
+ * {@link GraphVisualState} values from engine execution signals. Frontend
+ * bundles may import this from `@decaf-ts/integrations/graph/shared` (no
+ * engine runtime dependency); a future Mastra/NestJS driver maps its own
+ * runtime states onto {@link GraphVisualState} with the same rules.
+ */
+import type { GraphExecutionEvent } from "./types.d.mts";
+import { GraphExecutionStatus, GraphVisualState } from "./constants.d.mts";
+/**
+ * Maps an engine execution {@link GraphExecutionStatus} to the shared visual
+ * state. `CACHED` collapses onto {@link GraphVisualState.SUCCEEDED} for
+ * rendering; `CANCELLED`/`PENDING`/`PLANNING` yield `IDLE`.
+ *
+ * @param status - The engine execution status, if any.
+ * @returns The visual state for the node/edge.
+ */
+export declare function mapExecutionStatus(status?: GraphExecutionStatus): GraphVisualState;
+/**
+ * Options describing a single node's position within a run (DECAF-48 §4.4).
+ */
+export interface GraphVisualStateDerivation {
+    /** Whether the node has already executed (any terminal engine status). */
+    executed: boolean;
+    /** Whether the node is currently running. */
+    running: boolean;
+    /** Whether the node completed successfully (or from cache). */
+    succeeded?: boolean;
+    /** Whether the node failed. */
+    failed?: boolean;
+    /** Number of incoming edges that have completed value routing. */
+    completedUpstreams?: number;
+    /** Total number of incoming edges for the node. */
+    upstreamCount?: number;
+    /** Whether the node is reachable from the workflow inputs in the plan. */
+    reachable?: boolean;
+    /** Whether the whole run has failed (unexecuted nodes then fade/disable). */
+    runFailed?: boolean;
+}
+/**
+ * Derives the visual state for one node from its execution signals.
+ *
+ * Rules (DECAF-48 §4.4 / Req-5/Req-6):
+ * - currently running → {@link GraphVisualState.RUNNING}
+ * - failed → {@link GraphVisualState.FAILED}
+ * - executed and succeeded (or from cache) → {@link GraphVisualState.SUCCEEDED}
+ * - unexecuted and reachable with incomplete upstream deps → {@link GraphVisualState.BLOCKED}
+ * - unexecuted with `runFailed` → {@link GraphVisualState.SKIPPED} (faded/disabled)
+ * - otherwise → {@link GraphVisualState.IDLE}
+ *
+ * @param options - The node execution signals.
+ * @returns The derived visual state.
+ */
+export declare function deriveNodeVisualState(options: GraphVisualStateDerivation): GraphVisualState;
+/**
+ * Translates a {@link GraphExecutionEvent} into a node visual state when the
+ * event carries enough information. Used by contract conformance checks and
+ * engine-agnostic consumers that derive state from the shared event stream.
+ *
+ * @param event - The graph execution event.
+ * @returns The corresponding {@link GraphVisualState}, or `IDLE` when the
+ * event does not indicate a specific visual transition.
+ */
+export declare function visualStateOfEvent(event: GraphExecutionEvent): GraphVisualState;

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

@@ -2,9 +2,14 @@
  * @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.
+ * frontend bundle (no engine runtime dependency). Alongside the existing
+ * execution-status and event-type enums (rendered as status badges and event
+ * timelines), this module carries the DECAF-48 visual-state contract: the
+ * frontend-safe {@link GraphVisualState} enum, the `graph.run.log` /
+ * `graph.run.state` SSE topic constants, the run-log attribute keys
+ * ({@link GraphLogAttribute}), and the `NODE_STATE_CHANGED` /
+ * `EDGE_STATE_CHANGED` / `GRAPH_RUN_LOG` event types. The frontend must not
+ * pull in the execution engine.
  */
 /**
  * Execution status for a workflow or individual node.
@@ -19,8 +24,64 @@ export declare enum GraphExecutionStatus {
     CANCELLED = "cancelled",
     CACHED = "cached"
 }
+/**
+ * Visual execution state for a node or edge on the workflow canvas.
+ *
+ * Frontend-safe (DECAF-48 §4.4): a superset of {@link GraphExecutionStatus}
+ * normalised for rendering. `BLOCKED` is derived from the plan and execution
+ * events (waiting on upstream dependencies), not emitted as an engine status.
+ * `SKIPPED` is the post-failure "unexecuted/disabled" visual state.
+ */
+export declare enum GraphVisualState {
+    IDLE = "idle",
+    RUNNING = "running",
+    BLOCKED = "blocked",
+    SUCCEEDED = "succeeded",
+    FAILED = "failed",
+    SKIPPED = "skipped"
+}
+/**
+ * Namespace root for graph run SSE topics (DECAF-48 §4.2). A subscription
+ * filters on these granular topics before `observer.next(...)`.
+ */
+export declare const GRAPH_RUN_TOPIC = "graph.run";
+/**
+ * SSE sub-topic streaming per-node log lines during a run.
+ */
+export declare const GRAPH_RUN_LOG_TOPIC = "graph.run.log";
+/**
+ * SSE sub-topic streaming node/edge execution-state updates during a run.
+ */
+export declare const GRAPH_RUN_STATE_TOPIC = "graph.run.state";
+/**
+ * Logger custom-attribute keys attached to every run log line via
+ * DECAF-9 `logger.for({...})` (DECAF-48 §4.3). Rendered as discrete columns
+ * (not buried in the message string).
+ */
+export declare enum GraphLogAttribute {
+    NODE_ID = "nodeId",
+    WORKFLOW_ID = "workflowId",
+    RUN_ID = "runId",
+    USER = "user"
+}
+/**
+ * Namespace topic helper for a graph execution event.
+ *
+ * Log-carrier events resolve to `graph.run.log`; node/edge execution-state
+ * events resolve to `graph.run.state`; everything else stays under the shared
+ * `graph.run` topic and is only delivered to subscribers that match it.
+ *
+ * @param eventType - The graph execution event type to scope to a topic.
+ * @returns The SSE topic constant for the given event type.
+ */
+export declare function graphRunTopicOf(eventType: GraphExecutionEventType): string;
 /**
  * Event types emitted through the graph execution observer pipeline.
+ *
+ * DECAF-48 extends this set with the visual-state and run-log event types the
+ * engine emits on the existing Observable: {@link GraphExecutionEventType.NODE_STATE_CHANGED},
+ * {@link GraphExecutionEventType.EDGE_STATE_CHANGED} and
+ * {@link GraphExecutionEventType.GRAPH_RUN_LOG}.
  */
 export declare enum GraphExecutionEventType {
     WORKFLOW_STARTED = "workflow.started",
@@ -37,7 +98,13 @@ export declare enum GraphExecutionEventType {
     NODE_CACHE_HIT = "node.cacheHit",
     NODE_PINNED = "node.pinned",
     NODE_UNPINNED = "node.unpinned",
+    /** Node execution-state transition carrying a `GraphNodeStateChangedPayload` (DECAF-48 §4.4). */
+    NODE_STATE_CHANGED = "node.stateChanged",
     EDGE_VALUE_ROUTED = "edge.valueRouted",
+    /** Edge execution-state transition carrying a `GraphEdgeStateChangedPayload` (DECAF-48 §4.4). */
+    EDGE_STATE_CHANGED = "edge.stateChanged",
+    /** Structured run log line carrying a `GraphRunLogEntry` (DECAF-48 §4.3). */
+    GRAPH_RUN_LOG = "graph.run.log",
     LOOP_STARTED = "loop.started",
     LOOP_ITERATION_STARTED = "loop.iteration.started",
     LOOP_ITERATION_COMPLETED = "loop.iteration.completed",

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

@@ -2,9 +2,14 @@
  * @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.
+ * frontend bundle (no engine runtime dependency). Alongside the existing
+ * execution-status and event-type enums (rendered as status badges and event
+ * timelines), this module carries the DECAF-48 visual-state contract: the
+ * frontend-safe {@link GraphVisualState} enum, the `graph.run.log` /
+ * `graph.run.state` SSE topic constants, the run-log attribute keys
+ * ({@link GraphLogAttribute}), and the `NODE_STATE_CHANGED` /
+ * `EDGE_STATE_CHANGED` / `GRAPH_RUN_LOG` event types. The frontend must not
+ * pull in the execution engine.
  */
 /**
  * Execution status for a workflow or individual node.
@@ -19,8 +24,64 @@ export declare enum GraphExecutionStatus {
     CANCELLED = "cancelled",
     CACHED = "cached"
 }
+/**
+ * Visual execution state for a node or edge on the workflow canvas.
+ *
+ * Frontend-safe (DECAF-48 §4.4): a superset of {@link GraphExecutionStatus}
+ * normalised for rendering. `BLOCKED` is derived from the plan and execution
+ * events (waiting on upstream dependencies), not emitted as an engine status.
+ * `SKIPPED` is the post-failure "unexecuted/disabled" visual state.
+ */
+export declare enum GraphVisualState {
+    IDLE = "idle",
+    RUNNING = "running",
+    BLOCKED = "blocked",
+    SUCCEEDED = "succeeded",
+    FAILED = "failed",
+    SKIPPED = "skipped"
+}
+/**
+ * Namespace root for graph run SSE topics (DECAF-48 §4.2). A subscription
+ * filters on these granular topics before `observer.next(...)`.
+ */
+export declare const GRAPH_RUN_TOPIC = "graph.run";
+/**
+ * SSE sub-topic streaming per-node log lines during a run.
+ */
+export declare const GRAPH_RUN_LOG_TOPIC = "graph.run.log";
+/**
+ * SSE sub-topic streaming node/edge execution-state updates during a run.
+ */
+export declare const GRAPH_RUN_STATE_TOPIC = "graph.run.state";
+/**
+ * Logger custom-attribute keys attached to every run log line via
+ * DECAF-9 `logger.for({...})` (DECAF-48 §4.3). Rendered as discrete columns
+ * (not buried in the message string).
+ */
+export declare enum GraphLogAttribute {
+    NODE_ID = "nodeId",
+    WORKFLOW_ID = "workflowId",
+    RUN_ID = "runId",
+    USER = "user"
+}
+/**
+ * Namespace topic helper for a graph execution event.
+ *
+ * Log-carrier events resolve to `graph.run.log`; node/edge execution-state
+ * events resolve to `graph.run.state`; everything else stays under the shared
+ * `graph.run` topic and is only delivered to subscribers that match it.
+ *
+ * @param eventType - The graph execution event type to scope to a topic.
+ * @returns The SSE topic constant for the given event type.
+ */
+export declare function graphRunTopicOf(eventType: GraphExecutionEventType): string;
 /**
  * Event types emitted through the graph execution observer pipeline.
+ *
+ * DECAF-48 extends this set with the visual-state and run-log event types the
+ * engine emits on the existing Observable: {@link GraphExecutionEventType.NODE_STATE_CHANGED},
+ * {@link GraphExecutionEventType.EDGE_STATE_CHANGED} and
+ * {@link GraphExecutionEventType.GRAPH_RUN_LOG}.
  */
 export declare enum GraphExecutionEventType {
     WORKFLOW_STARTED = "workflow.started",
@@ -37,7 +98,13 @@ export declare enum GraphExecutionEventType {
     NODE_CACHE_HIT = "node.cacheHit",
     NODE_PINNED = "node.pinned",
     NODE_UNPINNED = "node.unpinned",
+    /** Node execution-state transition carrying a `GraphNodeStateChangedPayload` (DECAF-48 §4.4). */
+    NODE_STATE_CHANGED = "node.stateChanged",
     EDGE_VALUE_ROUTED = "edge.valueRouted",
+    /** Edge execution-state transition carrying a `GraphEdgeStateChangedPayload` (DECAF-48 §4.4). */
+    EDGE_STATE_CHANGED = "edge.stateChanged",
+    /** Structured run log line carrying a `GraphRunLogEntry` (DECAF-48 §4.3). */
+    GRAPH_RUN_LOG = "graph.run.log",
     LOOP_STARTED = "loop.started",
     LOOP_ITERATION_STARTED = "loop.iteration.started",
     LOOP_ITERATION_COMPLETED = "loop.iteration.completed",

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

@@ -15,4 +15,7 @@ import "@decaf-ts/ui-decorators/graph";
 export { Metadata } from "@decaf-ts/decoration";
 export * from "./constants.d.cts";
 export * from "./types.d.cts";
+export * from "./GraphExecutionStateMapper.d.cts";
 export * from "./nodes/index.d.cts";
+export { GRAPH_VISUAL_STATE_STYLES, graphVisualStyleOf, } from "@decaf-ts/ui-decorators/graph";
+export type { GraphNodeIoMetadata, GraphNodeIoViewMode, GraphVisualStyle, } from "@decaf-ts/ui-decorators/graph";

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

@@ -15,4 +15,7 @@ import "@decaf-ts/ui-decorators/graph";
 export { Metadata } from "@decaf-ts/decoration";
 export * from "./constants.d.mts";
 export * from "./types.d.mts";
+export * from "./GraphExecutionStateMapper.d.mts";
 export * from "./nodes/index.d.mts";
+export { GRAPH_VISUAL_STATE_STYLES, graphVisualStyleOf, } from "@decaf-ts/ui-decorators/graph";
+export type { GraphNodeIoMetadata, GraphNodeIoViewMode, GraphVisualStyle, } from "@decaf-ts/ui-decorators/graph";

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

@@ -1,17 +1,20 @@
 /**
  * @module integrations/graph/nodes/flow-control
  * @summary Production flow-control node kind declarations (DECAF-32 §22.2.2).
- * @description Canonical `@node`-decorated classes for the ten ALFRED-5
- * flow-control kinds. These are graph-level macros: the engine's planner
- * recognises them as ordinary executable nodes (§5.7) but they have no
- * built-in executors — downstream projects (e.g. ALFRED) register custom
- * executors or compile them into Mastra composition APIs (§22.2.2).
+ * @description Canonical `@node`-decorated classes for the ALFRED-5
+ * flow-control kinds, plus the DECAF-48 `core.utility.log` Log node. These
+ * are graph-level macros: the engine's planner recognises them as ordinary
+ * executable nodes (§5.7) but they have no built-in executors — downstream
+ * projects (e.g. ALFRED) register custom executors or compile them into
+ * Mastra composition APIs (§22.2.2). The `core.utility.log` node is the one
+ * exception: its {@link LogGraphNodeExecutor} is built in and logs the input
+ * through the run's `ctx.logger` (DECAF-48 §4.3).
  *
  * The three loop kinds (`core.loop.foreach/while/until`) already have built-in
  * executors (§5.9) and are NOT redeclared here.
  */
 import { Model } from "@decaf-ts/decorator-validation";
-import type { NodeMetadataChange, SwitchNodeMetadata } from "../types.d.cts";
+import type { LogNodeLevel, NodeMetadataChange, SwitchNodeMetadata } from "../types.d.cts";
 import { GraphNode } from "./base.d.cts";
 /**
  * If — conditional branch. Evaluates a `ConditionExpression` (§22.3) and
@@ -133,6 +136,16 @@ export declare class LogFlowNode extends Model {
     value: unknown;
     logged: unknown;
 }
+/**
+ * Utility Log — logs the input value through the run's `ctx.logger` at a
+ * configurable level and forwards it unchanged on the `logged` output port
+ * (DECAF-48 §4.3).
+ */
+export declare class UtilityLogNode extends Model {
+    value: unknown;
+    level: LogNodeLevel;
+    logged: unknown;
+}
 /**
  * Break — breaks out of the enclosing loop (foreach/while/until). When
  * executed inside a loop body, the loop terminates early and the loop's
@@ -147,4 +160,4 @@ export declare class BreakFlowNode extends Model {
 /**
  * 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, typeof LogFlowNode, typeof BreakFlowNode];
+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, typeof UtilityLogNode, typeof BreakFlowNode];

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

@@ -1,17 +1,20 @@
 /**
  * @module integrations/graph/nodes/flow-control
  * @summary Production flow-control node kind declarations (DECAF-32 §22.2.2).
- * @description Canonical `@node`-decorated classes for the ten ALFRED-5
- * flow-control kinds. These are graph-level macros: the engine's planner
- * recognises them as ordinary executable nodes (§5.7) but they have no
- * built-in executors — downstream projects (e.g. ALFRED) register custom
- * executors or compile them into Mastra composition APIs (§22.2.2).
+ * @description Canonical `@node`-decorated classes for the ALFRED-5
+ * flow-control kinds, plus the DECAF-48 `core.utility.log` Log node. These
+ * are graph-level macros: the engine's planner recognises them as ordinary
+ * executable nodes (§5.7) but they have no built-in executors — downstream
+ * projects (e.g. ALFRED) register custom executors or compile them into
+ * Mastra composition APIs (§22.2.2). The `core.utility.log` node is the one
+ * exception: its {@link LogGraphNodeExecutor} is built in and logs the input
+ * through the run's `ctx.logger` (DECAF-48 §4.3).
  *
  * The three loop kinds (`core.loop.foreach/while/until`) already have built-in
  * executors (§5.9) and are NOT redeclared here.
  */
 import { Model } from "@decaf-ts/decorator-validation";
-import type { NodeMetadataChange, SwitchNodeMetadata } from "../types.d.mts";
+import type { LogNodeLevel, NodeMetadataChange, SwitchNodeMetadata } from "../types.d.mts";
 import { GraphNode } from "./base.d.mts";
 /**
  * If — conditional branch. Evaluates a `ConditionExpression` (§22.3) and
@@ -133,6 +136,16 @@ export declare class LogFlowNode extends Model {
     value: unknown;
     logged: unknown;
 }
+/**
+ * Utility Log — logs the input value through the run's `ctx.logger` at a
+ * configurable level and forwards it unchanged on the `logged` output port
+ * (DECAF-48 §4.3).
+ */
+export declare class UtilityLogNode extends Model {
+    value: unknown;
+    level: LogNodeLevel;
+    logged: unknown;
+}
 /**
  * Break — breaks out of the enclosing loop (foreach/while/until). When
  * executed inside a loop body, the loop terminates early and the loop's
@@ -147,4 +160,4 @@ export declare class BreakFlowNode extends Model {
 /**
  * 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, typeof LogFlowNode, typeof BreakFlowNode];
+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, typeof UtilityLogNode, typeof BreakFlowNode];

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

@@ -2,13 +2,15 @@
  * @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.
+ * frontend bundle. Alongside the declarative graph metadata types (loop
+ * condition DSL, switch cases, node metadata patches), this module carries the
+ * DECAF-48 execution contract consumed by the frontend via SSE: the node/edge
+ * state-change payloads, the structured run log entry, the node I/O
+ * inspection payload, the run-scoped subscription ownership tuple, and the
+ * Log-node level. All consumed over SSE — no engine runtime dependency.
  */
 import type { GraphPortDefinition } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionEventType, GraphExecutionStatus } from "./constants.d.cts";
+import type { GraphExecutionEventType, GraphExecutionStatus, GraphVisualState } from "./constants.d.cts";
 /**
  * A value reference inside a {@link ConditionExpression}.
  *
@@ -166,3 +168,90 @@ export interface GraphExecutionEvent {
     error?: GraphExecutionErrorPayload;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Payload carried by `NODE_STATE_CHANGED` events (DECAF-48 §4.4).
+ *
+ * The visual state is the engine-agnostic contract a Mastra/NestJS driver
+ * MUST emit; the reference engine derives it from its own execution events.
+ */
+export interface GraphNodeStateChangedPayload {
+    nodeId: string;
+    state: GraphVisualState;
+    runId: string;
+    workflowId: string;
+    /** Engine status that produced the visual state (when available). */
+    status?: GraphExecutionStatus;
+    iteration?: number;
+}
+/**
+ * Payload carried by `EDGE_STATE_CHANGED` events (DECAF-48 §4.4).
+ */
+export interface GraphEdgeStateChangedPayload {
+    edgeId: string;
+    state: GraphVisualState;
+    runId: string;
+    workflowId: string;
+    /** Source node of the routed edge (when available). */
+    nodeId?: string;
+    /** Engine status that produced the visual state (when available). */
+    status?: GraphExecutionStatus;
+}
+/**
+ * Structured log line streamed over the `graph.run.log` SSE channel
+ * (DECAF-48 §4.3). Serialized from the run's `ctx.logger` output; the level
+ * drives the Chrome-console-style filter while the attributes render as
+ * discrete columns.
+ */
+export interface GraphRunLogEntry {
+    /** Log severity level driving the Chrome-console-style widget filter (all `LogNodeLevel` values plus `benchmark`). */
+    level: "silly" | "trace" | "debug" | "verbose" | "info" | "warn" | "error" | "critical" | "fatal" | "benchmark";
+    message: string;
+    timestamp: string;
+    runId: string;
+    workflowId: string;
+    nodeId?: string;
+    user?: string | null;
+    /** Structured payload associated with the log line, if any. */
+    payload?: unknown;
+}
+/**
+ * Structured per-node I/O payload exposed for node inspection (DECAF-48 §4.6).
+ *
+ * Frontend-safe: pure data delivered via `graph/shared` types over the SSE
+ * state channel (or a `GET /graph/results/:runId` lookup); the frontend
+ * renders both panes (inputs right, outputs/error left) from this one shape.
+ */
+export interface GraphNodeInspectionPayload {
+    runId: string;
+    workflowId: string;
+    nodeId: string;
+    state: GraphVisualState;
+    inputs: Record<string, unknown>;
+    /** Present when SUCCEEDED (or from cache). */
+    outputs?: Record<string, unknown>;
+    /** Present when FAILED. */
+    error?: GraphExecutionErrorPayload;
+}
+/**
+ * Log levels accepted by the Log node (DECAF-48 §4.3).
+ *
+ * Mirrors the DECAF-9 log level set so the Log node executor (and the
+ * {@link GraphRunLogger} dispatch) can forward onto the run's `ctx.logger`.
+ * Includes every level rendered by the Chrome-console-style widget filter.
+ */
+export type LogNodeLevel = "silly" | "trace" | "debug" | "verbose" | "info" | "warn" | "error" | "critical" | "fatal";
+/**
+ * Run-scoped SSE subscription ownership key (DECAF-48 §4.2).
+ *
+ * Subscription-mode SSE is keyed by run ownership: a consumer is only
+ * delivered graph events/logs for runs it owns. This tuple is the
+ * engine-agnostic contract a Mastra/NestJS driver MUST honour —
+ * `runId` together with the owning `user` (or a `system` runner when the
+ * identity is absent) scope every `graph.run.*` event before `next(...)`.
+ */
+export interface GraphRunSubscription {
+    runId: string;
+    ownerUser: string | null;
+    /** Optional topic filter (e.g. `graph.run.log`, `graph.run.state`). */
+    topics?: string[];
+}

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

@@ -2,13 +2,15 @@
  * @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.
+ * frontend bundle. Alongside the declarative graph metadata types (loop
+ * condition DSL, switch cases, node metadata patches), this module carries the
+ * DECAF-48 execution contract consumed by the frontend via SSE: the node/edge
+ * state-change payloads, the structured run log entry, the node I/O
+ * inspection payload, the run-scoped subscription ownership tuple, and the
+ * Log-node level. All consumed over SSE — no engine runtime dependency.
  */
 import type { GraphPortDefinition } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionEventType, GraphExecutionStatus } from "./constants.d.mts";
+import type { GraphExecutionEventType, GraphExecutionStatus, GraphVisualState } from "./constants.d.mts";
 /**
  * A value reference inside a {@link ConditionExpression}.
  *
@@ -166,3 +168,90 @@ export interface GraphExecutionEvent {
     error?: GraphExecutionErrorPayload;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Payload carried by `NODE_STATE_CHANGED` events (DECAF-48 §4.4).
+ *
+ * The visual state is the engine-agnostic contract a Mastra/NestJS driver
+ * MUST emit; the reference engine derives it from its own execution events.
+ */
+export interface GraphNodeStateChangedPayload {
+    nodeId: string;
+    state: GraphVisualState;
+    runId: string;
+    workflowId: string;
+    /** Engine status that produced the visual state (when available). */
+    status?: GraphExecutionStatus;
+    iteration?: number;
+}
+/**
+ * Payload carried by `EDGE_STATE_CHANGED` events (DECAF-48 §4.4).
+ */
+export interface GraphEdgeStateChangedPayload {
+    edgeId: string;
+    state: GraphVisualState;
+    runId: string;
+    workflowId: string;
+    /** Source node of the routed edge (when available). */
+    nodeId?: string;
+    /** Engine status that produced the visual state (when available). */
+    status?: GraphExecutionStatus;
+}
+/**
+ * Structured log line streamed over the `graph.run.log` SSE channel
+ * (DECAF-48 §4.3). Serialized from the run's `ctx.logger` output; the level
+ * drives the Chrome-console-style filter while the attributes render as
+ * discrete columns.
+ */
+export interface GraphRunLogEntry {
+    /** Log severity level driving the Chrome-console-style widget filter (all `LogNodeLevel` values plus `benchmark`). */
+    level: "silly" | "trace" | "debug" | "verbose" | "info" | "warn" | "error" | "critical" | "fatal" | "benchmark";
+    message: string;
+    timestamp: string;
+    runId: string;
+    workflowId: string;
+    nodeId?: string;
+    user?: string | null;
+    /** Structured payload associated with the log line, if any. */
+    payload?: unknown;
+}
+/**
+ * Structured per-node I/O payload exposed for node inspection (DECAF-48 §4.6).
+ *
+ * Frontend-safe: pure data delivered via `graph/shared` types over the SSE
+ * state channel (or a `GET /graph/results/:runId` lookup); the frontend
+ * renders both panes (inputs right, outputs/error left) from this one shape.
+ */
+export interface GraphNodeInspectionPayload {
+    runId: string;
+    workflowId: string;
+    nodeId: string;
+    state: GraphVisualState;
+    inputs: Record<string, unknown>;
+    /** Present when SUCCEEDED (or from cache). */
+    outputs?: Record<string, unknown>;
+    /** Present when FAILED. */
+    error?: GraphExecutionErrorPayload;
+}
+/**
+ * Log levels accepted by the Log node (DECAF-48 §4.3).
+ *
+ * Mirrors the DECAF-9 log level set so the Log node executor (and the
+ * {@link GraphRunLogger} dispatch) can forward onto the run's `ctx.logger`.
+ * Includes every level rendered by the Chrome-console-style widget filter.
+ */
+export type LogNodeLevel = "silly" | "trace" | "debug" | "verbose" | "info" | "warn" | "error" | "critical" | "fatal";
+/**
+ * Run-scoped SSE subscription ownership key (DECAF-48 §4.2).
+ *
+ * Subscription-mode SSE is keyed by run ownership: a consumer is only
+ * delivered graph events/logs for runs it owns. This tuple is the
+ * engine-agnostic contract a Mastra/NestJS driver MUST honour —
+ * `runId` together with the owning `user` (or a `system` runner when the
+ * identity is absent) scope every `graph.run.*` event before `next(...)`.
+ */
+export interface GraphRunSubscription {
+    runId: string;
+    ownerUser: string | null;
+    /** Optional topic filter (e.g. `graph.run.log`, `graph.run.state`). */
+    topics?: string[];
+}

package/lib/types/index.d.cts

@@ -7,6 +7,6 @@ export * from "./utils.d.cts";
 export * from "./namespaces/index.d.cts";
 export * from "./feature-flags/index.d.cts";
 export declare const VERSION: string;
-export declare const COMMIT = "2638fa3";
-export declare const FULL_VERSION = "0.6.1-2638fa3";
+export declare const COMMIT = "6c8a9c2";
+export declare const FULL_VERSION = "0.6.2-6c8a9c2";
 export declare const PACKAGE_NAME: string;

package/lib/types/index.d.mts

@@ -7,6 +7,6 @@ export * from "./utils.d.mts";
 export * from "./namespaces/index.d.mts";
 export * from "./feature-flags/index.d.mts";
 export declare const VERSION: string;
-export declare const COMMIT = "2638fa3";
-export declare const FULL_VERSION = "0.6.1-2638fa3";
+export declare const COMMIT = "6c8a9c2";
+export declare const FULL_VERSION = "0.6.2-6c8a9c2";
 export declare const PACKAGE_NAME: string;

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

@@ -1,5 +1,5 @@
-import { Model, type ModelArg } from "@decaf-ts/decorator-validation";
-export declare class GraphExecutionResultModel extends Model {
+import { BaseModel } from "@decaf-ts/core";
+export declare class GraphExecutionResultModel extends BaseModel {
     runId: string;
     workflowId: string;
     status: string;
@@ -8,5 +8,5 @@ export declare class GraphExecutionResultModel extends Model {
     nodeResults: Record<string, unknown>;
     startedAt: Date;
     finishedAt?: Date;
-    constructor(arg?: ModelArg<GraphExecutionResultModel>);
+    constructor(arg?: Partial<GraphExecutionResultModel>);
 }

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

@@ -1,5 +1,5 @@
-import { Model, type ModelArg } from "@decaf-ts/decorator-validation";
-export declare class GraphExecutionResultModel extends Model {
+import { BaseModel } from "@decaf-ts/core";
+export declare class GraphExecutionResultModel extends BaseModel {
     runId: string;
     workflowId: string;
     status: string;
@@ -8,5 +8,5 @@ export declare class GraphExecutionResultModel extends Model {
     nodeResults: Record<string, unknown>;
     startedAt: Date;
     finishedAt?: Date;
-    constructor(arg?: ModelArg<GraphExecutionResultModel>);
+    constructor(arg?: Partial<GraphExecutionResultModel>);
 }