@solidxai/core 0.1.12-beta.0 → 0.1.12-beta.2

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

@@ -0,0 +1,635 @@
+# 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?