@decaf-ts/integrations 0.3.0 → 0.3.2

package/lib/cjs/graph/pinning/GraphPinningService.cjs

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphPinningService = void 0;
+/**
+ * @module integrations/graph/pinning/GraphPinningService
+ * @summary Service for pinning and unpinning graph node values.
+ * @description Computes stable fingerprints, pins/unpins nodes and their upstream dependencies, reads pinned values, and emits pinning events. Pinning is all-or-nothing: if any upstream dependency is not pinnable, the operation fails.
+ */
+const constants_js_1 = require("./../constants.cjs");
+const GraphPinningError_js_1 = require("./../errors/GraphPinningError.cjs");
+const GraphTopology_js_1 = require("./../planning/GraphTopology.cjs");
+/**
+ * Service that manages pinning and unpinning of graph node values.
+ */
+class GraphPinningService {
+    constructor(store, policy, dependencyResolver) {
+        this.store = store;
+        this.policy = policy;
+        this.dependencyResolver = dependencyResolver;
+    }
+    /**
+     * Pins a node and all its upstream dependencies.
+     *
+     * @throws {GraphPinningError} when the node or any dependency is not pinnable.
+     */
+    async pinNode(options) {
+        const plan = options.plan;
+        const includeDependencies = options.includeDependencies ?? true;
+        const pinSet = includeDependencies
+            ? this.dependencyResolver.getPinSet(plan, options.nodeId)
+            : new Set([options.nodeId]);
+        // Validate all-or-nothing
+        for (const nodeId of pinSet) {
+            const node = plan.nodes.find((n) => n.id === nodeId);
+            if (!node) {
+                throw new GraphPinningError_js_1.GraphPinningError(`Node '${nodeId}' not found in plan`);
+            }
+            if (!this.policy.canPin(node)) {
+                throw new GraphPinningError_js_1.GraphPinningError(`Node '${nodeId}' is not pinnable`, { nodeId });
+            }
+        }
+        // Pin dependencies first, then the selected node
+        const ordered = this.topologicalOrder(plan, pinSet);
+        for (const nodeId of ordered) {
+            const node = plan.nodes.find((n) => n.id === nodeId);
+            const result = options.result.nodeResults[nodeId];
+            if (!result || !result.outputs) {
+                throw new GraphPinningError_js_1.GraphPinningError(`Node '${nodeId}' has no completed output to pin`);
+            }
+            const inputs = result.inputs ?? {};
+            const depFingerprints = this.dependencyFingerprints(plan, nodeId, options.result);
+            const key = this.createValueKey(options.workflow, node, inputs, depFingerprints, options.namespace);
+            const now = new Date().toISOString();
+            const cached = {
+                key,
+                outputs: result.outputs,
+                pinned: true,
+                createdAt: now,
+                updatedAt: now,
+                metadata: { ...options.result.metadata, nodeId },
+            };
+            await this.store.writeCached(key, cached);
+        }
+    }
+    /**
+     * Unpins a single node (does not unpin dependents in v1).
+     */
+    async unpinNode(options) {
+        const key = {
+            workflowId: options.workflow.name,
+            nodeId: options.nodeId,
+            fingerprint: options.fingerprint,
+            namespace: options.namespace,
+        };
+        await this.store.deleteCached(key);
+    }
+    /**
+     * Reads a pinned value for a node, returning `undefined` when no valid
+     * pinned value exists.
+     */
+    async readPinnedValue(workflow, node, inputs, dependencyFingerprints, namespace) {
+        const key = this.createValueKey(workflow, node, inputs, dependencyFingerprints, namespace);
+        const cached = await this.store.readCached(key);
+        if (cached && cached.pinned) {
+            if (cached.expiresAt && new Date(cached.expiresAt) < new Date()) {
+                return undefined;
+            }
+            return cached;
+        }
+        return undefined;
+    }
+    /**
+     * Creates a stable value key for a node.
+     */
+    createValueKey(workflow, node, inputs, dependencyFingerprints, namespace) {
+        return {
+            workflowId: workflow.name,
+            nodeId: node.id,
+            fingerprint: this.computeFingerprint(workflow, node, inputs, dependencyFingerprints),
+            namespace,
+        };
+    }
+    /**
+     * Computes a stable fingerprint for a node's inputs and dependencies.
+     */
+    computeFingerprint(workflow, node, inputs, dependencyFingerprints) {
+        const data = {
+            workflowId: workflow.name,
+            nodeId: node.id,
+            nodeKind: node.kind,
+            nodeDefinitionVersion: node.definition?.graph?.metadata?.version,
+            inputs: this.stableSerialize(inputs),
+            dependencyFingerprints: this.stableSerialize(dependencyFingerprints),
+        };
+        const json = this.stableSerialize(data);
+        // Use a deterministic non-cryptographic hash that works in both browser
+        // and Node environments without requiring `node:crypto`.
+        return this.simpleHash(json);
+    }
+    /**
+     * Returns a topological ordering of the given node set.
+     */
+    topologicalOrder(plan, nodeSet) {
+        const result = [];
+        const visited = new Set();
+        const visit = (nodeId) => {
+            if (visited.has(nodeId))
+                return;
+            visited.add(nodeId);
+            const deps = GraphTopology_js_1.GraphTopology.upstreamNodes(nodeId, plan.incomingByNode, false);
+            for (const dep of deps) {
+                if (nodeSet.has(dep))
+                    visit(dep);
+            }
+            result.push(nodeId);
+        };
+        for (const nodeId of nodeSet)
+            visit(nodeId);
+        return result;
+    }
+    /**
+     * Computes fingerprints for all upstream dependencies of a node.
+     */
+    dependencyFingerprints(plan, nodeId, result) {
+        const deps = this.dependencyResolver.getDependencies(plan, nodeId);
+        const fingerprints = {};
+        for (const dep of deps) {
+            const node = plan.nodes.find((n) => n.id === dep);
+            if (node) {
+                const depResult = result.nodeResults[dep];
+                const inputs = depResult?.inputs ?? {};
+                const nestedDeps = this.dependencyFingerprints(plan, dep, result);
+                fingerprints[dep] = this.computeFingerprint(plan.workflow, node, inputs, nestedDeps);
+            }
+        }
+        return fingerprints;
+    }
+    /**
+     * Serializes a value with recursively sorted keys for stable hashing.
+     */
+    stableSerialize(value) {
+        if (value === null || typeof value !== "object") {
+            return JSON.stringify(value);
+        }
+        if (Array.isArray(value)) {
+            return `[${value.map((v) => this.stableSerialize(v)).join(",")}]`;
+        }
+        const keys = Object.keys(value).sort();
+        const pairs = keys.map((k) => `${JSON.stringify(k)}:${this.stableSerialize(value[k])}`);
+        return `{${pairs.join(",")}}`;
+    }
+    /**
+     * Simple non-cryptographic hash for browser environments where
+     * `node:crypto` is unavailable. Produces a deterministic hex-like string
+     * from the input. This is NOT cryptographically secure but is sufficient
+     * for fingerprint-based cache keys.
+     */
+    simpleHash(str) {
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash |= 0;
+        }
+        return `fp_${Math.abs(hash).toString(16).padStart(8, "0")}_${str.length}`;
+    }
+}
+exports.GraphPinningService = GraphPinningService;
+void constants_js_1.GRAPH_PINNING_METADATA_KEY;
+//# sourceMappingURL=GraphPinningService.js.map
+//# sourceMappingURL=GraphPinningService.cjs.map

