@open-mercato/core 0.6.2-develop.3400.2.d948268f50 → 0.6.2-develop.3406.1.2b403f40da

package/src/modules/workflows/lib/code-registry.ts

@@ -0,0 +1,65 @@
+/**
+ * In-Memory Code Workflow Registry
+ *
+ * Stores code-based workflow definitions populated at bootstrap from
+ * the generated workflows.generated.ts. Definitions live purely in memory —
+ * no DB row is created until a user customizes the definition.
+ */
+
+import type { CodeWorkflowDefinition } from '@open-mercato/shared/modules/workflows'
+import { workflowDefinitionDataSchema } from '../data/validators'
+
+const codeWorkflowRegistry = new Map<string, CodeWorkflowDefinition>()
+
+/**
+ * Register code-based workflow definitions at bootstrap time.
+ * Validates each definition against the Zod schema and warns on failures.
+ */
+export function registerCodeWorkflows(workflows: CodeWorkflowDefinition[]): void {
+  for (const wf of workflows) {
+    const validation = workflowDefinitionDataSchema.safeParse(wf.definition)
+    if (!validation.success) {
+      console.warn(
+        `[workflows] Code workflow "${wf.workflowId}" failed validation:`,
+        validation.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; '),
+      )
+      continue
+    }
+
+    if (codeWorkflowRegistry.has(wf.workflowId)) {
+      console.warn(
+        `[workflows] Duplicate code workflow ID "${wf.workflowId}" from module "${wf.moduleId}" — overwriting`,
+      )
+    }
+
+    codeWorkflowRegistry.set(wf.workflowId, wf)
+  }
+}
+
+/**
+ * Get a single code workflow definition by workflowId.
+ */
+export function getCodeWorkflow(workflowId: string): CodeWorkflowDefinition | undefined {
+  return codeWorkflowRegistry.get(workflowId)
+}
+
+/**
+ * Get all registered code workflow definitions.
+ */
+export function getAllCodeWorkflows(): CodeWorkflowDefinition[] {
+  return Array.from(codeWorkflowRegistry.values())
+}
+
+/**
+ * Check if a workflowId is a code-based definition.
+ */
+export function isCodeWorkflow(workflowId: string): boolean {
+  return codeWorkflowRegistry.has(workflowId)
+}
+
+/**
+ * Clear the registry (for testing).
+ */
+export function clearCodeWorkflowRegistry(): void {
+  codeWorkflowRegistry.clear()
+}

package/src/modules/workflows/lib/find-definition.ts

