@solidxai/core 0.1.13-beta.7 → 0.1.13-beta.8

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

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