@decaf-ts/integrations 0.8.0 → 0.9.0

package/lib/types/graph/engine/planning/GraphExecutionPlanEdge.d.cts

@@ -1,17 +1,22 @@
 /**
  * @module integrations/graph/planning/GraphExecutionPlanEdge
  * @summary Plan edge type for the execution plan.
- * @description Represents a directed value route between two endpoints (node-to-node or node-to-workflow-boundary).
+ * @description Represents a directed route between two endpoints
+ * (node-to-node or node-to-workflow-boundary) produced by the §4.8 edge
+ * validation stage. Data edges route values; connection edges are structural.
  */
 /**
- * An edge in the execution plan representing a value route from a source
- * port to a target port.
+ * An edge in the execution plan representing a route from a source port to a
+ * target port.
  *
  * `sourceNodeId` or `targetNodeId` may be {@link GRAPH_WORKFLOW_BOUNDARY} when
- * the edge connects to the workflow boundary.
+ * the edge connects to the workflow boundary. `type` distinguishes value
+ * routing (`data`) from structural (`connection`) edges.
  */
 export interface GraphExecutionPlanEdge {
     id: string;
+    /** `data` routes values; `connection` is structural only. */
+    type: "data" | "connection";
     sourceNodeId: string;
     sourcePort: string;
     targetNodeId: string;

package/lib/types/graph/engine/planning/GraphExecutionPlanEdge.d.mts

@@ -1,17 +1,22 @@
 /**
  * @module integrations/graph/planning/GraphExecutionPlanEdge
  * @summary Plan edge type for the execution plan.
- * @description Represents a directed value route between two endpoints (node-to-node or node-to-workflow-boundary).
+ * @description Represents a directed route between two endpoints
+ * (node-to-node or node-to-workflow-boundary) produced by the §4.8 edge
+ * validation stage. Data edges route values; connection edges are structural.
  */
 /**
- * An edge in the execution plan representing a value route from a source
- * port to a target port.
+ * An edge in the execution plan representing a route from a source port to a
+ * target port.
  *
  * `sourceNodeId` or `targetNodeId` may be {@link GRAPH_WORKFLOW_BOUNDARY} when
- * the edge connects to the workflow boundary.
+ * the edge connects to the workflow boundary. `type` distinguishes value
+ * routing (`data`) from structural (`connection`) edges.
  */
 export interface GraphExecutionPlanEdge {
     id: string;
+    /** `data` routes values; `connection` is structural only. */
+    type: "data" | "connection";
     sourceNodeId: string;
     sourcePort: string;
     targetNodeId: string;

package/lib/types/graph/engine/planning/GraphExecutionPlanNode.d.cts

@@ -1,20 +1,28 @@
 /**
  * @module integrations/graph/planning/GraphExecutionPlanNode
- * @summary Plan node type for the execution plan.
- * @description Represents a single node resolved from a workflow definition, ready for execution.
+ * @summary Plan node type for the execution plan (DECAF-50 §4.9).
+ * @description A node fully resolved against the trusted backend catalogue:
+ * the canonical instance, the effective (dynamics-expanded) manifest, and
+ * the paired executor. The planner never carries raw node definitions.
  */
-import type { GraphNodeDefinition, GraphWorkflowNodeMetadata } from "@decaf-ts/ui-decorators/graph";
+import type { GraphJsonValue, GraphNodeInstance } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.cts";
 /**
- * A node in the execution plan, derived from a workflow's node metadata and
- * its resolved graph definition.
+ * A node in the execution plan, resolved from a
+ * {@link GraphResolvedWorkflow} (DECAF-50 §4.9).
  */
 export interface GraphExecutionPlanNode {
     id: string;
     kind: string;
-    label?: string;
-    source: GraphWorkflowNodeMetadata;
-    definition: GraphNodeDefinition;
+    /** The canonical node instance from the workflow document. */
+    instance: GraphNodeInstance;
+    /** The effective (dynamics-expanded) manifest for the instance. */
+    manifest: GraphResolvedNodeManifest;
+    /** The trusted executor paired with the kind in the backend catalogue. */
+    executor: GraphNodeExecutor;
     inputPorts: string[];
     outputPorts: string[];
-    metadata?: Record<string, unknown>;
+    connectionPorts: string[];
+    metadata?: Record<string, GraphJsonValue>;
 }

package/lib/types/graph/engine/planning/GraphExecutionPlanNode.d.mts

@@ -1,20 +1,28 @@
 /**
  * @module integrations/graph/planning/GraphExecutionPlanNode
- * @summary Plan node type for the execution plan.
- * @description Represents a single node resolved from a workflow definition, ready for execution.
+ * @summary Plan node type for the execution plan (DECAF-50 §4.9).
+ * @description A node fully resolved against the trusted backend catalogue:
+ * the canonical instance, the effective (dynamics-expanded) manifest, and
+ * the paired executor. The planner never carries raw node definitions.
  */
-import type { GraphNodeDefinition, GraphWorkflowNodeMetadata } from "@decaf-ts/ui-decorators/graph";
+import type { GraphJsonValue, GraphNodeInstance } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.mts";
 /**
- * A node in the execution plan, derived from a workflow's node metadata and
- * its resolved graph definition.
+ * A node in the execution plan, resolved from a
+ * {@link GraphResolvedWorkflow} (DECAF-50 §4.9).
  */
 export interface GraphExecutionPlanNode {
     id: string;
     kind: string;
-    label?: string;
-    source: GraphWorkflowNodeMetadata;
-    definition: GraphNodeDefinition;
+    /** The canonical node instance from the workflow document. */
+    instance: GraphNodeInstance;
+    /** The effective (dynamics-expanded) manifest for the instance. */
+    manifest: GraphResolvedNodeManifest;
+    /** The trusted executor paired with the kind in the backend catalogue. */
+    executor: GraphNodeExecutor;
     inputPorts: string[];
     outputPorts: string[];
-    metadata?: Record<string, unknown>;
+    connectionPorts: string[];
+    metadata?: Record<string, GraphJsonValue>;
 }

package/lib/types/graph/engine/planning/GraphExecutionPlanner.d.cts

@@ -1,60 +1,48 @@
-/**
- * @module integrations/graph/planning/GraphExecutionPlanner
- * @summary Topological planner for graph workflows.
- * @description Resolves workflow nodes and relations, validates topology, detects cycles, and produces topological execution layers using Kahn's algorithm.
- */
-import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedWorkflow } from "../validation/GraphResolvedWorkflow.d.cts";
 import type { GraphExecutionPlan } from "./GraphExecutionPlan.d.cts";
-import { GraphRelationResolver } from "./GraphRelationResolver.d.cts";
 /**
- * Planner that turns a {@link GraphWorkflowDefinition} into a
+ * Planner that turns a {@link GraphResolvedWorkflow} into a
  * {@link GraphExecutionPlan} with topological layers.
  */
 export declare class GraphExecutionPlanner {
-    private readonly resolver;
-    constructor(resolver?: GraphRelationResolver);
     /**
-     * Plans a workflow for execution.
+     * Plans a resolved workflow for execution.
      *
-     * @param workflow - The workflow definition to plan.
+     * @param workflow - The catalogue-resolved workflow (output of the
+     *   nine-stage validation gate). Raw `GraphWorkflowDefinition` objects and
+     *   inline `GraphNodeDefinition` objects are rejected.
      * @returns The execution plan with nodes, edges, layers, and maps.
-     * @throws {GraphTopologyError} when node IDs are not unique.
+     * @throws {GraphTopologyError} when the input is not a resolved workflow.
      * @throws {GraphCycleError} when the workflow contains an unsupported cycle.
      */
-    plan(workflow: GraphWorkflowDefinition): GraphExecutionPlan;
-    /**
-     * Validates that all workflow node IDs are unique.
-     */
-    private validateUniqueNodeIds;
+    plan(workflow: GraphResolvedWorkflow): GraphExecutionPlan;
     /**
-     * Resolves workflow node metadata into plan nodes with full definitions.
-     */
-    private resolveNodes;
-    /**
-     * Attempts to resolve the full graph node definition from metadata.
-     *
-     * Accepts either a decorated Model class/instance (resolved via
-     * `graphDefinitionOf`) or a plain `GraphNodeDefinition`-shaped object
-     * (useful for serialized workflows that inline node definitions).
+     * Builds catalogue-resolved plan nodes from the resolved workflow.
+     * Each plan node carries the canonical instance, the effective manifest,
+     * and the trusted executor — never a raw node definition.
      */
-    private resolveDefinition;
+    private buildPlanNodes;
     /**
-     * Returns `true` when a value looks like a raw {@link GraphNodeDefinition}
-     * (a plain object with a `ports` array and a `name` string).
+     * Builds plan edges from the flattened resolved edges (already validated by
+     * §4.8 stage 5/6).
      */
-    private isRawDefinition;
+    private buildPlanEdges;
     /**
-     * Builds a map of node id -> incoming edges.
+     * Builds a map of node id -> incoming edges (boundary excluded from keys).
      */
     private buildIncomingMap;
     /**
-     * Builds a map of node id -> outgoing edges.
+     * Builds a map of node id -> outgoing edges (boundary targets included as
+     * edge values so workflow outputs stay routable).
      */
     private buildOutgoingMap;
     /**
      * Produces topological layers using Kahn's algorithm.
      *
      * Workflow boundary edges do not count as executable-node dependencies.
+     * Both data and structural (connection) edges count as dependencies
+     * (DECAF-32 acyclicity preserved; loop constructs are excepted because
+     * their bodies are separate nested documents).
      */
     private topologicalLayers;
 }

package/lib/types/graph/engine/planning/GraphExecutionPlanner.d.mts

@@ -1,60 +1,48 @@
-/**
- * @module integrations/graph/planning/GraphExecutionPlanner
- * @summary Topological planner for graph workflows.
- * @description Resolves workflow nodes and relations, validates topology, detects cycles, and produces topological execution layers using Kahn's algorithm.
- */
-import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphResolvedWorkflow } from "../validation/GraphResolvedWorkflow.d.mts";
 import type { GraphExecutionPlan } from "./GraphExecutionPlan.d.mts";
