@decaf-ts/integrations 0.6.2 → 0.8.0

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

@@ -8,4 +8,5 @@
  * Frontend bundles MUST import from `@decaf-ts/integrations/graph/shared`
  * instead to avoid pulling in the execution engine.
  */
+import "./log/LogParameters";
 export * from "./engine/index.d.mts";

package/lib/types/graph/log/GraphRunLogger.d.cts

@@ -0,0 +1,72 @@
+import type { Logger, LogMeta, StringLike } from "@decaf-ts/logging";
+import type { GraphExecutionEvent } from "../shared/types.d.cts";
+/**
+ * Signature of the context's event emitter used to forward log entries onto
+ * the existing graph execution Observable.
+ */
+export type GraphLogForwardFn = (event: Partial<GraphExecutionEvent>) => Promise<void>;
+/**
+ * Options for constructing a {@link GraphRunLogger}.
+ */
+export interface GraphRunLoggerOptions {
+    runId: string;
+    workflowId: string;
+    nodeId: string;
+    user?: string | null;
+    /**
+     * Callback that forwards a structured log entry to the graph execution
+     * Observable (emits a `GRAPH_RUN_LOG` event). Errors are swallowed.
+     */
+    forward: GraphLogForwardFn;
+}
+/**
+ * Logger used by graph node executors (`ctx.logger`).
+ *
+ * Wraps the shared MiniLogger pipeline so the DECAF-48 attributes render as
+ * discrete custom attributes in the formatted output, and forwards each
+ * structured entry through {@link GraphRunLoggerOptions.forward} so the SSE
+ * log channel (`graph.run.log`) receives the level/message/attributes/
+ * timestamp payload.
+ */
+export declare class GraphRunLogger implements Logger {
+    private readonly inner;
+    private readonly baseOptions;
+    constructor(options: GraphRunLoggerOptions);
+    /**
+     * Produces the `Partial<LoggingConfig>` carrying the DECAF-48 attributes
+     * so the LogParameter descriptors render them (DECAF-9 §4.6).
+     */
+    private attributeConfig;
+    /** Emits a structured log entry synchronously (forward is fire-and-forget). */
+    private emit;
+    /** @inheritdoc */
+    benchmark(msg: StringLike, meta?: LogMeta): void;
+    /** @inheritdoc */
+    fatal(msg: StringLike | Error, error?: Error | LogMeta, meta?: LogMeta): void;
+    /** @inheritdoc */
+    critical(msg: StringLike | Error, error?: Error | LogMeta, meta?: LogMeta): void;
+    /** @inheritdoc */
+    silly(msg: StringLike, verbosity?: number | LogMeta, meta?: LogMeta): void;
+    /** @inheritdoc */
+    trace(msg: StringLike, meta?: LogMeta): void;
+    /** @inheritdoc */
+    verbose(msg: StringLike, verbosity?: number | LogMeta, meta?: LogMeta): void;
+    /** @inheritdoc */
+    info(msg: StringLike, meta?: LogMeta): void;
+    /** @inheritdoc */
+    error(msg: StringLike | Error, error?: Error | LogMeta, meta?: LogMeta): void;
+    /** @inheritdoc */
+    warn(msg: StringLike, meta?: LogMeta): void;
+    /** @inheritdoc */
+    debug(msg: StringLike, meta?: LogMeta): void;
+    /** @inheritdoc */
+    setConfig(): void;
+    /** @inheritdoc */
+    for(_method?: string | ((...args: any[]) => any) | {
+        new (...args: any[]): any;
+    } | object | Partial<any>, _config?: Partial<any>, ..._args: any[]): this;
+    /** @inheritdoc */
+    clear(): this;
+    /** @inheritdoc */
+    get root(): string[];
+}

package/lib/types/graph/log/GraphRunLogger.d.mts

