@decaf-ts/integrations 0.6.1 → 0.7.0

package/lib/esm/nest/graph/GraphExecutorRegistryFactory.js

@@ -4,9 +4,9 @@
  * @description Creates a registry pre-loaded with the demo executors used by
  * the graph execution backend's sample workflows. The executors cover the
  * flow-control kinds (including Code, Log, and Switch with code conditions),
- * the agent kind, and the loop kinds. Additional executors can be registered
- * on the returned registry before it is handed to the
- * {@link GraphExecutionEngine}.
+ * the DECAF-48 `core.utility.log` Log node, the agent kind, and the loop
+ * kinds. Additional executors can be registered on the returned registry
+ * before it is handed to the {@link GraphExecutionEngine}.
  */
 import { GraphNodeExecutorRegistry, ForeachGraphNodeExecutor, WhileGraphNodeExecutor, UntilGraphNodeExecutor, CodeGraphNodeExecutor, LogGraphNodeExecutor, SwitchGraphNodeExecutor, BreakGraphNodeExecutor, IsolatedVmCodeSandboxEvaluator, } from "./../../graph/index.js";
 import { GraphBreakSignal } from "./../../graph/engine/errors/GraphBreakSignal.js";
@@ -86,6 +86,7 @@ export function createDemoEngineConfig() {
             registry.register("core.loop.until", new UntilGraphNodeExecutor(engine));
             registry.register("core.flow.code", new CodeGraphNodeExecutor(engine));
             registry.register("core.flow.log", new LogGraphNodeExecutor());
+            registry.register("core.utility.log", new LogGraphNodeExecutor());
             registry.register("core.flow.switch", new SwitchGraphNodeExecutor(engine));
             registry.register("core.flow.break", new BreakGraphNodeExecutor());
         },

package/lib/esm/nest/graph/GraphExecutorRegistryFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"GraphExecutorRegistryFactory.js","sourceRoot":"","sources":["../../../../src/nest/graph/GraphExecutorRegistryFactory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GraphExecutorRegistryFactory.js","sourceRoot":"","sources":["../../../../src/nest/graph/GraphExecutorRegistryFactory.ts"],"names":[],"mappings":"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"}

package/lib/esm/nest/graph/GraphWorkflowModel.js

