@decaf-ts/integrations 0.10.5 → 0.10.8

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

@@ -161,6 +161,24 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
      * 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
@@ -218,6 +236,15 @@ export declare class GraphExecutionEngine implements Observable<[GraphExecutionO
     /**
      * 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;
     /**

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

@@ -19,10 +19,22 @@ export declare class GraphExecutionFrame {
     readonly startedAt: Date;
     readonly nodeResults: Map<string, GraphNodeExecutionResult>;
     readonly events: GraphExecutionEvent[];
+    /**
+     * Ids of the data edges activated by a routed upstream output port
+     * (DECAF-50 §4.9 branch semantics). A data edge is activated only when
+     * its source node actually emitted the edge's source port; downstream
+     * nodes with no activated incoming data edge are skipped rather than run
+     * with undefined inputs.
+     */
+    private readonly activeDataEdges;
     finishedAt?: Date;
     constructor(runId: GraphRunId, plan: GraphExecutionPlan, valueStore: GraphValueStore, eventFactory: GraphExecutionEventFactory);
     /** Records a node execution result. */
     recordNodeResult(result: GraphNodeExecutionResult): void;
+    /** Marks a data edge as activated by its routed source output port. */
+    activateDataEdge(edgeId: string): void;
+    /** Returns whether a data edge has been activated during this run. */
+    isDataEdgeActive(edgeId: string): boolean;
     /** Appends an event to the run's event log. */
     appendEvent(event: GraphExecutionEvent): void;
     /** Marks the run as finished. */

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

@@ -19,10 +19,22 @@ export declare class GraphExecutionFrame {
     readonly startedAt: Date;
     readonly nodeResults: Map<string, GraphNodeExecutionResult>;
     readonly events: GraphExecutionEvent[];
+    /**
+     * Ids of the data edges activated by a routed upstream output port
+     * (DECAF-50 §4.9 branch semantics). A data edge is activated only when
+     * its source node actually emitted the edge's source port; downstream
+     * nodes with no activated incoming data edge are skipped rather than run
+     * with undefined inputs.
+     */
+    private readonly activeDataEdges;
     finishedAt?: Date;
     constructor(runId: GraphRunId, plan: GraphExecutionPlan, valueStore: GraphValueStore, eventFactory: GraphExecutionEventFactory);
     /** Records a node execution result. */
     recordNodeResult(result: GraphNodeExecutionResult): void;
+    /** Marks a data edge as activated by its routed source output port. */
+    activateDataEdge(edgeId: string): void;
+    /** Returns whether a data edge has been activated during this run. */
+    isDataEdgeActive(edgeId: string): boolean;
     /** Appends an event to the run's event log. */
     appendEvent(event: GraphExecutionEvent): void;
     /** Marks the run as finished. */

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

@@ -9,8 +9,4 @@ export * from "./GraphExecutionResult.d.cts";
 export * from "./GraphExecutionFrame.d.cts";
 export * from "./GraphExecutionEngine.d.cts";
 export * from "./CodeSandboxEvaluator.d.cts";
-export * from "./SwitchGraphNodeExecutor.d.cts";
-export * from "./CodeGraphNodeExecutor.d.cts";
-export * from "./LogGraphNodeExecutor.d.cts";
-export * from "./BreakGraphNodeExecutor.d.cts";
 export * from "./IsolatedVmCodeSandboxEvaluator.d.cts";

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

@@ -9,8 +9,4 @@ export * from "./GraphExecutionResult.d.mts";
 export * from "./GraphExecutionFrame.d.mts";
 export * from "./GraphExecutionEngine.d.mts";
 export * from "./CodeSandboxEvaluator.d.mts";
-export * from "./SwitchGraphNodeExecutor.d.mts";
-export * from "./CodeGraphNodeExecutor.d.mts";
-export * from "./LogGraphNodeExecutor.d.mts";
-export * from "./BreakGraphNodeExecutor.d.mts";
 export * from "./IsolatedVmCodeSandboxEvaluator.d.mts";

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

@@ -29,10 +29,6 @@ export * from "./execution/GraphExecutionFrame.d.cts";
 export * from "./execution/GraphExecutionResult.d.cts";
 export * from "./execution/GraphExecutionEngine.d.cts";
 export * from "./execution/CodeSandboxEvaluator.d.cts";
-export * from "./execution/SwitchGraphNodeExecutor.d.cts";
-export * from "./execution/CodeGraphNodeExecutor.d.cts";
-export * from "./execution/LogGraphNodeExecutor.d.cts";
-export * from "./execution/BreakGraphNodeExecutor.d.cts";
 export * from "./execution/IsolatedVmCodeSandboxEvaluator.d.cts";
 export * from "./registry/GraphNodeExecutorRegistry.d.cts";
 export * from "./registry/GraphNodeExecutorResolver.d.cts";
@@ -52,9 +48,6 @@ export * from "./validation/index.d.cts";
 export * from "./loops/GraphConditionEvaluator.d.cts";
 export * from "./loops/ConditionExpressionEvaluator.d.cts";
 export * from "./loops/GraphLoopExecutionContext.d.cts";
-export * from "./loops/ForeachGraphNodeExecutor.d.cts";
-export * from "./loops/WhileGraphNodeExecutor.d.cts";
-export * from "./loops/UntilGraphNodeExecutor.d.cts";
 export * from "./pinning/GraphPinningMetadata.d.cts";
 export * from "./pinning/GraphPinningPolicy.d.cts";
 export * from "./pinning/GraphPinningDependencyResolver.d.cts";

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

@@ -29,10 +29,6 @@ export * from "./execution/GraphExecutionFrame.d.mts";
 export * from "./execution/GraphExecutionResult.d.mts";
 export * from "./execution/GraphExecutionEngine.d.mts";
 export * from "./execution/CodeSandboxEvaluator.d.mts";
-export * from "./execution/SwitchGraphNodeExecutor.d.mts";
-export * from "./execution/CodeGraphNodeExecutor.d.mts";
-export * from "./execution/LogGraphNodeExecutor.d.mts";
-export * from "./execution/BreakGraphNodeExecutor.d.mts";
 export * from "./execution/IsolatedVmCodeSandboxEvaluator.d.mts";
 export * from "./registry/GraphNodeExecutorRegistry.d.mts";
 export * from "./registry/GraphNodeExecutorResolver.d.mts";
@@ -52,9 +48,6 @@ export * from "./validation/index.d.mts";
 export * from "./loops/GraphConditionEvaluator.d.mts";
 export * from "./loops/ConditionExpressionEvaluator.d.mts";
 export * from "./loops/GraphLoopExecutionContext.d.mts";
-export * from "./loops/ForeachGraphNodeExecutor.d.mts";
-export * from "./loops/WhileGraphNodeExecutor.d.mts";
-export * from "./loops/UntilGraphNodeExecutor.d.mts";
 export * from "./pinning/GraphPinningMetadata.d.mts";
 export * from "./pinning/GraphPinningPolicy.d.mts";
 export * from "./pinning/GraphPinningDependencyResolver.d.mts";

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

@@ -6,6 +6,3 @@
 export * from "./GraphConditionEvaluator.d.cts";
 export * from "./ConditionExpressionEvaluator.d.cts";
 export * from "./GraphLoopExecutionContext.d.cts";
-export * from "./ForeachGraphNodeExecutor.d.cts";
-export * from "./WhileGraphNodeExecutor.d.cts";
-export * from "./UntilGraphNodeExecutor.d.cts";

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

@@ -6,6 +6,3 @@
 export * from "./GraphConditionEvaluator.d.mts";
 export * from "./ConditionExpressionEvaluator.d.mts";
 export * from "./GraphLoopExecutionContext.d.mts";
-export * from "./ForeachGraphNodeExecutor.d.mts";
-export * from "./WhileGraphNodeExecutor.d.mts";
-export * from "./UntilGraphNodeExecutor.d.mts";

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

@@ -0,0 +1,21 @@
+/**
+ * @module integrations/graph/engine/validation/GraphLooseNodeValidation
+ * @summary Loose-node validation (DECAF-50 §4.26 R2-3 item 8).
+ * @description A node connected to nothing is a loose node and fails workflow
+ * validation: every node instance must participate in at least one edge
+ * (data or connection). The rule is shared by the execution gate
+ * ({@link GraphWorkflowDocumentValidator}) and the persistence gate
+ * ({@link validateGraphWorkflowDocumentAtBoundary}) so both start and save
+ * reject a loose node. Nested loop-body documents are checked recursively.
+ */
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphValidationIssue } from "./GraphValidationIssue.d.cts";
+/**
+ * Records a `topology.loose-node` issue for every node instance that no edge
+ * references, recursively across nested loop-body documents.
+ *
+ * @param document - The canonical workflow document to inspect.
+ * @param issues - The accumulating issue list.
+ * @param path - Dotted path prefix for reported issues.
+ */
+export declare function collectLooseNodeIssues(document: GraphWorkflowDocument, issues: GraphValidationIssue[], path?: string): void;

package/lib/types/graph/engine/validation/GraphLooseNodeValidation.d.mts

@@ -0,0 +1,21 @@
+/**
+ * @module integrations/graph/engine/validation/GraphLooseNodeValidation
+ * @summary Loose-node validation (DECAF-50 §4.26 R2-3 item 8).
+ * @description A node connected to nothing is a loose node and fails workflow
+ * validation: every node instance must participate in at least one edge
+ * (data or connection). The rule is shared by the execution gate
+ * ({@link GraphWorkflowDocumentValidator}) and the persistence gate
+ * ({@link validateGraphWorkflowDocumentAtBoundary}) so both start and save
+ * reject a loose node. Nested loop-body documents are checked recursively.
+ */
+import type { GraphWorkflowDocument } from "@decaf-ts/ui-decorators/graph";
+import type { GraphValidationIssue } from "./GraphValidationIssue.d.mts";
+/**
+ * Records a `topology.loose-node` issue for every node instance that no edge
+ * references, recursively across nested loop-body documents.
+ *
+ * @param document - The canonical workflow document to inspect.
+ * @param issues - The accumulating issue list.
+ * @param path - Dotted path prefix for reported issues.
+ */
+export declare function collectLooseNodeIssues(document: GraphWorkflowDocument, issues: GraphValidationIssue[], path?: string): void;

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

@@ -45,15 +45,34 @@ export declare class GraphParameterValidator {
      * behavior, and binding shapes against the effective manifest.
      *
      * Called at stage 3 (parameters) with the manifest resolved at stage 2.
+     * `edgeSatisfiedInputPorts` carries the input port ids targeted by an
+     * incoming data edge so required parameters can be cross-satisfied by
+     * the matching input surface (§4.4.5 rules 1/5/7).
      */
-    validate(node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, issues: GraphValidationIssue[], path: string): void;
+    validate(node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, issues: GraphValidationIssue[], path: string, edgeSatisfiedInputPorts?: ReadonlySet<string>): void;
     /**
      * Declared-ness, required presence, typing, and declarative validation
      * rules for parameter values. Validation is visibility-invariant: hidden
      * parameters are validated identically (visibility cannot bypass
      * security-sensitive validation).
+     *
+     * Cross-satisfaction (§4.4.5 rules 1/5/7): when the manifest declares
+     * both a parameter and an input port with the same `id`, the single logical
+     * value may be carried on either surface. A required parameter is therefore
+     * satisfied when the instance provides `parameters[id]`, carries an
+     * `inputBindings[id]` (an edge-, literal-, or expression-bound value), or
+     * has an incoming data edge targeting port `id` (passed in via
+     * `edgeSatisfiedInputPorts`, computed from the raw document before the
+     * normative stage order reaches edge resolution).
      */
     private validateParameters;
+    /**
+     * Cross-satisfaction of a required parameter by the matching input surface
+     * (§4.4.5 rules 1/5/7): an `inputBindings[id]` entry or an incoming
+     * data edge targeting port `id` carries the same logical value, so the
+     * parameter is satisfied without a redundant `parameters[id]` entry.
+     */
+    private isParameterSatisfiedByInput;
     /**
      * Type-checks a parameter value against its parameter definition.
      */
@@ -80,6 +99,11 @@ export declare class GraphParameterValidator {
      * not also carry a literal binding (unless explicitly allowed), and every
      * required effective input port must be satisfiable (incoming edge,
      * literal, or expression binding).
+     *
+     * Cross-satisfaction (§4.4.5 rules 1/5/7): a required input port whose
+     * `id` is also a declared parameter may be satisfied by a provided
+     * `parameters[id]` value, exactly as the parameter pass accepts the
+     * input/binding surface for that same id.
      */
     validateBindingSatisfaction(node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, incoming: GraphResolvedEdgeInstance[], issues: GraphValidationIssue[], path: string, options?: {
         allowLiteralAndEdgeBindings?: boolean;

package/lib/types/graph/engine/validation/GraphParameterValidator.d.mts

@@ -45,15 +45,34 @@ export declare class GraphParameterValidator {
      * behavior, and binding shapes against the effective manifest.
      *
      * Called at stage 3 (parameters) with the manifest resolved at stage 2.
+     * `edgeSatisfiedInputPorts` carries the input port ids targeted by an
+     * incoming data edge so required parameters can be cross-satisfied by
+     * the matching input surface (§4.4.5 rules 1/5/7).
      */
-    validate(node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, issues: GraphValidationIssue[], path: string): void;
+    validate(node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, issues: GraphValidationIssue[], path: string, edgeSatisfiedInputPorts?: ReadonlySet<string>): void;
     /**
      * Declared-ness, required presence, typing, and declarative validation
      * rules for parameter values. Validation is visibility-invariant: hidden
      * parameters are validated identically (visibility cannot bypass
      * security-sensitive validation).
+     *
+     * Cross-satisfaction (§4.4.5 rules 1/5/7): when the manifest declares
+     * both a parameter and an input port with the same `id`, the single logical
+     * value may be carried on either surface. A required parameter is therefore
+     * satisfied when the instance provides `parameters[id]`, carries an
+     * `inputBindings[id]` (an edge-, literal-, or expression-bound value), or
+     * has an incoming data edge targeting port `id` (passed in via
+     * `edgeSatisfiedInputPorts`, computed from the raw document before the
+     * normative stage order reaches edge resolution).
      */
     private validateParameters;
+    /**
+     * Cross-satisfaction of a required parameter by the matching input surface
+     * (§4.4.5 rules 1/5/7): an `inputBindings[id]` entry or an incoming
+     * data edge targeting port `id` carries the same logical value, so the
+     * parameter is satisfied without a redundant `parameters[id]` entry.
+     */
+    private isParameterSatisfiedByInput;
     /**
      * Type-checks a parameter value against its parameter definition.
      */
@@ -80,6 +99,11 @@ export declare class GraphParameterValidator {
      * not also carry a literal binding (unless explicitly allowed), and every
      * required effective input port must be satisfiable (incoming edge,
      * literal, or expression binding).
+     *
+     * Cross-satisfaction (§4.4.5 rules 1/5/7): a required input port whose
+     * `id` is also a declared parameter may be satisfied by a provided
+     * `parameters[id]` value, exactly as the parameter pass accepts the
+     * input/binding surface for that same id.
      */
     validateBindingSatisfaction(node: GraphNodeInstance, manifest: GraphResolvedNodeManifest, incoming: GraphResolvedEdgeInstance[], issues: GraphValidationIssue[], path: string, options?: {
         allowLiteralAndEdgeBindings?: boolean;

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

@@ -17,3 +17,4 @@ export * from "./GraphEdgeInstanceValidator.d.cts";
 export * from "./GraphConnectionPolicyValidator.d.cts";
 export * from "./GraphCredentialReferenceValidator.d.cts";
 export * from "./GraphWorkflowDocumentValidator.d.cts";
+export * from "./GraphLooseNodeValidation.d.cts";

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

@@ -17,3 +17,4 @@ export * from "./GraphEdgeInstanceValidator.d.mts";
 export * from "./GraphConnectionPolicyValidator.d.mts";
 export * from "./GraphCredentialReferenceValidator.d.mts";
 export * from "./GraphWorkflowDocumentValidator.d.mts";
+export * from "./GraphLooseNodeValidation.d.mts";

package/lib/types/graph/nodes/agents/agent.d.cts

@@ -0,0 +1,31 @@
+import { GraphNode } from "../base.d.cts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.cts";
+/**
+ * Agent node — an AI agent that orchestrates a model, memory, and workspace.
+ *
+ * The agent has:
+ * - `@input` port on the **left**: `prompt` (the task prompt; supports
+ *   placeholder expressions like `{{ $input.something }}` per §22.4).
+ * - `@output` ports on the **right**: `response` (the agent's output), `actions`
+ *   (any actions the agent decided to take).
+ * - `@connection` ports on the **bottom**: `model` (LLM), `memory` (memory
+ *   store), `workspace` (workspace/context). Each connection has a distinct
+ *   category color.
+ *
+ * The node is rectangular (not rounded) to visually distinguish it from
+ * regular processing nodes. The `color` and `icon` are omitted from `@node()`
+ * so they are resolved from the `"Agent"` category style.
+ */
+export declare class AgentNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest): GraphExecutionValues;
+    prompt: string;
+    response: string;
+    actions: unknown[];
+    model: unknown;
+    memory: unknown;
+    workspace: unknown;
+}
+/**
+ * All built-in agent node constructors.
+ */
+export declare const GRAPH_AGENT_NODES: readonly [typeof AgentNode];

package/lib/types/graph/nodes/agents/agent.d.mts

@@ -0,0 +1,31 @@
+import { GraphNode } from "../base.d.mts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.mts";
+/**
+ * Agent node — an AI agent that orchestrates a model, memory, and workspace.
+ *
+ * The agent has:
+ * - `@input` port on the **left**: `prompt` (the task prompt; supports
+ *   placeholder expressions like `{{ $input.something }}` per §22.4).
+ * - `@output` ports on the **right**: `response` (the agent's output), `actions`
+ *   (any actions the agent decided to take).
+ * - `@connection` ports on the **bottom**: `model` (LLM), `memory` (memory
+ *   store), `workspace` (workspace/context). Each connection has a distinct
+ *   category color.
+ *
+ * The node is rectangular (not rounded) to visually distinguish it from
+ * regular processing nodes. The `color` and `icon` are omitted from `@node()`
+ * so they are resolved from the `"Agent"` category style.
+ */
+export declare class AgentNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest): GraphExecutionValues;
+    prompt: string;
+    response: string;
+    actions: unknown[];
+    model: unknown;
+    memory: unknown;
+    workspace: unknown;
+}
+/**
+ * All built-in agent node constructors.
+ */
+export declare const GRAPH_AGENT_NODES: readonly [typeof AgentNode];

package/lib/types/graph/nodes/base.d.cts

@@ -0,0 +1,58 @@
+/**
+ * @module integrations/graph/nodes/base
+ * @summary Base class for backend graph node declarations.
+ * @description `GraphNode` is the single authoritative backend representation of
+ * a built-in node kind (DECAF-50 §4.26 R2-1): the `@node`-decorated class
+ * carries both the published manifest metadata and the executable behaviour via
+ * `execute`. The catalogue derives each kind's executor from the class, so there
+ * is exactly one authority per node kind.
+ */
+import { Model } from "@decaf-ts/decorator-validation";
+import type { NodeMetadataChange } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionContext } from "../engine/execution/GraphExecutionContext.d.cts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../engine/types.d.cts";
+/**
+ * Constructor shape of a built-in backend node class: a `Model` subclass whose
+ * static `execute` performs the node's work.
+ */
+export interface GraphNodeClass {
+    /** Node kind discriminator declared via the `@node` decorator. */
+    readonly kind?: string;
+    /** The node's executable behaviour. */
+    execute(request: GraphNodeExecutionRequest, context: GraphExecutionContext): GraphExecutionValues | Promise<GraphExecutionValues>;
+}
+/**
+ * Base class for the built-in backend node kinds.
+ *
+ * Extends `Model` so the `@node`/`@uielement` decorators and the manifest
+ * compiler keep working unchanged. Concrete kinds override `execute`; the default
+ * throws so a kind that forgets to implement behaviour fails fast rather than
+ * silently producing no output.
+ */
+export declare class GraphNode extends Model {
+    /**
+     * Executes the node's behaviour against the request inputs and run context.
+     *
+     * @param _request - The node execution request (inputs, parameters,
+     * credentials, metadata).
+     * @param _context - The run-scoped execution context.
+     * @returns The node's output values keyed by port name.
+     * @throws {GraphExecutionError} when the kind does not implement `execute`.
+     */
+    static execute(_request: GraphNodeExecutionRequest, _context: GraphExecutionContext): GraphExecutionValues | Promise<GraphExecutionValues>;
+    /**
+     * Applies a metadata patch to this node class, returning the resulting
+     * ports, size, and data patches.
+     *
+     * The default implementation returns `null` (no changes). Concrete node
+     * kinds that support dynamic metadata override this to compute their own
+     * ports and size from the metadata — the caller (renderer) simply relays
+     * the result to the diagram model.
+     *
+     * @param _meta - The metadata patch (node-kind-specific, e.g.
+     *   `SwitchNodeMetadata`).
+     * @returns The computed change, or `null` when the node kind does not
+     *   support dynamic metadata.
+     */
+    static applyMetadata(_meta: unknown): NodeMetadataChange | null;
+}

package/lib/types/graph/nodes/base.d.mts

@@ -0,0 +1,58 @@
+/**
+ * @module integrations/graph/nodes/base
+ * @summary Base class for backend graph node declarations.
+ * @description `GraphNode` is the single authoritative backend representation of
+ * a built-in node kind (DECAF-50 §4.26 R2-1): the `@node`-decorated class
+ * carries both the published manifest metadata and the executable behaviour via
+ * `execute`. The catalogue derives each kind's executor from the class, so there
+ * is exactly one authority per node kind.
+ */
+import { Model } from "@decaf-ts/decorator-validation";
+import type { NodeMetadataChange } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionContext } from "../engine/execution/GraphExecutionContext.d.mts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../engine/types.d.mts";
+/**
+ * Constructor shape of a built-in backend node class: a `Model` subclass whose
+ * static `execute` performs the node's work.
+ */
+export interface GraphNodeClass {
+    /** Node kind discriminator declared via the `@node` decorator. */
+    readonly kind?: string;
+    /** The node's executable behaviour. */
+    execute(request: GraphNodeExecutionRequest, context: GraphExecutionContext): GraphExecutionValues | Promise<GraphExecutionValues>;
+}
+/**
+ * Base class for the built-in backend node kinds.
+ *
+ * Extends `Model` so the `@node`/`@uielement` decorators and the manifest
+ * compiler keep working unchanged. Concrete kinds override `execute`; the default
+ * throws so a kind that forgets to implement behaviour fails fast rather than
+ * silently producing no output.
+ */
+export declare class GraphNode extends Model {
+    /**
+     * Executes the node's behaviour against the request inputs and run context.
+     *
+     * @param _request - The node execution request (inputs, parameters,
+     * credentials, metadata).
+     * @param _context - The run-scoped execution context.
+     * @returns The node's output values keyed by port name.
+     * @throws {GraphExecutionError} when the kind does not implement `execute`.
+     */
+    static execute(_request: GraphNodeExecutionRequest, _context: GraphExecutionContext): GraphExecutionValues | Promise<GraphExecutionValues>;
+    /**
+     * Applies a metadata patch to this node class, returning the resulting
+     * ports, size, and data patches.
+     *
+     * The default implementation returns `null` (no changes). Concrete node
+     * kinds that support dynamic metadata override this to compute their own
+     * ports and size from the metadata — the caller (renderer) simply relays
+     * the result to the diagram model.
+     *
+     * @param _meta - The metadata patch (node-kind-specific, e.g.
+     *   `SwitchNodeMetadata`).
+     * @returns The computed change, or `null` when the node kind does not
+     *   support dynamic metadata.
+     */
+    static applyMetadata(_meta: unknown): NodeMetadataChange | null;
+}

package/lib/types/graph/nodes/boundary/input-value.d.cts

@@ -0,0 +1,6 @@
+import { GraphNode } from "../base.d.cts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.cts";
+export declare class GraphInputValueNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest): GraphExecutionValues;
+    value: unknown;
+}

package/lib/types/graph/nodes/boundary/input-value.d.mts

@@ -0,0 +1,6 @@
+import { GraphNode } from "../base.d.mts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.mts";
+export declare class GraphInputValueNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest): GraphExecutionValues;
+    value: unknown;
+}