-import { GraphRelationResolver } from "./GraphRelationResolver.d.mts";
 /**
- * Planner that turns a {@link GraphWorkflowDefinition} into a
+ * Planner that turns a {@link GraphResolvedWorkflow} into a
  * {@link GraphExecutionPlan} with topological layers.
  */
 export declare class GraphExecutionPlanner {
-    private readonly resolver;
-    constructor(resolver?: GraphRelationResolver);
     /**
-     * Plans a workflow for execution.
+     * Plans a resolved workflow for execution.
      *
-     * @param workflow - The workflow definition to plan.
+     * @param workflow - The catalogue-resolved workflow (output of the
+     *   nine-stage validation gate). Raw `GraphWorkflowDefinition` objects and
+     *   inline `GraphNodeDefinition` objects are rejected.
      * @returns The execution plan with nodes, edges, layers, and maps.
-     * @throws {GraphTopologyError} when node IDs are not unique.
+     * @throws {GraphTopologyError} when the input is not a resolved workflow.
      * @throws {GraphCycleError} when the workflow contains an unsupported cycle.
      */
-    plan(workflow: GraphWorkflowDefinition): GraphExecutionPlan;
-    /**
-     * Validates that all workflow node IDs are unique.
-     */
-    private validateUniqueNodeIds;
+    plan(workflow: GraphResolvedWorkflow): GraphExecutionPlan;
     /**
-     * Resolves workflow node metadata into plan nodes with full definitions.
-     */
-    private resolveNodes;
-    /**
-     * Attempts to resolve the full graph node definition from metadata.
-     *
-     * Accepts either a decorated Model class/instance (resolved via
-     * `graphDefinitionOf`) or a plain `GraphNodeDefinition`-shaped object
-     * (useful for serialized workflows that inline node definitions).
+     * Builds catalogue-resolved plan nodes from the resolved workflow.
+     * Each plan node carries the canonical instance, the effective manifest,
+     * and the trusted executor — never a raw node definition.
      */
-    private resolveDefinition;
+    private buildPlanNodes;
     /**
-     * Returns `true` when a value looks like a raw {@link GraphNodeDefinition}
-     * (a plain object with a `ports` array and a `name` string).
+     * Builds plan edges from the flattened resolved edges (already validated by
+     * §4.8 stage 5/6).
      */
-    private isRawDefinition;
+    private buildPlanEdges;
     /**
-     * Builds a map of node id -> incoming edges.
+     * Builds a map of node id -> incoming edges (boundary excluded from keys).
      */
     private buildIncomingMap;
     /**
-     * Builds a map of node id -> outgoing edges.
+     * Builds a map of node id -> outgoing edges (boundary targets included as
+     * edge values so workflow outputs stay routable).
      */
     private buildOutgoingMap;
     /**
      * Produces topological layers using Kahn's algorithm.
      *
      * Workflow boundary edges do not count as executable-node dependencies.
+     * Both data and structural (connection) edges count as dependencies
+     * (DECAF-32 acyclicity preserved; loop constructs are excepted because
+     * their bodies are separate nested documents).
      */
     private topologicalLayers;
 }

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