@@ -0,0 +1,72 @@
+import type { Logger, LogMeta, StringLike } from "@decaf-ts/logging";
+import type { GraphExecutionEvent } from "../shared/types.d.mts";
+/**
+ * Signature of the context's event emitter used to forward log entries onto
+ * the existing graph execution Observable.
+ */
+export type GraphLogForwardFn = (event: Partial<GraphExecutionEvent>) => Promise<void>;
+/**
+ * Options for constructing a {@link GraphRunLogger}.
+ */
+export interface GraphRunLoggerOptions {
+    runId: string;
+    workflowId: string;
+    nodeId: string;
+    user?: string | null;
+    /**
+     * Callback that forwards a structured log entry to the graph execution
+     * Observable (emits a `GRAPH_RUN_LOG` event). Errors are swallowed.
+     */
+    forward: GraphLogForwardFn;
+}
+/**
+ * Logger used by graph node executors (`ctx.logger`).
+ *
+ * Wraps the shared MiniLogger pipeline so the DECAF-48 attributes render as
+ * discrete custom attributes in the formatted output, and forwards each
+ * structured entry through {@link GraphRunLoggerOptions.forward} so the SSE
+ * log channel (`graph.run.log`) receives the level/message/attributes/
+ * timestamp payload.
+ */
+export declare class GraphRunLogger implements Logger {
+    private readonly inner;
+    private readonly baseOptions;
+    constructor(options: GraphRunLoggerOptions);
+    /**
+     * Produces the `Partial<LoggingConfig>` carrying the DECAF-48 attributes
+     * so the LogParameter descriptors render them (DECAF-9 §4.6).
+     */
+    private attributeConfig;
+    /** Emits a structured log entry synchronously (forward is fire-and-forget). */
+    private emit;
+    /** @inheritdoc */
+    benchmark(msg: StringLike, meta?: LogMeta): void;
+    /** @inheritdoc */
+    fatal(msg: StringLike | Error, error?: Error | LogMeta, meta?: LogMeta): void;
+    /** @inheritdoc */
+    critical(msg: StringLike | Error, error?: Error | LogMeta, meta?: LogMeta): void;
+    /** @inheritdoc */
+    silly(msg: StringLike, verbosity?: number | LogMeta, meta?: LogMeta): void;
+    /** @inheritdoc */
+    trace(msg: StringLike, meta?: LogMeta): void;
+    /** @inheritdoc */
+    verbose(msg: StringLike, verbosity?: number | LogMeta, meta?: LogMeta): void;
+    /** @inheritdoc */
+    info(msg: StringLike, meta?: LogMeta): void;
+    /** @inheritdoc */
+    error(msg: StringLike | Error, error?: Error | LogMeta, meta?: LogMeta): void;
+    /** @inheritdoc */
+    warn(msg: StringLike, meta?: LogMeta): void;
+    /** @inheritdoc */
+    debug(msg: StringLike, meta?: LogMeta): void;
+    /** @inheritdoc */
+    setConfig(): void;
+    /** @inheritdoc */
+    for(_method?: string | ((...args: any[]) => any) | {
+        new (...args: any[]): any;
+    } | object | Partial<any>, _config?: Partial<any>, ..._args: any[]): this;
+    /** @inheritdoc */
+    clear(): this;
+    /** @inheritdoc */
+    get root(): string[];
+}

package/lib/types/graph/log/LogParameters.d.cts

@@ -0,0 +1,7 @@
+/**
+ * Registers the four DECAF-48 run attributes as log parameter descriptors
+ * (nodeId / workflowId / runId / user). Rendered only when keyed with a
+ * non-null value so one-shot module imports from other packages never leak
+ * empty columns.
+ */
+export declare function registerGraphRunLogParameters(): void;

package/lib/types/graph/log/LogParameters.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Registers the four DECAF-48 run attributes as log parameter descriptors
+ * (nodeId / workflowId / runId / user). Rendered only when keyed with a
+ * non-null value so one-shot module imports from other packages never leak
+ * empty columns.
+ */
+export declare function registerGraphRunLogParameters(): void;

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

@@ -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.cts";
+import { GraphExecutionStatus, GraphVisualState } from "./constants.d.cts";
+/**
+ * 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/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];