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

package/.turbo/turbo-build.log

@@ -1,2 +1,2 @@
-[build:shared] found 204 entry points
+[build:shared] found 209 entry points
 [build:shared] built successfully

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.6.2-develop.3400.2.d948268f50";
+const APP_VERSION = "0.6.2-develop.3406.1.2b403f40da";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.2-develop.3400.2.d948268f50'\nexport const appVersion = APP_VERSION\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.2-develop.3406.1.2b403f40da'\nexport const appVersion = APP_VERSION\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/dist/modules/workflows/builder.js

@@ -0,0 +1,47 @@
+function defineWorkflow(config) {
+  const steps = config.steps.map((step) => ({
+    stepId: step.stepId,
+    stepName: step.stepName,
+    stepType: step.stepType,
+    ...step.description !== void 0 && { description: step.description },
+    ...step.config !== void 0 && { config: step.config },
+    ...step.userTaskConfig !== void 0 && { userTaskConfig: step.userTaskConfig },
+    ...step.subWorkflowConfig !== void 0 && { subWorkflowConfig: step.subWorkflowConfig },
+    ...step.signalConfig !== void 0 && { signalConfig: step.signalConfig },
+    ...step.activities !== void 0 && { activities: step.activities },
+    ...step.timeout !== void 0 && { timeout: step.timeout },
+    ...step.retryPolicy !== void 0 && { retryPolicy: step.retryPolicy },
+    ...step.preConditions !== void 0 && { preConditions: step.preConditions }
+  }));
+  const transitions = config.transitions.map((t) => ({
+    transitionId: t.transitionId,
+    fromStepId: t.fromStepId,
+    toStepId: t.toStepId,
+    trigger: t.trigger,
+    ...t.transitionName !== void 0 && { transitionName: t.transitionName },
+    ...t.preConditions !== void 0 && { preConditions: t.preConditions },
+    ...t.postConditions !== void 0 && { postConditions: t.postConditions },
+    ...t.activities !== void 0 && { activities: t.activities },
+    ...t.continueOnActivityFailure !== void 0 && { continueOnActivityFailure: t.continueOnActivityFailure },
+    ...t.priority !== void 0 && { priority: t.priority }
+  }));
+  return {
+    workflowId: config.workflowId,
+    workflowName: config.workflowName,
+    description: config.description ?? null,
+    version: config.version ?? 1,
+    enabled: config.enabled ?? true,
+    metadata: config.metadata ?? null,
+    definition: {
+      steps,
+      transitions,
+      ...config.triggers !== void 0 && { triggers: config.triggers }
+    },
+    moduleId: ""
+    // Set by generator/factory at registration time
+  };
+}
+export {
+  defineWorkflow
+};
+//# sourceMappingURL=builder.js.map

