@decaf-ts/integrations 0.10.8 → 0.12.0

package/lib/types/graph/engine/store/GraphCachedValue.d.cts

@@ -1,20 +0,0 @@
-/**
- * @module integrations/graph/store/GraphCachedValue
- * @summary A cached graph value with pinning metadata.
- * @description Represents a node's output that has been cached (and optionally pinned) in the value store.
- */
-import type { GraphExecutionValues } from "../types.d.cts";
-import type { GraphValueKey } from "./GraphValueKey.d.cts";
-/**
- * A value stored in the cache, including the outputs, pinning state, and
- * timestamps for TTL-based expiry.
- */
-export interface GraphCachedValue {
-    key: GraphValueKey;
-    outputs: GraphExecutionValues;
-    pinned: boolean;
-    createdAt: string;
-    updatedAt: string;
-    expiresAt?: string;
-    metadata?: Record<string, unknown>;
-}

package/lib/types/graph/engine/store/GraphCachedValue.d.mts

@@ -1,20 +0,0 @@
-/**
- * @module integrations/graph/store/GraphCachedValue
- * @summary A cached graph value with pinning metadata.
- * @description Represents a node's output that has been cached (and optionally pinned) in the value store.
- */
-import type { GraphExecutionValues } from "../types.d.mts";
-import type { GraphValueKey } from "./GraphValueKey.d.mts";
-/**
- * A value stored in the cache, including the outputs, pinning state, and
- * timestamps for TTL-based expiry.
- */
-export interface GraphCachedValue {
-    key: GraphValueKey;
-    outputs: GraphExecutionValues;
-    pinned: boolean;
-    createdAt: string;
-    updatedAt: string;
-    expiresAt?: string;
-    metadata?: Record<string, unknown>;
-}

package/lib/types/graph/engine/store/GraphValueKey.d.cts

@@ -1,18 +0,0 @@
-/**
- * @module integrations/graph/store/GraphValueKey
- * @summary Stable key for cached graph values.
- * @description Identifies a cached value in the store by workflow, node, fingerprint, and optional namespace/version.
- */
-/**
- * Key used to read/write cached values in a {@link GraphValueStoreAdapter}.
- *
- * The `fingerprint` must change when meaningful inputs or dependencies change
- * so stale values are never accidentally reused.
- */
-export interface GraphValueKey {
-    workflowId: string;
-    nodeId: string;
-    fingerprint: string;
-    namespace?: string;
-    version?: string;
-}

package/lib/types/graph/engine/store/GraphValueKey.d.mts

@@ -1,18 +0,0 @@
-/**
- * @module integrations/graph/store/GraphValueKey
- * @summary Stable key for cached graph values.
- * @description Identifies a cached value in the store by workflow, node, fingerprint, and optional namespace/version.
- */
-/**
- * Key used to read/write cached values in a {@link GraphValueStoreAdapter}.
- *
- * The `fingerprint` must change when meaningful inputs or dependencies change
- * so stale values are never accidentally reused.
- */
-export interface GraphValueKey {
-    workflowId: string;
-    nodeId: string;
-    fingerprint: string;
-    namespace?: string;
-    version?: string;
-}

package/lib/types/graph/engine/store/GraphValueStore.d.cts

@@ -1,41 +0,0 @@
-import type { GraphExecutionValues } from "../types.d.cts";
-import type { GraphValueStoreAdapter } from "./GraphValueStoreAdapter.d.cts";
-import type { GraphValueKey } from "./GraphValueKey.d.cts";
-import type { GraphCachedValue } from "./GraphCachedValue.d.cts";
-/**
- * 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 declare class GraphValueStore {
-    private readonly adapter;
-    private readonly runtimeValues;
-    /**
-     * @param adapter - The persistent adapter for cached/pinned values.
-     */
-    constructor(adapter: GraphValueStoreAdapter);
-    /** Seeds the workflow input values. */
-    seedWorkflowInputs(inputs: GraphExecutionValues): void;
-    /** Stores the outputs produced by a node. */
-    setNodeOutputs(nodeId: string, outputs: GraphExecutionValues): void;
-    /** Reads a single port value from a node's stored outputs. */
-    getPort(nodeId: string, port: string): unknown;
-    /** Returns whether a node has a value for the given port. */
-    hasPort(nodeId: string, port: string): boolean;
-    /** Sets a single workflow output port value. */
-    setWorkflowOutput(port: string, value: unknown): void;
-    /** Returns all workflow-level values (inputs merged with outputs). */
-    getWorkflowValues(): GraphExecutionValues;
-    /** Reads a cached value from the adapter. */
-    readCached(key: GraphValueKey): Promise<GraphCachedValue | undefined>;
-    /** Writes a cached value through the adapter. */
-    writeCached(key: GraphValueKey, value: GraphCachedValue): Promise<void>;
-    /** Deletes a cached value through the adapter. */
-    deleteCached(key: GraphValueKey): Promise<void>;
-    /** Returns a snapshot of all runtime values. */
-    snapshot(): Record<string, GraphExecutionValues>;
-    /** Returns the underlying adapter (used by the pinning service). */
-    getAdapter(): GraphValueStoreAdapter;
-}

