@decaf-ts/integrations 0.8.0 → 0.10.0

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

@@ -1,26 +1,38 @@
 /**
  * @module integrations/graph/execution/GraphExecutionContext
- * @summary Decaf Context for graph node execution.
- * @description Extends Decaf's {@link Context} so node executors receive the same contextual plumbing as task handlers. 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.
+ * @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 { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeInstance, GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
 import type { Logger } from "@decaf-ts/logging";
-import type { GraphExecutionEvent, GraphRunId } from "../types.d.cts";
+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";
 /**
  * Context passed to every graph node executor.
  *
- * Mirrors the `TaskEngine` / `TaskContext` pattern: the engine creates a
- * `GraphExecutionContext` per node execution and passes it to
- * `executor.execute(inputs, context)`. 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).
+ * 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 workflow: GraphWorkflowDefinition;
-    readonly node: GraphNodeDefinition;
+    readonly workflowId: string;
+    readonly document: GraphWorkflowDocument;
+    readonly node: GraphNodeInstance;
+    readonly manifest: GraphResolvedNodeManifest;
     readonly path: string[];
     private readonly emitFn;
     readonly metadata: Record<string, unknown>;
@@ -28,13 +40,15 @@ export declare class GraphExecutionContext extends Context {
     /**
      * @param runId - Unique identifier for the current execution run.
      * @param parentRunId - Run id of the parent execution (for nested loop bodies).
-     * @param workflow - The workflow definition being executed.
-     * @param node - The node definition being executed.
+     * @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.
      */
-    constructor(runId: GraphRunId, parentRunId: GraphRunId | undefined, workflow: GraphWorkflowDefinition, node: GraphNodeDefinition, path: string[], emitFn: (event: Partial<GraphExecutionEvent>) => Promise<void>, metadata?: Record<string, unknown>);
+    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>);
     /**
      * The decaf-ts {@link Logger} bound to this node's run context. Every log
      * line carries the DECAF-48 attributes (`nodeId` / `workflowId` / `runId` /

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

@@ -1,26 +1,38 @@
 /**
  * @module integrations/graph/execution/GraphExecutionContext
- * @summary Decaf Context for graph node execution.
- * @description Extends Decaf's {@link Context} so node executors receive the same contextual plumbing as task handlers. 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.
+ * @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 { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeInstance, GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
 import type { Logger } from "@decaf-ts/logging";
-import type { GraphExecutionEvent, GraphRunId } from "../types.d.mts";
+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";
 /**
  * Context passed to every graph node executor.
  *
- * Mirrors the `TaskEngine` / `TaskContext` pattern: the engine creates a
- * `GraphExecutionContext` per node execution and passes it to
- * `executor.execute(inputs, context)`. 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).
+ * 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 workflow: GraphWorkflowDefinition;
-    readonly node: GraphNodeDefinition;
+    readonly workflowId: string;
+    readonly document: GraphWorkflowDocument;
+    readonly node: GraphNodeInstance;
+    readonly manifest: GraphResolvedNodeManifest;
     readonly path: string[];
     private readonly emitFn;
     readonly metadata: Record<string, unknown>;
@@ -28,13 +40,15 @@ export declare class GraphExecutionContext extends Context {
     /**
      * @param runId - Unique identifier for the current execution run.
      * @param parentRunId - Run id of the parent execution (for nested loop bodies).
-     * @param workflow - The workflow definition being executed.
-     * @param node - The node definition being executed.
+     * @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.
      */