package/lib/cjs/graph/pinning/GraphPinningService.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph/pinning/GraphPinningService.cjs","sourceRoot":"","sources":["graph/pinning/GraphPinningService.js"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,oDAA+D;AAC/D,2EAAqE;AACrE,qEAA+D;AAC/D;;GAEG;AACH,MAAa,mBAAmB;IAC5B,YAAY,KAAK,EAAE,MAAM,EAAE,kBAAkB;QACzC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;IACjD,CAAC;IACD;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,OAAO;QACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QAC1B,MAAM,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,IAAI,IAAI,CAAC;QAChE,MAAM,MAAM,GAAG,mBAAmB;YAC9B,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC;YACzD,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAChC,0BAA0B;QAC1B,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;YAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;YACrD,IAAI,CAAC,IAAI,EAAE,CAAC;gBACR,MAAM,IAAI,wCAAiB,CAAC,SAAS,MAAM,qBAAqB,CAAC,CAAC;YACtE,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5B,MAAM,IAAI,wCAAiB,CAAC,SAAS,MAAM,mBAAmB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;YAChF,CAAC;QACL,CAAC;QACD,iDAAiD;QACjD,MAAM,OAAO,GAAG,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACpD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;YACrD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YAClD,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC7B,MAAM,IAAI,wCAAiB,CAAC,SAAS,MAAM,kCAAkC,CAAC,CAAC;YACnF,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;YACnC,MAAM,eAAe,GAAG,IAAI,CAAC,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YAClF,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;YACpG,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACrC,MAAM,MAAM,GAAG;gBACX,GAAG;gBACH,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,MAAM,EAAE,IAAI;gBACZ,SAAS,EAAE,GAAG;gBACd,SAAS,EAAE,GAAG;gBACd,QAAQ,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE;aACnD,CAAC;YACF,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC9C,CAAC;IACL,CAAC;IACD;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,OAAO;QACnB,MAAM,GAAG,GAAG;YACR,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;YACjC,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,SAAS,EAAE,OAAO,CAAC,SAAS;SAC/B,CAAC;QACF,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IACD;;;OAGG;IACH,KAAK,CAAC,eAAe,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,sBAAsB,EAAE,SAAS;QAC3E,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,sBAAsB,EAAE,SAAS,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAChD,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAC1B,IAAI,MAAM,CAAC,SAAS,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC;gBAC9D,OAAO,SAAS,CAAC;YACrB,CAAC;YACD,OAAO,MAAM,CAAC;QAClB,CAAC;QACD,OAAO,SAAS,CAAC;IACrB,CAAC;IACD;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,sBAAsB,EAAE,SAAS;QACpE,OAAO;YACH,UAAU,EAAE,QAAQ,CAAC,IAAI;YACzB,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,WAAW,EAAE,IAAI,CAAC,kBAAkB,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,sBAAsB,CAAC;YACpF,SAAS;SACZ,CAAC;IACN,CAAC;IACD;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,sBAAsB;QAC7D,MAAM,IAAI,GAAG;YACT,UAAU,EAAE,QAAQ,CAAC,IAAI;YACzB,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,QAAQ,EAAE,IAAI,CAAC,IAAI;YACnB,qBAAqB,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO;YAChE,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC;YACpC,sBAAsB,EAAE,IAAI,CAAC,eAAe,CAAC,sBAAsB,CAAC;SACvE,CAAC;QACF,MAAM,IAAI,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACxC,wEAAwE;QACxE,yDAAyD;QACzD,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IACD;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,OAAO;QAC1B,MAAM,MAAM,GAAG,EAAE,CAAC;QAClB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,EAAE;YACrB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;gBACnB,OAAO;YACX,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACpB,MAAM,IAAI,GAAG,gCAAa,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;YAC7E,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACrB,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;oBAChB,KAAK,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxB,CAAC,CAAC;QACF,KAAK,MAAM,MAAM,IAAI,OAAO;YACxB,KAAK,CAAC,MAAM,CAAC,CAAC;QAClB,OAAO,MAAM,CAAC;IAClB,CAAC;IACD;;OAEG;IACH,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,kBAAkB,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACnE,MAAM,YAAY,GAAG,EAAE,CAAC;QACxB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACrB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC;YAClD,IAAI,IAAI,EAAE,CAAC;gBACP,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;gBAC1C,MAAM,MAAM,GAAG,SAAS,EAAE,MAAM,IAAI,EAAE,CAAC;gBACvC,MAAM,UAAU,GAAG,IAAI,CAAC,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;gBAClE,YAAY,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;YACzF,CAAC;QACL,CAAC;QACD,OAAO,YAAY,CAAC;IACxB,CAAC;IACD;;OAEG;IACH,eAAe,CAAC,KAAK;QACjB,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9C,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QACtE,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACxF,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAClC,CAAC;IACD;;;;;OAKG;IACH,UAAU,CAAC,GAAG;QACV,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YAC/B,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;YACjC,IAAI,IAAI,CAAC,CAAC;QACd,CAAC;QACD,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;IAC9E,CAAC;CACJ;AA5KD,kDA4KC;AACD,KAAK,yCAA0B,CAAC;AAChC,+CAA+C"}

