@decaf-ts/integrations 0.3.4 → 0.3.5

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

@@ -0,0 +1,44 @@
+/**
+ * @module integrations/graph/nodes/agent
+ * @summary Production Agent node declaration.
+ * @description The Agent node is the primary AI agent entrypoint. It is a
+ * rectangular node with `@connection()` ports for its structural dependencies:
+ * `model` (the LLM), `memory` (the memory store), and `workspace` (the
+ * workspace/context). Connections are rendered on the bottom side of the node
+ * (DECAF-32 §21.3). Each connection category has a distinct color defined in
+ * the category style registry.
+ *
+ * The single `prompt` input accepts placeholder expressions (§22.4) such as
+ * `{{ $input.brief }}` or `{{ $node["Research"].output.summary }}` that are
+ * resolved at execution time by the placeholder compiler.
+ */
+import { Model } from "@decaf-ts/decorator-validation";
+import "./category-styles";
+/**
+ * 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 Model {
+    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/agent.d.mts

@@ -0,0 +1,44 @@
+/**
+ * @module integrations/graph/nodes/agent
+ * @summary Production Agent node declaration.
+ * @description The Agent node is the primary AI agent entrypoint. It is a
+ * rectangular node with `@connection()` ports for its structural dependencies:
+ * `model` (the LLM), `memory` (the memory store), and `workspace` (the
+ * workspace/context). Connections are rendered on the bottom side of the node
+ * (DECAF-32 §21.3). Each connection category has a distinct color defined in
+ * the category style registry.
+ *
+ * The single `prompt` input accepts placeholder expressions (§22.4) such as
+ * `{{ $input.brief }}` or `{{ $node["Research"].output.summary }}` that are
+ * resolved at execution time by the placeholder compiler.
+ */
+import { Model } from "@decaf-ts/decorator-validation";
+import "./category-styles";
+/**
+ * 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 Model {
+    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/category-styles.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Registers all built-in category styles. Called once at module init.
+ *
+ * Categories define the default visual style for nodes and connection ports.
+ * A node's explicit `color` / `icon` (on `@node()`) overrides the category
+ * style; when omitted, the category style is used.
+ */
+export declare function registerBuiltinCategoryStyles(): void;

package/lib/types/graph/nodes/category-styles.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Registers all built-in category styles. Called once at module init.
+ *
+ * Categories define the default visual style for nodes and connection ports.
+ * A node's explicit `color` / `icon` (on `@node()`) overrides the category
+ * style; when omitted, the category style is used.
+ */
+export declare function registerBuiltinCategoryStyles(): void;

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