-    constructor(runId: GraphRunId, parentRunId: GraphRunId | undefined, workflow: GraphWorkflowDefinition, node: GraphNodeDefinition, path: string[], emitFn: (event: Partial<GraphExecutionEvent>) => Promise<void>, metadata?: Record<string, unknown>);
+    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>);
     /**
      * The decaf-ts {@link Logger} bound to this node's run context. Every log
      * line carries the DECAF-48 attributes (`nodeId` / `workflowId` / `runId` /

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

@@ -1,15 +1,32 @@
 /**
  * @module integrations/graph/execution/GraphExecutionEngine
- * @summary Reference graph execution engine.
- * @description Executes graph workflows declared with `@decaf-ts/ui-decorators/graph`, emits events through Decaf's Observable pipeline, supports parallel node execution within topological layers, and returns a complete execution result. Per DECAF-48 §4.4 it also emits `NODE_STATE_CHANGED` / `EDGE_STATE_CHANGED` visual-state events on the same pipeline, and node executors log through the run-scoped `ctx.logger` (streamed over the `graph.run.log` SSE channel).
+ * @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 { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionEvent, GraphExecutionOptions, GraphExecutionResult, GraphExecutionValues, GraphPinNodeOptions, GraphUnpinNodeOptions } from "../types.d.cts";
+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";
 /**
@@ -17,15 +34,27 @@ import type { CodeSandboxEvaluator } from "./CodeSandboxEvaluator.d.cts";
  */
 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
-     * (DECAF-32 §22.4). When absent, code conditions throw
-     * `GRAPH_CODE_SANDBOX_NOT_CONFIGURED`. Downstream projects (e.g. ALFRED)
-     * supply the actual VM sandbox implementation.
+     * 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;
     /**
@@ -39,19 +68,27 @@ export interface GraphExecutionEngineConfig {
 /**
  * Reference graph execution engine.
  *
- * Executes a {@link GraphWorkflowDefinition} by:
- * 1. Planning the workflow into topological layers.
- * 2. Seeding workflow inputs into the value store.
- * 3. Executing nodes layer-by-layer with configurable concurrency.
- * 4. Routing values along edges.
- * 5. Emitting structured events through Decaf's Observable pipeline.
- * 6. Returning a complete {@link GraphExecutionResult}.
+ * 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);
@@ -76,15 +113,22 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
      */
     updateObservers(event: GraphExecutionEvent): Promise<void>;
     /**
-     * Executes a workflow with the given inputs and options.
+     * Executes a canonical workflow document with the given inputs and options.
      *
-     * @param workflow - The workflow definition to execute.
-     * @param inputs - Workflow input values keyed by input port name.
+     * 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).
+     *   results, and workflow outputs (or the failure payload).
+     * @throws {GraphDocumentValidationError} when the document fails the
+     *   nine-stage validation gate (carries every structured issue).
      */
-    execute(workflow: GraphWorkflowDefinition, inputs?: GraphExecutionValues, options?: GraphExecutionOptions): Promise<GraphExecutionResult>;
+    execute(document: GraphWorkflowDocument, inputs?: GraphExecutionValues, options?: GraphExecutionOptions): Promise<GraphExecutionResult>;
     /**
      * Pins a node and its upstream dependencies after a completed run.
      *
@@ -105,16 +149,46 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
      * 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.
+     * Executes a single node, honouring disabled-node semantics (§4.9).
      */
     private executeNode;
     /**
-     * Resolves a node's input values from incoming edges.
+     * 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
@@ -123,6 +197,13 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
      * `$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
@@ -135,7 +216,8 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
      */
     private computeDependencyFingerprints;
     /**
-     * Routes a node's outputs to downstream inputs and workflow outputs.
+     * Routes a node's outputs to downstream inputs and workflow outputs along
+     * data edges (connection edges are structural and never route values).
      */
     private routeOutgoingEdges;
     /**
@@ -157,6 +239,7 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
      * Merges default options with the given options.
      */
     private mergeOptions;
+    private assertNotAborted;
     /**
      * Generates a unique run id.
      */

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

