@decaf-ts/integrations 0.3.0 → 0.3.2

package/lib/esm/graph/constants.js

@@ -0,0 +1,106 @@
+/**
+ * @module integrations/graph/constants
+ * @summary Graph execution engine constants and enums.
+ * @description Shared constants, default limits, and enumerations used across the graph execution engine.
+ */
+/**
+ * Boundary identifier used as the node id for workflow-level input/output ports.
+ */
+export const GRAPH_WORKFLOW_BOUNDARY = "$workflow";
+/**
+ * Default concurrency for parallel node execution within a layer.
+ */
+export const GRAPH_DEFAULT_CONCURRENCY = 4;
+/**
+ * Default maximum iterations for `while` and `until` loop nodes.
+ */
+export const GRAPH_DEFAULT_MAX_LOOP_ITERATIONS = 100;
+/**
+ * Default maximum iterations for `foreach` loop nodes.
+ */
+export const GRAPH_DEFAULT_MAX_FOREACH_ITERATIONS = 1000;
+/**
+ * Metadata key under which pinning information is stored on a graph node.
+ */
+export const GRAPH_PINNING_METADATA_KEY = "graph.pinnable";
+/**
+ * Execution status for a workflow or individual node.
+ */
+export var GraphExecutionStatus;
+(function (GraphExecutionStatus) {
+    GraphExecutionStatus["PENDING"] = "pending";
+    GraphExecutionStatus["PLANNING"] = "planning";
+    GraphExecutionStatus["RUNNING"] = "running";
+    GraphExecutionStatus["SUCCEEDED"] = "succeeded";
+    GraphExecutionStatus["FAILED"] = "failed";
+    GraphExecutionStatus["SKIPPED"] = "skipped";
+    GraphExecutionStatus["CANCELLED"] = "cancelled";
+    GraphExecutionStatus["CACHED"] = "cached";
+})(GraphExecutionStatus || (GraphExecutionStatus = {}));
+/**
+ * Event types emitted through the graph execution observer pipeline.
+ */
+export var GraphExecutionEventType;
+(function (GraphExecutionEventType) {
+    GraphExecutionEventType["WORKFLOW_STARTED"] = "workflow.started";
+    GraphExecutionEventType["WORKFLOW_PLANNED"] = "workflow.planned";
+    GraphExecutionEventType["WORKFLOW_COMPLETED"] = "workflow.completed";
+    GraphExecutionEventType["WORKFLOW_FAILED"] = "workflow.failed";
+    GraphExecutionEventType["WORKFLOW_CANCELLED"] = "workflow.cancelled";
+    GraphExecutionEventType["NODE_QUEUED"] = "node.queued";
+    GraphExecutionEventType["NODE_STARTED"] = "node.started";
+    GraphExecutionEventType["NODE_OUTPUT"] = "node.output";
+    GraphExecutionEventType["NODE_COMPLETED"] = "node.completed";
+    GraphExecutionEventType["NODE_FAILED"] = "node.failed";
+    GraphExecutionEventType["NODE_SKIPPED"] = "node.skipped";
+    GraphExecutionEventType["NODE_CACHE_HIT"] = "node.cacheHit";
+    GraphExecutionEventType["NODE_PINNED"] = "node.pinned";
+    GraphExecutionEventType["NODE_UNPINNED"] = "node.unpinned";
+    GraphExecutionEventType["EDGE_VALUE_ROUTED"] = "edge.valueRouted";
+    GraphExecutionEventType["LOOP_STARTED"] = "loop.started";
+    GraphExecutionEventType["LOOP_ITERATION_STARTED"] = "loop.iteration.started";
+    GraphExecutionEventType["LOOP_ITERATION_COMPLETED"] = "loop.iteration.completed";
+    GraphExecutionEventType["LOOP_CONDITION_EVALUATED"] = "loop.condition.evaluated";
+    GraphExecutionEventType["LOOP_COMPLETED"] = "loop.completed";
+    GraphExecutionEventType["LOOP_LIMIT_REACHED"] = "loop.limitReached";
+    GraphExecutionEventType["VALIDATION_STARTED"] = "validation.started";
+    GraphExecutionEventType["VALIDATION_FAILED"] = "validation.failed";
+    GraphExecutionEventType["VALIDATION_COMPLETED"] = "validation.completed";
+    GraphExecutionEventType["STORE_READ"] = "store.read";
+    GraphExecutionEventType["STORE_WRITE"] = "store.write";
+    GraphExecutionEventType["STORE_DELETE"] = "store.delete";
+})(GraphExecutionEventType || (GraphExecutionEventType = {}));
+/**
+ * Pinning strategy determining when values are pinned.
+ */
+export var GraphPinningStrategy;
+(function (GraphPinningStrategy) {
+    GraphPinningStrategy["MANUAL"] = "manual";
+    GraphPinningStrategy["AUTOMATIC"] = "automatic";
+    GraphPinningStrategy["DISABLED"] = "disabled";
+})(GraphPinningStrategy || (GraphPinningStrategy = {}));
+/**
+ * Built-in condition types supported by the loop condition evaluator.
+ */
+export var GraphConditionType;
+(function (GraphConditionType) {
+    GraphConditionType["TRUTHY"] = "truthy";
+    GraphConditionType["FALSY"] = "falsy";
+    GraphConditionType["EQUALS"] = "equals";
+    GraphConditionType["NOT_EQUALS"] = "notEquals";
+    GraphConditionType["GREATER_THAN"] = "greaterThan";
+    GraphConditionType["GREATER_THAN_OR_EQUAL"] = "greaterThanOrEqual";
+    GraphConditionType["LESS_THAN"] = "lessThan";
+    GraphConditionType["LESS_THAN_OR_EQUAL"] = "lessThanOrEqual";
+    GraphConditionType["EXISTS"] = "exists";
+    GraphConditionType["CUSTOM"] = "custom";
+})(GraphConditionType || (GraphConditionType = {}));
+/**
+ * Loop node kinds recognised by the engine.
+ */
+export const GRAPH_LOOP_KIND = {
+    FOREACH: "core.loop.foreach",
+    WHILE: "core.loop.while",
+    UNTIL: "core.loop.until",
+};
+//# sourceMappingURL=constants.js.map