package/lib/types/graph/engine/store/GraphValueStore.d.mts

@@ -1,41 +0,0 @@
-import type { GraphExecutionValues } from "../types.d.mts";
-import type { GraphValueStoreAdapter } from "./GraphValueStoreAdapter.d.mts";
-import type { GraphValueKey } from "./GraphValueKey.d.mts";
-import type { GraphCachedValue } from "./GraphCachedValue.d.mts";
-/**
- * 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 declare class GraphValueStore {
-    private readonly adapter;
-    private readonly runtimeValues;
-    /**
-     * @param adapter - The persistent adapter for cached/pinned values.
-     */
-    constructor(adapter: GraphValueStoreAdapter);
-    /** Seeds the workflow input values. */
-    seedWorkflowInputs(inputs: GraphExecutionValues): void;
-    /** Stores the outputs produced by a node. */
-    setNodeOutputs(nodeId: string, outputs: GraphExecutionValues): void;
-    /** Reads a single port value from a node's stored outputs. */
-    getPort(nodeId: string, port: string): unknown;
-    /** Returns whether a node has a value for the given port. */
-    hasPort(nodeId: string, port: string): boolean;
-    /** Sets a single workflow output port value. */
-    setWorkflowOutput(port: string, value: unknown): void;
-    /** Returns all workflow-level values (inputs merged with outputs). */
-    getWorkflowValues(): GraphExecutionValues;
-    /** Reads a cached value from the adapter. */
-    readCached(key: GraphValueKey): Promise<GraphCachedValue | undefined>;
-    /** Writes a cached value through the adapter. */
-    writeCached(key: GraphValueKey, value: GraphCachedValue): Promise<void>;
-    /** Deletes a cached value through the adapter. */
-    deleteCached(key: GraphValueKey): Promise<void>;
-    /** Returns a snapshot of all runtime values. */
-    snapshot(): Record<string, GraphExecutionValues>;
-    /** Returns the underlying adapter (used by the pinning service). */
-    getAdapter(): GraphValueStoreAdapter;
-}

package/lib/types/graph/engine/store/GraphValueStoreAdapter.d.cts

@@ -1,32 +0,0 @@
-/**
- * @module integrations/graph/store/GraphValueStoreAdapter
- * @summary Adapter interface for persistent graph value storage.
- * @description Users provide implementations of this interface to control where cached/pinned values live (in-memory, database, Redis, file, etc.).
- */
-import type { GraphExecutionValues } from "../types.d.cts";
-import type { GraphValueKey } from "./GraphValueKey.d.cts";
-import type { GraphCachedValue } from "./GraphCachedValue.d.cts";
-/**
- * Adapter that persists cached and pinned graph values.
- *
- * The engine never assumes a specific storage backend; it always delegates to
- * an adapter. The {@link InMemoryGraphValueStoreAdapter} is the default.
- */
-export interface GraphValueStoreAdapter {
-    /** Reads a cached value for the given key. */
-    read(key: GraphValueKey): Promise<GraphCachedValue | undefined>;
-    /** Writes a cached value for the given key. */
-    write(key: GraphValueKey, value: GraphCachedValue): Promise<void>;
-    /** Deletes a cached value for the given key. */
-    delete(key: GraphValueKey): Promise<void>;
-    /** Returns whether a cached value exists for the given key. */
-    has(key: GraphValueKey): Promise<boolean>;
-    /** Lists cached values matching a prefix of the key. */
-    list?(prefix: Partial<GraphValueKey>): Promise<GraphCachedValue[]>;
-    /** Clears all cached values for a run. */
-    clearRun?(runId: string): Promise<void>;
-    /** Reads the runtime values for a node in a run. */
-    readRuntimeValues?(runId: string, nodeId: string): Promise<GraphExecutionValues | undefined>;
-    /** Writes the runtime values for a node in a run. */
-    writeRuntimeValues?(runId: string, nodeId: string, values: GraphExecutionValues): Promise<void>;
-}