package/lib/cjs/graph/pinning/index.cjs

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @module integrations/graph/pinning
+ * @summary Graph pinning subsystem.
+ * @description Re-exports the pinning metadata, policy, dependency resolver, and service.
+ */
+__exportStar(require("./GraphPinningMetadata.cjs"), exports);
+__exportStar(require("./GraphPinningPolicy.cjs"), exports);
+__exportStar(require("./GraphPinningDependencyResolver.cjs"), exports);
+__exportStar(require("./GraphPinningService.cjs"), exports);
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.cjs.map

package/lib/cjs/graph/pinning/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph/pinning/index.cjs","sourceRoot":"","sources":["graph/pinning/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;GAIG;AACH,4DAA0C;AAC1C,0DAAwC;AACxC,sEAAoD;AACpD,2DAAyC;AACzC,iCAAiC"}

package/lib/cjs/graph/planning/GraphExecutionPlan.cjs

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=GraphExecutionPlan.js.map
+//# sourceMappingURL=GraphExecutionPlan.cjs.map

package/lib/cjs/graph/planning/GraphExecutionPlan.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph/planning/GraphExecutionPlan.cjs","sourceRoot":"","sources":["graph/planning/GraphExecutionPlan.js"],"names":[],"mappings":";;AACA,8CAA8C"}

