@decaf-ts/integrations 0.3.1 → 0.3.2

package/lib/esm/graph/store/GraphValueStore.js

@@ -0,0 +1,71 @@
+/**
+ * @module integrations/graph/store/GraphValueStore
+ * @summary Runtime value store wrapping a persistent adapter.
+ * @description Holds runtime values for the current execution in memory and delegates cached/pinned values to a {@link GraphValueStoreAdapter}.
+ */
+import { GRAPH_WORKFLOW_BOUNDARY } from "./../constants.js";
+/**
+ * Manages values during a single graph execution.
+ *
+ * Runtime values (workflow inputs, node outputs, workflow outputs) are kept in
+ * an in-memory map. Persistent cache and pinning operations are delegated to
+ * the configured {@link GraphValueStoreAdapter}.
+ */
+export class GraphValueStore {
+    /**
+     * @param adapter - The persistent adapter for cached/pinned values.
+     */
+    constructor(adapter) {
+        this.adapter = adapter;
+        this.runtimeValues = new Map();
+    }
+    /** Seeds the workflow input values. */
+    seedWorkflowInputs(inputs) {
+        this.runtimeValues.set(GRAPH_WORKFLOW_BOUNDARY, { ...inputs });
+    }
+    /** Stores the outputs produced by a node. */
+    setNodeOutputs(nodeId, outputs) {
+        this.runtimeValues.set(nodeId, { ...outputs });
+    }
+    /** Reads a single port value from a node's stored outputs. */
+    getPort(nodeId, port) {
+        return this.runtimeValues.get(nodeId)?.[port];
+    }
+    /** Returns whether a node has a value for the given port. */
+    hasPort(nodeId, port) {
+        return Object.prototype.hasOwnProperty.call(this.runtimeValues.get(nodeId) ?? {}, port);
+    }
+    /** Sets a single workflow output port value. */
+    setWorkflowOutput(port, value) {
+        const current = this.runtimeValues.get(GRAPH_WORKFLOW_BOUNDARY) ?? {};
+        current[port] = value;
+        this.runtimeValues.set(GRAPH_WORKFLOW_BOUNDARY, current);
+    }
+    /** Returns all workflow-level values (inputs merged with outputs). */
+    getWorkflowValues() {
+        return {
+            ...(this.runtimeValues.get(GRAPH_WORKFLOW_BOUNDARY) ?? {}),
+        };
+    }
+    /** Reads a cached value from the adapter. */
+    async readCached(key) {
+        return this.adapter.read(key);
+    }
+    /** Writes a cached value through the adapter. */
+    async writeCached(key, value) {
+        await this.adapter.write(key, value);
+    }
+    /** Deletes a cached value through the adapter. */
+    async deleteCached(key) {
+        await this.adapter.delete(key);
+    }
+    /** Returns a snapshot of all runtime values. */
+    snapshot() {
+        return Object.fromEntries(this.runtimeValues.entries());
+    }
+    /** Returns the underlying adapter (used by the pinning service). */
+    getAdapter() {
+        return this.adapter;
+    }
+}
+//# sourceMappingURL=GraphValueStore.js.map

package/lib/esm/graph/store/GraphValueStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphValueStore.js","sourceRoot":"","sources":["../../../../src/graph/store/GraphValueStore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,uBAAuB,EAAE,0BAAqB;AAMvD;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAG1B;;OAEG;IACH,YAA6B,OAA+B;QAA/B,YAAO,GAAP,OAAO,CAAwB;QAL3C,kBAAa,GAAG,IAAI,GAAG,EAAgC,CAAC;IAKV,CAAC;IAEhE,uCAAuC;IACvC,kBAAkB,CAAC,MAA4B;QAC7C,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,uBAAuB,EAAE,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,6CAA6C;IAC7C,cAAc,CAAC,MAAc,EAAE,OAA6B;QAC1D,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,8DAA8D;IAC9D,OAAO,CAAC,MAAc,EAAE,IAAY;QAClC,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC;IAED,6DAA6D;IAC7D,OAAO,CAAC,MAAc,EAAE,IAAY;QAClC,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CACzC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EACpC,IAAI,CACL,CAAC;IACJ,CAAC;IAED,gDAAgD;IAChD,iBAAiB,CAAC,IAAY,EAAE,KAAc;QAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,uBAAuB,CAAC,IAAI,EAAE,CAAC;QACtE,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QACtB,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED,sEAAsE;IACtE,iBAAiB;QACf,OAAO;YACL,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,uBAAuB,CAAC,IAAI,EAAE,CAAC;SAC3D,CAAC;IACJ,CAAC;IAED,6CAA6C;IAC7C,KAAK,CAAC,UAAU,CAAC,GAAkB;QACjC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,WAAW,CAAC,GAAkB,EAAE,KAAuB;QAC3D,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,YAAY,CAAC,GAAkB;QACnC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED,gDAAgD;IAChD,QAAQ;QACN,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,oEAAoE;IACpE,UAAU;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;CACF"}