@@ -7,6 +7,5 @@ export * from "./GraphExecutionPlanNode.d.cts";
 export * from "./GraphExecutionPlanEdge.d.cts";
 export * from "./GraphExecutionPlanLayer.d.cts";
 export * from "./GraphExecutionPlan.d.cts";
-export * from "./GraphRelationResolver.d.cts";
 export * from "./GraphExecutionPlanner.d.cts";
 export * from "./GraphTopology.d.cts";

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

@@ -7,6 +7,5 @@ export * from "./GraphExecutionPlanNode.d.mts";
 export * from "./GraphExecutionPlanEdge.d.mts";
 export * from "./GraphExecutionPlanLayer.d.mts";
 export * from "./GraphExecutionPlan.d.mts";
-export * from "./GraphRelationResolver.d.mts";
 export * from "./GraphExecutionPlanner.d.mts";
 export * from "./GraphTopology.d.mts";

package/lib/types/graph/engine/registry/GraphNodeExecutorRegistry.d.cts

@@ -1,25 +1,39 @@
 /**
  * @module integrations/graph/registry/GraphNodeExecutorRegistry
- * @summary Registry for graph node executors.
- * @description Maps node kinds to their executor implementations. The engine resolves executors by node kind at execution time.
+ * @summary Compatibility facade over {@link GraphNodeCatalogue} (DECAF-50 §4.7).
+ * @description Holds no map of its own: every kind→executor binding lives in
+ * the catalogue's single kind→registration map. `register()` upserts the
+ * executor on an existing registration or creates a placeholder-manifest entry
+ * for legacy executor-only registrations; the strict manifest+executor pairing
+ * required by DECAF-50 is enforced by `GraphNodeCatalogue.register()`.
+ *
+ * Legacy error contract preserved: this facade keeps throwing
+ * {@link GraphExecutionError} where the pre-catalogue registry did, while the
+ * underlying catalogue throws the normative DECAF-50 catalogue errors.
  */
 import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.cts";
