@solidxai/core 0.1.13-beta.12 → 0.1.13-beta.13

package/docs/workflow/workflow-node-type-contracts.md

@@ -1,635 +0,0 @@
-# Workflow Node Type Contracts
-
-This document defines the v1 node type contract for the `workflow-builder` module.
-
-It covers:
-
-- the common contract every node type must satisfy
-- the five agreed v1 node types
-- expression/interpolation choices
-- pluggability using SolidX-style providers
-
-## Agreed V1 Node Types
-
-- `log.write`
-- `http.request`
-- `if`
-- `forEach`
-- `parallel`
-
-Deferred node types:
-
-- `switch`
-- `loopUntil`
-- `forEachItem`
-- `subflow`
-- database/query tasks
-- notification tasks beyond logging
-
-## Common Node Type Registry Contract
-
-Every node type should be registered through a provider contract rather than hard-coded into the workflow engine.
-
-Suggested registry fields:
-
-- `type`
-- `kind`
-- `displayName`
-- `category`
-- `description`
-- `configurationSchema`
-- `uiSchema`
-- `outputSchema`
-- `runtimeHandler`
-- `documentation`
-
-Suggested TypeScript-style interface:
-
-```ts
-export type WorkflowNodeKind = "task" | "control" | "subflow";
-
-export interface WorkflowNodeExecutionContext {
-  workflow: Record<string, any>;
-  execution: Record<string, any>;
-  trigger?: Record<string, any>;
-  inputs: Record<string, any>;
-  outputs: Record<string, any>;
-  step?: Record<string, any>;
-  log: (message: string, metadata?: Record<string, any>) => Promise<void>;
-}
-
-export interface WorkflowNodeExecutionResult {
-  status: "success" | "failed" | "skipped";
-  outputs?: Record<string, any>;
-  error?: {
-    message: string;
-    code?: string;
-    details?: Record<string, any>;
-  };
-}
-
-export interface WorkflowNodeTypeProvider<TConfig = Record<string, any>> {
-  type(): string;
-  kind(): WorkflowNodeKind;
-  displayName(): string;
-  category(): string;
-  description(): string;
-  configurationSchema(): Record<string, any>;
-  uiSchema?(): Record<string, any>;
-  outputSchema?(): Record<string, any>;
-  execute?(config: TConfig, ctxt: WorkflowNodeExecutionContext): Promise<WorkflowNodeExecutionResult>;
-}
-```
-
-Control nodes may not execute in the same way as runnable task nodes. They can either:
-
-- expose a specialized control handler, or
-- use the same `execute` contract and delegate child traversal to the engine
-
-V1 recommendation: the engine owns traversal for `if`, `forEach`, and `parallel`; the node provider owns schema, validation metadata, and control-specific evaluation rules.
-
-## SolidX Pluggability Pattern
-
-SolidX already uses a provider discovery pattern for selection providers, computed field providers, dashboard widget data providers, settings providers, mail providers, SMS providers, and other extension points.
-
-The pattern is:
-
-- define an interface for the provider contract
-- define a decorator that marks provider classes with metadata
-- implement providers as Nest injectable classes
-- discover decorated providers at application bootstrap
-- register discovered providers in a registry
-- resolve providers by `name()` or type-specific key at runtime
-
-Relevant existing examples in SolidX:
-
-- `SelectionProvider`
-- `ComputedFieldProvider`
-- `DashboardWidgetDataProvider`
-- `SolidIntrospectService`
-- `SolidRegistry`
-
-Recommended workflow equivalent:
-
-```ts
-export const IS_WORKFLOW_NODE_TYPE_PROVIDER = "IS_WORKFLOW_NODE_TYPE_PROVIDER";
-
-export const WorkflowNodeTypeProvider = () => {
-  return (target: Function) => {
-    Reflect.defineMetadata(IS_WORKFLOW_NODE_TYPE_PROVIDER, true, target);
-  };
-};
-```
-
-Example provider:
-
-```ts
-@WorkflowNodeTypeProvider()
-@Injectable()
-export class HttpRequestWorkflowNodeProvider implements WorkflowNodeTypeProvider<HttpRequestNodeConfig> {
-  type(): string {
-    return "http.request";
-  }
-
-  kind(): WorkflowNodeKind {
-    return "task";
-  }
-
-  displayName(): string {
-    return "HTTP Request";
-  }
-
-  category(): string {
-    return "Integration";
-  }
-
-  description(): string {
-    return "Makes an HTTP request and exposes response details as outputs.";
-  }
-
-  configurationSchema(): Record<string, any> {
-    return {
-      type: "object",
-      required: ["uri"],
-      properties: {
-        method: { type: "string", enum: ["GET", "POST", "PUT", "PATCH", "DELETE"], default: "GET" },
-        uri: { type: "string" },
-        headers: { type: "object", default: {} },
-        body: {},
-      },
-    };
-  }
-
-  outputSchema(): Record<string, any> {
-    return {
-      type: "object",
-      properties: {
-        statusCode: { type: "number" },
-        body: {},
-        headers: { type: "object" },
-        uri: { type: "string" },
-        method: { type: "string" },
-      },
-    };
-  }
-
-  async execute(config: HttpRequestNodeConfig, ctxt: WorkflowNodeExecutionContext): Promise<WorkflowNodeExecutionResult> {
-    // Runtime implementation detail to be finalized during build.
-    return { status: "success", outputs: {} };
-  }
-}
-```
-
-Discovery should follow the existing SolidX flow:
-
-- `SolidIntrospectService`-style bootstrap scanning finds decorated providers
-- the workflow module registers them into a `WorkflowNodeTypeRegistry`
-- the runtime resolves providers by `node.type`
-- only providers from currently imported/registered Nest modules are available
-
-## Expression and Interpolation Strategy
-
-We need one expression system for all workflow definitions.
-
-Supported use cases:
-
-- interpolate values inside strings
-- evaluate boolean conditions
-- resolve structured values
-- transform simple data
-- access execution context safely
-
-Minimum context:
-
-- `inputs`
-- `outputs`
-- `workflow`
-- `execution`
-- `trigger`
-- `step`
-
-Recommended syntax:
-
-```text
-{{ inputs.uri }}
-{{ outputs.makeRequest.statusCode }}
-{{ outputs.makeRequest.statusCode == 200 }}
-{{ step.value }}
-```
-
-This keeps us close to Kestra and makes seeded workflow YAML familiar.
-
-### Complex Expressions
-
-For v1, we should support two expression modes:
-
-- string interpolation
-- expression-only evaluation
-
-String interpolation:
-
-```json
-{
-  "message": "Status Code: {{ outputs.makeRequest.statusCode }}"
-}
-```
-
-Expression-only evaluation:
-
-```json
-{
-  "condition": "{{ outputs.makeRequest.statusCode == 200 }}"
-}
-```
-
-Recommended v1 expression capabilities:
-
-- property access
-- equality and comparison operators
-- boolean operators
-- numeric literals
-- string literals
-- array/object traversal
-- a small allowlist of helper functions
-
-Recommended v1 helper functions:
-
-- `json(value)`
-- `length(value)`
-- `default(value, fallback)`
-- `contains(value, search)`
-- `date(value, format)` later if needed
-- `secret(key)` later when secret handling is implemented
-
-Security rule:
-
-- expressions must be evaluated by a safe expression engine or a constrained evaluator
-- no arbitrary JavaScript execution
-- no filesystem, network, process, or module access from expressions
-
-Open implementation choice:
-
-- adopt an existing safe expression/template engine
-- implement a constrained expression evaluator for the first release
-
-Recommendation:
-
-- keep `{{ }}` as the DSL syntax
-- choose or build a constrained evaluator behind it
-- treat expression resolution as a service so the underlying engine can change without changing the workflow DSL
-
-## Node Type: `log.write`
-
-### Purpose
-
-Writes an interpolated message into the workflow execution log.
-
-### Kind
-
-`task`
-
-### Required Configuration
-
-- `message`
-
-### Optional Configuration
-
-- `level`
-- `metadata`
-
-### Configuration Shape
-
-```json
-{
-  "message": "Status Code: {{ outputs.makeRequest.statusCode }}",
-  "level": "info",
-  "metadata": {}
-}
-```
-
-### Output Schema
-
-No required outputs.
-
-Optional output:
-
-- `message`
-
-### Runtime Behavior
-
-- resolve expressions in `message`
-- write the message to execution logs
-- return success unless logging fails
-
-### Failure Behavior
-
-- fail the node if expression resolution fails
-- fail the node if log persistence fails
-
-### Validation Rules
-
-- `message` is required
-- `level` must be one of `debug`, `info`, `warn`, `error` if provided
-
-## Node Type: `http.request`
-
-### Purpose
-
-Makes an HTTP request and exposes response data to downstream nodes.
-
-### Kind
-
-`task`
-
-### Required Configuration
-
-- `uri`
-
-### Optional Configuration
-
-- `method`
-- `headers`
-- `query`
-- `body`
-- `timeoutMs`
-- `successStatusCodes`
-
-### Configuration Shape
-
-```json
-{
-  "method": "GET",
-  "uri": "{{ inputs.uri }}",
-  "headers": {},
-  "query": {},
-  "body": null,
-  "timeoutMs": 30000,
-  "successStatusCodes": [200, 201, 202, 204]
-}
-```
-
-### Output Schema
-
-- `statusCode`
-- `body`
-- `headers`
-- `uri`
-- `method`
-- `durationMs`
-
-### Runtime Behavior
-
-- resolve expressions in config
-- execute the HTTP request
-- capture status code, response body, headers, final URI, method, and duration
-- expose outputs as `outputs.<nodeId>.*`
-
-### Failure Behavior
-
-V1 recommendation:
-
-- transport errors fail the node
-- timeout errors fail the node
-- HTTP status codes outside `successStatusCodes` fail the node but still capture response outputs where possible
-
-This keeps failure semantics predictable while still allowing users to override success ranges.
-
-### Validation Rules
-
-- `uri` is required
-- `method` defaults to `GET`
-- `method` must be one of `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
-- `headers` must be an object if provided
-- `query` must be an object if provided
-- `timeoutMs` must be a positive number if provided
-- `successStatusCodes` must be an array of HTTP status numbers if provided
-
-## Node Type: `if`
-
-### Purpose
-
-Evaluates a condition and executes either the `then` or `else` node array.
-
-### Kind
-
-`control`
-
-### Required Configuration
-
-- `condition`
-- `then`
-
-### Optional Configuration
-
-- `else`
-
-### Configuration Shape
-
-```json
-{
-  "condition": "{{ outputs.makeRequest.statusCode == 200 }}"
-}
-```
-
-Child arrays:
-
-- `then`
-- `else`
-
-### Output Schema
-
-No direct outputs in v1.
-
-### Runtime Behavior
-
-- evaluate `condition` as a boolean expression
-- execute `then` nodes when true
-- execute `else` nodes when false and present
-- mark skipped branch nodes as skipped where execution records are created
-
-### Failure Behavior
-
-- fail the node if condition evaluation fails
-- fail the node if the selected branch fails, unless future error handling says otherwise
-
-### Validation Rules
-
-- `condition` is required
-- `condition` must evaluate to boolean
-- `then` must be a node array
-- `else` must be a node array if provided
-
-## Node Type: `forEach`
-
-### Purpose
-
-Executes child nodes once for each item in an array.
-
-### Kind
-
-`control`
-
-### Required Configuration
-
-- `values`
-- `children`
-
-### Optional Configuration
-
-- `concurrency`
-- `continueOnItemFailure`
-
-### Configuration Shape
-
-```json
-{
-  "values": "{{ inputs.customerIds }}",
-  "concurrency": 1,
-  "continueOnItemFailure": false
-}
-```
-
-Child array:
-
-- `children`
-
-### Runtime Context
-
-Each iteration exposes:
-
-- `step.value`
-- `step.index`
-
-Example:
-
-```text
-{{ step.value }}
-{{ step.index }}
-```
-
-### Output Schema
-
-Suggested v1 aggregate outputs:
-
-- `count`
-- `successCount`
-- `failedCount`
-- `items`
-
-### Runtime Behavior
-
-- evaluate `values`
-- require the resolved value to be an array
-- execute `children` once per item
-- expose current item as `step.value`
-- expose current index as `step.index`
-- aggregate per-item results
-
-### Failure Behavior
-
-V1 recommendation:
-
-- default behavior fails the `forEach` node on the first failed item
-- `continueOnItemFailure: true` allows all items to run and fails the node at the end if any item failed
-
-### Validation Rules
-
-- `values` is required
-- `children` must be a non-empty node array
-- `concurrency` must be a positive number if provided
-- `continueOnItemFailure` must be boolean if provided
-
-## Node Type: `parallel`
-
-### Purpose
-
-Executes multiple branches concurrently.
-
-### Kind
-
-`control`
-
-### Required Configuration
-
-- `branches`
-
-### Optional Configuration
-
-- `failFast`
-
-### Configuration Shape
-
-```json
-{
-  "failFast": true
-}
-```
-
-Branch shape:
-
-```json
-{
-  "id": "checkDocs",
-  "nodes": []
-}
-```
-
-### Output Schema
-
-Suggested v1 aggregate outputs:
-
-- `branchCount`
-- `successCount`
-- `failedCount`
-- `branches`
-
-### Runtime Behavior
-
-- execute each branch concurrently
-- execute nodes inside each branch sequentially
-- aggregate branch results
-
-### Failure Behavior
-
-V1 recommendation:
-
-- `failFast: true` stops scheduling remaining branches where possible after a branch fails
-- already running branches may complete
-- `failFast: false` runs all branches and fails at the end if any branch failed
-
-### Validation Rules
-
-- `branches` must be a non-empty array
-- every branch must have a unique `id`
-- every branch must have a `nodes` array
-- `failFast` must be boolean if provided
-
-## Cross-Cutting Validation Rules
-
-Definition-time validation should check:
-
-- every node has a unique `id` within the workflow
-- every node has a known registered `type`
-- node `kind` matches the registered provider kind
-- required configuration fields are present
-- node config satisfies the provider `configurationSchema`
-- child node arrays contain valid nodes
-- expression syntax is valid where expressions are used
-- references to known prior outputs are valid where statically knowable
-
-Some expression references cannot be fully validated until runtime, especially inside control-flow nodes.
-
-## Cross-Cutting Runtime Rules
-
-- node definitions hold design-time config only
-- runtime outputs, logs, state, retries, and errors belong to execution records
-- expressions are resolved immediately before a node executes
-- each node execution should record input context, output payload, status, timestamps, and error summary
-- disabled nodes should produce skipped step executions when execution records are created
-
-## Open Questions
-
-- Which expression engine should back `{{ }}`?
-- Should `forEach` expose loop data as `step.value` or `taskrun.value` to stay closer to Kestra?
-- Should `parallel.failFast` default to true or false?
-- Should `http.request` treat all `2xx` statuses as success by default instead of a fixed list?