package/lib/esm/graph/store/GraphValueStoreAdapter.js

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

package/lib/esm/graph/store/GraphValueStoreAdapter.js.map

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

package/lib/esm/graph/store/InMemoryGraphValueStoreAdapter.js

@@ -0,0 +1,64 @@
+/**
+ * In-memory implementation of {@link GraphValueStoreAdapter}.
+ *
+ * Values are keyed by a serialized string combining namespace, workflowId,
+ * nodeId, version, and fingerprint.
+ */
+export class InMemoryGraphValueStoreAdapter {
+    constructor() {
+        this.values = new Map();
+    }
+    /** @inheritDoc */
+    async read(key) {
+        return this.values.get(this.serializeKey(key));
+    }
+    /** @inheritDoc */
+    async write(key, value) {
+        this.values.set(this.serializeKey(key), value);
+    }
+    /** @inheritDoc */
+    async delete(key) {
+        this.values.delete(this.serializeKey(key));
+    }
+    /** @inheritDoc */
+    async has(key) {
+        return this.values.has(this.serializeKey(key));
+    }
+    /** @inheritDoc */
+    async list(prefix) {
+        const results = [];
+        for (const value of this.values.values()) {
+            const k = value.key;
+            if (prefix.workflowId !== undefined &&
+                k.workflowId !== prefix.workflowId)
+                continue;
+            if (prefix.nodeId !== undefined && k.nodeId !== prefix.nodeId)
+                continue;
+            if (prefix.namespace !== undefined &&
+                k.namespace !== prefix.namespace)
+                continue;
+            if (prefix.version !== undefined && k.version !== prefix.version)
+                continue;
+            results.push(value);
+        }
+        return results;
+    }
+    /** @inheritDoc */
+    async clearRun(runId) {
+        void runId;
+        this.values.clear();
+    }
+    /**
+     * Serializes a key into a stable string used as the Map key.
+     */
+    serializeKey(key) {
+        return [
+            key.namespace ?? "default",
+            key.workflowId,
+            key.nodeId,
+            key.version ?? "default",
+            key.fingerprint,
+        ].join(":");
+    }
+}
+//# sourceMappingURL=InMemoryGraphValueStoreAdapter.js.map

package/lib/esm/graph/store/InMemoryGraphValueStoreAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryGraphValueStoreAdapter.js","sourceRoot":"","sources":["../../../../src/graph/store/InMemoryGraphValueStoreAdapter.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,MAAM,OAAO,8BAA8B;IAA3C;QACmB,WAAM,GAAG,IAAI,GAAG,EAA4B,CAAC;IA+DhE,CAAC;IA7DC,kBAAkB;IAClB,KAAK,CAAC,IAAI,CAAC,GAAkB;QAC3B,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,kBAAkB;IAClB,KAAK,CAAC,KAAK,CAAC,GAAkB,EAAE,KAAuB;QACrD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IACjD,CAAC;IAED,kBAAkB;IAClB,KAAK,CAAC,MAAM,CAAC,GAAkB;QAC7B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,kBAAkB;IAClB,KAAK,CAAC,GAAG,CAAC,GAAkB;QAC1B,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,kBAAkB;IAClB,KAAK,CAAC,IAAI,CAAC,MAA8B;QACvC,MAAM,OAAO,GAAuB,EAAE,CAAC;QACvC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACzC,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC;YACpB,IACE,MAAM,CAAC,UAAU,KAAK,SAAS;gBAC/B,CAAC,CAAC,UAAU,KAAK,MAAM,CAAC,UAAU;gBAElC,SAAS;YACX,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;gBAAE,SAAS;YACxE,IACE,MAAM,CAAC,SAAS,KAAK,SAAS;gBAC9B,CAAC,CAAC,SAAS,KAAK,MAAM,CAAC,SAAS;gBAEhC,SAAS;YACX,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO;gBAC9D,SAAS;YACX,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,kBAAkB;IAClB,KAAK,CAAC,QAAQ,CAAC,KAAa;QAC1B,KAAK,KAAK,CAAC;QACX,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED;;OAEG;IACK,YAAY,CAAC,GAAkB;QACrC,OAAO;YACL,GAAG,CAAC,SAAS,IAAI,SAAS;YAC1B,GAAG,CAAC,UAAU;YACd,GAAG,CAAC,MAAM;YACV,GAAG,CAAC,OAAO,IAAI,SAAS;YACxB,GAAG,CAAC,WAAW;SAChB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACd,CAAC;CACF"}

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