@@ -0,0 +1,104 @@
+/**
+ * @module integrations/graph/nodes/flow-control
+ * @summary Production flow-control node kind declarations (DECAF-32 §22.2.2).
+ * @description Canonical `@node`-decorated classes for the ten ALFRED-5
+ * flow-control kinds. These are graph-level macros: the engine's planner
+ * recognises them as ordinary executable nodes (§5.7) but they have no
+ * built-in executors — downstream projects (e.g. ALFRED) register custom
+ * executors or compile them into Mastra composition APIs (§22.2.2).
+ *
+ * The three loop kinds (`core.loop.foreach/while/until`) already have built-in
+ * executors (§5.9) and are NOT redeclared here.
+ */
+import { Model } from "@decaf-ts/decorator-validation";
+/**
+ * If — conditional branch. Evaluates a `ConditionExpression` (§22.3) and
+ * routes the input to the `then` or `else` output.
+ */
+export declare class IfFlowNode extends Model {
+    value: unknown;
+    then: unknown;
+    else: unknown;
+}
+/**
+ * Switch — multi-branch. Routes the input to one of the case output ports
+ * or `default` based on matching conditions. Each case defines a
+ * {@link SwitchCaseCondition} (graphical or code mode) and a dedicated
+ * output port. Cases are stored in `metadata.switch.cases` and the
+ * renderer creates dynamic output ports from them (DECAF-32 §22.2.2).
+ *
+ * The node grows in height as cases are added. Each case gets its own
+ * output port on the right side, labeled with the case label.
+ */
+export declare class SwitchFlowNode extends Model {
+    value: unknown;
+    default: unknown;
+}
+/**
+ * Parallel — splits execution into concurrent branches.
+ */
+export declare class ParallelFlowNode extends Model {
+    value: unknown;
+    branches: unknown[];
+}
+/**
+ * Merge — normalises branch/parallel outputs into a single output.
+ */
+export declare class MergeFlowNode extends Model {
+    values: unknown[];
+    merged: unknown;
+}
+/**
+ * Map — transforms the current input into a new output object.
+ */
+export declare class MapFlowNode extends Model {
+    value: unknown;
+    result: unknown;
+}
+/**
+ * Delay — pauses execution for a configured duration.
+ */
+export declare class DelayFlowNode extends Model {
+    value: unknown;
+    valueOut: unknown;
+}
+/**
+ * Error boundary — try/catch/finally workflow behaviour.
+ */
+export declare class ErrorBoundaryFlowNode extends Model {
+    value: unknown;
+    result: unknown;
+    error: unknown;
+}
+/**
+ * Human approval — suspends execution until a human approves or rejects.
+ */
+export declare class HumanApprovalFlowNode extends Model {
+    value: unknown;
+    approved: unknown;
+    rejected: unknown;
+}
+/**
+ * Return — defines and normalises the final workflow output.
+ */
+export declare class ReturnFlowNode extends Model {
+    value: unknown;
+    result: unknown;
+}
+/**
+ * Code — sandboxed JS/TS code execution (ALFRED-5 §7).
+ *
+ * The engine does not implement the sandbox directly (§22.4). A future
+ * executor may wrap the `CodeSandbox` contract (ALFRED-5 §7.17) as a
+ * pluggable executor. The placeholder syntax (`{{ $input }}`, `{{ $item }}`,
+ * `{{ $index }}`, `{{ $vars }}`, `{{ $node["Name"].output }}`) is Mastra-
+ * agnostic and lives in the downstream project's `modules/core` (ALFRED-6).
+ */
+export declare class CodeFlowNode extends Model {
+    input: unknown;
+    result: unknown;
+}
+/**
+ * All built-in flow-control node constructors.
+ */
+export declare const GRAPH_FLOW_CONTROL_NODES: readonly [typeof IfFlowNode, typeof SwitchFlowNode, typeof ParallelFlowNode, typeof MergeFlowNode, typeof MapFlowNode, typeof DelayFlowNode, typeof ErrorBoundaryFlowNode, typeof HumanApprovalFlowNode, typeof ReturnFlowNode, typeof CodeFlowNode];

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