package/dist/modules/workflows/builder.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/modules/workflows/builder.ts"],
+  "sourcesContent": ["/**\n * Code-Based Workflow Definitions \u2014 Builder API\n *\n * Provides compile-time type safety for step IDs in transitions.\n * The `const` modifier on TSteps tells TypeScript to infer literal types\n * for stepId values. Transitions constrain fromStepId/toStepId to this union.\n *\n * @example\n * ```typescript\n * const workflow = defineWorkflow({\n *   workflowId: 'sales.order-approval',\n *   workflowName: 'Order Approval',\n *   steps: [\n *     { stepId: 'start', stepName: 'Start', stepType: 'START' },\n *     { stepId: 'review', stepName: 'Review', stepType: 'USER_TASK' },\n *     { stepId: 'end', stepName: 'End', stepType: 'END' },\n *   ] as const,\n *   transitions: [\n *     { transitionId: 'to-review', fromStepId: 'start', toStepId: 'review', trigger: 'auto' },\n *     // Compile error: '\"typo\"' is not assignable to '\"start\" | \"review\" | \"end\"'\n *     // { transitionId: 'bad', fromStepId: 'typo', toStepId: 'end', trigger: 'auto' },\n *   ],\n * })\n * ```\n */\n\nimport type {\n  CodeWorkflowDefinition,\n  CodeStepDefinition,\n  CodeTransitionDefinition,\n  CodeTriggerDefinition,\n  CodeActivityDefinition,\n  WorkflowStepType,\n  TransitionTrigger,\n} from './types'\n\n// ============================================================================\n// Builder Config Type (with const generic for type inference)\n// ============================================================================\n\ninterface WorkflowBuilderConfig<TSteps extends readonly StepInput<string>[]> {\n  workflowId: string\n  workflowName: string\n  description?: string\n  version?: number\n  enabled?: boolean\n  metadata?: { tags?: string[]; category?: string; icon?: string }\n  steps: TSteps\n  transitions: TransitionInput<TSteps[number]['stepId']>[]\n  triggers?: CodeTriggerDefinition[]\n}\n\ninterface StepInput<TStepId extends string> {\n  stepId: TStepId\n  stepName: string\n  stepType: WorkflowStepType\n  description?: string\n  config?: Record<string, unknown>\n  userTaskConfig?: CodeStepDefinition['userTaskConfig']\n  subWorkflowConfig?: CodeStepDefinition['subWorkflowConfig']\n  signalConfig?: CodeStepDefinition['signalConfig']\n  activities?: CodeActivityDefinition[]\n  timeout?: string\n  retryPolicy?: { maxAttempts: number; backoffMs: number }\n  preConditions?: CodeStepDefinition['preConditions']\n}\n\ninterface TransitionInput<TStepId extends string> {\n  transitionId: string\n  fromStepId: TStepId\n  toStepId: TStepId\n  transitionName?: string\n  trigger: TransitionTrigger\n  preConditions?: CodeTransitionDefinition['preConditions']\n  postConditions?: CodeTransitionDefinition['postConditions']\n  activities?: CodeActivityDefinition[]\n  continueOnActivityFailure?: boolean\n  priority?: number\n}\n\n// ============================================================================\n// defineWorkflow \u2014 Main Builder Function\n// ============================================================================\n\n/**\n * Define a code-based workflow with compile-time step ID safety.\n *\n * Use `as const` on the steps array for full type inference:\n * ```typescript\n * defineWorkflow({\n *   steps: [...] as const,\n *   transitions: [...], // fromStepId/toStepId auto-constrained\n * })\n * ```\n *\n * The returned `CodeWorkflowDefinition` has `moduleId` set to empty string.\n * The generator sets the correct `moduleId` at registration time.\n */\nexport function defineWorkflow<const TSteps extends readonly StepInput<string>[]>(\n  config: WorkflowBuilderConfig<TSteps>,\n): CodeWorkflowDefinition {\n  const steps: CodeStepDefinition[] = config.steps.map((step) => ({\n    stepId: step.stepId,\n    stepName: step.stepName,\n    stepType: step.stepType,\n    ...(step.description !== undefined && { description: step.description }),\n    ...(step.config !== undefined && { config: step.config }),\n    ...(step.userTaskConfig !== undefined && { userTaskConfig: step.userTaskConfig }),\n    ...(step.subWorkflowConfig !== undefined && { subWorkflowConfig: step.subWorkflowConfig }),\n    ...(step.signalConfig !== undefined && { signalConfig: step.signalConfig }),\n    ...(step.activities !== undefined && { activities: step.activities }),\n    ...(step.timeout !== undefined && { timeout: step.timeout }),\n    ...(step.retryPolicy !== undefined && { retryPolicy: step.retryPolicy }),\n    ...(step.preConditions !== undefined && { preConditions: step.preConditions }),\n  }))\n\n  const transitions: CodeTransitionDefinition[] = config.transitions.map((t) => ({\n    transitionId: t.transitionId,\n    fromStepId: t.fromStepId,\n    toStepId: t.toStepId,\n    trigger: t.trigger,\n    ...(t.transitionName !== undefined && { transitionName: t.transitionName }),\n    ...(t.preConditions !== undefined && { preConditions: t.preConditions }),\n    ...(t.postConditions !== undefined && { postConditions: t.postConditions }),\n    ...(t.activities !== undefined && { activities: t.activities }),\n    ...(t.continueOnActivityFailure !== undefined && { continueOnActivityFailure: t.continueOnActivityFailure }),\n    ...(t.priority !== undefined && { priority: t.priority }),\n  }))\n\n  return {\n    workflowId: config.workflowId,\n    workflowName: config.workflowName,\n    description: config.description ?? null,\n    version: config.version ?? 1,\n    enabled: config.enabled ?? true,\n    metadata: config.metadata ?? null,\n    definition: {\n      steps,\n      transitions,\n      ...(config.triggers !== undefined && { triggers: config.triggers }),\n    },\n    moduleId: '', // Set by generator/factory at registration time\n  }\n}\n"],
+  "mappings": "AAkGO,SAAS,eACd,QACwB;AACxB,QAAM,QAA8B,OAAO,MAAM,IAAI,CAAC,UAAU;AAAA,IAC9D,QAAQ,KAAK;AAAA,IACb,UAAU,KAAK;AAAA,IACf,UAAU,KAAK;AAAA,IACf,GAAI,KAAK,gBAAgB,UAAa,EAAE,aAAa,KAAK,YAAY;AAAA,IACtE,GAAI,KAAK,WAAW,UAAa,EAAE,QAAQ,KAAK,OAAO;AAAA,IACvD,GAAI,KAAK,mBAAmB,UAAa,EAAE,gBAAgB,KAAK,eAAe;AAAA,IAC/E,GAAI,KAAK,sBAAsB,UAAa,EAAE,mBAAmB,KAAK,kBAAkB;AAAA,IACxF,GAAI,KAAK,iBAAiB,UAAa,EAAE,cAAc,KAAK,aAAa;AAAA,IACzE,GAAI,KAAK,eAAe,UAAa,EAAE,YAAY,KAAK,WAAW;AAAA,IACnE,GAAI,KAAK,YAAY,UAAa,EAAE,SAAS,KAAK,QAAQ;AAAA,IAC1D,GAAI,KAAK,gBAAgB,UAAa,EAAE,aAAa,KAAK,YAAY;AAAA,IACtE,GAAI,KAAK,kBAAkB,UAAa,EAAE,eAAe,KAAK,cAAc;AAAA,EAC9E,EAAE;AAEF,QAAM,cAA0C,OAAO,YAAY,IAAI,CAAC,OAAO;AAAA,IAC7E,cAAc,EAAE;AAAA,IAChB,YAAY,EAAE;AAAA,IACd,UAAU,EAAE;AAAA,IACZ,SAAS,EAAE;AAAA,IACX,GAAI,EAAE,mBAAmB,UAAa,EAAE,gBAAgB,EAAE,eAAe;AAAA,IACzE,GAAI,EAAE,kBAAkB,UAAa,EAAE,eAAe,EAAE,cAAc;AAAA,IACtE,GAAI,EAAE,mBAAmB,UAAa,EAAE,gBAAgB,EAAE,eAAe;AAAA,IACzE,GAAI,EAAE,eAAe,UAAa,EAAE,YAAY,EAAE,WAAW;AAAA,IAC7D,GAAI,EAAE,8BAA8B,UAAa,EAAE,2BAA2B,EAAE,0BAA0B;AAAA,IAC1G,GAAI,EAAE,aAAa,UAAa,EAAE,UAAU,EAAE,SAAS;AAAA,EACzD,EAAE;AAEF,SAAO;AAAA,IACL,YAAY,OAAO;AAAA,IACnB,cAAc,OAAO;AAAA,IACrB,aAAa,OAAO,eAAe;AAAA,IACnC,SAAS,OAAO,WAAW;AAAA,IAC3B,SAAS,OAAO,WAAW;AAAA,IAC3B,UAAU,OAAO,YAAY;AAAA,IAC7B,YAAY;AAAA,MACV;AAAA,MACA;AAAA,MACA,GAAI,OAAO,aAAa,UAAa,EAAE,UAAU,OAAO,SAAS;AAAA,IACnE;AAAA,IACA,UAAU;AAAA;AAAA,EACZ;AACF;",
+  "names": []
+}