+import { GraphNodeCatalogue } from "../catalog/GraphNodeCatalogue.d.cts";
 /**
- * Registry that maps node `kind` strings to {@link GraphNodeExecutor}
- * instances.
+ * Compatibility facade over {@link GraphNodeCatalogue} for legacy
+ * kind→executor registration (DECAF-50 §4.7). Delegates every binding to the
+ * catalogue and preserves the pre-catalogue {@link GraphExecutionError}
+ * contract.
  */
 export declare class GraphNodeExecutorRegistry {
-    private readonly executors;
+    private readonly catalogue;
+    constructor(catalogue?: GraphNodeCatalogue);
+    /** The backing catalogue holding all kind→registration entries. */
+    get catalog(): GraphNodeCatalogue;
     /** Registers an executor for the given node kind. */
     register(kind: string, executor: GraphNodeExecutor): this;
-    /** Removes the executor for the given node kind. */
+    /** Removes the registration for the given node kind. */
     unregister(kind: string): this;
-    /** Returns whether an executor is registered for the given kind. */
+    /** Returns whether a registration exists for the given kind. */
     has(kind: string): boolean;
     /**
      * Resolves the executor for the given node kind.
      *
-     * @throws {GraphExecutionError} when no executor is registered for `kind`.
+     * @throws {GraphExecutionError} when no registration exists for `kind`.
      */
     resolve(kind: string): GraphNodeExecutor;
 }

