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

package/docs/workflow/workflow-solidx-model-field-spec.md

@@ -0,0 +1,284 @@
+# Workflow SolidX Model Field Specification
+
+This document translates the agreed workflow-management domain model into SolidX model and field definitions.
+
+It is intended as the final field-level design pass before using the SolidX model MCP tools.
+
+## SolidX Field Types
+
+The local `@solidxai/core` package defines these field types in `SolidFieldType`:
+
+- `int`
+- `bigint`
+- `decimal`
+- `shortText`
+- `longText`
+- `richText`
+- `json`
+- `boolean`
+- `date`
+- `datetime`
+- `time`
+- `relation`
+- `mediaSingle`
+- `mediaMultiple`
+- `email`
+- `password`
+- `selectionStatic`
+- `selectionDynamic`
+- `computed`
+- `uuid`
+
+Useful relation metadata:
+
+- `relationType`: `many-to-one`, `one-to-many`, `many-to-many`
+- `relationCascade`: `set null`, `restrict`, `cascade`
+
+## Modeling Philosophy
+
+- Workflow definitions store their canonical DSL in YAML text.
+- Workflow definitions are metadata-backed: manually created workflows should also be persisted back to the module metadata JSON so developers can commit and share them.
+- Workflow execution data is normalized enough to support monitoring, filtering, and debugging.
+- Workflow version history is not a separate model in v1.
+- `definitionVersion` and `definitionChecksum` live on both definition and execution records.
+- `WorkflowBlueprint` is intentionally deferred for now.
+
+## Model: `workflowDefinition`
+
+Purpose: stores the current reusable workflow definition.
+
+Suggested table name: `wm_workflow_definition`
+
+| Field | SolidX Type | Required | Notes |
+| --- | --- | --- | --- |
+| `key` | `shortText` | Yes | Stable workflow key. Should be unique. |
+| `moduleMetadata` | `relation` | Yes | Many-to-one to SolidX `moduleMetadata`; identifies the owning module/package for metadata persistence. |
+| `displayName` | `shortText` | Yes | Human-facing name. |
+| `namespace` | `shortText` | No | Dot-path grouping, e.g. `ops.monitoring`. |
+| `description` | `longText` | No | Workflow description. |
+| `status` | `selectionStatic` | Yes | `draft`, `active`, `inactive`, `archived`. |
+| `definitionVersion` | `shortText` | No | Human-managed or seed-managed version string. |
+| `definitionChecksum` | `shortText` | No | Hash of canonical `definitionYaml`. |
+| `definitionYaml` | `longText` | Yes | Canonical workflow DSL YAML used for sharing, seeding, validation, and execution. |
+| `tags` | `json` | No | Array of tags. |
+
+Recommended indexes/search fields:
+
+- `key`
+- `moduleMetadata`
+- `displayName`
+- `namespace`
+- `status`
+- `definitionChecksum`
+
+Recommended user key:
+
+- `key`
+
+Metadata persistence notes:
+
+- `key` acts as the workflow user key and metadata identity.
+- A TypeORM subscriber or workflow persistence service should synchronize workflow definition changes back to the owning module metadata JSON.
+- Since UI-created workflows are also metadata-backed, separate `sourceType`, `seedSource`, `seedKey`, `seedVersion`, and `isSeeded` fields are not needed.
+
+## Model: `workflowExecution`
+
+Purpose: stores one run of a workflow definition.
+
+Suggested table name: `wm_workflow_execution`
+
+| Field | SolidX Type | Required | Notes |
+| --- | --- | --- | --- |
+| `executionIdentifier` | `computed` | Yes | System-generated readable execution id. Recommended provider: `SequenceNumComputedFieldProvider`. |
+| `workflowDefinition` | `relation` | Yes | Many-to-one to `workflowDefinition`. |
+| `workflowKey` | `shortText` | Yes | Snapshot of definition key for easier querying. |
+| `workflowDisplayName` | `shortText` | No | Snapshot of display name. |
+| `status` | `selectionStatic` | Yes | `created`, `running`, `success`, `failed`, `cancelled`. |
+| `triggerType` | `selectionStatic` | Yes | `manual`, `schedule`, `webhook`, `flow`, `polling`, `event`. |
+| `triggerExecution` | `relation` | No | Many-to-one to `workflowTriggerExecution`; nullable for manual runs. |
+| `startedAt` | `datetime` | No | Execution start time. |
+| `finishedAt` | `datetime` | No | Execution end time. |
+| `durationMs` | `bigint` | No | Runtime duration. |
+| `inputPayload` | `json` | No | Runtime inputs supplied to the execution. |
+| `outputPayload` | `json` | No | Flow-level outputs. |
+| `definitionVersion` | `shortText` | No | Version used by this execution. |
+| `definitionChecksum` | `shortText` | No | Checksum used by this execution. |
+| `definitionSnapshot` | `longText` | Yes | Exact workflow YAML used for this run. |
+| `errorSummary` | `longText` | No | Human-readable failure summary. |
+| `errorDetails` | `json` | No | Structured error payload. |
+| `requestedByUserId` | `bigint` | No | User id or actor id if available. |
+
+Recommended indexes/search fields:
+
+- `executionIdentifier`
+- `workflowKey`
+- `status`
+- `triggerType`
+- `startedAt`
+- `finishedAt`
+- `definitionChecksum`
+
+Recommended computed field configuration:
+
+- `type`: `computed`
+- `computedFieldValueProvider`: `SequenceNumComputedFieldProvider`
+- `computedFieldValueProviderCtxt`: `{"sequenceName":"workflowExecution","mode":"counter"}`
+- `computedFieldValueType`: `string`
+- `computedFieldTriggerConfig`: after insert for `workflowExecution`
+
+Recommended model sequence:
+
+- `sequenceName`: `workflowExecution`
+- `prefix`: `WFE`
+- `separator`: `-`
+- `padding`: `8`
+- Example output: `WFE-00000001`
+
+## Model: `workflowStepExecution`
+
+Purpose: stores runtime state for one workflow node execution.
+
+Suggested table name: `wm_workflow_step_execution`
+
+| Field | SolidX Type | Required | Notes |
+| --- | --- | --- | --- |
+| `workflowExecution` | `relation` | Yes | Many-to-one to `workflowExecution`. |
+| `parentStepExecution` | `relation` | No | Self many-to-one for nested/control execution. |
+| `nodeId` | `shortText` | Yes | Node id from workflow YAML. |
+| `nodeName` | `shortText` | No | Snapshot of node name. |
+| `nodeKind` | `selectionStatic` | Yes | `task`, `control`, `subflow`. |
+| `nodeType` | `shortText` | Yes | e.g. `http.request`, `if`. |
+| `status` | `selectionStatic` | Yes | `pending`, `running`, `success`, `failed`, `skipped`. |
+| `attemptNumber` | `int` | Yes | Defaults to 1. |
+| `branchId` | `shortText` | No | For `parallel` branch context. |
+| `iterationIndex` | `int` | No | For `forEach` context. |
+| `startedAt` | `datetime` | No | Step start time. |
+| `finishedAt` | `datetime` | No | Step end time. |
+| `durationMs` | `bigint` | No | Step runtime duration. |
+| `inputContext` | `json` | No | Resolved node input context. |
+| `outputPayload` | `json` | No | Node outputs. |
+| `errorSummary` | `longText` | No | Human-readable failure summary. |
+| `errorDetails` | `json` | No | Structured error payload. |
+
+Recommended indexes/search fields:
+
+- `workflowExecution`
+- `nodeId`
+- `nodeType`
+- `status`
+- `startedAt`
+
+## Model: `workflowExecutionLog`
+
+Purpose: stores execution and step logs as queryable records.
+
+Suggested table name: `wm_workflow_execution_log`
+
+| Field | SolidX Type | Required | Notes |
+| --- | --- | --- | --- |
+| `workflowExecution` | `relation` | Yes | Many-to-one to `workflowExecution`. |
+| `workflowStepExecution` | `relation` | No | Many-to-one to `workflowStepExecution`; nullable for execution-level logs. |
+| `level` | `selectionStatic` | Yes | `debug`, `info`, `warn`, `error`. |
+| `message` | `longText` | Yes | Log message. |
+| `metadata` | `json` | No | Structured log metadata. |
+| `loggedAt` | `datetime` | Yes | Timestamp of log event. |
+
+Recommended indexes/search fields:
+
+- `workflowExecution`
+- `workflowStepExecution`
+- `level`
+- `loggedAt`
+
+## Model: `workflowExecutionArtifact`
+
+Purpose: stores references to files or large artifacts produced during execution.
+
+Suggested table name: `wm_workflow_execution_artifact`
+
+| Field | SolidX Type | Required | Notes |
+| --- | --- | --- | --- |
+| `workflowExecution` | `relation` | Yes | Many-to-one to `workflowExecution`. |
+| `workflowStepExecution` | `relation` | No | Many-to-one to `workflowStepExecution`. |
+| `artifactKey` | `shortText` | Yes | Stable artifact key within the execution. |
+| `displayName` | `shortText` | No | Human-facing name. |
+| `artifactType` | `selectionStatic` | Yes | `file`, `json`, `text`, `binary`, `uri`. |
+| `media` | `mediaSingle` | No | SolidX media attachment for stored file artifacts. |
+| `uri` | `longText` | No | External artifact URI if not stored in media. |
+| `contentType` | `shortText` | No | MIME type if known. |
+| `sizeBytes` | `bigint` | No | Artifact size. |
+| `metadata` | `json` | No | Structured artifact metadata. |
+| `createdAtRuntime` | `datetime` | No | Runtime artifact creation timestamp. |
+
+Recommended indexes/search fields:
+
+- `workflowExecution`
+- `workflowStepExecution`
+- `artifactKey`
+- `artifactType`
+
+## Model: `workflowTriggerExecution`
+
+Purpose: records trigger events that started or attempted to start workflow executions.
+
+Suggested table name: `wm_workflow_trigger_execution`
+
+| Field | SolidX Type | Required | Notes |
+| --- | --- | --- | --- |
+| `workflowDefinition` | `relation` | Yes | Many-to-one to `workflowDefinition`. |
+| `triggerId` | `shortText` | Yes | Trigger id from workflow YAML. |
+| `triggerType` | `selectionStatic` | Yes | `schedule`, `webhook`, `flow`, `polling`, `event`. |
+| `status` | `selectionStatic` | Yes | `received`, `accepted`, `ignored`, `failed`. |
+| `firedAt` | `datetime` | Yes | Trigger fire time. |
+| `inputPayload` | `json` | No | Inputs supplied by trigger. |
+| `triggerPayload` | `json` | No | Raw trigger/event payload. |
+| `workflowExecution` | `relation` | No | Many-to-one to `workflowExecution`; nullable if ignored/failed before execution creation. |
+| `errorSummary` | `longText` | No | Human-readable failure summary. |
+| `errorDetails` | `json` | No | Structured error payload. |
+
+Recommended indexes/search fields:
+
+- `workflowDefinition`
+- `triggerId`
+- `triggerType`
+- `status`
+- `firedAt`
+
+## Deferred Model: `workflowBlueprint`
+
+`WorkflowBlueprint` is intentionally ignored for now.
+
+When reintroduced, it should likely include:
+
+- `key`
+- `displayName`
+- `description`
+- `tags`
+- `definitionYaml`
+- `source`
+- `sourceVersion`
+
+## Relation Summary
+
+- `workflowDefinition` has many `workflowExecution`
+- `workflowDefinition` has many `workflowTriggerExecution`
+- `moduleMetadata` has many `workflowDefinition`
+- `workflowExecution` has many `workflowStepExecution`
+- `workflowExecution` has many `workflowExecutionLog`
+- `workflowExecution` has many `workflowExecutionArtifact`
+- `workflowTriggerExecution` may link to one created `workflowExecution`
+- `workflowStepExecution` may have many child `workflowStepExecution` records via `parentStepExecution`
+- `workflowStepExecution` has many `workflowExecutionLog`
+- `workflowStepExecution` has many `workflowExecutionArtifact`
+
+## MCP Modeling Readiness Checklist
+
+Before calling the SolidX model MCP tools, confirm:
+
+- Use `workflow-builder` as the module key.
+- Use the six active models above.
+- Use `longText` for `definitionYaml` and `definitionSnapshot`; parse them as YAML in the workflow services to keep the workflow engine DB agnostic.
+- Use `selectionStatic` for status/type enum fields.
+- Use `relation` fields for cross-model links.
+- Add a many-to-one relation from `workflowDefinition` to SolidX `moduleMetadata`.
+- Keep `WorkflowBlueprint` deferred.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidxai/core",
-  "version": "0.1.13-beta.2",
+  "version": "0.1.13-beta.4",
   "description": "This module is a NestJS module containing all the required core providers required by a Solid application",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/commands/seed.command.ts