package/dist/modules/workflows/factory.js

@@ -0,0 +1,14 @@
+function createWorkflowsModuleConfig(options) {
+  const workflows = options.workflows.map((wf) => ({
+    ...wf,
+    moduleId: options.moduleId
+  }));
+  return {
+    moduleId: options.moduleId,
+    workflows
+  };
+}
+export {
+  createWorkflowsModuleConfig
+};
+//# sourceMappingURL=factory.js.map

package/dist/modules/workflows/factory.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/modules/workflows/factory.ts"],
+  "sourcesContent": ["/**\n * Code-Based Workflow Definitions \u2014 Module Config Factory\n *\n * Analogous to createModuleEvents() for events.\n * Creates a WorkflowsModuleConfig that the generator aggregates.\n */\n\nimport type { CodeWorkflowDefinition, WorkflowsModuleConfig } from './types'\n\nexport function createWorkflowsModuleConfig(options: {\n  moduleId: string\n  workflows: CodeWorkflowDefinition[]\n}): WorkflowsModuleConfig {\n  const workflows = options.workflows.map((wf) => ({\n    ...wf,\n    moduleId: options.moduleId,\n  }))\n\n  return {\n    moduleId: options.moduleId,\n    workflows,\n  }\n}\n"],
+  "mappings": "AASO,SAAS,4BAA4B,SAGlB;AACxB,QAAM,YAAY,QAAQ,UAAU,IAAI,CAAC,QAAQ;AAAA,IAC/C,GAAG;AAAA,IACH,UAAU,QAAQ;AAAA,EACpB,EAAE;AAEF,SAAO;AAAA,IACL,UAAU,QAAQ;AAAA,IAClB;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/modules/workflows/index.js

@@ -0,0 +1,7 @@
+import { defineWorkflow } from "./builder.js";
+import { createWorkflowsModuleConfig } from "./factory.js";
+export {
+  createWorkflowsModuleConfig,
+  defineWorkflow
+};
+//# sourceMappingURL=index.js.map

package/dist/modules/workflows/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/modules/workflows/index.ts"],
+  "sourcesContent": ["export type {\n  CodeWorkflowDefinition,\n  CodeWorkflowDefinitionData,\n  CodeStepDefinition,\n  CodeTransitionDefinition,\n  CodeTriggerDefinition,\n  CodeActivityDefinition,\n  WorkflowStepType,\n  TransitionTrigger,\n  ActivityType,\n  WorkflowsModuleConfig,\n} from './types'\n\nexport { defineWorkflow } from './builder'\nexport { createWorkflowsModuleConfig } from './factory'\n"],
+  "mappings": "AAaA,SAAS,sBAAsB;AAC/B,SAAS,mCAAmC;",
+  "names": []
+}

package/dist/modules/workflows/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/modules/workflows/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/modules/workflows.js

@@ -0,0 +1,2 @@
+export * from "./workflows/index.js";
+//# sourceMappingURL=workflows.js.map

