@solidxai/core 0.1.13-beta.2 → 0.1.13-beta.4

package/docs/workflow/workflow-module-brd.md

@@ -0,0 +1,185 @@
+# Workflow Builder Module BRD
+
+## Purpose
+
+Build a reusable SolidX module named `workflow-builder` that allows teams to define, execute, monitor, seed, import, and share workflows inside SolidX applications.
+
+The module should be self-contained enough to be developed in this consuming project first and later exported or distributed to other SolidX projects.
+
+## Problem Statement
+
+Teams need a reusable way to orchestrate multi-step business and technical processes across systems. Today, these processes are often spread across scripts, cron jobs, ad hoc integrations, or manual operational steps. That creates low visibility, weak reuse, and brittle execution.
+
+We want a module that provides:
+
+- a workflow definition model
+- a builder experience
+- an execution engine
+- reusable step/action types
+- observability into runs
+- a shareable YAML-based workflow definition format
+
+## Goals
+
+- Provide a reusable workflow engine and builder as a SolidX module
+- Support both visual and code-friendly workflow definition
+- Represent workflows as JSON so they can be seeded, exported, imported, and shared
+- Support workflow inputs, outputs, triggers, expressions, and control-flow constructs
+- Separate workflow definition from workflow execution
+- Support extensible task and trigger types
+- Support runtime observability including status, logs, and outputs
+- Support blueprint/template style workflow starters
+
+## Non-Goals For V1
+
+- Full Kestra-level feature parity
+- A full revision browser and rollback UX
+- Distributed execution across many worker nodes
+- A large marketplace of task plugins on day one
+- Complex tenancy / cross-project federation
+
+## Primary Users
+
+- Application developers who define and maintain workflows
+- Operations or admin users who execute and monitor workflows
+- Solution builders who seed and distribute reusable workflow packs
+- Future less-technical users who may use a visual builder
+
+## Core Capabilities
+
+### 1. Workflow Definition
+
+Users can create a workflow with:
+
+- stable identity
+- display metadata
+- typed inputs
+- tasks / control-flow nodes
+- triggers
+- flow-level outputs
+
+### 2. Workflow Builder
+
+Users can define workflows through:
+
+- structured UI forms
+- topology / builder style interfaces over time
+- direct JSON or code-oriented editing over time
+
+### 3. Execution Engine
+
+Users can run workflows:
+
+- manually
+- via triggers
+- with runtime inputs
+
+The engine should execute tasks, resolve expressions, track state, and store outputs and logs.
+
+### 4. Monitoring
+
+Users can inspect:
+
+- workflow execution status
+- step execution status
+- logs
+- outputs
+- timestamps and runtime metadata
+
+### 5. Reuse and Distribution
+
+Users can:
+
+- seed workflows from module metadata or JSON assets
+- export workflow definitions
+- import workflow definitions
+- create blueprint/template workflows
+
+## Functional Requirements
+
+### Workflow Definitions
+
+- The system must store workflows as structured YAML definitions.
+- The system must support workflow identity independent of display name.
+- The system must support workflow grouping, likely via namespace or folder concepts.
+- The system must support a published current definition.
+- The system should support immutable execution-time snapshots of the definition used for a run.
+
+### Inputs and Outputs
+
+- The system must support typed workflow inputs.
+- The system must support default values and required flags.
+- The system must support task outputs and flow outputs.
+- The system must support output references across downstream tasks.
+
+### Task Model
+
+- The system must treat `node` as the universal workflow building block.
+- The system must distinguish node `kind` from node `type`.
+- The system must support runnable steps.
+- The system must support control-flow steps such as conditional branches and loops.
+- The system must support nested step structures where needed.
+- The system must use ordered node arrays with nested child arrays for control-flow structures in v1.
+- The system must support extensible step types with type-specific config.
+- The v1 task node catalog must include `log.write` and `http.request`.
+- The v1 control node catalog must include `if`, `forEach`, and `parallel`.
+
+### Triggers
+
+- The system must support multiple triggers per workflow.
+- The system must support trigger-specific configuration.
+- The system must support trigger-provided input values.
+- The system must support manual execution independent of triggers.
+
+### Expressions
+
+- The system must support expressions in workflow config.
+- The system must support references to inputs, outputs, execution context, and trigger context.
+- The system should support design-time validation where feasible.
+
+### Executions
+
+- The system must create a workflow execution record per run.
+- The system must create step execution records per executed step.
+- The system must persist execution state transitions.
+- The system must persist logs and outputs.
+- The system must preserve the exact workflow definition snapshot used for the run.
+
+### Secrets
+
+- The system must support secure secret references in workflow configuration.
+- The system must not expose resolved secret values in stored definitions or logs.
+
+### Blueprints and Seeding
+
+- The system must support seeded workflow definitions.
+- The system must support blueprint/template workflows for faster adoption.
+- The system should track seed source metadata and seed version.
+
+## Success Criteria
+
+- A developer can define a workflow in JSON and seed it into a project.
+- An admin can execute a workflow manually with inputs.
+- A workflow can run multiple tasks and pass outputs between them.
+- A workflow can include at least one control-flow pattern in v1 or early v1.x.
+- A workflow execution records exact runtime state, outputs, and logs.
+- Workflow definitions are portable between SolidX projects.
+
+## Proposed V1 Scope
+
+- Workflow definition CRUD
+- Typed inputs and flow outputs
+- Runnable task node support: `log.write`, `http.request`
+- Initial control-flow node support: `if`, `forEach`, `parallel`
+- Manual execution
+- Basic trigger support
+- Execution tracking and logs
+- Seed/import/export support
+- YAML definition model
+
+## Open Product Questions
+
+- How much of the v1 authoring experience should be form-based versus canvas-based?
+- Should subflows be in v1 or phase 2?
+- Should workflow grouping use namespace, folders, or both?
+- How much blueprint functionality belongs in v1 versus later?