@@ -1,15 +1,32 @@
 /**
  * @module integrations/graph/execution/GraphExecutionEngine
- * @summary Reference graph execution engine.
- * @description Executes graph workflows declared with `@decaf-ts/ui-decorators/graph`, emits events through Decaf's Observable pipeline, supports parallel node execution within topological layers, and returns a complete execution result. Per DECAF-48 §4.4 it also emits `NODE_STATE_CHANGED` / `EDGE_STATE_CHANGED` visual-state events on the same pipeline, and node executors log through the run-scoped `ctx.logger` (streamed over the `graph.run.log` SSE channel).
+ * @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 { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionEvent, GraphExecutionOptions, GraphExecutionResult, GraphExecutionValues, GraphPinNodeOptions, GraphUnpinNodeOptions } from "../types.d.mts";
+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.mts";
 import type { GraphExecutionObserver } from "../events/GraphExecutionObserver.d.mts";
 import { GraphExecutionEventEmitter } from "../events/GraphExecutionEventEmitter.d.mts";
 import type { GraphNodeExecutorRegistry } from "../registry/GraphNodeExecutorRegistry.d.mts";
+import type { GraphNodeCatalogue } from "../catalog/GraphNodeCatalogue.d.mts";
 import { GraphExecutionPlanner } from "../planning/GraphExecutionPlanner.d.mts";
+import { GraphWorkflowDocumentValidator, type GraphWorkflowDocumentValidationLimits } from "../validation/GraphWorkflowDocumentValidator.d.mts";
+import type { GraphCredentialAuthorizer } from "../validation/GraphCredentialReferenceValidator.d.mts";
 import type { GraphValueStoreAdapter } from "../store/GraphValueStoreAdapter.d.mts";
 import type { CodeSandboxEvaluator } from "./CodeSandboxEvaluator.d.mts";
 /**
@@ -17,15 +34,27 @@ import type { CodeSandboxEvaluator } from "./CodeSandboxEvaluator.d.mts";
  */
 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
-     * (DECAF-32 §22.4). When absent, code conditions throw
-     * `GRAPH_CODE_SANDBOX_NOT_CONFIGURED`. Downstream projects (e.g. ALFRED)
-     * supply the actual VM sandbox implementation.
+     * 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;
     /**
@@ -39,19 +68,27 @@ export interface GraphExecutionEngineConfig {
 /**
  * Reference graph execution engine.
  *
- * Executes a {@link GraphWorkflowDefinition} by:
- * 1. Planning the workflow into topological layers.
- * 2. Seeding workflow inputs into the value store.
- * 3. Executing nodes layer-by-layer with configurable concurrency.
- * 4. Routing values along edges.
- * 5. Emitting structured events through Decaf's Observable pipeline.
- * 6. Returning a complete {@link GraphExecutionResult}.
+ * 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);
@@ -76,15 +113,22 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
      */
     updateObservers(event: GraphExecutionEvent): Promise<void>;
     /**
-     * Executes a workflow with the given inputs and options.
+     * Executes a canonical workflow document with the given inputs and options.
      *
-     * @param workflow - The workflow definition to execute.
-     * @param inputs - Workflow input values keyed by input port name.
+     * 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).
+     *   results, and workflow outputs (or the failure payload).
+     * @throws {GraphDocumentValidationError} when the document fails the
+     *   nine-stage validation gate (carries every structured issue).
      */
-    execute(workflow: GraphWorkflowDefinition, inputs?: GraphExecutionValues, options?: GraphExecutionOptions): Promise<GraphExecutionResult>;
+    execute(document: GraphWorkflowDocument, inputs?: GraphExecutionValues, options?: GraphExecutionOptions): Promise<GraphExecutionResult>;
     /**
      * Pins a node and its upstream dependencies after a completed run.
      *
@@ -105,16 +149,46 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
      * 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.
+     * Executes a single node, honouring disabled-node semantics (§4.9).
      */
     private executeNode;
     /**
-     * Resolves a node's input values from incoming edges.
+     * 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
@@ -123,6 +197,13 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
      * `$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
@@ -135,7 +216,8 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
      */
     private computeDependencyFingerprints;
     /**
-     * Routes a node's outputs to downstream inputs and workflow outputs.
+     * Routes a node's outputs to downstream inputs and workflow outputs along
+     * data edges (connection edges are structural and never route values).
      */
     private routeOutgoingEdges;
     /**
@@ -157,6 +239,7 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
      * Merges default options with the given options.
      */
     private mergeOptions;