package/lib/cjs/graph/planning/GraphExecutionPlanEdge.cjs

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=GraphExecutionPlanEdge.js.map
+//# sourceMappingURL=GraphExecutionPlanEdge.cjs.map

package/lib/cjs/graph/planning/GraphExecutionPlanEdge.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph/planning/GraphExecutionPlanEdge.cjs","sourceRoot":"","sources":["graph/planning/GraphExecutionPlanEdge.js"],"names":[],"mappings":";;AAMA,kDAAkD"}

package/lib/cjs/graph/planning/GraphExecutionPlanLayer.cjs

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=GraphExecutionPlanLayer.js.map
+//# sourceMappingURL=GraphExecutionPlanLayer.cjs.map

package/lib/cjs/graph/planning/GraphExecutionPlanLayer.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph/planning/GraphExecutionPlanLayer.cjs","sourceRoot":"","sources":["graph/planning/GraphExecutionPlanLayer.js"],"names":[],"mappings":";;AACA,mDAAmD"}

package/lib/cjs/graph/planning/GraphExecutionPlanNode.cjs

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=GraphExecutionPlanNode.js.map
+//# sourceMappingURL=GraphExecutionPlanNode.cjs.map

package/lib/cjs/graph/planning/GraphExecutionPlanNode.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph/planning/GraphExecutionPlanNode.cjs","sourceRoot":"","sources":["graph/planning/GraphExecutionPlanNode.js"],"names":[],"mappings":";;AACA,kDAAkD"}