package/docs/workflow/workflow-module-domain-model.md

@@ -0,0 +1,252 @@
+# Workflow Builder Domain Model
+
+## Overview
+
+This is the initial domain model proposal for the reusable `workflow-builder` SolidX module.
+
+The main design rule is:
+
+- workflow definitions are not the same thing as workflow executions
+
+## Core Aggregates
+
+### WorkflowDefinition
+
+Represents the current reusable workflow definition.
+
+Suggested attributes:
+
+- `id`
+- `key`
+- `displayName`
+- `namespace`
+- `description`
+- `status`
+- `definitionVersion`
+- `definitionChecksum`
+- `definitionYaml`
+- `seedSource`
+- `seedVersion`
+- `isSeeded`
+- `createdAt`
+- `updatedAt`
+
+### WorkflowExecution
+
+Represents a single run of a workflow.
+
+Suggested attributes:
+
+- `id`
+- `workflowDefinitionId`
+- `workflowKey`
+- `status`
+- `triggerType`
+- `startedAt`
+- `finishedAt`
+- `inputPayload`
+- `resolvedContext`
+- `definitionVersion`
+- `definitionChecksum`
+- `definitionSnapshot`
+- `errorSummary`
+
+### StepExecution
+
+Represents the runtime record for an executed step.
+
+Suggested attributes:
+
+- `id`
+- `workflowExecutionId`
+- `stepId`
+- `stepType`
+- `parentStepExecutionId`
+- `status`
+- `startedAt`
+- `finishedAt`
+- `attemptNumber`
+- `inputContext`
+- `outputPayload`
+- `logSummary`
+- `errorSummary`
+
+## Definition Submodels
+
+### WorkflowInput
+
+- `id`
+- `type`
+- `displayName`
+- `description`
+- `required`
+- `defaultValue`
+- `schema`
+
+### WorkflowOutput
+
+- `id`
+- `type`
+- `valueExpression`
+- `description`
+
+### WorkflowTrigger
+
+- `id`
+- `type`
+- `name`
+- `enabled`
+- `configuration`
+- `inputOverrides`
+
+### WorkflowNode
+
+Base concept for a node in a workflow definition.
+
+Suggested common fields:
+
+- `id`
+- `name`
+- `type`
+- `kind`
+- `configuration`
+- `description`
+- `disabled`
+- `timeout`
+- `retryPolicy`
+- `onError`
+- `metadata`
+
+Where `kind` can initially distinguish:
+
+- `task`
+- `control`
+- `subflow`
+
+## Runtime Supporting Concepts
+
+### ExecutionContext
+
+Holds runtime-accessible values:
+
+- inputs
+- step outputs
+- flow outputs
+- workflow metadata
+- execution metadata
+- trigger metadata
+
+### SecretReference
+
+Represents a secure pointer rather than a literal secret.
+
+Suggested fields:
+
+- `provider`
+- `key`
+- `path`
+
+### BlueprintDefinition
+
+Represents a starter workflow template.
+
+Suggested attributes:
+
+- `id`
+- `key`
+- `displayName`
+- `description`
+- `tags`
+- `definitionYaml`
+- `source`
+
+## Relationship View
+
+- A `WorkflowDefinition` has many `WorkflowInput`
+- A `WorkflowDefinition` has many `WorkflowOutput`
+- A `WorkflowDefinition` has many `WorkflowTrigger`
+- A `WorkflowDefinition` has many `WorkflowNode`
+- A `WorkflowDefinition` has many `WorkflowExecution`
+- A `WorkflowExecution` has many `StepExecution`
+
+## Modeling Decision: Revisions
+
+Current recommendation:
+
+- do not require a full `WorkflowRevision` aggregate in v1
+- do preserve `definitionVersion`, `definitionChecksum`, and `definitionSnapshot` on execution
+
+Possible later addition:
+
+- `WorkflowRevision`
+- `WorkflowRevisionDiff`
+- `WorkflowReplayRequest`
+
+## Modeling Decision: Nodes vs Flat Steps
+
+We should model workflow steps as nodes, not as a flat ordered list only, because we need to support:
+
+- conditional branches
+- loops
+- nested structures
+- parallel blocks
+- subflows
+
+This does not force us into a fully general graph database style model, but it does mean the persisted workflow DSL must support nesting and references.
+
+Agreed v1 traversal shape:
+
+- ordered arrays for sequential execution
+- nested child arrays owned by control nodes
+- no freeform graph model in v1
+
+## Modeling Decision: Registries
+
+Task and trigger types should be externally registrable concepts, not enum values frozen into the core forever.
+
+Likely supporting registry models:
+
+- `TaskTypeDefinition`
+- `TriggerTypeDefinition`
+
+Suggested attributes:
+
+- `type`
+- `kind`
+- `displayName`
+- `category`
+- `configurationSchema`
+- `uiSchema`
+- `runtimeHandler`
+- `outputSchema`
+- `documentation`
+
+Agreed v1 node type catalog:
+
+- `log.write`
+- `http.request`
+- `if`
+- `forEach`
+- `parallel`
+
+## Candidate V1 Entities
+
+- `WorkflowDefinition`
+- `WorkflowExecution`
+- `StepExecution`
+- `BlueprintDefinition`
+
+With embedded or child structures for:
+
+- inputs
+- outputs
+- triggers
+- nodes
+- secret references
+
+## Open Domain Questions
+
+- Should namespace be its own entity or just a string path?
+- Should subflows be modeled as ordinary workflow references or a distinct node type?
+- Should artifacts/files be part of `StepExecution` directly or a separate `ExecutionArtifact` entity?
+- Should seeded workflows be editable in place or partially protected?