package/dist/modules/workflows.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/modules/workflows.ts"],
+  "sourcesContent": ["export * from './workflows/index'\n"],
+  "mappings": "AAAA,cAAc;",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.2-develop.3400.2.d948268f50",
+  "version": "0.6.2-develop.3406.1.2b403f40da",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -92,7 +92,7 @@
     "@mikro-orm/core": "^7.0.15",
     "@mikro-orm/decorators": "^7.0.15",
     "@mikro-orm/postgresql": "^7.0.15",
-    "@open-mercato/cache": "0.6.2-develop.3400.2.d948268f50",
+    "@open-mercato/cache": "0.6.2-develop.3406.1.2b403f40da",
     "dotenv": "^17.4.2",
     "rate-limiter-flexible": "^11.1.0",
     "reflect-metadata": "^0.2.2",

package/src/modules/workflows/__tests__/builder.test.ts

@@ -0,0 +1,394 @@
+import { describe, test, expect } from '@jest/globals'
+import { defineWorkflow } from '../builder'
+import { createWorkflowsModuleConfig } from '../factory'
+
+const minimalSteps = [
+  { stepId: 'start', stepName: 'Start', stepType: 'START' as const },
+  { stepId: 'end', stepName: 'End', stepType: 'END' as const },
+] as const
+
+const minimalTransitions = [
+  { transitionId: 'to-end', fromStepId: 'start', toStepId: 'end', trigger: 'auto' as const },
+]
+
+describe('defineWorkflow()', () => {
+  test('returns a CodeWorkflowDefinition with correct top-level structure', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'sales.order-approval',
+      workflowName: 'Order Approval',
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+    })
+
+    expect(workflow.workflowId).toBe('sales.order-approval')
+    expect(workflow.workflowName).toBe('Order Approval')
+    expect(workflow).toHaveProperty('definition')
+    expect(workflow).not.toHaveProperty('steps')
+    expect(workflow.definition.steps).toBeDefined()
+    expect(workflow.definition.transitions).toBeDefined()
+  })
+
+  test('maps steps with correct stepType, stepName, stepId', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      steps: [
+        { stepId: 'start', stepName: 'Start Step', stepType: 'START' as const },
+        { stepId: 'review', stepName: 'Review Step', stepType: 'USER_TASK' as const },
+        { stepId: 'end', stepName: 'End Step', stepType: 'END' as const },
+      ] as const,
+      transitions: [
+        { transitionId: 't1', fromStepId: 'start', toStepId: 'review', trigger: 'auto' as const },
+        { transitionId: 't2', fromStepId: 'review', toStepId: 'end', trigger: 'manual' as const },
+      ],
+    })
+
+    expect(workflow.definition.steps).toHaveLength(3)
+    expect(workflow.definition.steps[0]).toMatchObject({ stepId: 'start', stepName: 'Start Step', stepType: 'START' })
+    expect(workflow.definition.steps[1]).toMatchObject({ stepId: 'review', stepName: 'Review Step', stepType: 'USER_TASK' })
+    expect(workflow.definition.steps[2]).toMatchObject({ stepId: 'end', stepName: 'End Step', stepType: 'END' })
+  })
+
+  test('maps transitions with correct fromStepId and toStepId', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      steps: minimalSteps,
+      transitions: [
+        {
+          transitionId: 'start-to-end',
+          fromStepId: 'start',
+          toStepId: 'end',
+          trigger: 'auto' as const,
+          transitionName: 'Auto Complete',
+          priority: 1,
+        },
+      ],
+    })
+
+    expect(workflow.definition.transitions).toHaveLength(1)
+    expect(workflow.definition.transitions[0]).toMatchObject({
+      transitionId: 'start-to-end',
+      fromStepId: 'start',
+      toStepId: 'end',
+      trigger: 'auto',
+      transitionName: 'Auto Complete',
+      priority: 1,
+    })
+  })
+
+  test('sets moduleId to empty string', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+    })
+
+    expect(workflow.moduleId).toBe('')
+  })
+
+  test('defaults enabled to true when not specified', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+    })
+
+    expect(workflow.enabled).toBe(true)
+  })
+
+  test('respects explicit enabled: false', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      enabled: false,
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+    })
+
+    expect(workflow.enabled).toBe(false)
+  })
+
+  test('defaults version to 1 when not specified', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+    })
+
+    expect(workflow.version).toBe(1)
+  })
+
+  test('sets version correctly when specified', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      version: 3,
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+    })
+
+    expect(workflow.version).toBe(3)
+  })
+
+  test('defaults description to null when not specified', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+    })
+
+    expect(workflow.description).toBeNull()
+  })
+
+  test('sets description when specified', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      description: 'Handles order approvals',
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+    })
+
+    expect(workflow.description).toBe('Handles order approvals')
+  })
+
+  test('defaults metadata to null when not specified', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+    })
+
+    expect(workflow.metadata).toBeNull()
+  })
+
+  test('sets metadata when specified', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      metadata: { tags: ['sales', 'approval'], category: 'sales', icon: 'check' },
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+    })
+
+    expect(workflow.metadata).toEqual({ tags: ['sales', 'approval'], category: 'sales', icon: 'check' })
+  })
+
+  test('omits triggers from definition when not specified', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+    })
+
+    expect(workflow.definition.triggers).toBeUndefined()
+  })
+
+  test('includes triggers in definition when specified', () => {
+    const trigger = {
+      triggerId: 'on-order-created',
+      name: 'Order Created',
+      eventPattern: 'sales.order.created',
+      enabled: true,
+      priority: 0,
+    }
+
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+      triggers: [trigger],
+    })
+
+    expect(workflow.definition.triggers).toHaveLength(1)
+    expect(workflow.definition.triggers![0]).toMatchObject(trigger)
+  })
+
+  test('does not include optional step fields when not provided', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      steps: [{ stepId: 'start', stepName: 'Start', stepType: 'START' as const }] as const,
+      transitions: [],
+    })
+
+    const step = workflow.definition.steps[0]
+    expect(step).not.toHaveProperty('description')
+    expect(step).not.toHaveProperty('config')
+    expect(step).not.toHaveProperty('userTaskConfig')
+    expect(step).not.toHaveProperty('activities')
+    expect(step).not.toHaveProperty('timeout')
+    expect(step).not.toHaveProperty('retryPolicy')
+  })
+
+  test('includes optional step fields when provided', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      steps: [
+        {
+          stepId: 'review',
+          stepName: 'Review',
+          stepType: 'USER_TASK' as const,
+          description: 'Manager reviews the order',
+          timeout: 'P1D',
+          retryPolicy: { maxAttempts: 3, backoffMs: 1000 },
+          userTaskConfig: { assignedTo: 'manager', slaDuration: 'P1D' },
+        },
+      ] as const,
+      transitions: [],
+    })
+
+    const step = workflow.definition.steps[0]
+    expect(step.description).toBe('Manager reviews the order')
+    expect(step.timeout).toBe('P1D')
+    expect(step.retryPolicy).toEqual({ maxAttempts: 3, backoffMs: 1000 })
+    expect(step.userTaskConfig).toMatchObject({ assignedTo: 'manager', slaDuration: 'P1D' })
+  })
+
+  test('does not include optional transition fields when not provided', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      steps: minimalSteps,
+      transitions: [{ transitionId: 't1', fromStepId: 'start', toStepId: 'end', trigger: 'auto' as const }],
+    })
+
+    const transition = workflow.definition.transitions[0]
+    expect(transition).not.toHaveProperty('transitionName')
+    expect(transition).not.toHaveProperty('preConditions')
+    expect(transition).not.toHaveProperty('postConditions')
+    expect(transition).not.toHaveProperty('activities')
+    expect(transition).not.toHaveProperty('continueOnActivityFailure')
+    expect(transition).not.toHaveProperty('priority')
+  })
+
+  test('works correctly with as const steps (key type safety feature)', () => {
+    // TypeScript should infer literal step IDs from `as const`.
+    // This test ensures the runtime behavior is correct when the pattern is used.
+    const workflow = defineWorkflow({
+      workflowId: 'sales.order-approval',
+      workflowName: 'Order Approval',
+      steps: [
+        { stepId: 'start', stepName: 'Start', stepType: 'START' as const },
+        { stepId: 'review', stepName: 'Review', stepType: 'USER_TASK' as const },
+        { stepId: 'end', stepName: 'End', stepType: 'END' as const },
+      ] as const,
+      transitions: [
+        { transitionId: 'to-review', fromStepId: 'start', toStepId: 'review', trigger: 'auto' as const },
+        { transitionId: 'to-end', fromStepId: 'review', toStepId: 'end', trigger: 'manual' as const },
+      ],
+    })
+
+    expect(workflow.definition.steps.map((s) => s.stepId)).toEqual(['start', 'review', 'end'])
+    expect(workflow.definition.transitions.map((t) => t.fromStepId)).toEqual(['start', 'review'])
+    expect(workflow.definition.transitions.map((t) => t.toStepId)).toEqual(['review', 'end'])
+  })
+})
+
+describe('createWorkflowsModuleConfig()', () => {
+  const workflowA = defineWorkflow({
+    workflowId: 'test.workflow-a',
+    workflowName: 'Workflow A',
+    steps: minimalSteps,
+    transitions: minimalTransitions,
+  })
+
+  const workflowB = defineWorkflow({
+    workflowId: 'test.workflow-b',
+    workflowName: 'Workflow B',
+    steps: minimalSteps,
+    transitions: minimalTransitions,
+  })
+
+  test('returns WorkflowsModuleConfig with correct structure', () => {
+    const config = createWorkflowsModuleConfig({
+      moduleId: 'sales',
+      workflows: [workflowA],
+    })
+
+    expect(config).toHaveProperty('moduleId')
+    expect(config).toHaveProperty('workflows')
+    expect(Array.isArray(config.workflows)).toBe(true)
+  })
+
+  test('sets moduleId on the config', () => {
+    const config = createWorkflowsModuleConfig({
+      moduleId: 'sales',
+      workflows: [workflowA],
+    })
+
+    expect(config.moduleId).toBe('sales')
+  })
+
+  test('sets moduleId on all workflows', () => {
+    const config = createWorkflowsModuleConfig({
+      moduleId: 'sales',
+      workflows: [workflowA, workflowB],
+    })
+
+    expect(config.workflows[0].moduleId).toBe('sales')
+    expect(config.workflows[1].moduleId).toBe('sales')
+  })
+
+  test('preserves workflow properties after moduleId assignment', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'sales.order-approval',
+      workflowName: 'Order Approval',
+      description: 'Approves orders',
+      version: 2,
+      enabled: false,
+      metadata: { tags: ['sales'], category: 'approvals' },
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+    })
+
+    const config = createWorkflowsModuleConfig({
+      moduleId: 'sales',
+      workflows: [workflow],
+    })
+
+    const result = config.workflows[0]
+    expect(result.workflowId).toBe('sales.order-approval')
+    expect(result.workflowName).toBe('Order Approval')
+    expect(result.description).toBe('Approves orders')
+    expect(result.version).toBe(2)
+    expect(result.enabled).toBe(false)
+    expect(result.metadata).toEqual({ tags: ['sales'], category: 'approvals' })
+    expect(result.definition.steps).toHaveLength(2)
+    expect(result.definition.transitions).toHaveLength(1)
+  })
+
+  test('does not mutate the original workflow objects', () => {
+    const workflow = defineWorkflow({
+      workflowId: 'test.workflow',
+      workflowName: 'Test',
+      steps: minimalSteps,
+      transitions: minimalTransitions,
+    })
+
+    expect(workflow.moduleId).toBe('')
+
+    createWorkflowsModuleConfig({ moduleId: 'sales', workflows: [workflow] })
+
+    expect(workflow.moduleId).toBe('')
+  })
+
+  test('handles empty workflows array', () => {
+    const config = createWorkflowsModuleConfig({
+      moduleId: 'sales',
+      workflows: [],
+    })
+
+    expect(config.moduleId).toBe('sales')
+    expect(config.workflows).toHaveLength(0)
+  })
+})