@@ -0,0 +1,104 @@
+/**
+ * @module integrations/graph/nodes/flow-control
+ * @summary Production flow-control node kind declarations (DECAF-32 §22.2.2).
+ * @description Canonical `@node`-decorated classes for the ten ALFRED-5
+ * flow-control kinds. These are graph-level macros: the engine's planner
+ * recognises them as ordinary executable nodes (§5.7) but they have no
+ * built-in executors — downstream projects (e.g. ALFRED) register custom
+ * executors or compile them into Mastra composition APIs (§22.2.2).
+ *
+ * The three loop kinds (`core.loop.foreach/while/until`) already have built-in
+ * executors (§5.9) and are NOT redeclared here.
+ */
+import { Model } from "@decaf-ts/decorator-validation";
+/**
+ * If — conditional branch. Evaluates a `ConditionExpression` (§22.3) and
+ * routes the input to the `then` or `else` output.
+ */
+export declare class IfFlowNode extends Model {
+    value: unknown;
+    then: unknown;
+    else: unknown;
+}
+/**
+ * Switch — multi-branch. Routes the input to one of the case output ports
+ * or `default` based on matching conditions. Each case defines a
+ * {@link SwitchCaseCondition} (graphical or code mode) and a dedicated
+ * output port. Cases are stored in `metadata.switch.cases` and the
+ * renderer creates dynamic output ports from them (DECAF-32 §22.2.2).
+ *
+ * The node grows in height as cases are added. Each case gets its own
+ * output port on the right side, labeled with the case label.
+ */
+export declare class SwitchFlowNode extends Model {
+    value: unknown;
+    default: unknown;
+}
+/**
+ * Parallel — splits execution into concurrent branches.
+ */
+export declare class ParallelFlowNode extends Model {
+    value: unknown;
+    branches: unknown[];
+}
+/**
+ * Merge — normalises branch/parallel outputs into a single output.
+ */
+export declare class MergeFlowNode extends Model {
+    values: unknown[];
+    merged: unknown;
+}
+/**
+ * Map — transforms the current input into a new output object.
+ */
+export declare class MapFlowNode extends Model {
+    value: unknown;
+    result: unknown;
+}
+/**
+ * Delay — pauses execution for a configured duration.
+ */
+export declare class DelayFlowNode extends Model {
+    value: unknown;
+    valueOut: unknown;
+}
+/**
+ * Error boundary — try/catch/finally workflow behaviour.
+ */
+export declare class ErrorBoundaryFlowNode extends Model {
+    value: unknown;
+    result: unknown;
+    error: unknown;
+}
+/**
+ * Human approval — suspends execution until a human approves or rejects.
+ */
+export declare class HumanApprovalFlowNode extends Model {
+    value: unknown;
+    approved: unknown;
+    rejected: unknown;
+}
+/**
+ * Return — defines and normalises the final workflow output.
+ */
+export declare class ReturnFlowNode extends Model {
+    value: unknown;
+    result: unknown;
+}
+/**
+ * Code — sandboxed JS/TS code execution (ALFRED-5 §7).
+ *
+ * The engine does not implement the sandbox directly (§22.4). A future
+ * executor may wrap the `CodeSandbox` contract (ALFRED-5 §7.17) as a
+ * pluggable executor. The placeholder syntax (`{{ $input }}`, `{{ $item }}`,
+ * `{{ $index }}`, `{{ $vars }}`, `{{ $node["Name"].output }}`) is Mastra-
+ * agnostic and lives in the downstream project's `modules/core` (ALFRED-6).
+ */
+export declare class CodeFlowNode extends Model {
+    input: unknown;
+    result: unknown;
+}
+/**
+ * All built-in flow-control node constructors.
+ */
+export declare const GRAPH_FLOW_CONTROL_NODES: readonly [typeof IfFlowNode, typeof SwitchFlowNode, typeof ParallelFlowNode, typeof MergeFlowNode, typeof MapFlowNode, typeof DelayFlowNode, typeof ErrorBoundaryFlowNode, typeof HumanApprovalFlowNode, typeof ReturnFlowNode, typeof CodeFlowNode];

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

@@ -0,0 +1,16 @@
+/**
+ * @module integrations/graph/nodes
+ * @summary Production node kind declarations (DECAF-32 §22.2).
+ * @description Canonical `@node`-decorated classes for the ALFRED-5 node kind
+ * taxonomy. These are the framework's built-in node definitions — triggers
+ * (§22.2.1), flow-control/utility nodes (§22.2.2–22.2.3), and the Agent node
+ * (§21.3). The three loop kinds (`core.loop.foreach/while/until`) already have
+ * built-in executors (§5.9) and are not redeclared here.
+ *
+ * Consumers (for-angular, ALFRED, etc.) import these declarations to populate
+ * node palettes, registries, and reference snapshots.
+ */
+export * from "./category-styles.d.cts";
+export * from "./triggers.d.cts";
+export * from "./flow-control.d.cts";
+export * from "./agent.d.cts";

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