@@ -0,0 +1,100 @@
+/**
+ * Unified Workflow Definition Lookup
+ *
+ * Finds workflow definitions from the database first, falling back to the
+ * in-memory code workflow registry. This enables code-based definitions to
+ * be used seamlessly by the executor and validators.
+ */
+
+import { createHash } from 'node:crypto'
+import { EntityManager } from '@mikro-orm/core'
+import { WorkflowDefinition, type WorkflowDefinitionData } from '../data/entities'
+import { getCodeWorkflow } from './code-registry'
+
+/**
+ * Generate a deterministic UUID for a code workflow definition.
+ * Uses SHA-256 truncated to UUID v4 format so the same workflowId always
+ * produces the same UUID across restarts and horizontal replicas.
+ */
+export function codeWorkflowUuid(workflowId: string): string {
+  const hash = createHash('sha256').update(`code-workflow:${workflowId}`).digest('hex')
+  // Format as UUID v4 (set version nibble to 4, variant bits to 10xx)
+  return [
+    hash.slice(0, 8),
+    hash.slice(8, 12),
+    `4${hash.slice(13, 16)}`,
+    `${(parseInt(hash[16], 16) & 0x3 | 0x8).toString(16)}${hash.slice(17, 20)}`,
+    hash.slice(20, 32),
+  ].join('-')
+}
+
+/**
+ * Find a workflow definition by workflowId, checking the database first
+ * and falling back to the code registry.
+ *
+ * When a DB row exists with `codeWorkflowId` set, it means the user has
+ * customized the code definition — the DB version takes precedence.
+ *
+ * When no DB row exists but a code definition is registered, a virtual
+ * WorkflowDefinition-like object is constructed with a deterministic UUID.
+ */
+export async function findWorkflowDefinition(
+  em: EntityManager,
+  options: {
+    workflowId: string
+    version?: number
+    tenantId: string
+    organizationId: string
+  },
+): Promise<WorkflowDefinition | null> {
+  const { workflowId, version, tenantId, organizationId } = options
+
+  // 1. Try database first
+  const where: Record<string, unknown> = {
+    workflowId,
+    tenantId,
+    organizationId,
+    deletedAt: null,
+  }
+
+  if (version !== undefined) {
+    where.version = version
+  }
+
+  if (version === undefined) {
+    where.enabled = true
+    const dbDef = await em.findOne(WorkflowDefinition, where, {
+      orderBy: { version: 'DESC' },
+    })
+    if (dbDef) return dbDef
+  } else {
+    const dbDef = await em.findOne(WorkflowDefinition, where)
+    if (dbDef) return dbDef
+  }
+
+  // 2. Fall back to code registry (version filter not applicable to code defs)
+  const codeDef = getCodeWorkflow(workflowId)
+  if (!codeDef) return null
+
+  // When no version was requested, mirror the DB branch's `enabled = true` filter
+  // so disabled code workflows aren't silently executable.
+  if (version === undefined && !codeDef.enabled) return null
+
+  // Construct a virtual WorkflowDefinition object (not persisted)
+  const virtual = new WorkflowDefinition()
+  virtual.id = codeWorkflowUuid(workflowId)
+  virtual.workflowId = codeDef.workflowId
+  virtual.workflowName = codeDef.workflowName
+  virtual.description = codeDef.description ?? null
+  virtual.version = codeDef.version
+  virtual.definition = codeDef.definition as WorkflowDefinitionData
+  virtual.metadata = codeDef.metadata ?? null
+  virtual.enabled = codeDef.enabled
+  virtual.codeWorkflowId = codeDef.workflowId
+  virtual.tenantId = tenantId
+  virtual.organizationId = organizationId
+  virtual.createdAt = new Date(0) // code defs have no creation date
+  virtual.updatedAt = new Date(0)
+
+  return virtual
+}

package/src/modules/workflows/lib/seeds.ts

@@ -190,10 +190,11 @@ async function seedGuardRules(
 }
 
 export async function seedExampleWorkflows(em: EntityManager, scope: WorkflowSeedScope): Promise<void> {
-  await seedWorkflowDefinition(em, scope, 'checkout-demo-definition.json')
+  // workflows.checkout-demo and workflows.simple-approval are now code-defined
+  // (see packages/core/src/modules/workflows/workflows.ts). Seeding DB rows for
+  // them would shadow the code definitions in the merge layer, so they are no
+  // longer seeded here. Existing tenants are migrated via Migration20260428102318.
   await seedGuardRules(em, scope, 'guard-rules-example.json')
   await seedWorkflowDefinition(em, scope, 'sales-pipeline-definition.json')
-  await seedWorkflowDefinition(em, scope, 'simple-approval-definition.json')
   await seedGuardRules(em, scope, 'order-approval-guard-rules.json')
-  await seedWorkflowDefinition(em, scope, 'order-approval-definition.json')
 }

package/src/modules/workflows/lib/start-validator.ts

@@ -9,6 +9,7 @@
 import { EntityManager } from '@mikro-orm/core'
 import { WorkflowDefinition } from '../data/entities'
 import * as ruleEngine from '../../business_rules/lib/rule-engine'
+import { findWorkflowDefinition } from './find-definition'
 import type { StartPreCondition } from '../data/validators'
 
 // ============================================================================
@@ -258,38 +259,4 @@ function getLocalizedMessage(
   return defaultMessage
 }
 