+    private assertNotAborted;
     /**
      * Generates a unique run id.
      */

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

@@ -6,7 +6,8 @@
 import type { GraphExecutionPlan } from "../planning/GraphExecutionPlan.d.cts";
 import type { GraphValueStore } from "../store/GraphValueStore.d.cts";
 import type { GraphExecutionEventFactory } from "../events/GraphExecutionEventFactory.d.cts";
-import type { GraphExecutionEvent, GraphNodeExecutionResult, GraphRunId } from "../types.d.cts";
+import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeExecutionResult, GraphRunId } from "../types.d.cts";
 /**
  * Mutable state for a single graph execution run.
  */

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

@@ -6,7 +6,8 @@
 import type { GraphExecutionPlan } from "../planning/GraphExecutionPlan.d.mts";
 import type { GraphValueStore } from "../store/GraphValueStore.d.mts";
 import type { GraphExecutionEventFactory } from "../events/GraphExecutionEventFactory.d.mts";
-import type { GraphExecutionEvent, GraphNodeExecutionResult, GraphRunId } from "../types.d.mts";
+import type { GraphExecutionEvent } from "@decaf-ts/ui-decorators/graph";
+import type { GraphNodeExecutionResult, GraphRunId } from "../types.d.mts";
 /**
  * Mutable state for a single graph execution run.
  */

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

@@ -3,11 +3,11 @@
  * @summary Helper for building GraphExecutionResult objects.
  * @description Provides a builder function that assembles a result from a frame.
  */
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
 import type { GraphExecutionFrame } from "./GraphExecutionFrame.d.cts";
 import type { GraphExecutionResult, GraphExecutionValues } from "../types.d.cts";
-import type { GraphExecutionStatus } from "../../shared/constants.d.cts";
-import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionStatus } from "@decaf-ts/ui-decorators/graph";
 /**
  * Builds a {@link GraphExecutionResult} from a completed frame.
  */
-export declare function buildGraphExecutionResult(frame: GraphExecutionFrame, workflow: GraphWorkflowDefinition, inputs: GraphExecutionValues, status: GraphExecutionStatus, metadata?: Record<string, unknown>): GraphExecutionResult;
+export declare function buildGraphExecutionResult(frame: GraphExecutionFrame, document: GraphWorkflowDocument, inputs: GraphExecutionValues, status: GraphExecutionStatus, metadata?: Record<string, unknown>): GraphExecutionResult;

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

@@ -3,11 +3,11 @@
  * @summary Helper for building GraphExecutionResult objects.
  * @description Provides a builder function that assembles a result from a frame.
  */
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
 import type { GraphExecutionFrame } from "./GraphExecutionFrame.d.mts";
 import type { GraphExecutionResult, GraphExecutionValues } from "../types.d.mts";
-import type { GraphExecutionStatus } from "../../shared/constants.d.mts";
-import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionStatus } from "@decaf-ts/ui-decorators/graph";
 /**
  * Builds a {@link GraphExecutionResult} from a completed frame.
  */
-export declare function buildGraphExecutionResult(frame: GraphExecutionFrame, workflow: GraphWorkflowDefinition, inputs: GraphExecutionValues, status: GraphExecutionStatus, metadata?: Record<string, unknown>): GraphExecutionResult;
+export declare function buildGraphExecutionResult(frame: GraphExecutionFrame, document: GraphWorkflowDocument, inputs: GraphExecutionValues, status: GraphExecutionStatus, metadata?: Record<string, unknown>): GraphExecutionResult;