package/lib/types/graph/engine/store/GraphValueStoreAdapter.d.mts

@@ -1,32 +0,0 @@
-/**
- * @module integrations/graph/store/GraphValueStoreAdapter
- * @summary Adapter interface for persistent graph value storage.
- * @description Users provide implementations of this interface to control where cached/pinned values live (in-memory, database, Redis, file, etc.).
- */
-import type { GraphExecutionValues } from "../types.d.mts";
-import type { GraphValueKey } from "./GraphValueKey.d.mts";
-import type { GraphCachedValue } from "./GraphCachedValue.d.mts";
-/**
- * Adapter that persists cached and pinned graph values.
- *
- * The engine never assumes a specific storage backend; it always delegates to
- * an adapter. The {@link InMemoryGraphValueStoreAdapter} is the default.
- */
-export interface GraphValueStoreAdapter {
-    /** Reads a cached value for the given key. */
-    read(key: GraphValueKey): Promise<GraphCachedValue | undefined>;
-    /** Writes a cached value for the given key. */
-    write(key: GraphValueKey, value: GraphCachedValue): Promise<void>;
-    /** Deletes a cached value for the given key. */
-    delete(key: GraphValueKey): Promise<void>;
-    /** Returns whether a cached value exists for the given key. */
-    has(key: GraphValueKey): Promise<boolean>;
-    /** Lists cached values matching a prefix of the key. */
-    list?(prefix: Partial<GraphValueKey>): Promise<GraphCachedValue[]>;
-    /** Clears all cached values for a run. */
-    clearRun?(runId: string): Promise<void>;
-    /** Reads the runtime values for a node in a run. */
-    readRuntimeValues?(runId: string, nodeId: string): Promise<GraphExecutionValues | undefined>;
-    /** Writes the runtime values for a node in a run. */
-    writeRuntimeValues?(runId: string, nodeId: string, values: GraphExecutionValues): Promise<void>;
-}

package/lib/types/graph/engine/store/InMemoryGraphValueStoreAdapter.d.cts

@@ -1,33 +0,0 @@
-/**
- * @module integrations/graph/store/InMemoryGraphValueStoreAdapter
- * @summary Default in-memory value store adapter.
- * @description Stores all cached values in a Map. Suitable for testing and single-process execution.
- */
-import type { GraphValueStoreAdapter } from "./GraphValueStoreAdapter.d.cts";
-import type { GraphValueKey } from "./GraphValueKey.d.cts";
-import type { GraphCachedValue } from "./GraphCachedValue.d.cts";
-/**
- * In-memory implementation of {@link GraphValueStoreAdapter}.
- *
- * Values are keyed by a serialized string combining namespace, workflowId,
- * nodeId, version, and fingerprint.
- */
-export declare class InMemoryGraphValueStoreAdapter implements GraphValueStoreAdapter {
-    private readonly values;
-    /** @inheritDoc */
-    read(key: GraphValueKey): Promise<GraphCachedValue | undefined>;
-    /** @inheritDoc */
-    write(key: GraphValueKey, value: GraphCachedValue): Promise<void>;
-    /** @inheritDoc */
-    delete(key: GraphValueKey): Promise<void>;
-    /** @inheritDoc */
-    has(key: GraphValueKey): Promise<boolean>;
-    /** @inheritDoc */
-    list(prefix: Partial<GraphValueKey>): Promise<GraphCachedValue[]>;
-    /** @inheritDoc */
-    clearRun(runId: string): Promise<void>;
-    /**
-     * Serializes a key into a stable string used as the Map key.
-     */
-    private serializeKey;
-}

package/lib/types/graph/engine/store/InMemoryGraphValueStoreAdapter.d.mts