package/lib/esm/graph/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/graph/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,WAAW,CAAC;AAEnD;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C;;GAEG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,GAAG,CAAC;AAErD;;GAEG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,IAAI,CAAC;AAEzD;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,gBAAgB,CAAC;AAE3D;;GAEG;AACH,MAAM,CAAN,IAAY,oBASX;AATD,WAAY,oBAAoB;IAC9B,2CAAmB,CAAA;IACnB,6CAAqB,CAAA;IACrB,2CAAmB,CAAA;IACnB,+CAAuB,CAAA;IACvB,yCAAiB,CAAA;IACjB,2CAAmB,CAAA;IACnB,+CAAuB,CAAA;IACvB,yCAAiB,CAAA;AACnB,CAAC,EATW,oBAAoB,KAApB,oBAAoB,QAS/B;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,uBAiCX;AAjCD,WAAY,uBAAuB;IACjC,gEAAqC,CAAA;IACrC,gEAAqC,CAAA;IACrC,oEAAyC,CAAA;IACzC,8DAAmC,CAAA;IACnC,oEAAyC,CAAA;IAEzC,sDAA2B,CAAA;IAC3B,wDAA6B,CAAA;IAC7B,sDAA2B,CAAA;IAC3B,4DAAiC,CAAA;IACjC,sDAA2B,CAAA;IAC3B,wDAA6B,CAAA;IAC7B,2DAAgC,CAAA;IAChC,sDAA2B,CAAA;IAC3B,0DAA+B,CAAA;IAE/B,iEAAsC,CAAA;IAEtC,wDAA6B,CAAA;IAC7B,4EAAiD,CAAA;IACjD,gFAAqD,CAAA;IACrD,gFAAqD,CAAA;IACrD,4DAAiC,CAAA;IACjC,mEAAwC,CAAA;IAExC,oEAAyC,CAAA;IACzC,kEAAuC,CAAA;IACvC,wEAA6C,CAAA;IAE7C,oDAAyB,CAAA;IACzB,sDAA2B,CAAA;IAC3B,wDAA6B,CAAA;AAC/B,CAAC,EAjCW,uBAAuB,KAAvB,uBAAuB,QAiClC;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,oBAIX;AAJD,WAAY,oBAAoB;IAC9B,yCAAiB,CAAA;IACjB,+CAAuB,CAAA;IACvB,6CAAqB,CAAA;AACvB,CAAC,EAJW,oBAAoB,KAApB,oBAAoB,QAI/B;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,kBAWX;AAXD,WAAY,kBAAkB;IAC5B,uCAAiB,CAAA;IACjB,qCAAe,CAAA;IACf,uCAAiB,CAAA;IACjB,8CAAwB,CAAA;IACxB,kDAA4B,CAAA;IAC5B,kEAA4C,CAAA;IAC5C,4CAAsB,CAAA;IACtB,4DAAsC,CAAA;IACtC,uCAAiB,CAAA;IACjB,uCAAiB,CAAA;AACnB,CAAC,EAXW,kBAAkB,KAAlB,kBAAkB,QAW7B;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,mBAAmB;IAC5B,KAAK,EAAE,iBAAiB;IACxB,KAAK,EAAE,iBAAiB;CAChB,CAAC"}