@@ -0,0 +1,11 @@
+/**
+ * @module integrations/graph/store
+ * @summary Graph value store, adapter, and key types.
+ * @description Re-exports the value store adapter interface, in-memory default, key/cached-value types, and the runtime store wrapper.
+ */
+export * from "./GraphValueKey.js";
+export * from "./GraphCachedValue.js";
+export * from "./GraphValueStoreAdapter.js";
+export * from "./InMemoryGraphValueStoreAdapter.js";
+export * from "./GraphValueStore.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/graph/store/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,mCAAgC;AAChC,sCAAmC;AACnC,4CAAyC;AACzC,oDAAiD;AACjD,qCAAkC"}

package/lib/esm/graph/types.js

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

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

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

package/lib/esm/graph/validation/GraphDefinitionValidator.js

@@ -0,0 +1,28 @@
+import { GraphInputError } from "./../errors/GraphInputError.js";
+import { GraphExecutionPlanner } from "./../planning/GraphExecutionPlanner.js";
+/**
+ * Validates a {@link GraphWorkflowDefinition} before execution.
+ */
+export class GraphDefinitionValidator {
+    constructor(planner) {
+        this.planner = planner ?? new GraphExecutionPlanner();
+    }
+    /**
+     * Validates the workflow definition.
+     *
+     * @throws {GraphInputError} when the workflow has no name or invalid structure.
+     * @throws {GraphCycleError} when the workflow contains an unsupported cycle.
+     */
+    validate(workflow) {
+        if (!workflow.name) {
+            throw new GraphInputError("Workflow must have a name");
+        }
+        const nodeIds = new Set((workflow.nodes ?? []).map((n) => n.id));
+        if (nodeIds.size !== (workflow.nodes ?? []).length) {
+            throw new GraphInputError("Workflow node IDs must be unique");
+        }
+        // The planner performs full topology validation (endpoints, ports, cycles)
+        this.planner.plan(workflow);
+    }
+}
+//# sourceMappingURL=GraphDefinitionValidator.js.map

package/lib/esm/graph/validation/GraphDefinitionValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphDefinitionValidator.js","sourceRoot":"","sources":["../../../../src/graph/validation/GraphDefinitionValidator.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,eAAe,EAAE,uCAAkC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,+CAA0C;AAE1E;;GAEG;AACH,MAAM,OAAO,wBAAwB;IAGnC,YAAY,OAA+B;QACzC,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,IAAI,qBAAqB,EAAE,CAAC;IACxD,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,QAAiC;QACxC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnB,MAAM,IAAI,eAAe,CAAC,2BAA2B,CAAC,CAAC;QACzD,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACjE,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;YACnD,MAAM,IAAI,eAAe,CAAC,kCAAkC,CAAC,CAAC;QAChE,CAAC;QAED,2EAA2E;QAC3E,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC;CACF"}

package/lib/esm/graph/validation/GraphPortSchemaResolver.js

@@ -0,0 +1,53 @@
+/**
+ * Resolves a {@link GraphPortDefinition} to a Zod schema (or a lightweight
+ * validation function when Zod is not available).
+ *
+ * This implementation uses primitive type mapping. When the port's `model`
+ * field or underlying Decaf metadata references a `Model` class, consumers
+ * should use `modelToZod` from `@decaf-ts/as-zod` to build the schema.
+ */
+export class GraphPortSchemaResolver {
+    /**
+     * Resolves a single port to a schema descriptor.
+     *
+     * @returns A descriptor with the port name, a `validate` function, and
+     * optional Zod schema reference.
+     */
+    resolve(port) {
+        const validate = this.createValidator(port);
+        return { name: port.name, required: port.required, validate };
+    }
+    /**
+     * Resolves multiple ports into a map of name -> descriptor.
+     */
+    resolveAll(ports) {
+        const result = {};
+        for (const port of ports) {
+            result[port.name] = this.resolve(port);
+        }
+        return result;
+    }
+    /**
+     * Creates a validation function based on the port's type.
+     */
+    createValidator(port) {
+        const type = (port.type ?? port.designType ?? "").toLowerCase();
+        switch (type) {
+            case "string":
+                return (v) => typeof v === "string";
+            case "number":
+                return (v) => typeof v === "number";
+            case "boolean":
+                return (v) => typeof v === "boolean";
+            case "date":
+                return (v) => v instanceof Date || (typeof v === "string" && !isNaN(Date.parse(v)));
+            case "array":
+                return (v) => Array.isArray(v);
+            case "bigint":
+                return (v) => typeof v === "bigint";
+            default:
+                return () => true;
+        }
+    }
+}
+//# sourceMappingURL=GraphPortSchemaResolver.js.map

