@decaf-ts/integrations 0.10.8 → 0.11.0

package/lib/types/graph/engine/errors/GraphBreakSignal.d.mts

@@ -1,28 +0,0 @@
-/**
- * @module integrations/graph/errors/GraphBreakSignal
- * @summary Control-flow signal used by `core.flow.break` to exit a loop early.
- * @description Thrown by the Break node executor and caught by the enclosing
- * loop executor (`core.loop.foreach`, `core.loop.while`, `core.loop.until`).
- * Unlike a real error, a break signal is a cooperative control-flow token: it
- * is NOT propagated as a workflow failure. When caught, the loop terminates
- * early and returns the results collected so far (plus the optional `value`
- * carried by the signal as the final partial result).
- */
-import { GraphExecutionError } from "./GraphExecutionError.d.mts";
-/**
- * Control-flow signal thrown by `core.flow.break` nodes.
- *
- * Extends {@link GraphExecutionError} so it rides on the existing error
- * pipeline, but carries the `graphCode` `"GRAPH_BREAK_SIGNAL"` and the flag
- * `isBreakSignal = true` so loop executors can distinguish it from a genuine
- * execution failure via `instanceof` or the flag.
- */
-export declare class GraphBreakSignal extends GraphExecutionError {
-    /** Distinguishes a break signal from a genuine error without `instanceof`. */
-    readonly isBreakSignal = true;
-    /**
-     * @param value - Optional value forwarded by the Break node. The enclosing
-     *   loop appends this to the collected results as the last partial result.
-     */
-    constructor(value?: unknown);
-}

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

@@ -1,12 +0,0 @@
-/**
- * @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/engine/errors/GraphCycleError.d.mts

@@ -1,12 +0,0 @@
-/**
- * @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/engine/errors/GraphExecutionError.d.cts

@@ -1,19 +0,0 @@
-/**
- * @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/engine/errors/GraphExecutionError.d.mts

@@ -1,19 +0,0 @@
-/**
- * @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/engine/errors/GraphInputError.d.cts

@@ -1,12 +0,0 @@
-/**
- * @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);
-}

package/lib/types/graph/engine/errors/GraphInputError.d.mts

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

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

@@ -1,12 +0,0 @@
-/**
- * @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.d.cts";
-/**
- * Thrown when a loop exceeds its maximum iterations.
- */
-export declare class GraphLoopLimitError extends GraphExecutionError {
-    constructor(message: string, details?: unknown);
-}

package/lib/types/graph/engine/errors/GraphLoopLimitError.d.mts

@@ -1,12 +0,0 @@
-/**
- * @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.d.mts";
-/**
- * Thrown when a loop exceeds its maximum iterations.
- */
-export declare class GraphLoopLimitError extends GraphExecutionError {
-    constructor(message: string, details?: unknown);
-}

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

@@ -1,12 +0,0 @@
-/**
- * @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.d.cts";
-/**
- * Thrown when a pinning operation fails.
- */
-export declare class GraphPinningError extends GraphExecutionError {
-    constructor(message: string, details?: unknown);
-}

package/lib/types/graph/engine/errors/GraphPinningError.d.mts

@@ -1,12 +0,0 @@
-/**
- * @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.d.mts";
-/**
- * Thrown when a pinning operation fails.
- */
-export declare class GraphPinningError extends GraphExecutionError {
-    constructor(message: string, details?: unknown);
-}

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

@@ -1,12 +0,0 @@
-/**
- * @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.d.cts";
-/**
- * Thrown when a port reference is invalid.
- */
-export declare class GraphPortError extends GraphExecutionError {
-    constructor(message: string, details?: unknown);
-}

package/lib/types/graph/engine/errors/GraphPortError.d.mts

@@ -1,12 +0,0 @@
-/**
- * @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.d.mts";
-/**
- * Thrown when a port reference is invalid.
- */
-export declare class GraphPortError extends GraphExecutionError {
-    constructor(message: string, details?: unknown);
-}

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