package/src/modules/workflows/builder.ts

@@ -0,0 +1,144 @@
+/**
+ * Code-Based Workflow Definitions — Builder API
+ *
+ * Provides compile-time type safety for step IDs in transitions.
+ * The `const` modifier on TSteps tells TypeScript to infer literal types
+ * for stepId values. Transitions constrain fromStepId/toStepId to this union.
+ *
+ * @example
+ * ```typescript
+ * const workflow = defineWorkflow({
+ *   workflowId: 'sales.order-approval',
+ *   workflowName: 'Order Approval',
+ *   steps: [
+ *     { stepId: 'start', stepName: 'Start', stepType: 'START' },
+ *     { stepId: 'review', stepName: 'Review', stepType: 'USER_TASK' },
+ *     { stepId: 'end', stepName: 'End', stepType: 'END' },
+ *   ] as const,
+ *   transitions: [
+ *     { transitionId: 'to-review', fromStepId: 'start', toStepId: 'review', trigger: 'auto' },
+ *     // Compile error: '"typo"' is not assignable to '"start" | "review" | "end"'
+ *     // { transitionId: 'bad', fromStepId: 'typo', toStepId: 'end', trigger: 'auto' },
+ *   ],
+ * })
+ * ```
+ */
+
+import type {
+  CodeWorkflowDefinition,
+  CodeStepDefinition,
+  CodeTransitionDefinition,
+  CodeTriggerDefinition,
+  CodeActivityDefinition,
+  WorkflowStepType,
+  TransitionTrigger,
+} from './types'
+
+// ============================================================================
+// Builder Config Type (with const generic for type inference)
+// ============================================================================
+
+interface WorkflowBuilderConfig<TSteps extends readonly StepInput<string>[]> {
+  workflowId: string
+  workflowName: string
+  description?: string
+  version?: number
+  enabled?: boolean
+  metadata?: { tags?: string[]; category?: string; icon?: string }
+  steps: TSteps
+  transitions: TransitionInput<TSteps[number]['stepId']>[]
+  triggers?: CodeTriggerDefinition[]
+}
+
+interface StepInput<TStepId extends string> {
+  stepId: TStepId
+  stepName: string
+  stepType: WorkflowStepType
+  description?: string
+  config?: Record<string, unknown>
+  userTaskConfig?: CodeStepDefinition['userTaskConfig']
+  subWorkflowConfig?: CodeStepDefinition['subWorkflowConfig']
+  signalConfig?: CodeStepDefinition['signalConfig']
+  activities?: CodeActivityDefinition[]
+  timeout?: string
+  retryPolicy?: { maxAttempts: number; backoffMs: number }
+  preConditions?: CodeStepDefinition['preConditions']
+}
+
+interface TransitionInput<TStepId extends string> {
+  transitionId: string
+  fromStepId: TStepId
+  toStepId: TStepId
+  transitionName?: string
+  trigger: TransitionTrigger
+  preConditions?: CodeTransitionDefinition['preConditions']
+  postConditions?: CodeTransitionDefinition['postConditions']
+  activities?: CodeActivityDefinition[]
+  continueOnActivityFailure?: boolean
+  priority?: number
+}
+
+// ============================================================================
+// defineWorkflow — Main Builder Function
+// ============================================================================
+
+/**
+ * Define a code-based workflow with compile-time step ID safety.
+ *
+ * Use `as const` on the steps array for full type inference:
+ * ```typescript
+ * defineWorkflow({
+ *   steps: [...] as const,
+ *   transitions: [...], // fromStepId/toStepId auto-constrained
+ * })
+ * ```
+ *
+ * The returned `CodeWorkflowDefinition` has `moduleId` set to empty string.
+ * The generator sets the correct `moduleId` at registration time.
+ */
+export function defineWorkflow<const TSteps extends readonly StepInput<string>[]>(
+  config: WorkflowBuilderConfig<TSteps>,
+): CodeWorkflowDefinition {
+  const steps: CodeStepDefinition[] = config.steps.map((step) => ({
+    stepId: step.stepId,
+    stepName: step.stepName,
+    stepType: step.stepType,
+    ...(step.description !== undefined && { description: step.description }),
+    ...(step.config !== undefined && { config: step.config }),
+    ...(step.userTaskConfig !== undefined && { userTaskConfig: step.userTaskConfig }),
+    ...(step.subWorkflowConfig !== undefined && { subWorkflowConfig: step.subWorkflowConfig }),
+    ...(step.signalConfig !== undefined && { signalConfig: step.signalConfig }),
+    ...(step.activities !== undefined && { activities: step.activities }),
+    ...(step.timeout !== undefined && { timeout: step.timeout }),
+    ...(step.retryPolicy !== undefined && { retryPolicy: step.retryPolicy }),
+    ...(step.preConditions !== undefined && { preConditions: step.preConditions }),
+  }))
+
+  const transitions: CodeTransitionDefinition[] = config.transitions.map((t) => ({
+    transitionId: t.transitionId,
+    fromStepId: t.fromStepId,
+    toStepId: t.toStepId,
+    trigger: t.trigger,
+    ...(t.transitionName !== undefined && { transitionName: t.transitionName }),
+    ...(t.preConditions !== undefined && { preConditions: t.preConditions }),
+    ...(t.postConditions !== undefined && { postConditions: t.postConditions }),
+    ...(t.activities !== undefined && { activities: t.activities }),
+    ...(t.continueOnActivityFailure !== undefined && { continueOnActivityFailure: t.continueOnActivityFailure }),
+    ...(t.priority !== undefined && { priority: t.priority }),
+  }))
+
+  return {
+    workflowId: config.workflowId,
+    workflowName: config.workflowName,
+    description: config.description ?? null,
+    version: config.version ?? 1,
+    enabled: config.enabled ?? true,
+    metadata: config.metadata ?? null,
+    definition: {
+      steps,
+      transitions,
+      ...(config.triggers !== undefined && { triggers: config.triggers }),
+    },
+    moduleId: '', // Set by generator/factory at registration time
+  }
+}

