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

package/docs/workflow/workflow-core-module-handoff-summary.md

@@ -1,191 +0,0 @@
-# Workflow Core Module Handoff Summary
-
-## Current Branches
-
-- `solid-core-module` work is on branch `ft-workflow`.
-- `solid-core-ui` also has a matching `ft-workflow` branch created from `dev`.
-- The original consuming project docs have been moved into `solid-core-module/docs/workflow`.
-
-## What We Built So Far
-
-Workflow functionality has been moved out of the consuming project and into `solid-core-module` so workflows become a first-class Solid Core feature.
-
-The backend now includes generated/core workflow models, controllers, services, repositories, DTOs, metadata, and a first-pass runtime engine. The current runtime supports seeded workflow definitions and execution through the workflow definition controller.
-
-## Workflow Models
-
-The agreed model set currently implemented is:
-
-- `WorkflowDefinition`
-- `WorkflowExecution`
-- `WorkflowStepExecution`
-- `WorkflowExecutionLog`
-- `WorkflowExecutionArtifact`
-- `WorkflowTriggerExecution`
-
-`WorkflowBlueprint` remains intentionally ignored for now.
-
-Definition versioning is represented as fields on definition and execution records rather than a separate version table.
-
-## Metadata And Tables
-
-Workflow metadata now lives in `src/seeders/seed-data/solid-core-metadata.json`.
-
-Workflow tables use the `ss_` prefix, for example:
-
-- `ss_workflow_definition`
-- `ss_workflow_execution`
-- `ss_workflow_step_execution`
-- `ss_workflow_execution_log`
-- `ss_workflow_execution_artifact`
-- `ss_workflow_trigger_execution`
-
-`workflowExecution.executionIdentifier` is now a normal `shortText` field because the runtime generates it directly. It is no longer modeled as a computed field.
-
-## Runtime And Node System
-
-The runtime uses a registry-based node provider model:
-
-- Node providers are registered through a decorator and interface pattern.
-- Discovery happens at module startup using Nest discovery/reflection.
-- The registry skips discovered wrappers that do not have a valid provider class `metatype`.
-
-The current v1 node/provider set includes:
-
-- `log.write`
-- `http.request`
-- `if`
-- `forEach`
-- `parallel`
-
-The workflow YAML shape uses ordered arrays with nested child arrays for control nodes, following the Kestra-style structure we agreed on.
-
-## Execution Flow
-
-Workflow execution is exposed through `WorkflowDefinitionController`:
-
-```bash
-POST /workflow-definition/by-key/:key/execute
-POST /workflow-definition/:id/execute
-```
-
-The sample seeded workflow key is:
-
-```text
-sample-workflow-builder-smoke-test
-```
-
-Example curl:
-
-```bash
-curl -X POST "http://localhost:3000/workflow-definition/by-key/sample-workflow-builder-smoke-test/execute" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
-  -d '{
-    "triggerType": "manual",
-    "input": {
-      "name": "Harish",
-      "runHttp": false,
-      "url": "https://example.com",
-      "items": ["alpha", "beta", "gamma"]
-    }
-  }'
-```
-
-## Workflow Execution Relations
-
-`WorkflowExecution` now has contextual one-to-many relations for:
-
-- `workflowStepExecutions`
-- `workflowExecutionLogs`
-- `workflowExecutionArtifacts`
-
-These are exposed as tabs in the Workflow Execution form. The child models are not marked with `isChild: true`; that flag is reserved for another SolidX use case.
-
-Standalone menu items for step executions, logs, and artifacts were removed because these records are intended to be viewed in the context of a workflow execution.
-
-`WorkflowTriggerExecution` remains as a standalone menu item because trigger executions can conceptually exist independently from a completed workflow execution.
-
-## Admin Metadata UI Changes
-
-Workflow menus are grouped under a top-level `Workflow` menu, similar to the existing Layout Builder pattern.
-
-Workflow Definition form:
-
-- `Basic Info`
-- `Definition YAML`
-
-Workflow Execution form:
-
-- `Basic Info`
-- `Input`
-- `Output`
-- `Definition Snapshot`
-- `Steps`
-- `Logs`
-- `Artifacts`
-- `Errors`
-
-JSON fields in the dedicated JSON tabs use metadata-only layout attributes:
-
-- `className` on the field wrapper
-- `height` passed to `SolidCodeEditor`
-
-The JSON editor height is currently set with viewport-based values such as:
-
-```json
-"height": "calc(100vh - 260px)"
-```
-
-## Seeding
-
-`ModuleMetadataSeederService` was updated to seed workflow definitions from module metadata JSON.
-
-The consuming project currently still owns a sample workflow metadata file under:
-
-```text
-solid-api/src/workflow-builder/metadata/workflow-builder-metadata.json
-```
-
-That sample is useful for smoke testing the runtime.
-
-## Important Decisions
-
-- Workflow definitions are not treated as a single opaque blob internally, but they do have a canonical YAML DSL for sharing, seeding, validation, and developer workflows.
-- Runtime data belongs in execution records/context, not in the definition YAML.
-- New workflow node types should be registry-driven from day one.
-- JSON fields are processed in memory to keep the workflow engine DB agnostic.
-- Revisions/version tables are deferred; version/checksum fields are sufficient for now.
-
-## Recent Verification
-
-The following has passed after the latest workflow-related changes:
-
-```bash
-npm run build
-```
-
-Run it from:
-
-```text
-/Users/harishpatel/Code/javascript/solid-core-module
-```
-
-## Moved Design Docs
-
-The original design docs are now under this folder:
-
-```text
-docs/workflow
-```
-
-Key docs include:
-
-- `what-is-kestra.md`
-- `kestra-concepts-plugins-blueprints.md`
-- `workflow-module-brd.md`
-- `workflow-module-technical-spec.md`
-- `workflow-module-domain-model.md`
-- `workflow-module-metadata-dsl.md`
-- `workflow-node-type-contracts.md`
-- `workflow-solidx-model-field-spec.md`

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

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

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