@@ -1,9 +0,0 @@
-import { GraphExecutionError } from "./GraphExecutionError.d.cts";
-/**
- * Thrown when a graph run is cancelled before completion: carries the run id
- * under the `GRAPH_RUN_CANCELLED` code so run lifecycle bookkeeping can
- * distinguish cancellation from failure.
- */
-export declare class GraphRunCancelledError extends GraphExecutionError {
-    constructor(runId: string);
-}

package/lib/types/graph/engine/errors/GraphRunCancelledError.d.mts

@@ -1,9 +0,0 @@
-import { GraphExecutionError } from "./GraphExecutionError.d.mts";
-/**
- * Thrown when a graph run is cancelled before completion: carries the run id
- * under the `GRAPH_RUN_CANCELLED` code so run lifecycle bookkeeping can
- * distinguish cancellation from failure.
- */
-export declare class GraphRunCancelledError extends GraphExecutionError {
-    constructor(runId: string);
-}

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

@@ -1,12 +0,0 @@
-/**
- * @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.d.cts";
-/**
- * Thrown when a value store operation fails.
- */
-export declare class GraphStoreError extends GraphExecutionError {
-    constructor(message: string, details?: unknown);
-}

package/lib/types/graph/engine/errors/GraphStoreError.d.mts

@@ -1,12 +0,0 @@
-/**
- * @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.d.mts";
-/**
- * Thrown when a value store operation fails.
- */
-export declare class GraphStoreError extends GraphExecutionError {
-    constructor(message: string, details?: unknown);
-}

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

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

package/lib/types/graph/engine/errors/GraphTopologyError.d.mts

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

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

@@ -1,15 +0,0 @@
-/**
- * @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.d.cts";
-export * from "./GraphCycleError.d.cts";
-export * from "./GraphInputError.d.cts";
-export * from "./GraphLoopLimitError.d.cts";
-export * from "./GraphPinningError.d.cts";
-export * from "./GraphPortError.d.cts";
-export * from "./GraphStoreError.d.cts";
-export * from "./GraphTopologyError.d.cts";
-export * from "./GraphBreakSignal.d.cts";
-export * from "./GraphRunCancelledError.d.cts";

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

@@ -1,15 +0,0 @@
-/**
- * @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.d.mts";
-export * from "./GraphCycleError.d.mts";
-export * from "./GraphInputError.d.mts";
-export * from "./GraphLoopLimitError.d.mts";
-export * from "./GraphPinningError.d.mts";
-export * from "./GraphPortError.d.mts";
-export * from "./GraphStoreError.d.mts";
-export * from "./GraphTopologyError.d.mts";
-export * from "./GraphBreakSignal.d.mts";
-export * from "./GraphRunCancelledError.d.mts";

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

@@ -1,26 +0,0 @@
-/**
- * @module integrations/graph/events/GraphExecutionEventEmitter
- * @summary Observable implementation for graph execution events.
- * @description Implements Decaf's {@link Observable} interface so observers can subscribe to graph execution events. Observer failures are isolated and do not crash the workflow.
- */
-import type { Observable } from "@decaf-ts/core";
-import type { GraphExecutionObserver } from "./GraphExecutionObserver.d.cts";
-import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
-/**
- * Manages observer registration and event dispatch for the graph execution
- * engine.
- */
-export declare class GraphExecutionEventEmitter implements Observable<[GraphExecutionObserver], [GraphExecutionEvent]> {
-    private readonly observers;
-    /** Registers an observer and returns an unsubscribe function. */
-    observe(observer: GraphExecutionObserver): () => void;
-    /** Removes a previously-registered observer. */
-    unObserve(observer: GraphExecutionObserver): void;
-    /**
-     * Notifies all registered observers of a new event.
-     *
-     * Observer failures are caught and swallowed so that a misbehaving observer
-     * cannot crash the workflow execution.
-     */
-    updateObservers(event: GraphExecutionEvent): Promise<void>;
-}

package/lib/types/graph/engine/events/GraphExecutionEventEmitter.d.mts