package/src/modules/workflows/factory.ts

@@ -0,0 +1,23 @@
+/**
+ * Code-Based Workflow Definitions — Module Config Factory
+ *
+ * Analogous to createModuleEvents() for events.
+ * Creates a WorkflowsModuleConfig that the generator aggregates.
+ */
+
+import type { CodeWorkflowDefinition, WorkflowsModuleConfig } from './types'
+
+export function createWorkflowsModuleConfig(options: {
+  moduleId: string
+  workflows: CodeWorkflowDefinition[]
+}): WorkflowsModuleConfig {
+  const workflows = options.workflows.map((wf) => ({
+    ...wf,
+    moduleId: options.moduleId,
+  }))
+
+  return {
+    moduleId: options.moduleId,
+    workflows,
+  }
+}

package/src/modules/workflows/index.ts

@@ -0,0 +1,15 @@
+export type {
+  CodeWorkflowDefinition,
+  CodeWorkflowDefinitionData,
+  CodeStepDefinition,
+  CodeTransitionDefinition,
+  CodeTriggerDefinition,
+  CodeActivityDefinition,
+  WorkflowStepType,
+  TransitionTrigger,
+  ActivityType,
+  WorkflowsModuleConfig,
+} from './types'
+
+export { defineWorkflow } from './builder'
+export { createWorkflowsModuleConfig } from './factory'