@@ -7,6 +7,7 @@ interface SeedCommandOptions {
   seeder?: string;
   modulesToSeed?: string;
   prune?: boolean;
+  skipHooks?: boolean;
 }
 
 @Command({ name: 'seed', description: 'Install seed data for a given module' })
@@ -28,6 +29,7 @@ export class SeedCommand extends CommandRunner {
         modulesToSeed,
         pruneMetadata: false,
         seedGlobalMetadata: true,
+        skipHooks: false,
       };
       this.logger.log(`Modules to seed: ${modulesToSeed.join(', ')}`);
     } else {
@@ -39,10 +41,22 @@ export class SeedCommand extends CommandRunner {
         modulesToSeed: null,
         pruneMetadata: false,
         seedGlobalMetadata: true,
+        skipHooks: false,
       };
       parsedConf.pruneMetadata = true;
     }
 
+    if (options?.skipHooks) {
+      parsedConf = parsedConf ?? {
+        modulesToSeed: null,
+        pruneMetadata: false,
+        seedGlobalMetadata: true,
+        skipHooks: false,
+      };
+      parsedConf.skipHooks = true;
+      this.logger.log('Skipping pre-seed and post-seed hooks.');
+    }
+
     const seeder = this.solidRegistry
       .getSeeders()
       .filter((seeder) => seeder.name === options.seeder)