@@ -7,9 +7,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { Model, model } from "@decaf-ts/decorator-validation";
-import { column, pk, table } from "@decaf-ts/core";
-let GraphWorkflowModel = class GraphWorkflowModel extends Model {
+import { model } from "@decaf-ts/decorator-validation";
+import { BaseModel, column, pk, table } from "@decaf-ts/core";
+let GraphWorkflowModel = class GraphWorkflowModel extends BaseModel {
     constructor(arg) {
         super(arg);
     }
@@ -22,10 +22,6 @@ __decorate([
     column(),
     __metadata("design:type", Object)
 ], GraphWorkflowModel.prototype, "snapshot", void 0);
-__decorate([
-    column(),
-    __metadata("design:type", Date)
-], GraphWorkflowModel.prototype, "updatedAt", void 0);
 GraphWorkflowModel = __decorate([
     table("graph_workflow_snapshot"),
     model(),

package/lib/esm/nest/graph/GraphWorkflowModel.js.map

@@ -1 +1 @@
-{"version":3,"file":"GraphWorkflowModel.js","sourceRoot":"","sources":["../../../../src/nest/graph/GraphWorkflowModel.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAiB,MAAM,gCAAgC,CAAC;AAC7E,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAI5C,IAAM,kBAAkB,GAAxB,MAAM,kBAAmB,SAAQ,KAAK;IAU3C,YAAY,GAAkC;QAC5C,KAAK,CAAC,GAAG,CAAC,CAAC;IACb,CAAC;CACF,CAAA;AAXC;IADC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;;sDACnB;AAGpB;IADC,MAAM,EAAE;;oDAC0B;AAGnC;IADC,MAAM,EAAE;8BACG,IAAI;qDAAC;AARN,kBAAkB;IAF9B,KAAK,CAAC,yBAAyB,CAAC;IAChC,KAAK,EAAE;;GACK,kBAAkB,CAa9B"}
+{"version":3,"file":"GraphWorkflowModel.js","sourceRoot":"","sources":["../../../../src/nest/graph/GraphWorkflowModel.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAIvD,IAAM,kBAAkB,GAAxB,MAAM,kBAAmB,SAAQ,SAAS;IAO/C,YAAY,GAAiC;QAC3C,KAAK,CAAC,GAAG,CAAC,CAAC;IACb,CAAC;CACF,CAAA;AARC;IADC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;;sDACnB;AAGpB;IADC,MAAM,EAAE;;oDAC0B;AALxB,kBAAkB;IAF9B,KAAK,CAAC,yBAAyB,CAAC;IAChC,KAAK,EAAE;;GACK,kBAAkB,CAU9B"}

package/lib/esm/user-requests/index.js

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/user-requests
+ * @summary User Request Resolution Engine surface exported to integrations
+ * consumers.
+ * @description Re-exports the `@decaf-ts/ui-decorators/user-requests` barrel so
+ * integrations packages can hand user-request handling to app consumers
+ * through a flat entry point.
+ */
+export * from '@decaf-ts/ui-decorators/user-requests';
+//# sourceMappingURL=index.js.map

package/lib/esm/user-requests/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/user-requests/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,uCAAuC,CAAC"}

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

@@ -1,10 +1,11 @@
 /**
  * @module integrations/graph/execution/GraphExecutionContext
  * @summary Decaf Context for graph node execution.
- * @description Extends Decaf's {@link Context} so node executors receive the same contextual plumbing as task handlers. Executors use the context to emit progress, log messages, and report state through the engine's observer pipeline.
+ * @description Extends Decaf's {@link Context} so node executors receive the same contextual plumbing as task handlers. Executors use the context to emit progress, log messages, and report state through the engine's observer pipeline. Each context also exposes a run-scoped `ctx.logger` (DECAF-48 §4.3) bound to the executing node's `runId` / `workflowId` / `nodeId` / `user`, so every log line streams over `graph.run.log` with the DECAF-9 custom attributes.
  */
 import { Context } from "@decaf-ts/core";
 import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { Logger } from "@decaf-ts/logging";
 import type { GraphExecutionEvent, GraphRunId } from "../types.d.cts";
 /**
  * Context passed to every graph node executor.
@@ -12,7 +13,8 @@ import type { GraphExecutionEvent, GraphRunId } from "../types.d.cts";
  * Mirrors the `TaskEngine` / `TaskContext` pattern: the engine creates a
  * `GraphExecutionContext` per node execution and passes it to
  * `executor.execute(inputs, context)`. The executor uses `context.progress(...)`
- * and `context.log(...)` to report intermediate state.
+ * and `context.log(...)` to report intermediate state, and `context.logger`
+ * to emit structured run log lines (DECAF-48 §4.3).
  */
 export declare class GraphExecutionContext extends Context {
     readonly runId: GraphRunId;
@@ -22,6 +24,7 @@ export declare class GraphExecutionContext extends Context {
     readonly path: string[];
     private readonly emitFn;
     readonly metadata: Record<string, unknown>;
+    private readonly runLogger?;
     /**
      * @param runId - Unique identifier for the current execution run.
      * @param parentRunId - Run id of the parent execution (for nested loop bodies).
@@ -32,6 +35,13 @@ export declare class GraphExecutionContext extends Context {
      * @param metadata - Free-form metadata attached to this context.
      */
     constructor(runId: GraphRunId, parentRunId: GraphRunId | undefined, workflow: GraphWorkflowDefinition, node: GraphNodeDefinition, path: string[], emitFn: (event: Partial<GraphExecutionEvent>) => Promise<void>, metadata?: Record<string, unknown>);
+    /**
+     * The decaf-ts {@link Logger} bound to this node's run context. Every log
+     * line carries the DECAF-48 attributes (`nodeId` / `workflowId` / `runId` /
+     * `user`) and is forwarded onto the existing graph execution Observable as
+     * a `GRAPH_RUN_LOG` event (streamed over the `graph.run.log` SSE channel).
+     */
+    get logger(): Logger;
     /**
      * Emits a partial graph execution event. The engine fills in runId,
      * parentRunId, workflowId, nodeId, and path automatically.

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

@@ -1,10 +1,11 @@
 /**
  * @module integrations/graph/execution/GraphExecutionContext
  * @summary Decaf Context for graph node execution.
- * @description Extends Decaf's {@link Context} so node executors receive the same contextual plumbing as task handlers. Executors use the context to emit progress, log messages, and report state through the engine's observer pipeline.
+ * @description Extends Decaf's {@link Context} so node executors receive the same contextual plumbing as task handlers. Executors use the context to emit progress, log messages, and report state through the engine's observer pipeline. Each context also exposes a run-scoped `ctx.logger` (DECAF-48 §4.3) bound to the executing node's `runId` / `workflowId` / `nodeId` / `user`, so every log line streams over `graph.run.log` with the DECAF-9 custom attributes.
  */
 import { Context } from "@decaf-ts/core";
 import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { Logger } from "@decaf-ts/logging";
 import type { GraphExecutionEvent, GraphRunId } from "../types.d.mts";
 /**
  * Context passed to every graph node executor.
@@ -12,7 +13,8 @@ import type { GraphExecutionEvent, GraphRunId } from "../types.d.mts";
  * Mirrors the `TaskEngine` / `TaskContext` pattern: the engine creates a
  * `GraphExecutionContext` per node execution and passes it to
  * `executor.execute(inputs, context)`. The executor uses `context.progress(...)`
- * and `context.log(...)` to report intermediate state.
+ * and `context.log(...)` to report intermediate state, and `context.logger`
+ * to emit structured run log lines (DECAF-48 §4.3).
  */
 export declare class GraphExecutionContext extends Context {
     readonly runId: GraphRunId;
@@ -22,6 +24,7 @@ export declare class GraphExecutionContext extends Context {
     readonly path: string[];
     private readonly emitFn;
     readonly metadata: Record<string, unknown>;
+    private readonly runLogger?;
     /**
      * @param runId - Unique identifier for the current execution run.
      * @param parentRunId - Run id of the parent execution (for nested loop bodies).
@@ -32,6 +35,13 @@ export declare class GraphExecutionContext extends Context {
      * @param metadata - Free-form metadata attached to this context.
      */
     constructor(runId: GraphRunId, parentRunId: GraphRunId | undefined, workflow: GraphWorkflowDefinition, node: GraphNodeDefinition, path: string[], emitFn: (event: Partial<GraphExecutionEvent>) => Promise<void>, metadata?: Record<string, unknown>);
+    /**
+     * The decaf-ts {@link Logger} bound to this node's run context. Every log
+     * line carries the DECAF-48 attributes (`nodeId` / `workflowId` / `runId` /
+     * `user`) and is forwarded onto the existing graph execution Observable as
+     * a `GRAPH_RUN_LOG` event (streamed over the `graph.run.log` SSE channel).
+     */
+    get logger(): Logger;
     /**
      * Emits a partial graph execution event. The engine fills in runId,
      * parentRunId, workflowId, nodeId, and path automatically.

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

@@ -1,7 +1,7 @@
 /**
  * @module integrations/graph/execution/GraphExecutionEngine
  * @summary Reference graph execution engine.
- * @description Executes graph workflows declared with `@decaf-ts/ui-decorators/graph`, emits events through Decaf's Observable pipeline, supports parallel node execution within topological layers, and returns a complete execution result.
+ * @description Executes graph workflows declared with `@decaf-ts/ui-decorators/graph`, emits events through Decaf's Observable pipeline, supports parallel node execution within topological layers, and returns a complete execution result. Per DECAF-48 §4.4 it also emits `NODE_STATE_CHANGED` / `EDGE_STATE_CHANGED` visual-state events on the same pipeline, and node executors log through the run-scoped `ctx.logger` (streamed over the `graph.run.log` SSE channel).
  */
 import type { Observable } from "@decaf-ts/core";
 import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
@@ -56,11 +56,33 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
     readonly codeSandboxEvaluator?: CodeSandboxEvaluator;
     constructor(config: GraphExecutionEngineConfig);
     private readonly config;
+    /**
+     * Registers an observer on the engine's event pipeline.
+     *
+     * @param observer - The observer to register.
+     * @returns An unsubscribe function that removes the observer.
+     */
     observe(observer: GraphExecutionObserver): () => void;
+    /**
+     * Unregisters an observer from the engine's event pipeline.
+     *
+     * @param observer - The observer to remove.
+     */
     unObserve(observer: GraphExecutionObserver): void;
+    /**
+     * Dispatches an event to all registered observers.
+     *
+     * @param event - The event to distribute.
+     */
     updateObservers(event: GraphExecutionEvent): Promise<void>;
     /**
      * Executes a workflow with the given inputs and options.
+     *
+     * @param workflow - The workflow definition to execute.
+     * @param inputs - Workflow input values keyed by input port name.
+     * @param options - Optional execution overrides (merged over the defaults).
+     * @returns The complete execution result, including a `runId`, per-node
+     * results, and workflow outputs (or the failure payload).
      */
     execute(workflow: GraphWorkflowDefinition, inputs?: GraphExecutionValues, options?: GraphExecutionOptions): Promise<GraphExecutionResult>;
     /**
@@ -120,6 +142,17 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
      * Emits an event, records it in the frame, and dispatches to observers.
      */
     private emitEvent;
+    /**
+     * Emits a `NODE_STATE_CHANGED` event (DECAF-48 §4.4) carrying the given
+     * visual state for the node. Rides the existing Observable pipeline; no
+     * second out-of-band channel.
+     */
+    private emitNodeStateChanged;
+    /**
+     * Emits an `EDGE_STATE_CHANGED` event (DECAF-48 §4.4) carrying the given
+     * visual state for a routed edge.
+     */
+    private emitEdgeStateChanged;
     /**
      * Merges default options with the given options.
      */

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

@@ -1,7 +1,7 @@
 /**
  * @module integrations/graph/execution/GraphExecutionEngine
  * @summary Reference graph execution engine.
- * @description Executes graph workflows declared with `@decaf-ts/ui-decorators/graph`, emits events through Decaf's Observable pipeline, supports parallel node execution within topological layers, and returns a complete execution result.
+ * @description Executes graph workflows declared with `@decaf-ts/ui-decorators/graph`, emits events through Decaf's Observable pipeline, supports parallel node execution within topological layers, and returns a complete execution result. Per DECAF-48 §4.4 it also emits `NODE_STATE_CHANGED` / `EDGE_STATE_CHANGED` visual-state events on the same pipeline, and node executors log through the run-scoped `ctx.logger` (streamed over the `graph.run.log` SSE channel).
  */
 import type { Observable } from "@decaf-ts/core";
 import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
@@ -56,11 +56,33 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
     readonly codeSandboxEvaluator?: CodeSandboxEvaluator;
     constructor(config: GraphExecutionEngineConfig);
     private readonly config;
+    /**
+     * Registers an observer on the engine's event pipeline.
+     *
+     * @param observer - The observer to register.
+     * @returns An unsubscribe function that removes the observer.
+     */
     observe(observer: GraphExecutionObserver): () => void;
+    /**
+     * Unregisters an observer from the engine's event pipeline.
+     *
+     * @param observer - The observer to remove.
+     */
     unObserve(observer: GraphExecutionObserver): void;
+    /**
+     * Dispatches an event to all registered observers.
+     *
+     * @param event - The event to distribute.
+     */
     updateObservers(event: GraphExecutionEvent): Promise<void>;
     /**
      * Executes a workflow with the given inputs and options.
+     *
+     * @param workflow - The workflow definition to execute.
+     * @param inputs - Workflow input values keyed by input port name.
+     * @param options - Optional execution overrides (merged over the defaults).
+     * @returns The complete execution result, including a `runId`, per-node
+     * results, and workflow outputs (or the failure payload).
      */
     execute(workflow: GraphWorkflowDefinition, inputs?: GraphExecutionValues, options?: GraphExecutionOptions): Promise<GraphExecutionResult>;
     /**
@@ -120,6 +142,17 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
      * Emits an event, records it in the frame, and dispatches to observers.
      */
     private emitEvent;
+    /**
+     * Emits a `NODE_STATE_CHANGED` event (DECAF-48 §4.4) carrying the given
+     * visual state for the node. Rides the existing Observable pipeline; no
+     * second out-of-band channel.
+     */
+    private emitNodeStateChanged;
+    /**
+     * Emits an `EDGE_STATE_CHANGED` event (DECAF-48 §4.4) carrying the given
+     * visual state for a routed edge.
+     */
+    private emitEdgeStateChanged;
     /**
      * Merges default options with the given options.
      */

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

@@ -1,19 +1,25 @@
-/**
- * @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.
+ * Executor for `core.utility.log` / `core.flow.log` nodes.
  *
- * Reads the `value` input port, logs it through `context.log()`, and returns
- * it unchanged on the `logged` output port.
+ * Reads the `value` input port, logs it through `context.logger` at the
+ * configured level, and returns it unchanged on the `logged` output port.
  */
 export declare class LogGraphNodeExecutor implements GraphNodeExecutor {
+    /**
+     * Logs the `value` input through the run's `ctx.logger` and forwards it
+     * unchanged on the `logged` output port.
+     *
+     * The level is read from the node's UI config (`node.props.level`, see
+     * {@link logLevelOf}) and defaults to `info`. The emitted log line carries
+     * the DECAF-48 run attributes and streams over `graph.run.log` through the
+     * shared `ctx.logger` path (DECAF-48 Req-1).
+     *
+     * @param input - Resolved input values keyed by port name (expects `value`).
+     * @param context - The run-scoped execution context exposing `ctx.logger`.
+     * @returns The node's output values keyed by port name (the `logged` port).
+     */
     execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
 }

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

@@ -1,19 +1,25 @@
-/**
- * @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.
+ * Executor for `core.utility.log` / `core.flow.log` nodes.
  *
- * Reads the `value` input port, logs it through `context.log()`, and returns
- * it unchanged on the `logged` output port.
+ * Reads the `value` input port, logs it through `context.logger` at the
+ * configured level, and returns it unchanged on the `logged` output port.
  */
 export declare class LogGraphNodeExecutor implements GraphNodeExecutor {
+    /**
+     * Logs the `value` input through the run's `ctx.logger` and forwards it
+     * unchanged on the `logged` output port.
+     *
+     * The level is read from the node's UI config (`node.props.level`, see
+     * {@link logLevelOf}) and defaults to `info`. The emitted log line carries
+     * the DECAF-48 run attributes and streams over `graph.run.log` through the
+     * shared `ctx.logger` path (DECAF-48 Req-1).
+     *
+     * @param input - Resolved input values keyed by port name (expects `value`).
+     * @param context - The run-scoped execution context exposing `ctx.logger`.
+     * @returns The node's output values keyed by port name (the `logged` port).
+     */
     execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
 }

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

@@ -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.cts";

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;