package/lib/esm/graph/decorators.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=decorators.js.map

package/lib/esm/graph/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../src/graph/decorators.ts"],"names":[],"mappings":""}

package/lib/esm/graph/errors/GraphCycleError.js

@@ -0,0 +1,15 @@
+/**
+ * @module integrations/graph/errors/GraphCycleError
+ * @summary Error thrown when a workflow contains an unsupported cycle.
+ * @description Ordinary (non-loop) workflow graphs must be acyclic. This error is raised when the planner detects a cycle.
+ */
+import { GraphExecutionError } from "./GraphExecutionError.js";
+/**
+ * Thrown when a graph workflow contains an unsupported cycle.
+ */
+export class GraphCycleError extends GraphExecutionError {
+    constructor(details) {
+        super("Graph workflow contains an unsupported cycle", "GRAPH_CYCLE_ERROR", details);
+    }
+}
+//# sourceMappingURL=GraphCycleError.js.map

package/lib/esm/graph/errors/GraphCycleError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphCycleError.js","sourceRoot":"","sources":["../../../../src/graph/errors/GraphCycleError.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,iCAA8B;AAE5D;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,mBAAmB;IACtD,YAAY,OAAiB;QAC3B,KAAK,CACH,8CAA8C,EAC9C,mBAAmB,EACnB,OAAO,CACR,CAAC;IACJ,CAAC;CACF"}

package/lib/esm/graph/errors/GraphExecutionError.js

@@ -0,0 +1,22 @@
+/**
+ * @module integrations/graph/errors/GraphExecutionError
+ * @summary Base error for all graph execution failures.
+ * @description Extends Decaf's {@link InternalError} so graph errors follow the standard Decaf error hierarchy while carrying a graph-specific string code.
+ */
+import { InternalError } from "@decaf-ts/db-decorators";
+/**
+ * Base error for the graph execution engine.
+ *
+ * Extends `InternalError` (HTTP 500) to comply with the Decaf constitution which
+ * requires runtime errors to be `BaseError` subclasses. The additional
+ * `graphCode` property carries a machine-readable string code such as
+ * `"GRAPH_CYCLE_ERROR"`.
+ */
+export class GraphExecutionError extends InternalError {
+    constructor(message, graphCode = "GRAPH_EXECUTION_ERROR", details) {
+        super(message, GraphExecutionError.name, 500);
+        this.graphCode = graphCode;
+        this.details = details;
+    }
+}
+//# sourceMappingURL=GraphExecutionError.js.map

package/lib/esm/graph/errors/GraphExecutionError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphExecutionError.js","sourceRoot":"","sources":["../../../../src/graph/errors/GraphExecutionError.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IAIpD,YACE,OAAe,EACf,SAAS,GAAG,uBAAuB,EACnC,OAAiB;QAEjB,KAAK,CAAC,OAAO,EAAE,mBAAmB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC9C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/lib/esm/graph/errors/GraphInputError.js