@@ -0,0 +1,16 @@
+/**
+ * @module integrations/graph/nodes
+ * @summary Production node kind declarations (DECAF-32 §22.2).
+ * @description Canonical `@node`-decorated classes for the ALFRED-5 node kind
+ * taxonomy. These are the framework's built-in node definitions — triggers
+ * (§22.2.1), flow-control/utility nodes (§22.2.2–22.2.3), and the Agent node
+ * (§21.3). The three loop kinds (`core.loop.foreach/while/until`) already have
+ * built-in executors (§5.9) and are not redeclared here.
+ *
+ * Consumers (for-angular, ALFRED, etc.) import these declarations to populate
+ * node palettes, registries, and reference snapshots.
+ */
+export * from "./category-styles.d.mts";
+export * from "./triggers.d.mts";
+export * from "./flow-control.d.mts";
+export * from "./agent.d.mts";

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

@@ -0,0 +1,53 @@
+/**
+ * @module integrations/graph/nodes/triggers
+ * @summary Production trigger node kind declarations (DECAF-32 §22.2.1).
+ * @description Canonical `@node`-decorated classes for the six ALFRED-5 trigger
+ * kinds. Triggers are metadata-only entrypoints: they define how a workflow
+ * starts and produce a trigger payload on their `@output` ports. They have no
+ * `@input` ports (nothing feeds a trigger) and no built-in executors — the
+ * engine's execution model starts from workflow inputs (§5.8) and treats
+ * trigger nodes as metadata-only entrypoints.
+ */
+import { Model } from "@decaf-ts/decorator-validation";
+/**
+ * Manual trigger — user clicks Run; input form generated from `inputSchema`.
+ */
+export declare class ManualTriggerNode extends Model {
+    payload: unknown;
+}
+/**
+ * Webhook trigger — HTTP request received; path/method/auth/responseMode config.
+ */
+export declare class WebhookTriggerNode extends Model {
+    payload: unknown;
+}
+/**
+ * Schedule trigger — cron-like schedule; timezone + payload config.
+ */
+export declare class ScheduleTriggerNode extends Model {
+    payload: unknown;
+}
+/**
+ * Event trigger — internal event bus topic subscriber.
+ */
+export declare class EventTriggerNode extends Model {
+    payload: unknown;
+}
+/**
+ * Form trigger — generated public/internal form; field definitions.
+ */
+export declare class FormTriggerNode extends Model {
+    payload: unknown;
+}
+/**
+ * Chat trigger — chat message entrypoint; message/sessionId/userId schema.
+ */
+export declare class ChatTriggerNode extends Model {
+    message: string;
+    sessionId: string;
+    userId: string;
+}
+/**
+ * All built-in trigger node constructors.
+ */
+export declare const GRAPH_TRIGGER_NODES: readonly [typeof ManualTriggerNode, typeof WebhookTriggerNode, typeof ScheduleTriggerNode, typeof EventTriggerNode, typeof FormTriggerNode, typeof ChatTriggerNode];

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

@@ -0,0 +1,53 @@
+/**
+ * @module integrations/graph/nodes/triggers
+ * @summary Production trigger node kind declarations (DECAF-32 §22.2.1).
+ * @description Canonical `@node`-decorated classes for the six ALFRED-5 trigger
+ * kinds. Triggers are metadata-only entrypoints: they define how a workflow
+ * starts and produce a trigger payload on their `@output` ports. They have no
+ * `@input` ports (nothing feeds a trigger) and no built-in executors — the
+ * engine's execution model starts from workflow inputs (§5.8) and treats
+ * trigger nodes as metadata-only entrypoints.
+ */
+import { Model } from "@decaf-ts/decorator-validation";
+/**
+ * Manual trigger — user clicks Run; input form generated from `inputSchema`.
+ */
+export declare class ManualTriggerNode extends Model {
+    payload: unknown;
+}
+/**
+ * Webhook trigger — HTTP request received; path/method/auth/responseMode config.
+ */
+export declare class WebhookTriggerNode extends Model {
+    payload: unknown;
+}
+/**
+ * Schedule trigger — cron-like schedule; timezone + payload config.
+ */
+export declare class ScheduleTriggerNode extends Model {
+    payload: unknown;
+}
+/**
+ * Event trigger — internal event bus topic subscriber.
+ */
+export declare class EventTriggerNode extends Model {
+    payload: unknown;
+}
+/**
+ * Form trigger — generated public/internal form; field definitions.
+ */
+export declare class FormTriggerNode extends Model {
+    payload: unknown;
+}
+/**
+ * Chat trigger — chat message entrypoint; message/sessionId/userId schema.
+ */
+export declare class ChatTriggerNode extends Model {
+    message: string;
+    sessionId: string;
+    userId: string;
+}
+/**
+ * All built-in trigger node constructors.
+ */
+export declare const GRAPH_TRIGGER_NODES: readonly [typeof ManualTriggerNode, typeof WebhookTriggerNode, typeof ScheduleTriggerNode, typeof EventTriggerNode, typeof FormTriggerNode, typeof ChatTriggerNode];

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