@@ -74,4 +88,9 @@ export class SeedCommand extends CommandRunner {
   parsePrune(): boolean {
     return true;
   }
+
+  @Option({ flags: '--skip-hooks', description: 'Skip emitting pre-seed and post-seed lifecycle hooks/events.' })
+  parseSkipHooks(): boolean {
+    return true;
+  }
 }

package/src/entities/saved-filters.entity.ts

@@ -18,17 +18,17 @@ export class SavedFilters extends CommonEntity {
     isPrivate: boolean = false;
 
     @Index()
-    @ManyToOne(() => User, { onDelete: "CASCADE", nullable: true })
+    @ManyToOne(() => User, { nullable: true })
     @JoinColumn()
     user: User;
 
     @Index()
-    @ManyToOne(() => ModelMetadata, { onDelete: "CASCADE", nullable: false })
+    @ManyToOne(() => ModelMetadata, { nullable: false })
     @JoinColumn()
     model: ModelMetadata;
 
     @Index()
-    @ManyToOne(() => ViewMetadata, { onDelete: "CASCADE", nullable: false })
+    @ManyToOne(() => ViewMetadata, { nullable: false })
     @JoinColumn()
     view: ViewMetadata;
 

package/src/entities/workflow-trigger-execution.entity.ts

@@ -35,7 +35,7 @@ export class WorkflowTriggerExecution extends CommonEntity {
     status: string = "received";
 
     @Index()
-    @Column({ type: "boolean", nullable: true, default: false })
+    @Column({ nullable: true, default: false })
     matched: boolean = false;
 
     @Index()

package/src/index.ts

@@ -248,10 +248,12 @@ export * from './services/workflow/workflow-expression.service'
 export * from './services/workflow/workflow-invocation.service'
 export * from './services/workflow/workflow-node-registry.service'
 export * from './services/workflow/workflow-runtime.service'
+export * from './services/workflow/nodes/execution-fail.node'
 export * from './services/workflow/nodes/for-each.node'
 export * from './services/workflow/nodes/http-request.node'
 export * from './services/workflow/nodes/if.node'
 export * from './services/workflow/nodes/log-write.node'
+export * from './services/workflow/nodes/loop-until.node'
 export * from './services/workflow/nodes/parallel.node'
 export * from './services/workflow/nodes/sequential.node'
 export * from './services/workflow/nodes/solidx-crud.nodes'

package/src/interfaces.ts

@@ -272,6 +272,7 @@ export interface ModuleMetadataSeederOptions {
   modulesToSeed: string[] | null;
   pruneMetadata: boolean;
   seedGlobalMetadata: boolean;
+  skipHooks: boolean;
 }
 
 export interface ModuleMetadataSeederEventPayload {

package/src/seeders/module-metadata-seeder.service.ts

@@ -148,24 +148,30 @@ export class ModuleMetadataSeederService {
         let modulesToSeed: string[] | null = null;
         const requestedModulesToSeed = Array.isArray(conf?.modulesToSeed) ? [...conf.modulesToSeed] : null;
         const shouldSeedGlobalMetadata = conf?.seedGlobalMetadata !== false;
+        const skipHooks = Boolean(conf?.skipHooks);
         const seedOptions: ModuleMetadataSeederEventPayload['options'] = {
             modulesToSeed: requestedModulesToSeed,
             pruneMetadata: Boolean(conf?.pruneMetadata),
             seedGlobalMetadata: shouldSeedGlobalMetadata,
+            skipHooks,
         };
         const seedRunId = uuidv4();
         const startedAt = new Date();
         const seededModuleNames: string[] = [];
 
-        this.emitModuleMetadataSeederEvent(
-            EventType.MODULE_METADATA_SEEDER_STARTED,
-            {
-                seedRunId,
-                options: seedOptions,
-                startedAt: startedAt.toISOString(),
-                currentStep,
-            },
-        );
+        if (skipHooks) {
+            console.log('▶ Skipping pre-seed hooks (--skip-hooks).');
+        } else {
+            this.emitModuleMetadataSeederEvent(
+                EventType.MODULE_METADATA_SEEDER_STARTED,
+                {
+                    seedRunId,
+                    options: seedOptions,
+                    startedAt: startedAt.toISOString(),
+                    currentStep,
+                },
+            );
+        }
 
         try {
             this.enablePruning = Boolean(conf?.pruneMetadata);
@@ -323,37 +329,45 @@ export class ModuleMetadataSeederService {
             // Add a console log indicating seeding is finished. This needs to be console.log so that it looks proper when this code is run via CLI.
             console.log(`✔ Seeding completed.`);
             //this.logger.log(`All Seeders finished`);
-            await this.emitModuleMetadataSeederFinishedEvent(
-                EventType.MODULE_METADATA_SEEDER_FINISHED,
-                {
-                    seedRunId,
-                    options: seedOptions,
-                    startedAt: startedAt.toISOString(),
-                    finishedAt: new Date().toISOString(),
-                    durationMs: Date.now() - startedAt.getTime(),
-                    success: true,
-                    seededModuleNames,
-                    currentStep,
-                },
-            );
+            if (skipHooks) {
+                console.log('▶ Skipping post-seed hooks (--skip-hooks).');
+            } else {
+                await this.emitModuleMetadataSeederFinishedEvent(
+                    EventType.MODULE_METADATA_SEEDER_FINISHED,
+                    {
+                        seedRunId,
+                        options: seedOptions,
+                        startedAt: startedAt.toISOString(),
+                        finishedAt: new Date().toISOString(),
+                        durationMs: Date.now() - startedAt.getTime(),
+                        success: true,
+                        seededModuleNames,
+                        currentStep,
+                    },
+                );
+            }
 
             //FIXME: Handle displaying the created users credentials in a better way.
             // this.logger.log(`Newly created username is: ${usersDetail?.length > 0 ? usersDetail[0]?.username : ''} and password is ${usersDetail?.length > 0 ? usersDetail[0]?.password : ''}`);
         } catch (error: any) {
-            await this.emitModuleMetadataSeederFinishedEvent(
-                EventType.MODULE_METADATA_SEEDER_FINISHED,
-                {
-                    seedRunId,
-                    options: seedOptions,
-                    startedAt: startedAt.toISOString(),
-                    finishedAt: new Date().toISOString(),
-                    durationMs: Date.now() - startedAt.getTime(),
-                    success: false,
-                    seededModuleNames,
-                    currentStep,
-                    errorMessage: error?.message,
-                },
-            );
+            if (skipHooks) {
+                console.log('▶ Skipping post-seed hooks (--skip-hooks).');
+            } else {
+                await this.emitModuleMetadataSeederFinishedEvent(
+                    EventType.MODULE_METADATA_SEEDER_FINISHED,
+                    {
+                        seedRunId,
+                        options: seedOptions,
+                        startedAt: startedAt.toISOString(),
+                        finishedAt: new Date().toISOString(),
+                        durationMs: Date.now() - startedAt.getTime(),
+                        success: false,
+                        seededModuleNames,
+                        currentStep,
+                        errorMessage: error?.message,
+                    },
+                );
+            }
             this.logSeedFailureForCli(error, {
                 moduleName: currentModule,
                 step: currentStep,