@@ -0,0 +1,15 @@
+/**
+ * @module integrations/graph/errors/GraphInputError
+ * @summary Error thrown when workflow or node inputs are invalid.
+ * @description Raised by the value validator when required inputs are missing or fail schema validation.
+ */
+import { GraphExecutionError } from "./GraphExecutionError.js";
+/**
+ * Thrown when workflow or node inputs are invalid.
+ */
+export class GraphInputError extends GraphExecutionError {
+    constructor(message, details) {
+        super(message, "GRAPH_INPUT_ERROR", details);
+    }
+}
+//# sourceMappingURL=GraphInputError.js.map

package/lib/esm/graph/errors/GraphInputError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphInputError.js","sourceRoot":"","sources":["../../../../src/graph/errors/GraphInputError.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,iCAA8B;AAE5D;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,mBAAmB;IACtD,YAAY,OAAe,EAAE,OAAiB;QAC5C,KAAK,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;CACF"}

package/lib/esm/graph/errors/GraphLoopLimitError.js

@@ -0,0 +1,15 @@
+/**
+ * @module integrations/graph/errors/GraphLoopLimitError
+ * @summary Error thrown when a loop exceeds its maximum iterations.
+ * @description Raised by loop executors when the iteration count reaches the configured safety limit.
+ */
+import { GraphExecutionError } from "./GraphExecutionError.js";
+/**
+ * Thrown when a loop exceeds its maximum iterations.
+ */
+export class GraphLoopLimitError extends GraphExecutionError {
+    constructor(message, details) {
+        super(message, "GRAPH_LOOP_LIMIT_ERROR", details);
+    }
+}
+//# sourceMappingURL=GraphLoopLimitError.js.map

package/lib/esm/graph/errors/GraphLoopLimitError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphLoopLimitError.js","sourceRoot":"","sources":["../../../../src/graph/errors/GraphLoopLimitError.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,iCAA8B;AAE5D;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,mBAAmB;IAC1D,YAAY,OAAe,EAAE,OAAiB;QAC5C,KAAK,CAAC,OAAO,EAAE,wBAAwB,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;CACF"}

package/lib/esm/graph/errors/GraphPinningError.js

@@ -0,0 +1,15 @@
+/**
+ * @module integrations/graph/errors/GraphPinningError
+ * @summary Error thrown when a pinning operation fails.
+ * @description Raised when a node cannot be pinned, e.g. because an upstream dependency is not pinnable.
+ */
+import { GraphExecutionError } from "./GraphExecutionError.js";
+/**
+ * Thrown when a pinning operation fails.
+ */
+export class GraphPinningError extends GraphExecutionError {
+    constructor(message, details) {
+        super(message, "GRAPH_PINNING_ERROR", details);
+    }
+}
+//# sourceMappingURL=GraphPinningError.js.map

package/lib/esm/graph/errors/GraphPinningError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphPinningError.js","sourceRoot":"","sources":["../../../../src/graph/errors/GraphPinningError.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,iCAA8B;AAE5D;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,mBAAmB;IACxD,YAAY,OAAe,EAAE,OAAiB;QAC5C,KAAK,CAAC,OAAO,EAAE,qBAAqB,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;CACF"}

package/lib/esm/graph/errors/GraphPortError.js

@@ -0,0 +1,15 @@
+/**
+ * @module integrations/graph/errors/GraphPortError
+ * @summary Error thrown when a port reference is invalid.
+ * @description Raised by the relation resolver or validator when a referenced port is missing or unknown.
+ */
+import { GraphExecutionError } from "./GraphExecutionError.js";
+/**
+ * Thrown when a port reference is invalid.
+ */
+export class GraphPortError extends GraphExecutionError {
+    constructor(message, details) {
+        super(message, "GRAPH_PORT_ERROR", details);
+    }
+}
+//# sourceMappingURL=GraphPortError.js.map

package/lib/esm/graph/errors/GraphPortError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphPortError.js","sourceRoot":"","sources":["../../../../src/graph/errors/GraphPortError.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,iCAA8B;AAE5D;;GAEG;AACH,MAAM,OAAO,cAAe,SAAQ,mBAAmB;IACrD,YAAY,OAAe,EAAE,OAAiB;QAC5C,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;CACF"}