-/**
- * Find workflow definition by ID and optional version
- */
-async function findWorkflowDefinition(
-  em: EntityManager,
-  options: {
-    workflowId: string
-    version?: number
-    tenantId: string
-    organizationId: string
-  }
-): Promise<WorkflowDefinition | null> {
-  const { workflowId, version, tenantId, organizationId } = options
-
-  const where: any = {
-    workflowId,
-    tenantId,
-    organizationId,
-    deletedAt: null,
-  }
-
-  if (version !== undefined) {
-    where.version = version
-  }
-
-  // If no version specified, get latest enabled version
-  if (version === undefined) {
-    where.enabled = true
-    return em.findOne(WorkflowDefinition, where, {
-      orderBy: { version: 'DESC' },
-    })
-  }
-
-  return em.findOne(WorkflowDefinition, where)
-}
+// findWorkflowDefinition is imported from ./find-definition

package/src/modules/workflows/lib/workflow-executor.ts

@@ -19,6 +19,7 @@ import {
   type WorkflowInstanceStatus,
 } from '../data/entities'
 import { compensateWorkflow } from './compensation-handler'
+import { findWorkflowDefinition } from './find-definition'
 
 // ============================================================================
 // Types and Interfaces
@@ -903,45 +904,7 @@ export async function updateWorkflowContext(
   await em.flush()
 }
 