package/lib/types/graph/engine/registry/GraphNodeExecutorRegistry.d.mts

@@ -1,25 +1,39 @@
 /**
  * @module integrations/graph/registry/GraphNodeExecutorRegistry
- * @summary Registry for graph node executors.
- * @description Maps node kinds to their executor implementations. The engine resolves executors by node kind at execution time.
+ * @summary Compatibility facade over {@link GraphNodeCatalogue} (DECAF-50 §4.7).
+ * @description Holds no map of its own: every kind→executor binding lives in
+ * the catalogue's single kind→registration map. `register()` upserts the
+ * executor on an existing registration or creates a placeholder-manifest entry
+ * for legacy executor-only registrations; the strict manifest+executor pairing
+ * required by DECAF-50 is enforced by `GraphNodeCatalogue.register()`.
+ *
+ * Legacy error contract preserved: this facade keeps throwing
+ * {@link GraphExecutionError} where the pre-catalogue registry did, while the
+ * underlying catalogue throws the normative DECAF-50 catalogue errors.
  */
 import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.mts";
+import { GraphNodeCatalogue } from "../catalog/GraphNodeCatalogue.d.mts";
 /**
- * Registry that maps node `kind` strings to {@link GraphNodeExecutor}
- * instances.
+ * Compatibility facade over {@link GraphNodeCatalogue} for legacy
+ * kind→executor registration (DECAF-50 §4.7). Delegates every binding to the
+ * catalogue and preserves the pre-catalogue {@link GraphExecutionError}
+ * contract.
  */
 export declare class GraphNodeExecutorRegistry {
-    private readonly executors;
+    private readonly catalogue;
+    constructor(catalogue?: GraphNodeCatalogue);
+    /** The backing catalogue holding all kind→registration entries. */
+    get catalog(): GraphNodeCatalogue;
     /** Registers an executor for the given node kind. */
     register(kind: string, executor: GraphNodeExecutor): this;
-    /** Removes the executor for the given node kind. */
+    /** Removes the registration for the given node kind. */
     unregister(kind: string): this;
-    /** Returns whether an executor is registered for the given kind. */
+    /** Returns whether a registration exists for the given kind. */
     has(kind: string): boolean;
     /**
      * Resolves the executor for the given node kind.
      *
-     * @throws {GraphExecutionError} when no executor is registered for `kind`.
+     * @throws {GraphExecutionError} when no registration exists for `kind`.
      */
     resolve(kind: string): GraphNodeExecutor;
 }

package/lib/types/graph/engine/runs/GraphRunEventPublisher.d.cts