package/lib/cjs/graph/planning/GraphExecutionPlanner.cjs

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphExecutionPlanner = void 0;
+const graph_1 = require("@decaf-ts/ui-decorators/graph");
+const constants_js_1 = require("./../constants.cjs");
+const GraphCycleError_js_1 = require("./../errors/GraphCycleError.cjs");
+const GraphTopologyError_js_1 = require("./../errors/GraphTopologyError.cjs");
+const GraphRelationResolver_js_1 = require("./GraphRelationResolver.cjs");
+/**
+ * Planner that turns a {@link GraphWorkflowDefinition} into a
+ * {@link GraphExecutionPlan} with topological layers.
+ */
+class GraphExecutionPlanner {
+    constructor(resolver) {
+        this.resolver = resolver ?? new GraphRelationResolver_js_1.GraphRelationResolver();
+    }
+    /**
+     * Plans a workflow for execution.
+     *
+     * @param workflow - The workflow definition to plan.
+     * @returns The execution plan with nodes, edges, layers, and maps.
+     * @throws {GraphTopologyError} when node IDs are not unique.
+     * @throws {GraphCycleError} when the workflow contains an unsupported cycle.
+     */
+    plan(workflow) {
+        this.validateUniqueNodeIds(workflow);
+        const nodes = this.resolveNodes(workflow);
+        const edges = this.resolver.resolve(workflow);
+        const incomingByNode = this.buildIncomingMap(edges);
+        const outgoingByNode = this.buildOutgoingMap(edges);
+        const layers = this.topologicalLayers(nodes, edges);
+        return {
+            workflow,
+            workflowId: workflow.name,
+            nodes,
+            edges,
+            layers,
+            incomingByNode,
+            outgoingByNode,
+        };
+    }
+    /**
+     * Validates that all workflow node IDs are unique.
+     */
+    validateUniqueNodeIds(workflow) {
+        const seen = new Set();
+        for (const node of workflow.nodes ?? []) {
+            if (seen.has(node.id)) {
+                throw new GraphTopologyError_js_1.GraphTopologyError(`Duplicate node id '${node.id}' in workflow '${workflow.name}'`, { nodeId: node.id, workflowId: workflow.name });
+            }
+            seen.add(node.id);
+        }
+    }
+    /**
+     * Resolves workflow node metadata into plan nodes with full definitions.
+     */
+    resolveNodes(workflow) {
+        const result = [];
+        for (const nodeMeta of workflow.nodes ?? []) {
+            const definition = this.resolveDefinition(nodeMeta);
+            const inputPorts = (definition.ports ?? [])
+                .filter((p) => p.direction === "input")
+                .map((p) => p.name);
+            const outputPorts = (definition.ports ?? [])
+                .filter((p) => p.direction === "output")
+                .map((p) => p.name);
+            result.push({
+                id: nodeMeta.id,
+                kind: nodeMeta.kind ?? definition.kind ?? nodeMeta.id,
+                label: nodeMeta.label,
+                source: nodeMeta,
+                definition,
+                inputPorts,
+                outputPorts,
+                metadata: nodeMeta.metadata,
+            });
+        }
+        return result;
+    }
+    /**
+     * 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).
+     */
+    resolveDefinition(nodeMeta) {
+        if (nodeMeta.node) {
+            if (this.isRawDefinition(nodeMeta.node)) {
+                return nodeMeta.node;
+            }
+            try {
+                return (0, graph_1.graphDefinitionOf)(nodeMeta.node);
+            }
+            catch {
+                // fall through to stub
+            }
+        }
+        // Return a minimal stub definition so planning can proceed
+        return {
+            name: nodeMeta.id,
+            tag: nodeMeta.id,
+            kind: nodeMeta.kind ?? nodeMeta.id,
+            labels: [],
+            ports: [],
+        };
+    }
+    /**
+     * Returns `true` when a value looks like a raw {@link GraphNodeDefinition}
+     * (a plain object with a `ports` array and a `name` string).
+     */
+    isRawDefinition(value) {
+        return (typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value) &&
+            typeof value.name === "string" &&
+            Array.isArray(value.ports));
+    }
+    /**
+     * Builds a map of node id -> incoming edges.
+     */
+    buildIncomingMap(edges) {
+        const map = new Map();
+        for (const edge of edges) {
+            const list = map.get(edge.targetNodeId) ?? [];
+            list.push(edge);
+            map.set(edge.targetNodeId, list);
+        }
+        return map;
+    }
+    /**
+     * Builds a map of node id -> outgoing edges.
+     */
+    buildOutgoingMap(edges) {
+        const map = new Map();
+        for (const edge of edges) {
+            const list = map.get(edge.sourceNodeId) ?? [];
+            list.push(edge);
+            map.set(edge.sourceNodeId, list);
+        }
+        return map;
+    }
+    /**
+     * Produces topological layers using Kahn's algorithm.
+     *
+     * Workflow boundary edges do not count as executable-node dependencies.
+     */
+    topologicalLayers(nodes, edges) {
+        const executableNodes = nodes.filter((n) => n.id !== constants_js_1.GRAPH_WORKFLOW_BOUNDARY);
+        const nodeIds = new Set(executableNodes.map((n) => n.id));
+        // Only edges between two executable nodes count as dependencies
+        const execEdges = edges.filter((e) => nodeIds.has(e.sourceNodeId) && nodeIds.has(e.targetNodeId));
+        // Compute in-degree
+        const indegree = new Map();
+        for (const node of executableNodes)
+            indegree.set(node.id, 0);
+        for (const edge of execEdges) {
+            indegree.set(edge.targetNodeId, (indegree.get(edge.targetNodeId) ?? 0) + 1);
+        }
+        const layers = [];
+        const planned = new Set();
+        let ready = executableNodes.filter((n) => (indegree.get(n.id) ?? 0) === 0);
+        let layerIndex = 0;
+        while (ready.length > 0) {
+            const layer = { index: layerIndex++, nodes: ready };
+            layers.push(layer);
+            const nextReady = [];
+            for (const node of ready) {
+                planned.add(node.id);
+                const outgoing = execEdges.filter((e) => e.sourceNodeId === node.id);
+                for (const edge of outgoing) {
+                    const deg = (indegree.get(edge.targetNodeId) ?? 1) - 1;
+                    indegree.set(edge.targetNodeId, deg);
+                    if (deg === 0 && !planned.has(edge.targetNodeId)) {
+                        const next = executableNodes.find((n) => n.id === edge.targetNodeId);
+                        if (next)
+                            nextReady.push(next);
+                    }
+                }
+            }
+            ready = nextReady;
+        }
+        if (planned.size !== executableNodes.length) {
+            const unplanned = executableNodes
+                .filter((n) => !planned.has(n.id))
+                .map((n) => n.id);
+            throw new GraphCycleError_js_1.GraphCycleError({
+                unplannedNodes: unplanned,
+                workflowId: nodes[0]?.definition?.name,
+            });
+        }
+        return layers;
+    }
+}
+exports.GraphExecutionPlanner = GraphExecutionPlanner;
+//# sourceMappingURL=GraphExecutionPlanner.js.map
+//# sourceMappingURL=GraphExecutionPlanner.cjs.map