@@ -134,6 +134,10 @@ export interface GraphLoopMetadata {
 }
 /**
  * Definition of a condition evaluated by the loop condition evaluator.
+ *
+ * When the condition object carries an `op` field (see {@link ConditionExpression}),
+ * the {@link GraphConditionEvaluator} dispatches to the {@link ConditionExpressionEvaluator}
+ * instead of the built-in `type`-based switch.
  */
 export interface GraphConditionDefinition {
     type: "truthy" | "falsy" | "equals" | "notEquals" | "greaterThan" | "greaterThanOrEqual" | "lessThan" | "lessThanOrEqual" | "exists" | "custom";
@@ -142,6 +146,104 @@ export interface GraphConditionDefinition {
     evaluator?: string;
     metadata?: Record<string, unknown>;
 }
+/**
+ * A value reference inside a {@link ConditionExpression}.
+ *
+ * - `{ const: x }` — a literal constant.
+ * - `{ path: "a.b" }` — a dotted path resolved against the current loop state.
+ * - `{ step: "nodeId", path: "out" }` — a cross-node reference (resolved from
+ *   the execution state in v1; reserved for future multi-step evaluation).
+ */
+export type ExprValue = {
+    const: unknown;
+} | {
+    path: string;
+} | {
+    step: string;
+    path: string;
+};
+/**
+ * Declarative, serializable condition expression DSL (ALFRED-5 §8 / DECAF-32 §22.3).
+ *
+ * The engine's {@link GraphConditionEvaluator} recognises this DSL when the
+ * condition object carries an `op` field and dispatches to the
+ * {@link ConditionExpressionEvaluator}.
+ */
+export type ConditionExpression = {
+    op: "eq";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "neq";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "gt";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "gte";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "lt";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "lte";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "and";
+    conditions: ConditionExpression[];
+} | {
+    op: "or";
+    conditions: ConditionExpression[];
+} | {
+    op: "not";
+    condition: ConditionExpression;
+} | {
+    op: "exists";
+    value: ExprValue;
+};
+/**
+ * A code-based condition evaluated in a restricted VM sandbox (§22.4).
+ *
+ * The engine does NOT implement the sandbox directly — a pluggable
+ * {@link CodeSandboxEvaluator} must be registered for code conditions to work.
+ * The code must follow the same restrictions as the Code Node (§22.4):
+ * no system API access, placeholder syntax for workflow data references.
+ */
+export interface CodeCondition {
+    type: "code";
+    code: string;
+    language?: "javascript" | "typescript";
+}
+/**
+ * A condition on a Switch case — either a declarative
+ * {@link ConditionExpression} (graphical mode) or a {@link CodeCondition}
+ * (code mode).
+ */
+export type SwitchCaseCondition = ConditionExpression | CodeCondition;
+/**
+ * A single case in a Switch node.
+ *
+ * Each case pairs a condition with a dedicated output port. When the
+ * condition evaluates to `true`, the input is routed to `outputPort`.
+ */
+export interface SwitchCase {
+    id: string;
+    label: string;
+    condition: SwitchCaseCondition;
+    outputPort: string;
+}
+/**
+ * Metadata for a Switch node, stored in `metadata.switch`.
+ */
+export interface SwitchNodeMetadata {
+    cases: SwitchCase[];
+    defaultPort?: string;
+}
 /**
  * Pinning metadata attached to a node via `@pinnable()`.
  */

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

@@ -134,6 +134,10 @@ export interface GraphLoopMetadata {
 }
 /**
  * Definition of a condition evaluated by the loop condition evaluator.
+ *
+ * When the condition object carries an `op` field (see {@link ConditionExpression}),
+ * the {@link GraphConditionEvaluator} dispatches to the {@link ConditionExpressionEvaluator}
+ * instead of the built-in `type`-based switch.
  */
 export interface GraphConditionDefinition {
     type: "truthy" | "falsy" | "equals" | "notEquals" | "greaterThan" | "greaterThanOrEqual" | "lessThan" | "lessThanOrEqual" | "exists" | "custom";
@@ -142,6 +146,104 @@ export interface GraphConditionDefinition {
     evaluator?: string;
     metadata?: Record<string, unknown>;
 }
+/**
+ * A value reference inside a {@link ConditionExpression}.
+ *
+ * - `{ const: x }` — a literal constant.
+ * - `{ path: "a.b" }` — a dotted path resolved against the current loop state.
+ * - `{ step: "nodeId", path: "out" }` — a cross-node reference (resolved from
+ *   the execution state in v1; reserved for future multi-step evaluation).
+ */
+export type ExprValue = {
+    const: unknown;
+} | {
+    path: string;
+} | {
+    step: string;
+    path: string;
+};
+/**
+ * Declarative, serializable condition expression DSL (ALFRED-5 §8 / DECAF-32 §22.3).
+ *
+ * The engine's {@link GraphConditionEvaluator} recognises this DSL when the
+ * condition object carries an `op` field and dispatches to the
+ * {@link ConditionExpressionEvaluator}.
+ */
+export type ConditionExpression = {
+    op: "eq";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "neq";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "gt";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "gte";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "lt";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "lte";
+    left: ExprValue;
+    right: ExprValue;
+} | {
+    op: "and";
+    conditions: ConditionExpression[];
+} | {
+    op: "or";
+    conditions: ConditionExpression[];
+} | {
+    op: "not";
+    condition: ConditionExpression;
+} | {
+    op: "exists";
+    value: ExprValue;
+};
+/**
+ * A code-based condition evaluated in a restricted VM sandbox (§22.4).
+ *
+ * The engine does NOT implement the sandbox directly — a pluggable
+ * {@link CodeSandboxEvaluator} must be registered for code conditions to work.
+ * The code must follow the same restrictions as the Code Node (§22.4):
+ * no system API access, placeholder syntax for workflow data references.
+ */
+export interface CodeCondition {
+    type: "code";
+    code: string;
+    language?: "javascript" | "typescript";
+}
+/**
+ * A condition on a Switch case — either a declarative
+ * {@link ConditionExpression} (graphical mode) or a {@link CodeCondition}
+ * (code mode).
+ */
+export type SwitchCaseCondition = ConditionExpression | CodeCondition;
+/**
+ * A single case in a Switch node.
+ *
+ * Each case pairs a condition with a dedicated output port. When the
+ * condition evaluates to `true`, the input is routed to `outputPort`.
+ */
+export interface SwitchCase {
+    id: string;
+    label: string;
+    condition: SwitchCaseCondition;
+    outputPort: string;
+}
+/**
+ * Metadata for a Switch node, stored in `metadata.switch`.
+ */
+export interface SwitchNodeMetadata {
+    cases: SwitchCase[];
+    defaultPort?: string;
+}
 /**
  * Pinning metadata attached to a node via `@pinnable()`.
  */