@@ -0,0 +1,26 @@
+import { type GraphRunEventEnvelope, type GraphRunEventEnvelopeInput, type GraphRunLimits } from "@decaf-ts/ui-decorators/graph";
+import { type GraphRunEventStore } from "./types.d.cts";
+/**
+ * Sequences and persists run events for the SSE run stream (DECAF-50 §4.16):
+ * assigns a monotonically increasing `sequence` per run, stamps ISO
+ * timestamps, truncates oversized/non-serializable payloads to the
+ * configured limits, and chains appends per run so store writes preserve
+ * publish order.
+ */
+export declare class GraphRunEventPublisher {
+    private readonly store;
+    private readonly limits;
+    private readonly sequences;
+    private readonly chains;
+    constructor(store: GraphRunEventStore, limits?: GraphRunLimits);
+    /**
+     * Assigns the next sequence number for the run, stamps and limits the
+     * payload, and appends the envelope to the store in publish order.
+     */
+    publish(event: GraphRunEventEnvelopeInput): Promise<GraphRunEventEnvelope>;
+    /** Highest sequence number issued for the run (0 when none). */
+    lastSequence(runId: string): number;
+    /** Drops sequencing state for a finished run. */
+    release(runId: string): void;
+    private limitPayload;
+}

package/lib/types/graph/engine/runs/GraphRunEventPublisher.d.mts

@@ -0,0 +1,26 @@
+import { type GraphRunEventEnvelope, type GraphRunEventEnvelopeInput, type GraphRunLimits } from "@decaf-ts/ui-decorators/graph";
+import { type GraphRunEventStore } from "./types.d.mts";
+/**
+ * Sequences and persists run events for the SSE run stream (DECAF-50 §4.16):
+ * assigns a monotonically increasing `sequence` per run, stamps ISO
+ * timestamps, truncates oversized/non-serializable payloads to the
+ * configured limits, and chains appends per run so store writes preserve
+ * publish order.
+ */
+export declare class GraphRunEventPublisher {
+    private readonly store;
+    private readonly limits;
+    private readonly sequences;
+    private readonly chains;
+    constructor(store: GraphRunEventStore, limits?: GraphRunLimits);
+    /**
+     * Assigns the next sequence number for the run, stamps and limits the
+     * payload, and appends the envelope to the store in publish order.
+     */
+    publish(event: GraphRunEventEnvelopeInput): Promise<GraphRunEventEnvelope>;
+    /** Highest sequence number issued for the run (0 when none). */
+    lastSequence(runId: string): number;
+    /** Drops sequencing state for a finished run. */
+    release(runId: string): void;
+    private limitPayload;
+}

package/lib/types/graph/engine/runs/GraphRunExecutor.d.cts