@@ -1,26 +0,0 @@
-/**
- * @module integrations/graph/events/GraphExecutionEventEmitter
- * @summary Observable implementation for graph execution events.
- * @description Implements Decaf's {@link Observable} interface so observers can subscribe to graph execution events. Observer failures are isolated and do not crash the workflow.
- */
-import type { Observable } from "@decaf-ts/core";
-import type { GraphExecutionObserver } from "./GraphExecutionObserver.d.mts";
-import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
-/**
- * Manages observer registration and event dispatch for the graph execution
- * engine.
- */
-export declare class GraphExecutionEventEmitter implements Observable<[GraphExecutionObserver], [GraphExecutionEvent]> {
-    private readonly observers;
-    /** Registers an observer and returns an unsubscribe function. */
-    observe(observer: GraphExecutionObserver): () => void;
-    /** Removes a previously-registered observer. */
-    unObserve(observer: GraphExecutionObserver): void;
-    /**
-     * Notifies all registered observers of a new event.
-     *
-     * Observer failures are caught and swallowed so that a misbehaving observer
-     * cannot crash the workflow execution.
-     */
-    updateObservers(event: GraphExecutionEvent): Promise<void>;
-}

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

@@ -1,25 +0,0 @@
-/**
- * @module integrations/graph/events/GraphExecutionEventFactory
- * @summary Factory for creating graph execution events with unique ids, sequence numbers, and timestamps.
- * @description Provides a stateful factory that produces monotonically-sequenced events for a single execution run.
- */
-import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
-/**
- * Factory that enriches partial events with a unique id, an incrementing
- * sequence number, and a timestamp.
- */
-export declare class GraphExecutionEventFactory {
-    private sequence;
-    /**
-     * 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: Omit<GraphExecutionEvent, "id" | "sequence" | "timestamp">): GraphExecutionEvent;
-    /**
-     * Generates a unique event id using `crypto.randomUUID` when available,
-     * falling back to a timestamp + random string.
-     */
-    private createEventId;
-}

package/lib/types/graph/engine/events/GraphExecutionEventFactory.d.mts

@@ -1,25 +0,0 @@
-/**
- * @module integrations/graph/events/GraphExecutionEventFactory
- * @summary Factory for creating graph execution events with unique ids, sequence numbers, and timestamps.
- * @description Provides a stateful factory that produces monotonically-sequenced events for a single execution run.
- */
-import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
-/**
- * Factory that enriches partial events with a unique id, an incrementing
- * sequence number, and a timestamp.
- */
-export declare class GraphExecutionEventFactory {
-    private sequence;
-    /**
-     * 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: Omit<GraphExecutionEvent, "id" | "sequence" | "timestamp">): GraphExecutionEvent;
-    /**
-     * Generates a unique event id using `crypto.randomUUID` when available,
-     * falling back to a timestamp + random string.
-     */
-    private createEventId;
-}

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

@@ -1,17 +0,0 @@
-/**
- * @module integrations/graph/events/GraphExecutionObserver
- * @summary Observer interface for graph execution events.
- * @description Extends Decaf's {@link Observer} so graph events flow through the standard Observable/Observer pipeline.
- */
-import type { Observer } from "@decaf-ts/core";
-import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
-/**
- * Observer that receives {@link GraphExecutionEvent} instances from the
- * graph execution engine.
- */
-export interface GraphExecutionObserver extends Observer<[GraphExecutionEvent]> {
-    /**
-     * Called by the engine when a new graph execution event is emitted.
-     */
-    refresh(event: GraphExecutionEvent): Promise<void>;
-}

package/lib/types/graph/engine/events/GraphExecutionObserver.d.mts

@@ -1,17 +0,0 @@
-/**
- * @module integrations/graph/events/GraphExecutionObserver
- * @summary Observer interface for graph execution events.
- * @description Extends Decaf's {@link Observer} so graph events flow through the standard Observable/Observer pipeline.
- */
-import type { Observer } from "@decaf-ts/core";
-import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
-/**
- * Observer that receives {@link GraphExecutionEvent} instances from the
- * graph execution engine.
- */
-export interface GraphExecutionObserver extends Observer<[GraphExecutionEvent]> {
-    /**
-     * Called by the engine when a new graph execution event is emitted.
-     */
-    refresh(event: GraphExecutionEvent): Promise<void>;
-}

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