@@ -1,33 +0,0 @@
-/**
- * @module integrations/graph/store/InMemoryGraphValueStoreAdapter
- * @summary Default in-memory value store adapter.
- * @description Stores all cached values in a Map. Suitable for testing and single-process execution.
- */
-import type { GraphValueStoreAdapter } from "./GraphValueStoreAdapter.d.mts";
-import type { GraphValueKey } from "./GraphValueKey.d.mts";
-import type { GraphCachedValue } from "./GraphCachedValue.d.mts";
-/**
- * In-memory implementation of {@link GraphValueStoreAdapter}.
- *
- * Values are keyed by a serialized string combining namespace, workflowId,
- * nodeId, version, and fingerprint.
- */
-export declare class InMemoryGraphValueStoreAdapter implements GraphValueStoreAdapter {
-    private readonly values;
-    /** @inheritDoc */
-    read(key: GraphValueKey): Promise<GraphCachedValue | undefined>;
-    /** @inheritDoc */
-    write(key: GraphValueKey, value: GraphCachedValue): Promise<void>;
-    /** @inheritDoc */
-    delete(key: GraphValueKey): Promise<void>;
-    /** @inheritDoc */
-    has(key: GraphValueKey): Promise<boolean>;
-    /** @inheritDoc */
-    list(prefix: Partial<GraphValueKey>): Promise<GraphCachedValue[]>;
-    /** @inheritDoc */
-    clearRun(runId: string): Promise<void>;
-    /**
-     * Serializes a key into a stable string used as the Map key.
-     */
-    private serializeKey;
-}

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