@@ -0,0 +1,75 @@
+/**
+ * @module integrations/graph/engine/runs/GraphRunExecutor
+ * @summary Asynchronous graph run execution (DECAF-50 §4.16).
+ * @description Schedules runs against the {@link GraphExecutionEngine},
+ * mirrors engine events into the run's sequenced SSE stream, enforces run
+ * timeouts via per-run `AbortController`s, and finalizes the run's terminal
+ * state in the run store. Exactly one execution per `runId` — repeated
+ * schedules await the same completion promise.
+ */
+import type { Context, MaybeContextualArg } from "@decaf-ts/core";
+import { type GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.cts";
+import type { GraphExecutionResult, GraphExecutionValues } from "../types.d.cts";
+import { GraphRunEventPublisher } from "./GraphRunEventPublisher.d.cts";
+import { type GraphRunLimits } from "@decaf-ts/ui-decorators/graph";
+import { type GraphRun, type GraphRunStore } from "./types.d.cts";
+/** Why a run was aborted: explicit user cancellation or run timeout. */
+export type GraphRunAbortReason = "user" | "timeout";
+/** Lifecycle hooks observed by {@link GraphRunExecutor} when a run completes. */
+export interface GraphRunExecutionHooks {
+    /** Called once a run reaches a terminal state, with its result when successful. */
+    onRunCompleted?: (run: GraphRun, result?: GraphExecutionResult) => Promise<void>;
+}
+/**
+ * Resolves the canonical document (and its fingerprint) a run executes,
+ * accepting an optional Decaf {@link Context} as leading argument.
+ */
+export type GraphRunDocumentProvider = (...args: MaybeContextualArg<Context>) => Promise<{
+    document: GraphWorkflowDocument;
+    fingerprint: string;
+}>;
+/**
+ * Executes graph runs asynchronously (DECAF-50 §4.16): schedules a run
+ * against the {@link GraphExecutionEngine}, mirrors engine events into the
+ * run's sequenced SSE stream, enforces run timeouts via per-run
+ * `AbortController`s, and finalizes the run's terminal state in the run
+ * store. Exactly one execution per `runId` — repeated schedules await the
+ * same completion promise.
+ */
+export declare class GraphRunExecutor {
+    private readonly engine;
+    private readonly runStore;
+    private readonly publisher;
+    private readonly limits;
+    private readonly hooks;
+    private readonly controllers;
+    private readonly completions;
+    private readonly timeouts;
+    constructor(engine: GraphExecutionEngine, runStore: GraphRunStore, publisher: GraphRunEventPublisher, hooks?: GraphRunExecutionHooks, limits?: GraphRunLimits);
+    /** Returns (creating if needed) the run's `AbortController`. */
+    begin(runId: string): AbortController;
+    /** Aborts the run, if it is still in flight. Returns whether an abort was issued. */
+    abort(runId: string, reason: GraphRunAbortReason): boolean;
+    /** Whether the run's abort signal has fired. */
+    isAborted(runId: string): boolean;
+    /** The run's abort reason, when aborted. */
+    abortReason(runId: string): GraphRunAbortReason | undefined;
+    /** The run's in-flight completion promise, when one is scheduled. */
+    waitFor(runId: string): Promise<GraphRun> | undefined;
+    /**
+     * Schedules the run for execution and returns its completion promise
+     * (deduplicated per `runId`). Engine events are mirrored to the run's SSE
+     * stream; failures still emit a terminal event and finalize the run as
+     * `failed`.
+     */
+    schedule(run: GraphRun, documentProvider: GraphRunDocumentProvider, inputs: GraphExecutionValues, ...args: MaybeContextualArg<Context>): Promise<GraphRun>;
+    /** Releases all per-run state (controller, completion, timeout, publisher sequencing). */
+    release(runId: string): void;
+    private armTimeout;
+    private runExecution;
+    private emitTerminal;
+    private finalize;
+    private persist;
+    private envelopeOf;
+}

package/lib/types/graph/engine/runs/GraphRunExecutor.d.mts

@@ -0,0 +1,75 @@
+/**
+ * @module integrations/graph/engine/runs/GraphRunExecutor
+ * @summary Asynchronous graph run execution (DECAF-50 §4.16).
+ * @description Schedules runs against the {@link GraphExecutionEngine},
+ * mirrors engine events into the run's sequenced SSE stream, enforces run
+ * timeouts via per-run `AbortController`s, and finalizes the run's terminal
+ * state in the run store. Exactly one execution per `runId` — repeated
+ * schedules await the same completion promise.
+ */
+import type { Context, MaybeContextualArg } from "@decaf-ts/core";
+import { type GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.mts";
+import type { GraphExecutionResult, GraphExecutionValues } from "../types.d.mts";
+import { GraphRunEventPublisher } from "./GraphRunEventPublisher.d.mts";
+import { type GraphRunLimits } from "@decaf-ts/ui-decorators/graph";
+import { type GraphRun, type GraphRunStore } from "./types.d.mts";
+/** Why a run was aborted: explicit user cancellation or run timeout. */
+export type GraphRunAbortReason = "user" | "timeout";
+/** Lifecycle hooks observed by {@link GraphRunExecutor} when a run completes. */
+export interface GraphRunExecutionHooks {
+    /** Called once a run reaches a terminal state, with its result when successful. */
+    onRunCompleted?: (run: GraphRun, result?: GraphExecutionResult) => Promise<void>;
+}
+/**
+ * Resolves the canonical document (and its fingerprint) a run executes,
+ * accepting an optional Decaf {@link Context} as leading argument.
+ */
+export type GraphRunDocumentProvider = (...args: MaybeContextualArg<Context>) => Promise<{
+    document: GraphWorkflowDocument;
+    fingerprint: string;
+}>;
+/**
+ * Executes graph runs asynchronously (DECAF-50 §4.16): schedules a run
+ * against the {@link GraphExecutionEngine}, mirrors engine events into the
+ * run's sequenced SSE stream, enforces run timeouts via per-run
+ * `AbortController`s, and finalizes the run's terminal state in the run
+ * store. Exactly one execution per `runId` — repeated schedules await the
+ * same completion promise.
+ */
+export declare class GraphRunExecutor {
+    private readonly engine;
+    private readonly runStore;
+    private readonly publisher;
+    private readonly limits;
+    private readonly hooks;
+    private readonly controllers;
+    private readonly completions;
+    private readonly timeouts;
+    constructor(engine: GraphExecutionEngine, runStore: GraphRunStore, publisher: GraphRunEventPublisher, hooks?: GraphRunExecutionHooks, limits?: GraphRunLimits);
+    /** Returns (creating if needed) the run's `AbortController`. */
+    begin(runId: string): AbortController;
+    /** Aborts the run, if it is still in flight. Returns whether an abort was issued. */
+    abort(runId: string, reason: GraphRunAbortReason): boolean;
+    /** Whether the run's abort signal has fired. */
+    isAborted(runId: string): boolean;
+    /** The run's abort reason, when aborted. */
+    abortReason(runId: string): GraphRunAbortReason | undefined;
+    /** The run's in-flight completion promise, when one is scheduled. */
+    waitFor(runId: string): Promise<GraphRun> | undefined;
+    /**
+     * Schedules the run for execution and returns its completion promise
+     * (deduplicated per `runId`). Engine events are mirrored to the run's SSE
+     * stream; failures still emit a terminal event and finalize the run as
+     * `failed`.
+     */
+    schedule(run: GraphRun, documentProvider: GraphRunDocumentProvider, inputs: GraphExecutionValues, ...args: MaybeContextualArg<Context>): Promise<GraphRun>;
+    /** Releases all per-run state (controller, completion, timeout, publisher sequencing). */
+    release(runId: string): void;
+    private armTimeout;
+    private runExecution;
+    private emitTerminal;
+    private finalize;
+    private persist;
+    private envelopeOf;
+}

package/lib/types/graph/engine/runs/GraphRunFingerprint.d.cts

@@ -0,0 +1,8 @@
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+/**
+ * Computes a stable SHA-256 fingerprint of a canonical
+ * {@link GraphWorkflowDocument}: object keys are sorted and `undefined`
+ * values skipped, so documents that serialize identically always produce the
+ * same fingerprint regardless of key insertion order.
+ */
+export declare function graphRunDocumentFingerprint(document: GraphWorkflowDocument): string;

package/lib/types/graph/engine/runs/GraphRunFingerprint.d.mts

@@ -0,0 +1,8 @@
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+/**
+ * Computes a stable SHA-256 fingerprint of a canonical
+ * {@link GraphWorkflowDocument}: object keys are sorted and `undefined`
+ * values skipped, so documents that serialize identically always produce the
+ * same fingerprint regardless of key insertion order.
+ */
+export declare function graphRunDocumentFingerprint(document: GraphWorkflowDocument): string;