@@ -1,8 +0,0 @@
-/**
- * @module integrations/graph/events
- * @summary Graph execution event pipeline.
- * @description Re-exports the observer interface, event emitter, and event factory.
- */
-export * from "./GraphExecutionObserver.d.cts";
-export * from "./GraphExecutionEventEmitter.d.cts";
-export * from "./GraphExecutionEventFactory.d.cts";

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

@@ -1,8 +0,0 @@
-/**
- * @module integrations/graph/events
- * @summary Graph execution event pipeline.
- * @description Re-exports the observer interface, event emitter, and event factory.
- */
-export * from "./GraphExecutionObserver.d.mts";
-export * from "./GraphExecutionEventEmitter.d.mts";
-export * from "./GraphExecutionEventFactory.d.mts";

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

@@ -1,76 +0,0 @@
-/**
- * @module integrations/graph/execution/CodeSandboxEvaluator
- * @summary Pluggable contract for evaluating code-based conditions (DECAF-32 §22.4).
- * @description The engine does NOT implement the VM sandbox directly (§22.4).
- * Downstream projects (e.g. ALFRED) register a `CodeSandboxEvaluator` via the
- * `GraphExecutionEngineConfig.codeSandboxEvaluator` field. When absent, code
- * conditions throw a `GRAPH_CODE_SANDBOX_NOT_CONFIGURED` error.
- *
- * The sandbox must follow the same restrictions as the Code Node (§22.4):
- * - No system API access (`require`, `process`, `fs`, `child_process`, etc.)
- * - Placeholder syntax for workflow data references (`{{ $input.foo }}`,
- *   `{{ $node["Name"].output }}`, `{{ $vars.bar }}`, etc.)
- * - Static code validation (e.g. `acorn`-based) before execution
- * - The code must return a boolean value (for conditions) or any value
- *   (for Code Node transforms)
- */
-/**
- * Context passed to the code sandbox evaluator.
- */
-export interface CodeSandboxContext {
-    /** The raw code string authored by the user. */
-    code: string;
-    /** The programming language (defaults to `"javascript"`). */
-    language?: "javascript" | "typescript";
-    /** The current input values, accessible as `$input` in placeholders. */
-    input: Record<string, unknown>;
-    /** Workflow variables, accessible as `$vars` in placeholders. */
-    vars?: Record<string, unknown>;
-    /** Current loop item (if inside a foreach), accessible as `$item`. */
-    item?: unknown;
-    /** Current loop index (if inside a foreach), accessible as `$index`. */
-    index?: number;
-    /** Outputs of upstream nodes, accessible as `$node["Name"].output`. */
-    nodes?: Record<string, Record<string, unknown>>;
-    /**
-     * Optional logger that receives `console.log/warn/debug/error` calls from
-     * inside the sandbox. When provided, a `console` object is injected into
-     * the isolate whose methods forward to this logger.
-     */
-    logger?: SandboxLogger;
-}
-/**
- * Minimal logger interface the sandbox can call without importing the full
- * Decaf logging package (keeps the interface frontend-safe). Mirrors the
- * methods on `@decaf-ts/logging`'s `Logger`.
- */
-export interface SandboxLogger {
-    benchmark(msg: string, meta?: unknown): void;
-    fatal(msg: string, meta?: unknown): void;
-    critical(msg: string, meta?: unknown): void;
-    silly(msg: string, meta?: unknown): void;
-    verbose(msg: string, meta?: unknown): void;
-    info(msg: string, meta?: unknown): void;
-    debug(msg: string, meta?: unknown): void;
-    error(msg: string, meta?: unknown): void;
-    warn(msg: string, meta?: unknown): void;
-    trace(msg: string, meta?: unknown): void;
-}
-/**
- * Pluggable evaluator for code-based conditions and Code Node transforms.
- *
- * Implementations MUST enforce the Code Node restrictions (§22.4):
- * no system API access, static validation, placeholder resolution.
- */
-export interface CodeSandboxEvaluator {
-    /**
-     * Evaluates the given code in a restricted sandbox and returns the result.
-     *
-     * For conditions, the code is expected to return a boolean.
-     * For Code Node transforms, the code may return any value.
-     *
-     * @param ctx - The sandbox context containing code, input, and references.
-     * @returns The result of evaluating the code.
-     */
-    evaluate(ctx: CodeSandboxContext): Promise<unknown> | unknown;
-}