package/lib/esm/graph/validation/GraphPortSchemaResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphPortSchemaResolver.js","sourceRoot":"","sources":["../../../../src/graph/validation/GraphPortSchemaResolver.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,MAAM,OAAO,uBAAuB;IAClC;;;;;OAKG;IACH,OAAO,CAAC,IAAyB;QAK/B,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAC5C,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAC;IAChE,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,KAA4B;QACrC,MAAM,MAAM,GAA+F,EAAE,CAAC;QAC9G,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACK,eAAe,CAAC,IAAyB;QAC/C,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAChE,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,QAAQ;gBACX,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;YACtC,KAAK,QAAQ;gBACX,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;YACtC,KAAK,SAAS;gBACZ,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC;YACvC,KAAK,MAAM;gBACT,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACtF,KAAK,OAAO;gBACV,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACjC,KAAK,QAAQ;gBACX,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;YACtC;gBACE,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC;QACtB,CAAC;IACH,CAAC;CACF"}

package/lib/esm/graph/validation/GraphValueValidator.js

@@ -0,0 +1,47 @@
+import { GraphInputError } from "./../errors/GraphInputError.js";
+/**
+ * Validates runtime values against port definitions.
+ */
+export class GraphValueValidator {
+    constructor(resolver) {
+        this.resolver = resolver;
+    }
+    /** Validates workflow-level input values. */
+    validateWorkflowInputs(workflow, values) {
+        this.validatePorts(workflow.inputs, values, "workflow input");
+    }
+    /** Validates workflow-level output values. */
+    validateWorkflowOutputs(workflow, values) {
+        this.validatePorts(workflow.outputs, values, "workflow output");
+    }
+    /** Validates a node's input values. */
+    validateNodeInputs(node, values) {
+        const inputPorts = (node.ports ?? []).filter((p) => p.direction === "input");
+        this.validatePorts(inputPorts, values, `node '${node.name}' input`);
+    }
+    /** Validates a node's output values. */
+    validateNodeOutputs(node, values) {
+        const outputPorts = (node.ports ?? []).filter((p) => p.direction === "output");
+        this.validatePorts(outputPorts, values, `node '${node.name}' output`);
+    }
+    /**
+     * Validates values against a set of port definitions.
+     */
+    validatePorts(ports, values, context) {
+        if (!ports)
+            return;
+        for (const port of ports) {
+            const has = Object.prototype.hasOwnProperty.call(values, port.name);
+            if (port.required && !has) {
+                throw new GraphInputError(`Missing required ${context} port '${port.name}'`);
+            }
+            if (has) {
+                const descriptor = this.resolver.resolve(port);
+                if (!descriptor.validate(values[port.name])) {
+                    throw new GraphInputError(`Invalid value for ${context} port '${port.name}'`);
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=GraphValueValidator.js.map

package/lib/esm/graph/validation/GraphValueValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphValueValidator.js","sourceRoot":"","sources":["../../../../src/graph/validation/GraphValueValidator.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,eAAe,EAAE,uCAAkC;AAI5D;;GAEG;AACH,MAAM,OAAO,mBAAmB;IAC9B,YAA6B,QAAiC;QAAjC,aAAQ,GAAR,QAAQ,CAAyB;IAAG,CAAC;IAElE,6CAA6C;IAC7C,sBAAsB,CACpB,QAAiC,EACjC,MAA4B;QAE5B,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAChE,CAAC;IAED,8CAA8C;IAC9C,uBAAuB,CACrB,QAAiC,EACjC,MAA4B;QAE5B,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAClE,CAAC;IAED,uCAAuC;IACvC,kBAAkB,CAChB,IAAyB,EACzB,MAA4B;QAE5B,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,CAC1C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,OAAO,CAC/B,CAAC;QACF,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,IAAI,CAAC,IAAI,SAAS,CAAC,CAAC;IACtE,CAAC;IAED,wCAAwC;IACxC,mBAAmB,CACjB,IAAyB,EACzB,MAA4B;QAE5B,MAAM,WAAW,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,CAC3C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,QAAQ,CAChC,CAAC;QACF,IAAI,CAAC,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,IAAI,CAAC,IAAI,UAAU,CAAC,CAAC;IACxE,CAAC;IAED;;OAEG;IACK,aAAa,CACnB,KAAwC,EACxC,MAA4B,EAC5B,OAAe;QAEf,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YACpE,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,GAAG,EAAE,CAAC;gBAC1B,MAAM,IAAI,eAAe,CACvB,oBAAoB,OAAO,UAAU,IAAI,CAAC,IAAI,GAAG,CAClD,CAAC;YACJ,CAAC;YACD,IAAI,GAAG,EAAE,CAAC;gBACR,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAC/C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;oBAC5C,MAAM,IAAI,eAAe,CACvB,qBAAqB,OAAO,UAAU,IAAI,CAAC,IAAI,GAAG,CACnD,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

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

@@ -0,0 +1,9 @@
+/**
+ * @module integrations/graph/validation
+ * @summary Graph validation utilities.
+ * @description Re-exports the definition validator, port schema resolver, and value validator.
+ */
+export * from "./GraphDefinitionValidator.js";
+export * from "./GraphPortSchemaResolver.js";
+export * from "./GraphValueValidator.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/graph/validation/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,8CAA2C;AAC3C,6CAA0C;AAC1C,yCAAsC"}

package/lib/esm/index.js

@@ -4,8 +4,8 @@
  * @description Exposes the package utilities and build-time version metadata for `@decaf-ts/integrations`.
  */
 export * from "./utils.js";
-export const VERSION = "0.3.0";
-export const COMMIT = "bf16ce1";
-export const FULL_VERSION = "0.3.0-bf16ce1";
+export const VERSION = "0.3.1";
+export const COMMIT = "538f19e";
+export const FULL_VERSION = "0.3.1-538f19e";
 export const PACKAGE_NAME = "@decaf-ts/integrations";
 //# sourceMappingURL=index.js.map

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

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

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

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

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

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/graph/decorators
+ * @summary Reserved for future core-level graph decorators.
+ * @description This file is intentionally empty for now. Graph decorators such as `@pinnable()` live in `@decaf-ts/ui-decorators/graph`. Additional decorators may be added here if the core engine needs its own metadata keys.
+ */
+export {};

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

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/graph/decorators
+ * @summary Reserved for future core-level graph decorators.
+ * @description This file is intentionally empty for now. Graph decorators such as `@pinnable()` live in `@decaf-ts/ui-decorators/graph`. Additional decorators may be added here if the core engine needs its own metadata keys.
+ */
+export {};

package/lib/types/graph/errors/GraphCycleError.d.cts

@@ -0,0 +1,12 @@
+/**
+ * @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.d.cts";
+/**
+ * Thrown when a graph workflow contains an unsupported cycle.
+ */
+export declare class GraphCycleError extends GraphExecutionError {
+    constructor(details?: unknown);
+}

package/lib/types/graph/errors/GraphCycleError.d.mts

@@ -0,0 +1,12 @@
+/**
+ * @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.d.mts";
+/**
+ * Thrown when a graph workflow contains an unsupported cycle.
+ */
+export declare class GraphCycleError extends GraphExecutionError {
+    constructor(details?: unknown);
+}

package/lib/types/graph/errors/GraphExecutionError.d.cts

@@ -0,0 +1,19 @@
+/**
+ * @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 declare class GraphExecutionError extends InternalError {
+    readonly graphCode: string;
+    readonly details?: unknown;
+    constructor(message: string, graphCode?: string, details?: unknown);
+}

package/lib/types/graph/errors/GraphExecutionError.d.mts

@@ -0,0 +1,19 @@
+/**
+ * @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 declare class GraphExecutionError extends InternalError {
+    readonly graphCode: string;
+    readonly details?: unknown;
+    constructor(message: string, graphCode?: string, details?: unknown);
+}

package/lib/types/graph/errors/GraphInputError.d.cts

@@ -0,0 +1,12 @@
+/**
+ * @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.d.cts";
+/**
+ * Thrown when workflow or node inputs are invalid.
+ */
+export declare class GraphInputError extends GraphExecutionError {
+    constructor(message: string, details?: unknown);
+}