package/lib/types/graph/nodes/flow-control/break.d.cts

@@ -0,0 +1,8 @@
+import { GraphNode } from "../base.d.cts";
+import type { GraphExecutionContext } from "../../engine/execution/GraphExecutionContext.d.cts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.cts";
+export declare class BreakFlowNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest, _context: GraphExecutionContext): GraphExecutionValues;
+    value: unknown;
+    broken: unknown;
+}

package/lib/types/graph/nodes/flow-control/break.d.mts

@@ -0,0 +1,8 @@
+import { GraphNode } from "../base.d.mts";
+import type { GraphExecutionContext } from "../../engine/execution/GraphExecutionContext.d.mts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.mts";
+export declare class BreakFlowNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest, _context: GraphExecutionContext): GraphExecutionValues;
+    value: unknown;
+    broken: unknown;
+}

package/lib/types/graph/nodes/flow-control/error-boundary.d.cts

@@ -0,0 +1,8 @@
+import { GraphNode } from "../base.d.cts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.cts";
+export declare class ErrorBoundaryFlowNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest): GraphExecutionValues;
+    value: unknown;
+    result: unknown;
+    error: unknown;
+}

package/lib/types/graph/nodes/flow-control/error-boundary.d.mts

@@ -0,0 +1,8 @@
+import { GraphNode } from "../base.d.mts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.mts";
+export declare class ErrorBoundaryFlowNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest): GraphExecutionValues;
+    value: unknown;
+    result: unknown;
+    error: unknown;
+}