package/lib/cjs/graph/planning/GraphExecutionPlanner.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph/planning/GraphExecutionPlanner.cjs","sourceRoot":"","sources":["graph/planning/GraphExecutionPlanner.js"],"names":[],"mappings":"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"}

package/lib/cjs/graph/planning/GraphRelationResolver.cjs

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphRelationResolver = void 0;
+const graph_1 = require("@decaf-ts/ui-decorators/graph");
+const constants_js_1 = require("./../constants.cjs");
+const GraphPortError_js_1 = require("./../errors/GraphPortError.cjs");
+const GraphTopologyError_js_1 = require("./../errors/GraphTopologyError.cjs");
+/**
+ * Resolves raw workflow relation metadata into normalized execution edges.
+ */
+class GraphRelationResolver {
+    /**
+     * Resolves all relations of a workflow into execution edges.
+     *
+     * @param workflow - The workflow definition.
+     * @returns Array of normalized edges.
+     * @throws {GraphTopologyError} when an endpoint is unknown or ambiguous.
+     * @throws {GraphPortError} when a referenced port is missing or unknown.
+     */
+    resolve(workflow) {
+        const nodeIds = new Set(workflow.nodes.map((n) => n.id));
+        const boundaryAliases = this.boundaryAliases(workflow);
+        const inputPorts = this.portNames(workflow.inputs);
+        const outputPorts = this.portNames(workflow.outputs);
+        const nodePortMap = this.buildNodePortMap(workflow);
+        const edges = [];
+        for (const relation of workflow.relations ?? []) {
+            const edge = this.resolveRelation(relation, nodeIds, boundaryAliases, inputPorts, outputPorts, nodePortMap);
+            edges.push(edge);
+        }
+        return edges;
+    }
+    /**
+     * Resolves a single relation into an edge.
+     */
+    resolveRelation(relation, nodeIds, boundaryAliases, inputPorts, outputPorts, nodePortMap) {
+        const sourceNodeId = this.resolveEndpoint(relation.source, nodeIds, boundaryAliases);
+        const targetNodeId = this.resolveEndpoint(relation.target, nodeIds, boundaryAliases);
+        const sourcePort = relation.sourcePort;
+        const targetPort = relation.targetPort;
+        if (!sourcePort) {
+            throw new GraphPortError_js_1.GraphPortError(`Relation is missing sourcePort (source: ${String(relation.source)}, target: ${String(relation.target)})`, { relation });
+        }
+        if (!targetPort) {
+            throw new GraphPortError_js_1.GraphPortError(`Relation is missing targetPort (source: ${String(relation.source)}, target: ${String(relation.target)})`, { relation });
+        }
+        this.validatePort(sourceNodeId, sourcePort, true, boundaryAliases, inputPorts, outputPorts, nodePortMap);
+        this.validatePort(targetNodeId, targetPort, false, boundaryAliases, inputPorts, outputPorts, nodePortMap);
+        return {
+            id: this.createEdgeId(sourceNodeId, sourcePort, targetNodeId, targetPort),
+            sourceNodeId,
+            sourcePort,
+            targetNodeId,
+            targetPort,
+            label: relation.label,
+            metadata: relation.metadata,
+        };
+    }
+    /**
+     * Resolves an endpoint (source or target) to a node id or the workflow boundary.
+     */
+    resolveEndpoint(endpoint, nodeIds, boundaryAliases) {
+        const name = String(endpoint);
+        if (boundaryAliases.has(name))
+            return constants_js_1.GRAPH_WORKFLOW_BOUNDARY;
+        if (nodeIds.has(name))
+            return name;
+        throw new GraphTopologyError_js_1.GraphTopologyError(`Unknown endpoint '${name}'`, { endpoint: name, knownNodes: Array.from(nodeIds) });
+    }
+    /**
+     * Validates that a port exists on the given node or boundary.
+     */
+    validatePort(nodeId, port, isSource, boundaryAliases, inputPorts, outputPorts, nodePortMap) {
+        if (nodeId === constants_js_1.GRAPH_WORKFLOW_BOUNDARY) {
+            const ports = isSource ? inputPorts : outputPorts;
+            if (!ports.has(port)) {
+                throw new GraphPortError_js_1.GraphPortError(`Unknown ${isSource ? "input" : "output"} port '${port}' on workflow boundary`, { nodeId, port, isSource, available: Array.from(ports) });
+            }
+            return;
+        }
+        const nodePorts = nodePortMap.get(nodeId);
+        if (!nodePorts) {
+            throw new GraphTopologyError_js_1.GraphTopologyError(`No port map for node '${nodeId}'`, {
+                nodeId,
+            });
+        }
+        const ports = isSource ? nodePorts.output : nodePorts.input;
+        if (!ports.has(port)) {
+            throw new GraphPortError_js_1.GraphPortError(`Unknown ${isSource ? "output" : "input"} port '${port}' on node '${nodeId}'`, { nodeId, port, isSource, available: Array.from(ports) });
+        }
+    }
+    /**
+     * Builds the set of boundary aliases for a workflow.
+     */
+    boundaryAliases(workflow) {
+        return new Set([
+            constants_js_1.GRAPH_WORKFLOW_BOUNDARY,
+            "workflow",
+            "graph",
+            workflow.name,
+        ]);
+    }
+    /**
+     * Extracts port names from a list of port definitions.
+     */
+    portNames(ports) {
+        return new Set((ports ?? []).map((p) => p.name));
+    }
+    /**
+     * Builds a map of node id -> { input ports, output ports }.
+     */
+    buildNodePortMap(workflow) {
+        const map = new Map();
+        for (const nodeMeta of workflow.nodes ?? []) {
+            const input = new Set();
+            const output = new Set();
+            const def = this.resolveNodeDefinition(nodeMeta);
+            if (def) {
+                for (const port of def.ports ?? []) {
+                    if (port.direction === "input")
+                        input.add(port.name);
+                    else
+                        output.add(port.name);
+                }
+            }
+            map.set(nodeMeta.id, { input, output });
+        }
+        return map;
+    }
+    /**
+     * Attempts to resolve a node's full definition from its 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).
+     */
+    resolveNodeDefinition(nodeMeta) {
+        if (nodeMeta.node) {
+            if (this.isRawDefinition(nodeMeta.node)) {
+                return nodeMeta.node;
+            }
+            try {
+                const def = (0, graph_1.graphDefinitionOf)(nodeMeta.node);
+                return def;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Returns `true` when a value looks like a raw {@link GraphNodeDefinition}
+     * (a plain object with a `ports` array and a `name` string).
+     */
+    isRawDefinition(value) {
+        return (typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value) &&
+            typeof value.name === "string" &&
+            Array.isArray(value.ports));
+    }
+    /**
+     * Creates a stable edge id from its endpoints and ports.
+     */
+    createEdgeId(sourceNodeId, sourcePort, targetNodeId, targetPort) {
+        return `${sourceNodeId}:${sourcePort}->${targetNodeId}:${targetPort}`;
+    }
+}
+exports.GraphRelationResolver = GraphRelationResolver;
+//# sourceMappingURL=GraphRelationResolver.js.map
+//# sourceMappingURL=GraphRelationResolver.cjs.map