package/src/modules/workflows/types.ts

@@ -0,0 +1,190 @@
+/**
+ * Code-Based Workflow Definitions — Shared Types
+ *
+ * These types are used by the builder API, generator extension, and in-memory registry.
+ * They mirror the JSONB shape stored in workflow_definitions.definition but add
+ * generic type safety for step ID references in transitions.
+ */
+
+// ============================================================================
+// Step Types
+// ============================================================================
+
+export type WorkflowStepType =
+  | 'START'
+  | 'END'
+  | 'USER_TASK'
+  | 'AUTOMATED'
+  | 'PARALLEL_FORK'
+  | 'PARALLEL_JOIN'
+  | 'SUB_WORKFLOW'
+  | 'WAIT_FOR_SIGNAL'
+  | 'WAIT_FOR_TIMER'
+
+export type TransitionTrigger = 'auto' | 'manual' | 'signal' | 'timer'
+
+export type ActivityType =
+  | 'SEND_EMAIL'
+  | 'CALL_API'
+  | 'UPDATE_ENTITY'
+  | 'EMIT_EVENT'
+  | 'CALL_WEBHOOK'
+  | 'EXECUTE_FUNCTION'
+  | 'WAIT'
+
+// ============================================================================
+// Activity Definition
+// ============================================================================
+
+export interface CodeActivityDefinition {
+  activityId: string
+  activityName: string
+  activityType: ActivityType
+  config: Record<string, unknown>
+  async?: boolean
+  retryPolicy?: {
+    maxAttempts: number
+    initialIntervalMs: number
+    backoffCoefficient: number
+    maxIntervalMs: number
+  }
+  timeout?: string
+  compensation?: {
+    activityId: string
+    automatic?: boolean
+  }
+}
+
+// ============================================================================
+// Step Definition (generic over step IDs)
+// ============================================================================
+
+export interface CodeStepDefinition<TStepId extends string = string> {
+  stepId: TStepId
+  stepName: string
+  stepType: WorkflowStepType
+  description?: string
+  config?: Record<string, unknown>
+  userTaskConfig?: {
+    formSchema?: Record<string, unknown>
+    assignedTo?: string | string[]
+    assignmentRule?: string
+    slaDuration?: string
+    escalationRules?: Array<{
+      trigger: 'sla_breach' | 'no_progress' | 'custom'
+      action: 'reassign' | 'notify' | 'escalate'
+      escalateTo?: string
+      notifyUsers?: string[]
+    }>
+  }
+  subWorkflowConfig?: {
+    subWorkflowId: string
+    version?: number
+    inputMapping?: Record<string, string>
+    outputMapping?: Record<string, string>
+    timeoutMs?: number
+  }
+  signalConfig?: {
+    signalName: string
+    timeout?: string
+  }
+  activities?: CodeActivityDefinition[]
+  timeout?: string
+  retryPolicy?: {
+    maxAttempts: number
+    backoffMs: number
+  }
+  preConditions?: Array<{
+    ruleId: string
+    required?: boolean
+    validationMessage?: Record<string, string>
+  }>
+}
+
+// ============================================================================
+// Transition Definition (generic over step IDs)
+// ============================================================================
+
+export interface CodeTransitionDefinition<TStepId extends string = string> {
+  transitionId: string
+  fromStepId: TStepId
+  toStepId: TStepId
+  transitionName?: string
+  trigger: TransitionTrigger
+  preConditions?: Array<{
+    ruleId: string
+    required?: boolean
+  }>
+  postConditions?: Array<{
+    ruleId: string
+    required?: boolean
+  }>
+  activities?: CodeActivityDefinition[]
+  continueOnActivityFailure?: boolean
+  priority?: number
+}
+
+// ============================================================================
+// Trigger Definition
+// ============================================================================
+
+export interface CodeTriggerDefinition {
+  triggerId: string
+  name: string
+  description?: string | null
+  eventPattern: string
+  config?: {
+    filterConditions?: Array<{
+      field: string
+      operator: string
+      value: unknown
+    }>
+    contextMapping?: Array<{
+      targetKey: string
+      sourceExpression: string
+      defaultValue?: unknown
+    }>
+    debounceMs?: number
+    maxConcurrentInstances?: number
+    entityType?: string
+  } | null
+  enabled: boolean
+  priority: number
+}
+
+// ============================================================================
+// Workflow Definition Data (matches JSONB shape)
+// ============================================================================
+
+export interface CodeWorkflowDefinitionData {
+  steps: CodeStepDefinition[]
+  transitions: CodeTransitionDefinition[]
+  triggers?: CodeTriggerDefinition[]
+  queries?: unknown[]
+  signals?: unknown[]
+  timers?: unknown[]
+}
+
+// ============================================================================
+// Code Workflow Definition (output of defineWorkflow)
+// ============================================================================
+
+export interface CodeWorkflowDefinition {
+  workflowId: string
+  workflowName: string
+  description: string | null
+  version: number
+  enabled: boolean
+  metadata: { tags?: string[]; category?: string; icon?: string } | null
+  definition: CodeWorkflowDefinitionData
+  moduleId: string
+}
+
+// ============================================================================
+// Module Config (for generator discovery)
+// ============================================================================
+
+export interface WorkflowsModuleConfig {
+  moduleId: string
+  workflows: CodeWorkflowDefinition[]
+}

package/src/modules/workflows.ts

@@ -0,0 +1 @@
+export * from './workflows/index'