package/lib/esm/graph/errors/GraphStoreError.js

@@ -0,0 +1,15 @@
+/**
+ * @module integrations/graph/errors/GraphStoreError
+ * @summary Error thrown when a value store operation fails.
+ * @description Raised by the value store or adapter when reading, writing, or deleting cached values fails.
+ */
+import { GraphExecutionError } from "./GraphExecutionError.js";
+/**
+ * Thrown when a value store operation fails.
+ */
+export class GraphStoreError extends GraphExecutionError {
+    constructor(message, details) {
+        super(message, "GRAPH_STORE_ERROR", details);
+    }
+}
+//# sourceMappingURL=GraphStoreError.js.map

package/lib/esm/graph/errors/GraphStoreError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphStoreError.js","sourceRoot":"","sources":["../../../../src/graph/errors/GraphStoreError.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,iCAA8B;AAE5D;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,mBAAmB;IACtD,YAAY,OAAe,EAAE,OAAiB;QAC5C,KAAK,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;CACF"}

package/lib/esm/graph/errors/GraphTopologyError.js

@@ -0,0 +1,15 @@
+/**
+ * @module integrations/graph/errors/GraphTopologyError
+ * @summary Error thrown when workflow topology is invalid.
+ * @description Raised by the relation resolver or planner when an endpoint is unknown or ambiguous.
+ */
+import { GraphExecutionError } from "./GraphExecutionError.js";
+/**
+ * Thrown when workflow topology is invalid.
+ */
+export class GraphTopologyError extends GraphExecutionError {
+    constructor(message, details) {
+        super(message, "GRAPH_TOPOLOGY_ERROR", details);
+    }
+}
+//# sourceMappingURL=GraphTopologyError.js.map

package/lib/esm/graph/errors/GraphTopologyError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphTopologyError.js","sourceRoot":"","sources":["../../../../src/graph/errors/GraphTopologyError.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,iCAA8B;AAE5D;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,mBAAmB;IACzD,YAAY,OAAe,EAAE,OAAiB;QAC5C,KAAK,CAAC,OAAO,EAAE,sBAAsB,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;CACF"}

package/lib/esm/graph/errors/index.js

@@ -0,0 +1,14 @@
+/**
+ * @module integrations/graph/errors
+ * @summary Graph execution error classes.
+ * @description Re-exports all structured error types used by the graph execution engine.
+ */
+export * from "./GraphExecutionError.js";
+export * from "./GraphCycleError.js";
+export * from "./GraphInputError.js";
+export * from "./GraphLoopLimitError.js";
+export * from "./GraphPinningError.js";
+export * from "./GraphPortError.js";
+export * from "./GraphStoreError.js";
+export * from "./GraphTopologyError.js";
+//# sourceMappingURL=index.js.map

package/lib/esm/graph/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/graph/errors/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,yCAAsC;AACtC,qCAAkC;AAClC,qCAAkC;AAClC,yCAAsC;AACtC,uCAAoC;AACpC,oCAAiC;AACjC,qCAAkC;AAClC,wCAAqC"}

package/lib/esm/graph/events/GraphExecutionEvent.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=GraphExecutionEvent.js.map

package/lib/esm/graph/events/GraphExecutionEvent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphExecutionEvent.js","sourceRoot":"","sources":["../../../../src/graph/events/GraphExecutionEvent.ts"],"names":[],"mappings":""}

package/lib/esm/graph/events/GraphExecutionEventEmitter.js

@@ -0,0 +1,35 @@
+/**
+ * Manages observer registration and event dispatch for the graph execution
+ * engine.
+ */
+export class GraphExecutionEventEmitter {
+    constructor() {
+        this.observers = new Set();
+    }
+    /** Registers an observer and returns an unsubscribe function. */
+    observe(observer) {
+        this.observers.add(observer);
+        return () => this.unObserve(observer);
+    }
+    /** Removes a previously-registered observer. */
+    unObserve(observer) {
+        this.observers.delete(observer);
+    }
+    /**
+     * Notifies all registered observers of a new event.
+     *
+     * Observer failures are caught and swallowed so that a misbehaving observer
+     * cannot crash the workflow execution.
+     */
+    async updateObservers(event) {
+        await Promise.all(Array.from(this.observers).map(async (observer) => {
+            try {
+                await Promise.resolve(observer.refresh(event));
+            }
+            catch {
+                // Observer failures must not crash execution.
+            }
+        }));
+    }
+}
+//# sourceMappingURL=GraphExecutionEventEmitter.js.map