package/lib/types/graph/engine/execution/CodeSandboxEvaluator.d.mts

@@ -1,76 +0,0 @@
-/**
- * @module integrations/graph/execution/CodeSandboxEvaluator
- * @summary Pluggable contract for evaluating code-based conditions (DECAF-32 §22.4).
- * @description The engine does NOT implement the VM sandbox directly (§22.4).
- * Downstream projects (e.g. ALFRED) register a `CodeSandboxEvaluator` via the
- * `GraphExecutionEngineConfig.codeSandboxEvaluator` field. When absent, code
- * conditions throw a `GRAPH_CODE_SANDBOX_NOT_CONFIGURED` error.
- *
- * The sandbox must follow the same restrictions as the Code Node (§22.4):
- * - No system API access (`require`, `process`, `fs`, `child_process`, etc.)
- * - Placeholder syntax for workflow data references (`{{ $input.foo }}`,
- *   `{{ $node["Name"].output }}`, `{{ $vars.bar }}`, etc.)
- * - Static code validation (e.g. `acorn`-based) before execution
- * - The code must return a boolean value (for conditions) or any value
- *   (for Code Node transforms)
- */
-/**
- * Context passed to the code sandbox evaluator.
- */
-export interface CodeSandboxContext {
-    /** The raw code string authored by the user. */
-    code: string;
-    /** The programming language (defaults to `"javascript"`). */
-    language?: "javascript" | "typescript";
-    /** The current input values, accessible as `$input` in placeholders. */
-    input: Record<string, unknown>;
-    /** Workflow variables, accessible as `$vars` in placeholders. */
-    vars?: Record<string, unknown>;
-    /** Current loop item (if inside a foreach), accessible as `$item`. */
-    item?: unknown;
-    /** Current loop index (if inside a foreach), accessible as `$index`. */
-    index?: number;
-    /** Outputs of upstream nodes, accessible as `$node["Name"].output`. */
-    nodes?: Record<string, Record<string, unknown>>;
-    /**
-     * Optional logger that receives `console.log/warn/debug/error` calls from
-     * inside the sandbox. When provided, a `console` object is injected into
-     * the isolate whose methods forward to this logger.
-     */
-    logger?: SandboxLogger;
-}
-/**
- * Minimal logger interface the sandbox can call without importing the full
- * Decaf logging package (keeps the interface frontend-safe). Mirrors the
- * methods on `@decaf-ts/logging`'s `Logger`.
- */
-export interface SandboxLogger {
-    benchmark(msg: string, meta?: unknown): void;
-    fatal(msg: string, meta?: unknown): void;
-    critical(msg: string, meta?: unknown): void;
-    silly(msg: string, meta?: unknown): void;
-    verbose(msg: string, meta?: unknown): void;
-    info(msg: string, meta?: unknown): void;
-    debug(msg: string, meta?: unknown): void;
-    error(msg: string, meta?: unknown): void;
-    warn(msg: string, meta?: unknown): void;
-    trace(msg: string, meta?: unknown): void;
-}
-/**
- * Pluggable evaluator for code-based conditions and Code Node transforms.
- *
- * Implementations MUST enforce the Code Node restrictions (§22.4):
- * no system API access, static validation, placeholder resolution.
- */
-export interface CodeSandboxEvaluator {
-    /**
-     * Evaluates the given code in a restricted sandbox and returns the result.
-     *
-     * For conditions, the code is expected to return a boolean.
-     * For Code Node transforms, the code may return any value.
-     *
-     * @param ctx - The sandbox context containing code, input, and references.
-     * @returns The result of evaluating the code.
-     */
-    evaluate(ctx: CodeSandboxContext): Promise<unknown> | unknown;
-}