@decaf-ts/integrations 0.10.8 → 0.11.0

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

@@ -1,79 +0,0 @@
-/**
- * @module integrations/graph/execution/GraphExecutionContext
- * @summary Decaf Context for graph node execution (DECAF-50 §4.9).
- * @description Extends Decaf's {@link Context} so node executors receive the
- * same contextual plumbing as task handlers. The context carries the
- * canonical workflow document, the executing node's canonical instance, and
- * its effective resolved manifest — never a raw node definition. Executors
- * use the context to emit progress, log messages, and report state through
- * the engine's observer pipeline. Each context also exposes a run-scoped
- * `ctx.logger` (DECAF-48 §4.3) bound to the executing node's `runId` /
- * `workflowId` / `nodeId` / `user`, so every log line streams over
- * `graph.run.log` with the DECAF-9 custom attributes.
- */
-import { Context } from "@decaf-ts/core";
-import type { GraphNodeInstance, GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
-import type { Logger } from "@decaf-ts/logging";
-import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
-import type { GraphRunId } from "../types.d.cts";
-import type { GraphExecutionEngine } from "./GraphExecutionEngine.d.cts";
-/**
- * Context passed to every graph node executor.
- *
- * The engine creates a `GraphExecutionContext` per node execution and passes
- * it to the executor alongside the node's inputs/parameters. The executor
- * uses `context.progress(...)` and `context.log(...)` to report intermediate
- * state, and `context.logger` to emit structured run log lines (DECAF-48
- * §4.3).
- */
-export declare class GraphExecutionContext extends Context {
-    readonly runId: GraphRunId;
-    readonly parentRunId: GraphRunId | undefined;
-    readonly workflowId: string;
-    readonly document: GraphWorkflowDocument;
-    readonly node: GraphNodeInstance;
-    readonly manifest: GraphResolvedNodeManifest;
-    readonly path: string[];
-    private readonly emitFn;
-    readonly metadata: Record<string, unknown>;
-    readonly engine?: GraphExecutionEngine | undefined;
-    private readonly runLogger?;
-    /**
-     * @param runId - Unique identifier for the current execution run.
-     * @param parentRunId - Run id of the parent execution (for nested loop bodies).
-     * @param workflowId - The canonical workflow document id.
-     * @param document - The canonical workflow document being executed.
-     * @param node - The canonical node instance being executed.
-     * @param manifest - The effective (dynamics-expanded) manifest for the node.
-     * @param path - Dotted path from the workflow root to this node.
-     * @param emitFn - Callback invoked when an event is emitted from this context.
-     * @param metadata - Free-form metadata attached to this context.
-     * @param engine - The owning execution engine, exposed to node classes
-     *   whose `execute` needs engine-level services (nested workflow
-     *   execution, code sandbox evaluation).
-     */
-    constructor(runId: GraphRunId, parentRunId: GraphRunId | undefined, workflowId: string, document: GraphWorkflowDocument, node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, path: string[], emitFn: (event: Partial<GraphExecutionEvent>) => Promise<void>, metadata?: Record<string, unknown>, engine?: GraphExecutionEngine | undefined);
-    /**
-     * The decaf-ts {@link Logger} bound to this node's run context. Every log
-     * line carries the DECAF-48 attributes (`nodeId` / `workflowId` / `runId` /
-     * `user`) and is forwarded onto the existing graph execution Observable as
-     * a `GRAPH_RUN_LOG` event (streamed over the `graph.run.log` SSE channel).
-     */
-    get logger(): Logger;
-    /**
-     * Emits a partial graph execution event. The engine fills in runId,
-     * parentRunId, workflowId, nodeId, and path automatically.
-     */
-    emit(event: Partial<GraphExecutionEvent>): Promise<void>;
-    /**
-     * Emits a `NODE_OUTPUT` event with the given payload, useful for reporting
-     * intermediate progress from within a node executor.
-     */
-    progress(payload: unknown): Promise<void>;
-    /**
-     * Emits a `NODE_OUTPUT` event with a structured `{ message, payload }` shape
-     * so executors can log human-readable messages.
-     */
-    log(message: string, payload?: unknown): Promise<void>;
-}

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

@@ -1,79 +0,0 @@
-/**
- * @module integrations/graph/execution/GraphExecutionContext
- * @summary Decaf Context for graph node execution (DECAF-50 §4.9).
- * @description Extends Decaf's {@link Context} so node executors receive the
- * same contextual plumbing as task handlers. The context carries the
- * canonical workflow document, the executing node's canonical instance, and
- * its effective resolved manifest — never a raw node definition. Executors
- * use the context to emit progress, log messages, and report state through
- * the engine's observer pipeline. Each context also exposes a run-scoped
- * `ctx.logger` (DECAF-48 §4.3) bound to the executing node's `runId` /
- * `workflowId` / `nodeId` / `user`, so every log line streams over
- * `graph.run.log` with the DECAF-9 custom attributes.
- */
-import { Context } from "@decaf-ts/core";
-import type { GraphNodeInstance, GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
-import type { Logger } from "@decaf-ts/logging";
-import type { GraphResolvedNodeManifest } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
-import type { GraphRunId } from "../types.d.mts";
-import type { GraphExecutionEngine } from "./GraphExecutionEngine.d.mts";
-/**
- * Context passed to every graph node executor.
- *
- * The engine creates a `GraphExecutionContext` per node execution and passes
- * it to the executor alongside the node's inputs/parameters. The executor
- * uses `context.progress(...)` and `context.log(...)` to report intermediate
- * state, and `context.logger` to emit structured run log lines (DECAF-48
- * §4.3).
- */
-export declare class GraphExecutionContext extends Context {
-    readonly runId: GraphRunId;
-    readonly parentRunId: GraphRunId | undefined;
-    readonly workflowId: string;
-    readonly document: GraphWorkflowDocument;
-    readonly node: GraphNodeInstance;
-    readonly manifest: GraphResolvedNodeManifest;
-    readonly path: string[];
-    private readonly emitFn;
-    readonly metadata: Record<string, unknown>;
-    readonly engine?: GraphExecutionEngine | undefined;
-    private readonly runLogger?;
-    /**
-     * @param runId - Unique identifier for the current execution run.
-     * @param parentRunId - Run id of the parent execution (for nested loop bodies).
-     * @param workflowId - The canonical workflow document id.
-     * @param document - The canonical workflow document being executed.
-     * @param node - The canonical node instance being executed.
-     * @param manifest - The effective (dynamics-expanded) manifest for the node.
-     * @param path - Dotted path from the workflow root to this node.
-     * @param emitFn - Callback invoked when an event is emitted from this context.
-     * @param metadata - Free-form metadata attached to this context.
-     * @param engine - The owning execution engine, exposed to node classes
-     *   whose `execute` needs engine-level services (nested workflow
-     *   execution, code sandbox evaluation).
-     */
-    constructor(runId: GraphRunId, parentRunId: GraphRunId | undefined, workflowId: string, document: GraphWorkflowDocument, node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, path: string[], emitFn: (event: Partial<GraphExecutionEvent>) => Promise<void>, metadata?: Record<string, unknown>, engine?: GraphExecutionEngine | undefined);
-    /**
-     * The decaf-ts {@link Logger} bound to this node's run context. Every log
-     * line carries the DECAF-48 attributes (`nodeId` / `workflowId` / `runId` /
-     * `user`) and is forwarded onto the existing graph execution Observable as
-     * a `GRAPH_RUN_LOG` event (streamed over the `graph.run.log` SSE channel).
-     */
-    get logger(): Logger;
-    /**
-     * Emits a partial graph execution event. The engine fills in runId,
-     * parentRunId, workflowId, nodeId, and path automatically.
-     */
-    emit(event: Partial<GraphExecutionEvent>): Promise<void>;
-    /**
-     * Emits a `NODE_OUTPUT` event with the given payload, useful for reporting
-     * intermediate progress from within a node executor.
-     */
-    progress(payload: unknown): Promise<void>;
-    /**
-     * Emits a `NODE_OUTPUT` event with a structured `{ message, payload }` shape
-     * so executors can log human-readable messages.
-     */
-    log(message: string, payload?: unknown): Promise<void>;
-}

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

@@ -1,278 +0,0 @@
-/**
- * @module integrations/graph/execution/GraphExecutionEngine
- * @summary Reference graph execution engine (DECAF-50 §4.9).
- * @description Executes canonical {@link GraphWorkflowDocument}s. The public
- * `execute(document, inputs, options)` entrypoint performs resolution
- * internally: the document runs through the nine-stage §4.8 validation gate
- * (structured issue accumulation), is resolved against the trusted backend
- * catalogue into a {@link GraphResolvedWorkflow}, planned by the
- * {@link GraphExecutionPlanner} (resolved workflows only — never raw
- * definitions), and executed layer by layer. Node inputs are built from
- * routed edges, literal bindings, allowed expressions, manifest defaults,
- * and node parameters; configuration and input data are separated in the
- * {@link GraphNodeExecutionRequest}. Executor outputs are validated against
- * the effective output manifest. Disabled nodes follow the explicit
- * {@link GraphDisabledNodeBehavior} semantics. Events are emitted through
- * Decaf's Observable pipeline, including the DECAF-48 §4.4 visual-state
- * events and the `graph.run.log` run-log channel.
- */
-import type { Observable } from "@decaf-ts/core";
-import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionOptions, GraphExecutionResult, GraphExecutionValues, GraphPinNodeOptions, GraphUnpinNodeOptions } from "../types.d.cts";
-import type { GraphExecutionObserver } from "../events/GraphExecutionObserver.d.cts";
-import { GraphExecutionEventEmitter } from "../events/GraphExecutionEventEmitter.d.cts";
-import type { GraphNodeExecutorRegistry } from "../registry/GraphNodeExecutorRegistry.d.cts";
-import type { GraphNodeCatalogue } from "../catalog/GraphNodeCatalogue.d.cts";
-import { GraphExecutionPlanner } from "../planning/GraphExecutionPlanner.d.cts";
-import { GraphWorkflowDocumentValidator, type GraphWorkflowDocumentValidationLimits } from "../validation/GraphWorkflowDocumentValidator.d.cts";
-import type { GraphCredentialAuthorizer } from "../validation/GraphCredentialReferenceValidator.d.cts";
-import type { GraphValueStoreAdapter } from "../store/GraphValueStoreAdapter.d.cts";
-import type { CodeSandboxEvaluator } from "./CodeSandboxEvaluator.d.cts";
-/**
- * Configuration for the {@link GraphExecutionEngine}.
- */
-export interface GraphExecutionEngineConfig {
-    registry: GraphNodeExecutorRegistry;
-    /**
-     * Trusted backend kind catalogue. Defaults to the registry facade's
-     * catalogue; required for the nine-stage document validation gate.
-     */
-    catalogue?: GraphNodeCatalogue;
-    /** Optional pre-configured document validator (overrides catalogue/limits). */
-    documentValidator?: GraphWorkflowDocumentValidator;
-    /** Backend-enforced document resource limits (§4.8 stage 1). */
-    documentLimits?: GraphWorkflowDocumentValidationLimits;
-    /** Pluggable credential existence/authorization hook (§4.8 stage 8). */
-    credentialAuthorizer?: GraphCredentialAuthorizer;
-    planner?: GraphExecutionPlanner;
-    valueStoreAdapter?: GraphValueStoreAdapter;
-    eventEmitter?: GraphExecutionEventEmitter;
-    defaultOptions?: Partial<GraphExecutionOptions>;
-    /**
-     * Optional pluggable code sandbox evaluator for code-based conditions and
-     * expression bindings (DECAF-32 §22.4). When absent, code conditions and
-     * expression bindings throw `GRAPH_CODE_SANDBOX_NOT_CONFIGURED`.
-     * Downstream projects (e.g. ALFRED) supply the actual VM sandbox
-     * implementation.
-     */
-    codeSandboxEvaluator?: CodeSandboxEvaluator;
-    /**
-     * Optional callback invoked at the end of engine construction with the
-     * fully-initialised engine instance. Use this to register executors that
-     * need a back-reference to the engine (e.g. loop executors that execute
-     * sub-workflows through the same engine).
-     */
-    onEngineCreated?: (engine: GraphExecutionEngine) => void;
-}
-/**
- * Reference graph execution engine.
- *
- * Executes a canonical {@link GraphWorkflowDocument} by:
- * 1. Validating it through the nine-stage gate and resolving it against the
- *    backend catalogue (§4.8).
- * 2. Planning the resolved workflow into topological layers (§4.9).
- * 3. Seeding workflow inputs into the value store.
- * 4. Executing nodes layer-by-layer with configurable concurrency, honouring
- *    disabled-node semantics.
- * 5. Building node inputs from routed edges, literal bindings, allowed
- *    expressions, and manifest defaults; keeping configuration (parameters,
- *    credentials) separate from input data.
- * 6. Validating executor outputs against the effective output manifest.
- * 7. Routing values along data edges.
- * 8. Emitting structured events through Decaf's Observable pipeline.
- * 9. Returning a complete {@link GraphExecutionResult}.
- */
-export declare class GraphExecutionEngine implements Observable<[GraphExecutionObserver], [GraphExecutionEvent]> {
-    private readonly emitter;
-    private readonly planner;
-    private readonly valueStoreAdapter;
-    private readonly defaultOptions;
-    private readonly documentValidator;
-    /** Pluggable code sandbox evaluator (§22.4); may be undefined. */
-    readonly codeSandboxEvaluator?: CodeSandboxEvaluator;
-    constructor(config: GraphExecutionEngineConfig);
-    private readonly config;
-    /**
-     * Registers an observer on the engine's event pipeline.
-     *
-     * @param observer - The observer to register.
-     * @returns An unsubscribe function that removes the observer.
-     */
-    observe(observer: GraphExecutionObserver): () => void;
-    /**
-     * Unregisters an observer from the engine's event pipeline.
-     *
-     * @param observer - The observer to remove.
-     */
-    unObserve(observer: GraphExecutionObserver): void;
-    /**
-     * Dispatches an event to all registered observers.
-     *
-     * @param event - The event to distribute.
-     */
-    updateObservers(event: GraphExecutionEvent): Promise<void>;
-    /**
-     * Executes a canonical workflow document with the given inputs and options.
-     *
-     * Resolution happens internally (DECAF-50 §4.9): the document is validated
-     * through the nine-stage gate and resolved against the backend catalogue
-     * before planning. Decorated `GraphWorkflowDefinition` objects are NOT
-     * accepted — compile them with the §4.18 transition compiler first.
-     *
-     * @param document - The canonical workflow document to execute.
-     * @param inputs - Workflow input values keyed by input port id.
-     * @param options - Optional execution overrides (merged over the defaults).
-     * @returns The complete execution result, including a `runId`, per-node
-     *   results, and workflow outputs (or the failure payload).
-     * @throws {GraphDocumentValidationError} when the document fails the
-     *   nine-stage validation gate (carries every structured issue).
-     */
-    execute(document: GraphWorkflowDocument, inputs?: GraphExecutionValues, options?: GraphExecutionOptions): Promise<GraphExecutionResult>;
-    /**
-     * Pins a node and its upstream dependencies after a completed run.
-     *
-     * Delegates to {@link GraphPinningService}. The plan and result must come
-     * from a prior successful execution of the same workflow.
-     */
-    pinNode(options: GraphPinNodeOptions): Promise<void>;
-    /**
-     * Unpins a node by its fingerprint.
-     */
-    unpinNode(options: GraphUnpinNodeOptions): Promise<void>;
-    /**
-     * Creates a {@link GraphPinningService} backed by this engine's value store
-     * adapter.
-     */
-    private createPinningService;
-    /**
-     * Emits a pinning-related event to all observers.
-     */
-    private emitPinningEvent;
-    /**
-     * Fills unprovided workflow inputs with their declared port defaults.
-     */
-    private withWorkflowInputDefaults;
-    /**
-     * Executes a layer of nodes with the configured concurrency.
-     */
-    private executeLayer;
-    /**
-     * Executes a single node, honouring disabled-node semantics (§4.9).
-     */
-    private executeNode;
-    /**
-     * Resolves whether a plan node is activated for execution under the
-     * DECAF-50 §4.9 branch semantics. A node with no incoming data edges is
-     * a root/source node and always runs. A node fed by one or more data
-     * edges runs only when at least one of those edges was activated by a
-     * routed upstream output port — a branch the upstream switch (or any
-     * partial-output node) did not select leaves its downstream edges
-     * unactivated, so the branch is never executed. Workflow-boundary edges
-     * are active from the start because workflow inputs are seeded before
-     * execution begins.
-     */
-    private isNodeActivated;
-    /**
-     * Skips a node whose incoming data edges were all left unactivated by an
-     * upstream branch selection. The node is not executed and its outputs are
-     * never routed or collected into workflow outputs (DECAF-50 §4.9).
-     */
-    private skipInactiveNode;
-    /**
-     * Applies the explicit disabled-node semantics (§4.9):
-     * `skip`, `passThroughFirstInput`, or `emitDefaults`, resolved from the
-     * instance metadata, document settings, and the default.
-     */
-    private executeDisabledNode;
-    /**
-     * Invokes the node's catalogue-resolved executor (§4.9 request contract,
-     * post-cutover: every executor receives the full request with
-     * configuration and input data separated).
-     */
-    private invokeExecutor;
-    /**
-     * Validates executor outputs against the effective output manifest
-     * (§4.9): unknown outputs are rejected by default; missing required
-     * outputs fail the node. Lenient transition manifests (legacy
-     * executor-only registrations) are exempt until cutover.
-     */
-    private validateNodeOutputs;
-    /**
-     * Collects the resolved credential references for a node: credential-type
-     * parameter values plus the `credentials` record in instance metadata.
-     * Documents carry references only — secret material never enters requests.
-     */
-    private collectCredentials;
-    /**
-     * Resolves a node's input values from routed data edges, literal bindings,
-     * allowed expression bindings, and manifest port defaults (§4.9).
-     *
-     * When multiple edges target the same port, their values are spread into the
-     * top-level inputs keyed by each edge's `sourcePort`. This allows multiple
-     * workflow input badges to connect to a single port (e.g. the Code node's
-     * `data` port) and have all values accessible directly as
-     * `$input.{sourcePort}` (e.g. `$input.count`, `$input.text`).
-     */
-    private resolveNodeInputs;
-    /**
-     * Evaluates an expression binding with the EXISTING allowed-expression
-     * machinery only (the pluggable {@link CodeSandboxEvaluator}, DECAF-32
-     * §22.4) — no new evaluator. The expression sees the already-routed input
-     * values as `$input` and the run metadata as context.
-     */
-    private evaluateExpressionBinding;
-    /**
-     * Attempts to read a pinned value for the node. Returns the cached outputs
-     * when a valid pinned value exists, or `undefined` to proceed with normal
-     * execution.
-     */
-    private tryPinnedValue;
-    /**
-     * Recursively computes fingerprints for all upstream dependencies of a node
-     * using the results already accumulated in the frame.
-     */
-    private computeDependencyFingerprints;
-    /**
-     * Routes a node's outputs to downstream inputs and workflow outputs along
-     * data edges (connection edges are structural and never route values).
-     *
-     * An edge is traversed only when the source node actually emitted the
-     * edge's `sourcePort` (DECAF-50 §4.9 branch semantics). A node that
-     * emitted a subset of its declared outputs — e.g. a switch that selected
-     * one case — therefore activates only the downstream branch edges of the
-     * emitted ports; unselected branch edges are left unactivated, so their
-     * downstream nodes are skipped and never contribute to workflow outputs.
-     * Emitting an output port explicitly with `undefined` still counts as
-     * activated (the port was produced by the executor).
-     */
-    private routeOutgoingEdges;
-    /**
-     * Emits an event, records it in the frame, and dispatches to observers.
-     */
-    private emitEvent;
-    /**
-     * Emits a `NODE_STATE_CHANGED` event (DECAF-48 §4.4) carrying the given
-     * visual state for the node. Rides the existing Observable pipeline; no
-     * second out-of-band channel.
-     */
-    private emitNodeStateChanged;
-    /**
-     * Emits an `EDGE_STATE_CHANGED` event (DECAF-48 §4.4) carrying the given
-     * visual state for a routed edge.
-     */
-    private emitEdgeStateChanged;
-    /**
-     * Merges default options with the given options.
-     */
-    private mergeOptions;
-    private assertNotAborted;
-    /**
-     * Generates a unique run id.
-     */
-    private generateRunId;
-    /**
-     * Converts an error into a serialized payload.
-     */
-    private toErrorPayload;
-}