package/lib/types/graph/nodes/flow-control/human-approval.d.cts

@@ -0,0 +1,8 @@
+import { GraphNode } from "../base.d.cts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.cts";
+export declare class HumanApprovalFlowNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest): GraphExecutionValues;
+    value: unknown;
+    approved: unknown;
+    rejected: unknown;
+}

package/lib/types/graph/nodes/flow-control/human-approval.d.mts

@@ -0,0 +1,8 @@
+import { GraphNode } from "../base.d.mts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.mts";
+export declare class HumanApprovalFlowNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest): GraphExecutionValues;
+    value: unknown;
+    approved: unknown;
+    rejected: unknown;
+}

package/lib/types/graph/nodes/flow-control/if.d.cts

@@ -0,0 +1,8 @@
+import { GraphNode } from "../base.d.cts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.cts";
+export declare class IfFlowNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest): GraphExecutionValues;
+    value: unknown;
+    then: unknown;
+    else: unknown;
+}

package/lib/types/graph/nodes/flow-control/if.d.mts

@@ -0,0 +1,8 @@
+import { GraphNode } from "../base.d.mts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.mts";
+export declare class IfFlowNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest): GraphExecutionValues;
+    value: unknown;
+    then: unknown;
+    else: unknown;
+}

package/lib/types/graph/nodes/flow-control/parallel.d.cts

@@ -0,0 +1,7 @@
+import { GraphNode } from "../base.d.cts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.cts";
+export declare class ParallelFlowNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest): GraphExecutionValues;
+    value: unknown;
+    branches: unknown[];
+}

package/lib/types/graph/nodes/flow-control/parallel.d.mts

@@ -0,0 +1,7 @@
+import { GraphNode } from "../base.d.mts";
+import type { GraphExecutionValues, GraphNodeExecutionRequest } from "../../engine/types.d.mts";
+export declare class ParallelFlowNode extends GraphNode {
+    static execute(request: GraphNodeExecutionRequest): GraphExecutionValues;
+    value: unknown;
+    branches: unknown[];
+}