@@ -1,10 +0,0 @@
-/**
- * @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.d.cts";
-export * from "./GraphCachedValue.d.cts";
-export * from "./GraphValueStoreAdapter.d.cts";
-export * from "./InMemoryGraphValueStoreAdapter.d.cts";
-export * from "./GraphValueStore.d.cts";

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

@@ -1,10 +0,0 @@
-/**
- * @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.d.mts";
-export * from "./GraphCachedValue.d.mts";
-export * from "./GraphValueStoreAdapter.d.mts";
-export * from "./InMemoryGraphValueStoreAdapter.d.mts";
-export * from "./GraphValueStore.d.mts";

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

@@ -1,208 +0,0 @@
-/**
- * @module integrations/graph/engine/types
- * @summary Graph execution engine core types.
- * @description Engine-private type aliases and interfaces. Frontend-safe
- * types (`ExprValue`, `ConditionExpression`, `CodeCondition`,
- * `SwitchCaseCondition`, `SwitchCase`, `SwitchNodeMetadata`,
- * `NodeMetadataChange`, `GraphExecutionEvent`, `GraphExecutionErrorPayload`)
- * live in `@decaf-ts/ui-decorators/graph`; engine modules import shared
- * symbols from there and engine-private symbols from here.
- */
-import type { GraphCredentialReference, GraphJsonValue, GraphNodeInstance, GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
-import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionStatus } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionErrorPayload, GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
-/**
- * Unique identifier for a single graph execution run.
- */
-export type GraphRunId = string;
-/**
- * Identifier for a workflow definition.
- */
-export type GraphWorkflowId = string;
-/**
- * Identifier for a node within a workflow.
- */
-export type GraphNodeId = string;
-/**
- * Name of a port on a node or workflow boundary.
- */
-export type GraphPortName = string;
-/**
- * A bag of named values exchanged between nodes and the workflow boundary.
- */
-export type GraphExecutionValues = Record<string, unknown>;
-/**
- * Options that influence a single execution of a workflow.
- */
-export interface GraphExecutionOptions {
-    runId?: GraphRunId;
-    parentRunId?: GraphRunId;
-    workflowId?: GraphWorkflowId;
-    path?: string[];
-    concurrency?: number;
-    failFast?: boolean;
-    validateInputs?: boolean;
-    validateOutputs?: boolean;
-    maxLoopIterations?: number;
-    maxForeachIterations?: number;
-    usePinnedValues?: boolean;
-    writeThroughCache?: boolean;
-    metadata?: Record<string, unknown>;
-    abortSignal?: AbortSignal;
-}
-/**
- * Result of executing a single node.
- */
-export interface GraphNodeExecutionResult {
-    nodeId: GraphNodeId;
-    status: GraphExecutionStatus;
-    inputs: GraphExecutionValues;
-    outputs?: GraphExecutionValues;
-    error?: GraphExecutionErrorPayload;
-    startedAt: Date;
-    finishedAt?: Date;
-    fromCache?: boolean;
-    pinned?: boolean;
-    events: GraphExecutionEvent[];
-}
-/**
- * Result of executing an entire workflow.
- *
- * The executed source of truth is the canonical {@link GraphWorkflowDocument}
- * (never a decorated workflow definition).
- */
-export interface GraphExecutionResult {
-    runId: GraphRunId;
-    parentRunId?: GraphRunId;
-    workflowId: GraphWorkflowId;
-    status: GraphExecutionStatus;
-    document: GraphWorkflowDocument;
-    inputs: GraphExecutionValues;
-    outputs: GraphExecutionValues;
-    nodeResults: Record<GraphNodeId, GraphNodeExecutionResult>;
-    events: GraphExecutionEvent[];
-    startedAt: Date;
-    finishedAt?: Date;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Credential references resolved for a node execution (DECAF-50 §4.9/§4.16).
- * Documents carry references only; secret material never enters the request.
- */
-export type GraphResolvedCredentials = Record<string, GraphCredentialReference>;
-/**
- * Request passed to request-based node executors (DECAF-50 §4.9).
- * Configuration (`parameters`, `credentials`, `metadata`) and input data
- * (`inputs`) are separated.
- */
-export interface GraphNodeExecutionRequest {
-    nodeId: string;
-    kind: string;
-    inputs: GraphExecutionValues;
-    parameters: Record<string, GraphJsonValue>;
-    credentials: GraphResolvedCredentials;
-    metadata?: Record<string, GraphJsonValue>;
-}
-/**
- * Options used to construct a {@link GraphExecutionContext}.
- */
-export interface GraphExecutionContextOptions {
-    runId: GraphRunId;
-    parentRunId?: GraphRunId;
-    workflowId: GraphWorkflowId;
-    document: GraphWorkflowDocument;
-    node: GraphNodeInstance;
-    manifest: GraphResolvedNodeManifest;
-    path: string[];
-    metadata?: Record<string, unknown>;
-}
-/**
- * Metadata describing a loop node's behaviour.
- */
-export interface GraphLoopMetadata {
-    /** The nested loop-body workflow document (DECAF-50 §4.9). */
-    body: GraphWorkflowDocument;
-    maxIterations?: number;
-    timeoutMs?: number;
-    condition?: GraphConditionDefinition;
-    concurrency?: number;
-    inputPort?: string;
-    outputPort?: string;
-    itemPort?: string;
-    resultPort?: string;
-    statePort?: string;
-    /**
-     * How many items are taken from the input list per iteration (foreach only).
-     * Default `1`. When greater than `1`, the body receives a slice (array) on
-     * the item port and the collected result is one entry per slice.
-     */
-    slice?: number;
-}
-/**
- * Definition of a condition evaluated by the loop condition evaluator.
- *
- * When the condition object carries an `op` field (see {@link ConditionExpression}),
- * the {@link GraphConditionEvaluator} dispatches to the {@link ConditionExpressionEvaluator}
- * instead of the built-in `type`-based switch.
- */
-export interface GraphConditionDefinition {
-    type: "truthy" | "falsy" | "equals" | "notEquals" | "greaterThan" | "greaterThanOrEqual" | "lessThan" | "lessThanOrEqual" | "exists" | "custom";
-    left?: string;
-    right?: unknown;
-    evaluator?: string;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Pinning metadata attached to a node via `@pinnable()`.
- */
-export interface GraphPinningMetadata {
-    enabled: boolean;
-    ttlMs?: number;
-    strategy: "manual" | "automatic" | "disabled";
-    includeDependencies: boolean;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Options for pinning a node after a completed run.
- */
-export interface GraphPinNodeOptions {
-    document: GraphWorkflowDocument;
-    plan: unknown;
-    result: GraphExecutionResult;
-    nodeId: string;
-    includeDependencies?: boolean;
-    namespace?: string;
-}
-/**
- * Options for unpinning a node.
- */
-export interface GraphUnpinNodeOptions {
-    document: GraphWorkflowDocument;
-    nodeId: string;
-    fingerprint: string;
-    namespace?: string;
-}
-/**
- * A patch applied to a graph workflow snapshot after execution.
- */
-export interface GraphExecutionSnapshotPatch {
-    runId: string;
-    status: GraphExecutionStatus;
-    nodes: Record<string, {
-        status: GraphExecutionStatus;
-        startedAt?: string;
-        finishedAt?: string;
-        error?: GraphExecutionErrorPayload;
-        outputs?: Record<string, unknown>;
-        fromCache?: boolean;
-        pinned?: boolean;
-    }>;
-    edges: Record<string, {
-        status: GraphExecutionStatus;
-        lastValue?: unknown;
-        updatedAt: string;
-    }>;
-    outputs: Record<string, unknown>;
-    events: GraphExecutionEvent[];
-}