-/**
- * Find workflow definition by ID and optional version
- *
- * @param em - Entity manager
- * @param options - Search options
- * @returns Workflow definition or null
- */
-async function findWorkflowDefinition(
-  em: EntityManager,
-  options: {
-    workflowId: string
-    version?: number
-    tenantId: string
-    organizationId: string
-  }
-): Promise<WorkflowDefinition | null> {
-  const { workflowId, version, tenantId, organizationId } = options
-
-  const where: any = {
-    workflowId,
-    tenantId,
-    organizationId,
-    deletedAt: null,
-  }
-
-  if (version !== undefined) {
-    where.version = version
-  }
-
-  // If no version specified, get latest enabled version
-  if (version === undefined) {
-    where.enabled = true
-    return em.findOne(WorkflowDefinition, where, {
-      orderBy: { version: 'DESC' },
-    })
-  }
-
-  return em.findOne(WorkflowDefinition, where)
-}
+// findWorkflowDefinition is imported from ./find-definition
 
 /**
  * Log workflow event to event sourcing table

package/src/modules/workflows/migrations/.snapshot-open-mercato.json

@@ -518,6 +518,16 @@
           "length": 100,
           "mappedType": "string"
         },
+        "code_workflow_id": {
+          "name": "code_workflow_id",
+          "type": "varchar(100)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "length": 100,
+          "mappedType": "string"
+        },
         "workflow_name": {
           "name": "workflow_name",
           "type": "varchar(255)",

package/src/modules/workflows/migrations/Migration20260414120000.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260414120000 extends Migration {
+
+  override async up(): Promise<void> {
+    this.addSql(`alter table "workflow_definitions" add column if not exists "code_workflow_id" varchar(100) null;`);
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`alter table "workflow_definitions" drop column if exists "code_workflow_id";`);
+  }
+
+}

package/src/modules/workflows/migrations/Migration20260428102318.ts

@@ -0,0 +1,57 @@
+import { Migration } from '@mikro-orm/migrations';
+
+const RENAMES: Array<{ from: string; to: string }> = [
+  { from: 'checkout_simple_v1', to: 'workflows.checkout-demo' },
+  { from: 'sales_order_approval_v1', to: 'sales.order-approval' },
+  { from: 'simple_approval_v1', to: 'workflows.simple-approval' },
+];
+
+export class Migration20260428102318 extends Migration {
+
+  override async up(): Promise<void> {
+    for (const { from, to } of RENAMES) {
+      this.addSql(
+        `update "workflow_definitions" ` +
+        `set "workflow_id" = '${to}' ` +
+        `where "workflow_id" = '${from}' ` +
+        `and not exists (` +
+          `select 1 from "workflow_definitions" d2 ` +
+          `where d2."workflow_id" = '${to}' and d2."tenant_id" = "workflow_definitions"."tenant_id"` +
+        `);`
+      );
+      this.addSql(
+        `update "workflow_instances" ` +
+        `set "workflow_id" = '${to}' ` +
+        `where "workflow_id" = '${from}' ` +
+        `and exists (` +
+          `select 1 from "workflow_definitions" d ` +
+          `where d."id" = "workflow_instances"."definition_id" and d."workflow_id" = '${to}'` +
+        `);`
+      );
+    }
+  }
+
+  override async down(): Promise<void> {
+    for (const { from, to } of RENAMES) {
+      this.addSql(
+        `update "workflow_definitions" ` +
+        `set "workflow_id" = '${from}' ` +
+        `where "workflow_id" = '${to}' ` +
+        `and not exists (` +
+          `select 1 from "workflow_definitions" d2 ` +
+          `where d2."workflow_id" = '${from}' and d2."tenant_id" = "workflow_definitions"."tenant_id"` +
+        `);`
+      );
+      this.addSql(
+        `update "workflow_instances" ` +
+        `set "workflow_id" = '${from}' ` +
+        `where "workflow_id" = '${to}' ` +
+        `and exists (` +
+          `select 1 from "workflow_definitions" d ` +
+          `where d."id" = "workflow_instances"."definition_id" and d."workflow_id" = '${from}'` +
+        `);`
+      );
+    }
+  }
+
+}

package/src/modules/workflows/widgets/injection/order-approval/widget.client.tsx

@@ -42,7 +42,7 @@ type DictionaryEntry = {
   icon?: string
 }
 
-const WORKFLOW_ID = 'sales_order_approval_v1'
+const WORKFLOW_ID = 'sales.order-approval'
 
 export default function OrderApprovalWidget({ data }: InjectionWidgetComponentProps<unknown, OrderRecord>) {
   const t = useT()

package/src/modules/workflows/workflows.ts

@@ -0,0 +1,278 @@
+/**
+ * Workflows Module — Code-Based Workflow Definitions
+ *
+ * Demo workflows shipped with the workflows module.
+ * These are auto-discovered by the generator and loaded into the in-memory registry.
+ */
+
+import { defineWorkflow, createWorkflowsModuleConfig } from '@open-mercato/shared/modules/workflows'
+
+// ============================================================================
+// Simple Approval Workflow
+// ============================================================================
+
+const simpleApproval = defineWorkflow({
+  workflowId: 'workflows.simple-approval',
+  workflowName: 'Simple Approval Workflow',
+  description: 'Basic three-step approval workflow: Start → Approval → End',
+  metadata: { category: 'Testing', tags: ['test', 'approval', 'simple'], icon: 'check-circle' },
+  steps: [
+    { stepId: 'start', stepName: 'Start', stepType: 'START', description: 'Initialize workflow' },
+    {
+      stepId: 'approval',
+      stepName: 'Pending Approval',
+      stepType: 'USER_TASK',
+      description: 'Approve or reject request',
+      userTaskConfig: { assignedTo: 'approver', slaDuration: 'PT1H' },
+    },
+    { stepId: 'end', stepName: 'Complete', stepType: 'END', description: 'Workflow complete' },
+  ] as const,
+  transitions: [
+    {
+      transitionId: 'start_to_approval',
+      transitionName: 'Submit for Approval',
+      fromStepId: 'start',
+      toStepId: 'approval',
+      trigger: 'auto',
+      priority: 100,
+      activities: [
+        {
+          activityId: 'notify_approver',
+          activityName: 'Notify Approver',
+          activityType: 'SEND_EMAIL',
+          config: {
+            to: '{{context.approver.email}}',
+            subject: 'Approval Required: {{context.request.title}}',
+            template: 'approval_request',
+            data: {
+              requestId: '{{context.request.id}}',
+              title: '{{context.request.title}}',
+              requester: '{{context.requester.name}}',
+            },
+          },
+          timeout: 'PT10S',
+          async: true,
+          retryPolicy: { maxAttempts: 3, initialIntervalMs: 2000, backoffCoefficient: 2, maxIntervalMs: 20000 },
+        },
+        {
+          activityId: 'emit_approval_requested',
+          activityName: 'Emit Approval Requested Event',
+          activityType: 'EMIT_EVENT',
+          config: {
+            eventType: 'approval.requested',
+            payload: { requestId: '{{context.request.id}}', workflowInstanceId: '{{workflow.instanceId}}' },
+          },
+          async: true,
+        },
+      ],
+    },
+    {
+      transitionId: 'approval_to_end',
+      transitionName: 'Approval Decision',
+      fromStepId: 'approval',
+      toStepId: 'end',
+      trigger: 'manual',
+      priority: 100,
+      activities: [
+        {
+          activityId: 'notify_requester',
+          activityName: 'Notify Requester of Decision',
+          activityType: 'SEND_EMAIL',
+          config: {
+            to: '{{context.requester.email}}',
+            subject: 'Approval Decision: {{context.request.title}}',
+            template: 'approval_decision',
+            data: {
+              requestId: '{{context.request.id}}',
+              title: '{{context.request.title}}',
+              decision: '{{task.result.approved}}',
+              comments: '{{task.result.comments}}',
+              approver: '{{task.completedBy}}',
+            },
+          },
+          timeout: 'PT10S',
+          async: true,
+        },
+        {
+          activityId: 'emit_approval_completed',
+          activityName: 'Emit Approval Completed Event',
+          activityType: 'EMIT_EVENT',
+          config: {
+            eventType: 'approval.completed',
+            payload: {
+              requestId: '{{context.request.id}}',
+              approved: '{{task.result.approved}}',
+              approvedBy: '{{task.completedBy}}',
+              timestamp: '{{now}}',
+            },
+          },
+          async: true,
+        },
+      ],
+    },
+  ],
+})
+
+// ============================================================================
+// Checkout Demo Workflow
+// ============================================================================
+
+const checkoutDemo = defineWorkflow({
+  workflowId: 'workflows.checkout-demo',
+  workflowName: 'Checkout with Payment Webhook',
+  description: 'Realistic checkout workflow with signal-based payment confirmation',
+  metadata: { category: 'E-commerce', tags: ['checkout', 'demo', 'payments', 'signals'], icon: 'ShoppingCart' },
+  steps: [
+    {
+      stepId: 'start',
+      stepName: 'Start',
+      stepType: 'START',
+      description: 'Checkout process initiated',
+      preConditions: [{
+        ruleId: 'workflow_checkout_cart_not_empty',
+        required: true,
+        validationMessage: {
+          en: 'Your shopping cart is empty. Please add items before starting checkout.',
+          pl: 'Twój koszyk jest pusty. Dodaj produkty przed rozpoczęciem zakupu.',
+        },
+      }],
+    },
+    { stepId: 'cart_validation', stepName: 'Cart Validation', stepType: 'AUTOMATED', description: 'Validate cart has items and inventory is available', timeout: 'PT10S' },
+    {
+      stepId: 'customer_info',
+      stepName: 'Customer Information',
+      stepType: 'USER_TASK',
+      description: 'Collect customer shipping and contact information',
+      userTaskConfig: {
+        formSchema: {
+          type: 'object',
+          properties: {
+            fullName: { type: 'string', title: 'Full Name', description: "Customer's full legal name" },
+            email: { type: 'string', format: 'email', title: 'Email Address', description: 'Email for order confirmation' },
+            phone: { type: 'string', title: 'Phone Number', description: 'Contact number for delivery' },
+            comment: { type: 'string', title: 'Order Comment', maxLength: 500, description: 'Special instructions or notes' },
+          },
+          required: ['fullName', 'email'],
+        },
+        slaDuration: 'PT24H',
+      },
+    },
+    { stepId: 'payment_initiation', stepName: 'Initiate Payment', stepType: 'AUTOMATED', description: 'Send payment request to payment provider', timeout: 'PT10S' },
+    {
+      stepId: 'wait_payment_confirmation',
+      stepName: 'Wait for Payment Confirmation',
+      stepType: 'WAIT_FOR_SIGNAL',
+      description: 'Waiting for payment provider webhook confirmation',
+      signalConfig: { signalName: 'payment_confirmed', timeout: 'PT5M' },
+    },
+    { stepId: 'order_confirmation', stepName: 'Order Confirmation', stepType: 'AUTOMATED', description: 'Create order record and send confirmation', timeout: 'PT15S' },
+    { stepId: 'end', stepName: 'Complete', stepType: 'END', description: 'Checkout completed successfully' },
+  ] as const,
+  transitions: [
+    {
+      transitionId: 'start_to_cart',
+      transitionName: 'Initialize Checkout',
+      fromStepId: 'start',
+      toStepId: 'cart_validation',
+      trigger: 'auto',
+      priority: 100,
+      activities: [{
+        activityId: 'log_checkout_start',
+        activityName: 'Log Checkout Start',
+        activityType: 'EMIT_EVENT',
+        config: {
+          eventName: 'checkout.started',
+          payload: { customerId: '{{context.customerId}}', cartId: '{{context.cartId}}', currency: '{{context.currency}}', timestamp: '{{now}}' },
+        },
+        async: false,
+      }],
+    },
+    {
+      transitionId: 'cart_to_customer_info',
+      transitionName: 'Collect Customer Information',
+      fromStepId: 'cart_validation',
+      toStepId: 'customer_info',
+      trigger: 'auto',
+      priority: 100,
+      preConditions: [{ ruleId: 'workflow_checkout_cart_not_empty', required: true }],
+    },
+    {
+      transitionId: 'customer_info_to_payment',
+      transitionName: 'Initiate Payment',
+      fromStepId: 'customer_info',
+      toStepId: 'payment_initiation',
+      trigger: 'auto',
+      priority: 100,
+    },
+    {
+      transitionId: 'payment_to_wait_confirmation',
+      transitionName: 'Wait for Confirmation',
+      fromStepId: 'payment_initiation',
+      toStepId: 'wait_payment_confirmation',
+      trigger: 'auto',
+      priority: 100,
+    },
+    {
+      transitionId: 'confirmation_to_order',
+      transitionName: 'Payment Confirmed',
+      fromStepId: 'wait_payment_confirmation',
+      toStepId: 'order_confirmation',
+      trigger: 'auto',
+      priority: 100,
+    },
+    {
+      transitionId: 'confirmation_to_end',
+      transitionName: 'Finalize Order',
+      fromStepId: 'order_confirmation',
+      toStepId: 'end',
+      trigger: 'auto',
+      priority: 100,
+      activities: [
+        {
+          activityId: 'create_order',
+          activityName: 'Create Order Record',
+          activityType: 'CALL_API',
+          config: {
+            endpoint: '/api/sales/orders',
+            method: 'POST',
+            body: {
+              customerEntityId: '{{context.customer.id}}',
+              currencyCode: '{{context.cart.currency}}',
+              placedAt: '{{now}}',
+              grandTotalGrossAmount: '{{context.cart.total}}',
+            },
+            validateTenantMatch: true,
+          },
+          timeout: 'PT10S',
+          async: false,
+          retryPolicy: { maxAttempts: 3, initialIntervalMs: 2000, backoffCoefficient: 2, maxIntervalMs: 10000 },
+        },
+        {
+          activityId: 'send_confirmation_email',
+          activityName: 'Send Order Confirmation Email',
+          activityType: 'SEND_EMAIL',
+          config: {
+            to: '{{context.customer.email}}',
+            subject: 'Order Confirmation',
+            template: 'order_confirmation',
+            data: { customerName: '{{context.customer.name}}', total: '{{context.cart.total}}' },
+          },
+          timeout: 'PT15S',
+          async: true,
+          retryPolicy: { maxAttempts: 3, initialIntervalMs: 2000, backoffCoefficient: 2, maxIntervalMs: 20000 },
+        },
+      ],
+    },
+  ],
+})
+
+// ============================================================================
+// Module Export
+// ============================================================================
+
+export const workflowsConfig = createWorkflowsModuleConfig({
+  moduleId: 'workflows',
+  workflows: [simpleApproval, checkoutDemo],
+})
+
+export default workflowsConfig