package/lib/esm/graph/events/GraphExecutionEventEmitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphExecutionEventEmitter.js","sourceRoot":"","sources":["../../../../src/graph/events/GraphExecutionEventEmitter.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,OAAO,0BAA0B;IAAvC;QAEmB,cAAS,GAAG,IAAI,GAAG,EAA0B,CAAC;IA8BjE,CAAC;IA5BC,iEAAiE;IACjE,OAAO,CAAC,QAAgC;QACtC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,gDAAgD;IAChD,SAAS,CAAC,QAAgC;QACxC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,eAAe,CAAC,KAA0B;QAC9C,MAAM,OAAO,CAAC,GAAG,CACf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;YAChD,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YACjD,CAAC;YAAC,MAAM,CAAC;gBACP,8CAA8C;YAChD,CAAC;QACH,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF"}

package/lib/esm/graph/events/GraphExecutionEventFactory.js

@@ -0,0 +1,32 @@
+/**
+ * Factory that enriches partial events with a unique id, an incrementing
+ * sequence number, and a timestamp.
+ */
+export class GraphExecutionEventFactory {
+    constructor() {
+        this.sequence = 0;
+    }
+    /**
+     * Creates a fully-populated event from the given base fields.
+     *
+     * @param base - All event fields except `id`, `sequence`, and `timestamp`.
+     * @returns A complete {@link GraphExecutionEvent}.
+     */
+    create(base) {
+        return {
+            ...base,
+            id: this.createEventId(),
+            sequence: ++this.sequence,
+            timestamp: new Date(),
+        };
+    }
+    /**
+     * Generates a unique event id using `crypto.randomUUID` when available,
+     * falling back to a timestamp + random string.
+     */
+    createEventId() {
+        return (globalThis.crypto?.randomUUID?.() ??
+            `${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    }
+}
+//# sourceMappingURL=GraphExecutionEventFactory.js.map

package/lib/esm/graph/events/GraphExecutionEventFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphExecutionEventFactory.js","sourceRoot":"","sources":["../../../../src/graph/events/GraphExecutionEventFactory.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,OAAO,0BAA0B;IAAvC;QACU,aAAQ,GAAG,CAAC,CAAC;IA6BvB,CAAC;IA3BC;;;;;OAKG;IACH,MAAM,CACJ,IAAgE;QAEhE,OAAO;YACL,GAAG,IAAI;YACP,EAAE,EAAE,IAAI,CAAC,aAAa,EAAE;YACxB,QAAQ,EAAE,EAAE,IAAI,CAAC,QAAQ;YACzB,SAAS,EAAE,IAAI,IAAI,EAAE;SACtB,CAAC;IACJ,CAAC;IAED;;;OAGG;IACK,aAAa;QACnB,OAAO,CACL,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE;YACjC,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CACvD,CAAC;IACJ,CAAC;CACF"}

package/lib/esm/graph/events/GraphExecutionObserver.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=GraphExecutionObserver.js.map

package/lib/esm/graph/events/GraphExecutionObserver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphExecutionObserver.js","sourceRoot":"","sources":["../../../../src/graph/events/GraphExecutionObserver.ts"],"names":[],"mappings":""}

package/lib/esm/graph/events/index.js

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/graph/events
+ * @summary Graph execution event pipeline.
+ * @description Re-exports the observer interface, event emitter, and event factory.
+ */
+export * from "./GraphExecutionEvent.js";
+export * from "./GraphExecutionObserver.js";
+export * from "./GraphExecutionEventEmitter.js";
+export * from "./GraphExecutionEventFactory.js";
+//# sourceMappingURL=index.js.map

package/lib/esm/graph/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/graph/events/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,yCAAsC;AACtC,4CAAyC;AACzC,gDAA6C;AAC7C,gDAA6C"}

package/lib/esm/graph/execution/GraphExecutionContext.js

@@ -0,0 +1,74 @@
+/**
+ * @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.
+ */
+import { Context } from "@decaf-ts/core";
+import { GraphExecutionEventType } from "./../constants.js";
+/**
+ * Context passed to every graph node executor.
+ *
+ * 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.
+ */
+export class GraphExecutionContext extends Context {
+    /**
+     * @param runId - Unique identifier for the current execution run.
+     * @param parentRunId - Run id of the parent execution (for nested loop bodies).
+     * @param workflow - The workflow definition being executed.
+     * @param node - The node definition being executed.
+     * @param path - Dotted path from the workflow root to this node.
+     * @param emitFn - Callback invoked when an event is emitted from this context.
+     * @param metadata - Free-form metadata attached to this context.
+     */
+    constructor(runId, parentRunId, workflow, node, path, emitFn, metadata = {}) {
+        super();
+        this.runId = runId;
+        this.parentRunId = parentRunId;
+        this.workflow = workflow;
+        this.node = node;
+        this.path = path;
+        this.emitFn = emitFn;
+        this.metadata = metadata;
+    }
+    /**
+     * Emits a partial graph execution event. The engine fills in runId,
+     * parentRunId, workflowId, nodeId, and path automatically.
+     */
+    async emit(event) {
+        await this.emitFn({
+            ...event,
+            runId: this.runId,
+            parentRunId: this.parentRunId,
+            workflowId: this.workflow.name,
+            nodeId: this.node.name,
+            path: event.path ?? this.path,
+        });
+    }
+    /**
+     * Emits a `NODE_OUTPUT` event with the given payload, useful for reporting
+     * intermediate progress from within a node executor.
+     */
+    async progress(payload) {
+        await this.emit({
+            type: GraphExecutionEventType.NODE_OUTPUT,
+            payload,
+        });
+    }
+    /**
+     * Emits a `NODE_OUTPUT` event with a structured `{ message, payload }` shape
+     * so executors can log human-readable messages.
+     */
+    async log(message, payload) {
+        await this.emit({
+            type: GraphExecutionEventType.NODE_OUTPUT,
+            payload: {
+                message,
+                payload,
+            },
+        });
+    }
+}
+//# sourceMappingURL=GraphExecutionContext.js.map

package/lib/esm/graph/execution/GraphExecutionContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphExecutionContext.js","sourceRoot":"","sources":["../../../../src/graph/execution/GraphExecutionContext.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAMzC,OAAO,EAAE,uBAAuB,EAAE,0BAAqB;AAMvD;;;;;;;GAOG;AACH,MAAM,OAAO,qBAAsB,SAAQ,OAAO;IAChD;;;;;;;;OAQG;IACH,YACW,KAAiB,EACjB,WAAmC,EACnC,QAAiC,EACjC,IAAyB,EACzB,IAAc,EACN,MAA8D,EACtE,WAAoC,EAAE;QAE/C,KAAK,EAAE,CAAC;QARC,UAAK,GAAL,KAAK,CAAY;QACjB,gBAAW,GAAX,WAAW,CAAwB;QACnC,aAAQ,GAAR,QAAQ,CAAyB;QACjC,SAAI,GAAJ,IAAI,CAAqB;QACzB,SAAI,GAAJ,IAAI,CAAU;QACN,WAAM,GAAN,MAAM,CAAwD;QACtE,aAAQ,GAAR,QAAQ,CAA8B;IAGjD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,KAAmC;QAC5C,MAAM,IAAI,CAAC,MAAM,CAAC;YAChB,GAAG,KAAK;YACR,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI;YAC9B,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI;YACtB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI;SAC9B,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ,CAAC,OAAgB;QAC7B,MAAM,IAAI,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,uBAAuB,CAAC,WAAW;YACzC,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAG,CAAC,OAAe,EAAE,OAAiB;QAC1C,MAAM,IAAI,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,uBAAuB,CAAC,WAAW;YACzC,OAAO,EAAE;gBACP,OAAO;gBACP,OAAO;aACR;SACF,CAAC,CAAC;IACL,CAAC;CACF"}