@acorex/platform 21.0.0-next.5 → 21.0.0-next.8

package/fesm2022/acorex-platform-workflow.mjs

@@ -1,8 +1,8 @@
 import * as i0 from '@angular/core';
-import { Injectable, inject, Optional, Inject, NgModule, InjectionToken } from '@angular/core';
+import { Injectable, inject, InjectionToken, Optional, Inject, NgModule } from '@angular/core';
 import { Subject, filter } from 'rxjs';
 import { cloneDeep, get, set } from 'lodash-es';
-import { setSmart } from '@acorex/platform/core';
+import { setSmart, AXPDataGenerator } from '@acorex/platform/core';
 import { AXPCommandService } from '@acorex/platform/runtime';
 
 class AXPWorkflowError extends Error {
@@ -411,263 +411,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.12", ngImpo
                 }]
         }] });
 
-class AXPWorkflowModule {
-    static forRoot(config) {
-        return {
-            ngModule: AXPWorkflowModule,
-            providers: [
-                {
-                    provide: 'AXPWorkflowModuleFactory',
-                    useFactory: (registry) => () => {
-                        registry.registerAction('start-workflow', AXPStartWorkflowAction);
-                        registry.registerAction('decide', AXPWorkflowDecideAction);
-                        //
-                        if (config?.functions) {
-                            for (const [key, type] of Object.entries(config.functions)) {
-                                registry.registerFunction(key, type);
-                            }
-                        }
-                        //
-                        if (config?.actions) {
-                            for (const [key, type] of Object.entries(config.actions)) {
-                                registry.registerAction(key, type);
-                            }
-                        }
-                        //
-                        if (config?.workflows) {
-                            for (const [key, type] of Object.entries(config.workflows)) {
-                                registry.registerWorkflow(key, type);
-                            }
-                        }
-                    },
-                    deps: [AXPWorkflowRegistryService],
-                    multi: true,
-                },
-                ...Object.values(config?.actions ?? { AXPStartWorkflowAction }),
-                ...Object.values(config?.functions ?? {}),
-            ],
-        };
-    }
-    static forChild(config) {
-        return {
-            ngModule: AXPWorkflowModule,
-            providers: [
-                // Built-in activities are already registered in forRoot via @NgModule providers
-                // No need to register again in forChild
-                {
-                    provide: 'AXPWorkflowModuleFactory',
-                    useFactory: (registry) => () => {
-                        registry.registerAction('start-workflow', AXPStartWorkflowAction);
-                        registry.registerAction('decide', AXPWorkflowDecideAction);
-                        //
-                        if (config?.functions) {
-                            for (const [key, type] of Object.entries(config.functions)) {
-                                registry.registerFunction(key, type);
-                            }
-                        }
-                        //
-                        if (config?.actions) {
-                            for (const [key, type] of Object.entries(config.actions)) {
-                                registry.registerAction(key, type);
-                            }
-                        }
-                        //
-                        if (config?.workflows) {
-                            for (const [key, type] of Object.entries(config.workflows)) {
-                                registry.registerWorkflow(key, type);
-                            }
-                        }
-                    },
-                    deps: [AXPWorkflowRegistryService],
-                    multi: true,
-                },
-                ...Object.values(config?.actions ?? {}),
-                ...Object.values(config?.functions ?? {}),
-            ],
-        };
-    }
-    /**
-     * @ignore
-     */
-    constructor(instances) {
-        instances?.forEach((f) => {
-            f();
-        });
-    }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowModule, deps: [{ token: 'AXPWorkflowModuleFactory', optional: true }], target: i0.ɵɵFactoryTarget.NgModule }); }
-    static { this.ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowModule }); }
-    static { this.ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowModule }); }
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowModule, decorators: [{
-            type: NgModule,
-            args: [{
-                    imports: [],
-                    exports: [],
-                    declarations: [],
-                    providers: [],
-                }]
-        }], ctorParameters: () => [{ type: undefined, decorators: [{
-                    type: Optional
-                }, {
-                    type: Inject,
-                    args: ['AXPWorkflowModuleFactory']
-                }] }] });
-
 /**
  * Injection token for workflow definition loaders.
  * Multiple loaders can be provided (multi: true).
  */
 const AXP_WORKFLOW_DEFINITION_LOADER = new InjectionToken('AXP_WORKFLOW_DEFINITION_LOADER');
-/**
- * Resolver service for workflow definitions.
- * Aggregates all registered loaders and resolves workflow definitions.
- */
-class AXPWorkflowDefinitionResolver {
-    constructor() {
-        this.loaders = inject(AXP_WORKFLOW_DEFINITION_LOADER, { optional: true });
-    }
-    /**
-     * Get workflow definition by name (unique key).
-     * Tries all registered loaders until one returns a definition.
-     * @param name - The workflow name (unique key)
-     * @returns Workflow definition or null if not found
-     */
-    async get(name) {
-        const loaderArray = Array.isArray(this.loaders) ? this.loaders : this.loaders ? [this.loaders] : [];
-        for (const loader of loaderArray) {
-            try {
-                const definition = await loader.get(name);
-                if (definition) {
-                    return definition;
-                }
-            }
-            catch (error) {
-                console.warn(`[AXPWorkflowDefinitionResolver] Loader failed for ${name}:`, error);
-            }
-        }
-        return null;
-    }
-    /**
-     * Get all available workflow names from all loaders.
-     * @returns Array of unique workflow names
-     */
-    async getAllNames() {
-        const loaderArray = Array.isArray(this.loaders) ? this.loaders : this.loaders ? [this.loaders] : [];
-        const allNames = new Set();
-        for (const loader of loaderArray) {
-            if (loader.getAllNames) {
-                try {
-                    const names = await loader.getAllNames();
-                    names.forEach((name) => allNames.add(name));
-                }
-                catch (error) {
-                    console.warn('[AXPWorkflowDefinitionResolver] Failed to get names from loader:', error);
-                }
-            }
-        }
-        return Array.from(allNames);
-    }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowDefinitionResolver, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowDefinitionResolver, providedIn: 'root' }); }
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowDefinitionResolver, decorators: [{
-            type: Injectable,
-            args: [{ providedIn: 'root' }]
-        }] });
-
-/**
- * Registry service for workflow definitions.
- * Caches loaded definitions and provides change notifications.
- */
-class AXPWorkflowDefinitionRegistryService {
-    constructor() {
-        this.resolver = inject(AXPWorkflowDefinitionResolver);
-        this.cache = new Map();
-        this.onChanged = new Subject();
-    }
-    /**
-     * Observable for workflow definition changes.
-     */
-    get onChanged$() {
-        return this.onChanged.asObservable();
-    }
-    /**
-     * Get workflow definition by name (unique key).
-     * Uses cache if available, otherwise loads from resolver.
-     * @param name - The workflow name (unique key)
-     * @returns Workflow definition or null if not found
-     */
-    async get(name) {
-        // Check cache first
-        if (this.cache.has(name)) {
-            return this.cache.get(name);
-        }
-        // Load from resolver
-        const definition = await this.resolver.get(name);
-        if (definition) {
-            this.cache.set(name, definition);
-            this.onChanged.next({ name, action: 'registered' });
-        }
-        return definition;
-    }
-    /**
-     * Register a workflow definition in the cache.
-     * @param definition - The workflow definition to register
-     */
-    register(definition) {
-        this.cache.set(definition.name, definition);
-        this.onChanged.next({ name: definition.name, action: 'registered' });
-    }
-    /**
-     * Update a workflow definition in the cache.
-     * @param definition - The updated workflow definition
-     */
-    update(definition) {
-        if (this.cache.has(definition.name)) {
-            this.cache.set(definition.name, definition);
-            this.onChanged.next({ name: definition.name, action: 'updated' });
-        }
-    }
-    /**
-     * Remove a workflow definition from the cache.
-     * @param name - The workflow name to remove
-     */
-    remove(name) {
-        if (this.cache.has(name)) {
-            this.cache.delete(name);
-            this.onChanged.next({ name, action: 'removed' });
-        }
-    }
-    /**
-     * Clear all cached workflow definitions.
-     */
-    clear() {
-        this.cache.clear();
-    }
-    /**
-     * Check if a workflow definition is cached.
-     * @param definitionId - The workflow definition ID
-     * @returns True if cached, false otherwise
-     */
-    has(definitionId) {
-        return this.cache.has(definitionId);
-    }
-    /**
-     * Get all cached workflow definition IDs.
-     * @returns Array of definition IDs (only those that have been loaded)
-     */
-    getAllIds() {
-        return Array.from(this.cache.keys());
-    }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowDefinitionRegistryService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowDefinitionRegistryService, providedIn: 'root' }); }
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowDefinitionRegistryService, decorators: [{
-            type: Injectable,
-            args: [{
-                    providedIn: 'root',
-                }]
-        }] });
 
 // ============================================
 // WORKFLOW INSTANCE v3.0.0 TYPES
@@ -1105,133 +853,215 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.12", ngImpo
         }] });
 
 /**
- * Abstract service for workflow execution operations.
- *
- * This service handles communication with backend for workflow execution.
- *
- * Implementation should be provided in connectivity layer:
- * - Mock implementation: @acorex/connectivity/mock
- * - API implementation: @acorex/connectivity/api
- *
- * @example
- * ```typescript
- * // In connectivity/mock
- * @Injectable()
- * export class AXCWorkflowExecutionService implements AXPWorkflowExecutionService {
- *   async startExecution(request: AXPStartWorkflowExecutionRequest): Promise<AXPStartWorkflowExecutionResponse> {
- *     // Mock implementation
- *   }
- * }
+ * Injection token for workflow engine.
+ * Default implementation is AXPWorkflowLocalEngine.
+ */
+const AXP_WORKFLOW_ENGINE = new InjectionToken('AXP_WORKFLOW_ENGINE');
+
+//#endregion
+/**
+ * Service responsible for executing frontend workflow tasks.
  *
- * // In connectivity/api
- * @Injectable()
- * export class AXCWorkflowExecutionService implements AXPWorkflowExecutionService {
- *   constructor(private http: HttpClient) {}
+ * This service handles the execution of frontend or hybrid tasks using
+ * the command infrastructure. It translates command results into
+ * workflow-compatible output and outcome format.
  *
- *   async startExecution(request: AXPStartWorkflowExecutionRequest): Promise<AXPStartWorkflowExecutionResponse> {
- *     return firstValueFrom(
- *       this.http.post<AXPStartWorkflowExecutionResponse>(
- *         `${this.config.baseUrl}/api/workflows/${request.workflowId}/start`,
- *         { input: request.input }
- *       )
- *     );
- *   }
- * }
- * ```
+ * This service is replaceable per platform and contains all execution logic.
  */
-class AXPWorkflowExecutionService {
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowExecutionService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowExecutionService }); }
+class FrontendTaskExecutor {
+    constructor() {
+        //#region ----   Services & Dependencies   ----
+        this.commandService = inject(AXPCommandService);
+    }
+    //#endregion
+    //#region ----   Public Methods   ----
+    /**
+     * Execute a frontend workflow task.
+     *
+     * Only executes tasks with executionMode 'frontend' or 'both'.
+     * Backend tasks should not be passed to this executor.
+     *
+     * @param task - Task to execute
+     * @returns Execution result with output and outcome
+     *
+     * @throws Error if task is not a frontend task
+     */
+    async execute(task) {
+        // Validate execution mode
+        if (task.executionMode !== 'frontend' && task.executionMode !== 'both') {
+            throw new Error(`Task '${task.activityId}' is not a frontend task. ` +
+                `Execution mode: ${task.executionMode}. Backend tasks are handled automatically.`);
+        }
+        try {
+            // Check if command exists
+            const commandExists = this.commandService.exists(task.activityType);
+            if (!commandExists) {
+                console.warn(`[FrontendTaskExecutor] ⚠️ Frontend activity '${task.activityType}' is not registered. ` +
+                    `Skipping execution.`);
+                return {
+                    output: null,
+                    outcome: 'Done'
+                };
+            }
+            // Prepare command input
+            // Flatten properties if nested (workflow-studio format)
+            let commandInput = task.input || task.config || {};
+            if (commandInput['properties'] && typeof commandInput['properties'] === 'object') {
+                // Flatten: {properties: {text: "..."}} -> {text: "..."}
+                commandInput = { ...commandInput['properties'] };
+            }
+            // Execute activity via CommandBus
+            // Activities registered as AXPCommand return {output, outcomes}
+            const result = await this.commandService.execute(task.activityType, commandInput);
+            if (!result) {
+                return {
+                    output: null,
+                    outcome: 'Failed',
+                };
+            }
+            if (!result.success) {
+                return {
+                    output: {
+                        error: result.message?.text,
+                    },
+                    outcome: 'Failed',
+                };
+            }
+            const commandResult = result.data;
+            const outcomes = commandResult?.outcomes ?? {};
+            // Determine outcome from command results
+            // Default to 'Done' if no outcomes specified
+            let outcome = 'Done';
+            if (Object.keys(outcomes).length > 0) {
+                outcome = outcomes['Done'] ? 'Done' : Object.keys(outcomes)[0] || 'Done';
+            }
+            return {
+                output: commandResult?.output ?? null,
+                outcome,
+            };
+        }
+        catch (error) {
+            console.error(`[FrontendTaskExecutor] ❌ Error executing frontend activity '${task.activityType}':`, error);
+            return {
+                output: { error: error.message || 'Unknown error' },
+                outcome: 'Failed'
+            };
+        }
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: FrontendTaskExecutor, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: FrontendTaskExecutor, providedIn: 'root' }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowExecutionService, decorators: [{
-            type: Injectable
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: FrontendTaskExecutor, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root'
+                }]
         }] });
 
 //#endregion
 /**
- * Production Workflow Coordinator.
+ * Workflow Manager - Facade for workflow lifecycle orchestration.
  *
- * Separates frontend/backend execution:
- * - Frontend activities: Execute with AXPCommand in browser
- * - Backend activities: Execute via API calls to backend
- * - State caching: Caches workflow state in client for performance
+ * This service is the ONLY interface the frontend uses to interact with workflows.
+ * It follows Clean Architecture principles and does NOT contain execution or business logic.
  *
+ * Responsibilities:
+ * - Orchestrate workflow lifecycle (start, execute, complete, resume)
+ * - Delegate execution to FrontendTaskExecutor
+ * - Cache workflow state in memory
+ * - Expose a stable API for UI
+ *
+ * Rules:
+ * - No HTTP calls (delegates to AXPWorkflowEngine)
+ * - No CommandBus / Command execution (delegates to FrontendTaskExecutor)
+ * - No workflow branching logic (backend decides)
+ * - No business validation (backend validates)
+ * - No backend assumptions (uses abstract runtime service)
  */
-class WorkflowCoordinator {
+class AXPWorkflowManager {
     constructor() {
         //#region ----   Services & Dependencies   ----
-        this.workflowExecutionService = inject(AXPWorkflowExecutionService);
-        this.commandService = inject(AXPCommandService);
+        this.workflowEngine = inject(AXP_WORKFLOW_ENGINE);
+        this.frontendTaskExecutor = inject(FrontendTaskExecutor);
         //#endregion
-        //#region ----   State Cache (Client-side for Performance)   ----
+        //#region ----   State Cache   ----
         /**
          * Cache workflow states in memory for quick access.
-         * Key: executionId
-         * Value: AXPWorkflowExecutionState
+         * Key: instanceId
+         * Value: AXPWorkflowInstanceState
          */
         this.stateCache = new Map();
+        /**
+         * Cache TTL in milliseconds (5 minutes).
+         */
+        this.CACHE_TTL = 5 * 60 * 1000;
     }
     //#endregion
     //#region ----   Public Methods   ----
     /**
-     * Start workflow execution in backend.
+     * Start a new workflow instance.
      *
+     * Creates a new workflow instance in backend and returns instance ID.
      * Backend decides what to do: returns pendingTask or indicates completion.
-     * Frontend only calls API - no business logic here.
      *
-     * @param workflowId - Workflow ID
-     * @param input - Initial input data
-     * @returns Execution result with pendingTask (if any)
+     * @param workflowId - Workflow ID to start
+     * @param input - Initial input data (optional)
+     * @returns Start result with instanceId, state, and nextTask
      *
      * @example
      * ```typescript
-     * const result = await coordinator.startWorkflow('my-workflow', { userId: '123' });
+     * const result = await workflowManager.start('my-workflow', { userId: '123' });
      *
-     * if (result.pendingTask) {
-     *   // Execute task if frontend, or wait for backend to complete
-     *   if (result.pendingTask.executionMode === 'frontend') {
-     *     await coordinator.executeTask(result.pendingTask);
-     *     await coordinator.completeTask(result.executionId, result.pendingTask, outcome, output);
+     * if (result.success && result.nextTask) {
+     *   // Execute task if frontend
+     *   if (result.nextTask.executionMode === 'frontend') {
+     *     const execResult = await workflowManager.execute(result.nextTask);
+     *     await workflowManager.complete(result.instanceId!, result.nextTask, execResult.outcome, execResult.output);
      *   }
      * }
      * ```
      */
-    async startWorkflow(workflowId, input = {}) {
+    async start(workflowId, input = {}) {
         try {
-            const execution = await this.startWorkflowExecution(workflowId, input);
-            const result = {
+            const response = await this.workflowEngine.start({
+                workflowId,
+                input
+            });
+            // Cache state (normalize Date)
+            const startNormalizedState = { ...response.state };
+            if (startNormalizedState.lastUpdated && !(startNormalizedState.lastUpdated instanceof Date)) {
+                startNormalizedState.lastUpdated = new Date(startNormalizedState.lastUpdated);
+            }
+            this.stateCache.set(response.instanceId, startNormalizedState);
+            return {
                 success: true,
-                output: execution.state.output,
-                nextTask: execution.pendingTask || null,
-                executionId: execution.executionId,
-                state: execution.state
+                instanceId: response.instanceId,
+                state: startNormalizedState,
+                nextTask: response.pendingTask || null,
+                output: startNormalizedState.output
             };
-            return result;
         }
         catch (error) {
-            console.error('[WorkflowCoordinator] ❌ Error in startWorkflow', error);
+            console.error('[AXPWorkflowManager] ❌ Error starting workflow:', error);
             return {
                 success: false,
-                error: error.message || 'Failed to start workflow',
-                nextTask: null
+                error: error.message || 'Failed to start workflow'
             };
         }
     }
     /**
-     * Execute a frontend task using AXPCommand.
+     * Execute a frontend task.
      *
-     * Only executes if task.executionMode is 'frontend' or 'both'.
-     * Backend tasks are handled automatically by backend.
+     * Delegates to FrontendTaskExecutor for actual execution.
+     * Only executes tasks with executionMode 'frontend' or 'both'.
      *
      * @param task - Task to execute
      * @returns Execution result with output and outcome
+     *
+     * @throws Error if task is not a frontend task
      */
-    async executeTask(task) {
-        // Only execute frontend tasks
-        if (task.executionMode !== 'frontend' && task.executionMode !== 'both') {
-            throw new Error(`Task '${task.activityId}' is not a frontend task. Backend handles it automatically.`);
-        }
-        return await this.executeFrontendActivity(task);
+    async execute(task) {
+        return this.frontendTaskExecutor.execute(task);
     }
     /**
      * Complete a task and get next task from backend.
@@ -1239,72 +1069,71 @@ class WorkflowCoordinator {
      * Sends task result to backend API.
      * Backend decides: next task, fail, or complete workflow.
      *
-     * @param executionId - Execution ID
+     * @param instanceId - Workflow instance ID
      * @param task - Completed task
      * @param outcome - Task outcome (e.g., 'Done', 'Confirmed', 'Cancelled')
-     * @param output - Task output/result
-     * @returns Next task from backend (if any)
+     * @param output - Task output/result (optional)
+     * @returns Complete result with next task (if any)
      */
-    async completeTask(executionId, task, outcome, output) {
+    async complete(instanceId, task, outcome, output) {
         try {
             // Send result to backend - backend decides next step
-            const response = await this.workflowExecutionService.resumeExecution({
-                executionId,
+            const response = await this.workflowEngine.resume({
+                instanceId,
                 stepId: task.activityId,
                 taskToken: task.taskToken,
                 outcome,
                 userInput: output
             });
             // Update cache
+            let completeNormalizedState = response.state;
             if (response.state) {
-                this.stateCache.set(executionId, response.state);
+                // Normalize lastUpdated to Date (for cache safety)
+                completeNormalizedState = { ...response.state };
+                if (completeNormalizedState.lastUpdated && !(completeNormalizedState.lastUpdated instanceof Date)) {
+                    completeNormalizedState.lastUpdated = new Date(completeNormalizedState.lastUpdated);
+                }
+                this.stateCache.set(instanceId, completeNormalizedState);
             }
             return {
                 success: true,
-                output: response.output,
+                instanceId,
+                state: completeNormalizedState,
                 nextTask: response.nextTask || null,
-                executionId,
-                state: response.state
+                output: response.output
             };
         }
         catch (error) {
+            console.error('[AXPWorkflowManager] ❌ Error completing task:', error);
             return {
                 success: false,
-                error: error.message || 'Failed to complete task',
-                nextTask: null
+                instanceId,
+                error: error.message || 'Failed to complete task'
             };
         }
     }
-    /**
-     * Execute workflow by ID (backward compatibility).
-     *
-     * @deprecated Use startWorkflow + executeTask + completeTask pattern instead.
-     * This method is kept for backward compatibility but will be removed.
-     */
-    async executeWorkflowById(workflowId, input = {}) {
-        // Just start workflow - caller should handle task execution
-        return await this.startWorkflow(workflowId, input);
-    }
     /**
      * Resume a suspended workflow (e.g., after user interaction).
      *
      * Backend determines nextStep based on outcome and outcomeConnections.
-     * Client only provides executionId, stepId, outcome, and optional userInput.
+     * Client only provides instanceId, stepId, outcome, and optional userInput.
      *
-     * @param executionId - Workflow execution ID
+     * @param instanceId - Workflow instance ID
      * @param stepId - Step ID that was waiting for user input
      * @param outcome - User action outcome (e.g., 'Confirmed', 'Cancelled', 'Submitted')
      * @param userInput - Optional user input data
+     * @param taskToken - Secure task token (required for secure resumption)
+     * @returns Resume result with next task (if any)
      */
-    async resumeWorkflow(executionId, stepId, outcome, userInput, taskToken) {
+    async resume(instanceId, stepId, outcome, userInput, taskToken) {
         try {
             // Ensure taskToken is provided for secure resumption
             if (!taskToken) {
-                throw new Error('Missing taskToken for resumeWorkflow');
+                throw new Error('Missing taskToken for resume operation');
             }
             // Backend handles everything: checks outcomeConnections and determines nextStep
-            const response = await this.workflowExecutionService.resumeExecution({
-                executionId,
+            const response = await this.workflowEngine.resume({
+                instanceId,
                 stepId,
                 taskToken,
                 outcome,
@@ -1312,152 +1141,951 @@ class WorkflowCoordinator {
             });
             // Update cache with state from backend
             if (response.state) {
-                this.stateCache.set(executionId, response.state);
+                // Normalize lastUpdated to Date (for cache safety)
+                const normalizedState = { ...response.state };
+                if (normalizedState.lastUpdated && !(normalizedState.lastUpdated instanceof Date)) {
+                    normalizedState.lastUpdated = new Date(normalizedState.lastUpdated);
+                }
+                this.stateCache.set(instanceId, normalizedState);
+            }
+            // Normalize state Date for return
+            const normalizedState = response.state ? { ...response.state } : undefined;
+            if (normalizedState && normalizedState.lastUpdated && !(normalizedState.lastUpdated instanceof Date)) {
+                normalizedState.lastUpdated = new Date(normalizedState.lastUpdated);
             }
             return {
                 success: true,
-                output: response.output,
+                instanceId,
+                state: normalizedState || response.state,
                 nextTask: response.nextTask || null, // Backend determines this from outcomeConnections
-                executionId,
-                state: response.state
+                output: response.output
             };
         }
         catch (error) {
+            console.error('[AXPWorkflowManager] ❌ Error resuming workflow:', error);
             return {
                 success: false,
-                error: error.message || 'Failed to resume workflow',
-                nextTask: null
+                instanceId,
+                error: error.message || 'Failed to resume workflow'
             };
         }
     }
     /**
-     * Get workflow execution state (from cache or backend).
+     * Get workflow instance state.
+     *
+     * Retrieves state from cache (if valid) or from backend.
+     *
+     * @param instanceId - Workflow instance ID
+     * @returns Workflow instance state or null if not found
      */
-    async getWorkflowState(executionId) {
+    async getState(instanceId) {
         // Check cache first
-        const cached = this.stateCache.get(executionId);
+        const cached = this.stateCache.get(instanceId);
         if (cached) {
-            // Cache is valid for 5 minutes
-            const cacheAge = Date.now() - cached.lastUpdated.getTime();
-            if (cacheAge < 5 * 60 * 1000) {
-                return cached;
+            // Normalize lastUpdated to Date (for cache safety)
+            const normalizedCached = { ...cached };
+            if (normalizedCached.lastUpdated && !(normalizedCached.lastUpdated instanceof Date)) {
+                normalizedCached.lastUpdated = new Date(normalizedCached.lastUpdated);
+            }
+            // Validate cache age
+            const cacheAge = Date.now() - normalizedCached.lastUpdated.getTime();
+            if (cacheAge < this.CACHE_TTL) {
+                return normalizedCached;
             }
         }
         // Fetch from backend
         try {
-            const state = await this.workflowExecutionService.getExecutionState({
-                executionId
+            const state = await this.workflowEngine.getState({
+                instanceId
             });
+            // Normalize lastUpdated to Date (for cache safety)
+            const normalizedState = { ...state };
+            if (normalizedState.lastUpdated && !(normalizedState.lastUpdated instanceof Date)) {
+                normalizedState.lastUpdated = new Date(normalizedState.lastUpdated);
+            }
             // Update cache
-            this.stateCache.set(executionId, state);
-            return state;
+            this.stateCache.set(instanceId, normalizedState);
+            return normalizedState;
         }
-        catch {
+        catch (error) {
+            console.error('[AXPWorkflowManager] ❌ Error getting workflow state:', error);
             return null;
         }
     }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowManager, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowManager, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowManager, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root'
+                }]
+        }] });
+
+//#endregion
+/**
+ * Local engine implementation that manages workflow progression and state.
+ *
+ * This engine:
+ * - Returns frontend/both activities as pendingTask (does NOT execute them)
+ * - Skips backend activities (does not error, continues execution)
+ * - Maintains workflow state in memory
+ * - Does not require backend API calls
+ *
+ * Execution of frontend tasks is handled by AXPWorkflowManager via FrontendTaskExecutor.
+ * This engine only manages workflow progression and state storage.
+ *
+ * This is the DEFAULT engine provider. Applications can override it with
+ * an API-based engine implementation.
+ */
+class AXPWorkflowLocalEngine {
+    //#region ----   Services & Dependencies   ----
+    constructor(definitionLoaders = null) {
+        this.definitionLoaders = definitionLoaders;
+        //#endregion
+        //#region ----   Instance Storage   ----
+        /**
+         * In-memory storage for workflow instances.
+         * Key: instanceId
+         * Value: LocalWorkflowState
+         */
+        this.instances = new Map();
+        /**
+         * Task token storage for secure resume operations.
+         * Key: taskToken
+         * Value: { instanceId, activityId }
+         */
+        this.taskTokens = new Map();
+    }
+    //#endregion
+    //#region ----   Public Methods (AXPWorkflowEngine)   ----
+    /**
+     * Start a new workflow instance.
+     *
+     * Creates an in-memory workflow instance and progresses it.
+     * Frontend/both activities are returned as pendingTask for external execution.
+     * Backend activities are skipped.
+     */
+    async start(request) {
+        // Generate instance ID
+        const instanceId = AXPDataGenerator.uuid();
+        const now = new Date();
+        // Load workflow definition
+        const definition = await this.getDefinition(request.workflowId);
+        if (!definition) {
+            throw new Error(`Workflow definition not found: ${request.workflowId}`);
+        }
+        // Initialize workflow state
+        const state = {
+            instanceId,
+            workflowId: request.workflowId,
+            status: 'running',
+            variables: {},
+            input: request.input || {},
+            output: undefined,
+            lastUpdated: now,
+        };
+        // Create local state
+        const localState = {
+            instanceId,
+            workflowId: request.workflowId,
+            definition,
+            state,
+            completedActivities: new Set(),
+            activityResults: new Map(),
+        };
+        // Store instance
+        this.instances.set(instanceId, localState);
+        // Execute workflow steps
+        const pendingTask = await this.executeWorkflowSteps(localState);
+        // Update state
+        localState.state.lastUpdated = new Date();
+        return {
+            instanceId,
+            state: localState.state,
+            pendingTask: pendingTask || null,
+        };
+    }
+    /**
+     * Resume a suspended workflow instance.
+     *
+     * Validates task token, applies externally executed result,
+     * and continues progressing workflow steps.
+     */
+    async resume(request) {
+        // Validate task token
+        const tokenInfo = this.taskTokens.get(request.taskToken);
+        if (!tokenInfo || tokenInfo.instanceId !== request.instanceId || tokenInfo.activityId !== request.stepId) {
+            throw new Error('Invalid task token');
+        }
+        // Get instance
+        const localState = this.instances.get(request.instanceId);
+        if (!localState) {
+            throw new Error(`Workflow instance not found: ${request.instanceId}`);
+        }
+        // Store activity result (from external execution)
+        localState.activityResults.set(request.stepId, {
+            output: request.userInput || {},
+            outcome: request.outcome,
+        });
+        localState.completedActivities.add(request.stepId);
+        // Merge output/userInput into state variables
+        if (request.userInput) {
+            localState.state.variables = {
+                ...localState.state.variables,
+                ...(request.userInput || {}),
+            };
+        }
+        // Mark activity as completed and continue progression
+        // Continue progressing workflow steps (skipping backend activities)
+        const nextTask = await this.executeWorkflowSteps(localState);
+        // Update state
+        localState.state.lastUpdated = new Date();
+        // Determine final status
+        if (!nextTask && localState.state.status === 'running') {
+            localState.state.status = 'completed';
+            localState.state.output = localState.state.variables;
+        }
+        return {
+            output: request.userInput || {},
+            outcomes: { [request.outcome]: true },
+            state: localState.state,
+            nextTask: nextTask || null,
+        };
+    }
+    /**
+     * Get current workflow instance state.
+     */
+    async getState(request) {
+        const localState = this.instances.get(request.instanceId);
+        if (!localState) {
+            throw new Error(`Workflow instance not found: ${request.instanceId}`);
+        }
+        // Normalize lastUpdated to Date (for cache safety)
+        const state = { ...localState.state };
+        if (state.lastUpdated && !(state.lastUpdated instanceof Date)) {
+            state.lastUpdated = new Date(state.lastUpdated);
+        }
+        return state;
+    }
     //#endregion
     //#region ----   Private Methods   ----
     /**
-     * Execute a frontend activity using CommandBus.
+     * Get workflow definition from available loaders.
+     */
+    async getDefinition(workflowId) {
+        // Try all loaders in order
+        const loaders = this.definitionLoaders || [];
+        for (const loader of loaders) {
+            const definition = await loader.get(workflowId);
+            if (definition) {
+                return definition;
+            }
+        }
+        return null;
+    }
+    /**
+     * Progress workflow steps starting from the current position.
      *
-     * Frontend activities are executed in the browser using AXPCommandService.
-     * Activities can also be executed in both frontend and backend (hybrid mode).
+     * For frontend/both activities: returns task immediately (suspends workflow).
+     * For backend activities: skips and continues.
      *
-     * @param task - Frontend task to execute
-     * @returns Execution result with output and outcome
+     * Returns the next pending task (if frontend activity found) or null (if completed).
      */
-    async executeFrontendActivity(task) {
-        try {
-            // Check if command exists
-            const commandExists = this.commandService.exists(task.activityType);
-            if (!commandExists) {
-                console.warn(`[WorkflowCoordinator] ⚠️ Frontend activity '${task.activityType}' is not registered. Skipping execution.`);
-                return {
-                    output: null,
-                    outcome: 'Done'
-                };
+    async executeWorkflowSteps(localState) {
+        const graph = localState.definition.graph;
+        const activities = graph.activities || [];
+        const connections = graph.connections || [];
+        // Build activity map
+        const activityMap = new Map();
+        activities.forEach(activity => {
+            activityMap.set(activity.id, activity);
+        });
+        // Build connection graph
+        const outgoingConnections = new Map();
+        const incomingConnections = new Map();
+        connections.forEach(conn => {
+            const sourceId = conn.source.activtyName;
+            const targetId = conn.target.activtyName;
+            if (!outgoingConnections.has(sourceId)) {
+                outgoingConnections.set(sourceId, []);
             }
-            // Execute activity via CommandBus
-            // Activities registered as AXPCommand return {output, outcomes}
-            // 🎯 Flatten properties if nested (workflow-studio format)
-            let commandInput = task.input || task.config || {};
-            if (commandInput['properties'] && typeof commandInput['properties'] === 'object') {
-                // Flatten: {properties: {text: "..."}} -> {text: "..."}
-                commandInput = { ...commandInput['properties'] };
+            outgoingConnections.get(sourceId).push(conn);
+            if (!incomingConnections.has(targetId)) {
+                incomingConnections.set(targetId, []);
             }
-            const result = await this.commandService.execute(task.activityType, commandInput);
-            if (!result) {
-                return {
+            incomingConnections.get(targetId).push(conn);
+        });
+        // Find starting activity (use startActivityId or no incoming connections, or first activity)
+        let currentActivityId = localState.currentActivityId;
+        if (!currentActivityId) {
+            // Use startActivityId if available
+            if (graph.startActivityId) {
+                currentActivityId = graph.startActivityId;
+            }
+            else {
+                // Find root activity (no incoming connections)
+                for (const activity of activities) {
+                    if (!incomingConnections.has(activity.id)) {
+                        currentActivityId = activity.id;
+                        break;
+                    }
+                }
+                // If no root found, use first activity
+                if (!currentActivityId && activities.length > 0) {
+                    currentActivityId = activities[0].id;
+                }
+            }
+        }
+        // Execute workflow steps
+        while (currentActivityId) {
+            const activity = activityMap.get(currentActivityId);
+            if (!activity) {
+                break;
+            }
+            // Skip if already completed
+            if (localState.completedActivities.has(currentActivityId)) {
+                // Move to next activity
+                const nextId = this.getNextActivityId(currentActivityId, outgoingConnections, localState.activityResults);
+                currentActivityId = nextId ?? undefined;
+                continue;
+            }
+            // Determine execution mode
+            const executionMode = activity.executionMode || 'frontend';
+            // Handle backend activities: skip
+            if (executionMode === 'backend') {
+                console.log(`[WorkflowLocalEngine] ⏭️ Skipping backend activity: ${activity.name} (${activity.id})`);
+                localState.completedActivities.add(currentActivityId);
+                localState.activityResults.set(currentActivityId, {
                     output: null,
-                    outcome: 'Failed',
-                };
+                    outcome: 'Done',
+                });
+                // Move to next activity
+                const nextId = this.getNextActivityId(currentActivityId, outgoingConnections, localState.activityResults);
+                currentActivityId = nextId ?? undefined;
+                continue;
             }
-            if (!result.success) {
-                return {
-                    output: {
-                        error: result.message?.text,
-                    },
-                    outcome: 'Failed',
+            // Handle frontend/both activities: return as pendingTask (do NOT execute)
+            if (executionMode === 'frontend' || executionMode === 'both') {
+                // Create task for external execution
+                const task = {
+                    taskToken: AXPDataGenerator.uuid(),
+                    activityId: activity.id,
+                    activityType: activity.name,
+                    activityName: activity.title || undefined,
+                    executionMode: executionMode,
+                    input: activity.inputs || {},
+                    config: activity.customProperties || {},
                 };
+                // Store task token for secure resume
+                this.taskTokens.set(task.taskToken, {
+                    instanceId: localState.instanceId,
+                    activityId: activity.id,
+                });
+                // Update state to indicate suspension
+                localState.currentActivityId = currentActivityId;
+                localState.state.status = 'suspended';
+                localState.state.currentStepId = currentActivityId;
+                // Return task immediately - AXPWorkflowManager will execute it
+                return task;
             }
-            const commandResult = result.data;
-            const outcomes = commandResult?.outcomes ?? {};
-            let outcome = 'Done';
-            if (Object.keys(outcomes).length > 0) {
-                outcome = outcomes['Done'] ? 'Done' : Object.keys(outcomes)[0] || 'Done';
-            }
-            return {
-                output: commandResult?.output ?? null,
-                outcome,
-            };
-        }
-        catch (error) {
-            console.error(`[WorkflowCoordinator] ❌ Error executing frontend activity '${task.activityType}':`, error);
-            return {
-                output: { error: error.message || 'Unknown error' },
-                outcome: 'Failed'
-            };
+            // Move to next activity
+            const nextId = this.getNextActivityId(currentActivityId, outgoingConnections, localState.activityResults);
+            currentActivityId = nextId ?? undefined;
         }
+        // Workflow completed
+        localState.state.status = 'completed';
+        localState.state.output = localState.state.variables;
+        localState.currentActivityId = undefined;
+        return null;
     }
     /**
-     * Start workflow execution in backend.
-     * Backend returns executionId, initial state, and first task to execute.
+     * Get next activity ID based on connections and outcomes.
      */
-    async startWorkflowExecution(workflowId, input) {
-        const response = await this.workflowExecutionService.startExecution({
-            workflowId,
-            input
-        });
-        // Cache state
-        this.stateCache.set(response.executionId, response.state);
-        return {
-            executionId: response.executionId,
-            state: response.state,
-            pendingTask: response.pendingTask
-        };
+    getNextActivityId(currentActivityId, outgoingConnections, activityResults) {
+        const connections = outgoingConnections.get(currentActivityId) || [];
+        if (connections.length === 0) {
+            return null; // No outgoing connections - workflow ends
+        }
+        // Get current activity result
+        const result = activityResults.get(currentActivityId);
+        const outcome = result?.outcome || 'Done';
+        // Find connection matching outcome
+        // Outcome matching is typically done via port name (e.g., "Done", "Failed")
+        for (const conn of connections) {
+            const sourcePort = conn.source.port || 'Done';
+            if (sourcePort === outcome) {
+                return conn.target.activtyName;
+            }
+        }
+        // If no matching outcome, use first connection (default path)
+        if (connections.length > 0) {
+            return connections[0].target.activtyName;
+        }
+        return null;
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: WorkflowCoordinator, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: WorkflowCoordinator, providedIn: 'root' }); }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowLocalEngine, deps: [{ token: AXP_WORKFLOW_DEFINITION_LOADER, optional: true }], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowLocalEngine }); }
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: WorkflowCoordinator, decorators: [{
-            type: Injectable,
-            args: [{
-                    providedIn: 'root'
-                }]
-        }] });
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowLocalEngine, decorators: [{
+            type: Injectable
+        }], ctorParameters: () => [{ type: undefined, decorators: [{
+                    type: Optional
+                }, {
+                    type: Inject,
+                    args: [AXP_WORKFLOW_DEFINITION_LOADER]
+                }] }] });
 
-/**
- * Types and interfaces for Workflow Execution Service.
- */
+// Workflow Runtime Services
 
-// Production Workflow Coordinator (Frontend/Backend Separation)
+const AXP_WORKFLOW_PROVIDER = new InjectionToken('AXP_WORKFLOW_PROVIDER', {
+    factory: () => [],
+});
+const AXP_WORKFLOW_CATEGORY_PROVIDER = new InjectionToken('AXP_WORKFLOW_CATEGORY_PROVIDER', {
+    factory: () => [],
+});
 
-// Workflow Definition Types (Storage/Database)
+//#region ----   Imports   ----
+//#endregion
+/**
+ * Optimized Workflow Definition Service
+ *
+ * Manages workflow definitions (metadata) for UI and tooling.
+ * Similar to AXPActivityDefinitionService - only handles metadata, not execution.
+ *
+ * Performance optimizations:
+ * 1. Uses childrenCount to determine if category has children (no query needed)
+ * 2. Uses itemsCount to determine if category has workflows (no query needed)
+ * 3. Aggressive caching prevents duplicate API calls
+ * 4. Single pending request per resource prevents race conditions
+ * 5. Lazy loading - only loads data when needed
+ */
+class AXPWorkflowDefinitionService {
+    constructor() {
+        //#region ----   Providers & Caches   ----
+        this.categoryProviders = inject(AXP_WORKFLOW_CATEGORY_PROVIDER, { optional: true }) || [];
+        this.workflowProviders = inject(AXP_WORKFLOW_PROVIDER, { optional: true }) || [];
+        //#endregion
+        //#region ----   Cache Storage   ----
+        /** Cache for categories by id - O(1) lookup */
+        this.categoriesById = new Map();
+        /** Cache for categories by parentId - O(1) lookup */
+        this.categoriesByParentId = new Map();
+        /** Cache for workflow definitions by categoryId - O(1) lookup */
+        this.workflowsByCategory = new Map();
+        /** Cache for individual workflow definitions by name - O(1) lookup */
+        this.workflowsByName = new Map();
+        /** Track which provider index owns each category (by category ID) */
+        this.categoryOwnership = new Map(); // Maps categoryId → provider index
+        /** Pending API requests to prevent duplicate calls */
+        this.pendingCategoriesRequests = new Map();
+        this.pendingWorkflowsRequests = new Map();
+        this.pendingWorkflowRequests = new Map();
+    }
+    //#endregion
+    //#region ----   Public API: Categories   ----
+    /**
+     * Get categories by parentId with aggressive caching
+     *
+     * Optimization: Returns cached result immediately if available,
+     * preventing unnecessary API calls during navigation
+     *
+     * @param parentId - Parent category ID (undefined = root categories)
+     * @returns Array of categories with count metadata (childrenCount, itemsCount)
+     */
+    async getCategories(parentId) {
+        // ✅ Fast path: Return cached result
+        if (this.categoriesByParentId.has(parentId)) {
+            return this.categoriesByParentId.get(parentId);
+        }
+        // ✅ Prevent duplicate requests: Return pending promise
+        if (this.pendingCategoriesRequests.has(parentId)) {
+            return this.pendingCategoriesRequests.get(parentId);
+        }
+        // ✅ Create single request and cache it
+        const requestPromise = this.loadCategoriesFromProviders(parentId);
+        this.pendingCategoriesRequests.set(parentId, requestPromise);
+        return requestPromise;
+    }
+    /**
+     * Get single category by ID with O(1) lookup
+     *
+     * Optimization: Uses Map for instant retrieval, falls back to
+     * searching cache, then providers if not found
+     */
+    async getCategoryById(categoryId) {
+        // ✅ Fast path: O(1) lookup in cache
+        if (this.categoriesById.has(categoryId)) {
+            return this.categoriesById.get(categoryId);
+        }
+        // ✅ Search in cached parent-child lists
+        for (const categories of this.categoriesByParentId.values()) {
+            const found = categories.find(cat => cat.id === categoryId);
+            if (found) {
+                this.categoriesById.set(categoryId, found);
+                return found;
+            }
+        }
+        // ✅ Load root categories if not loaded
+        if (!this.categoriesByParentId.has(undefined)) {
+            await this.getCategories();
+            if (this.categoriesById.has(categoryId)) {
+                return this.categoriesById.get(categoryId);
+            }
+        }
+        // ✅ Breadth-first search through hierarchy
+        return this.searchCategoryInHierarchy(categoryId);
+    }
+    /**
+     * Get category path from root to specified category
+     *
+     * Optimization: Builds path using cached categories only
+     */
+    async getCategoriesPathById(categoryId) {
+        const path = [];
+        let currentCategoryId = categoryId;
+        while (currentCategoryId) {
+            const category = await this.getCategoryById(currentCategoryId);
+            if (!category) {
+                throw new Error(`Category '${currentCategoryId}' not found`);
+            }
+            path.unshift(category);
+            currentCategoryId = category.parentId;
+        }
+        return path;
+    }
+    //#endregion
+    //#region ----   Public API: Workflow Definitions   ----
+    /**
+     * Get workflow definitions for a category with smart caching
+     *
+     * Optimization: Checks itemsCount before querying
+     * - If itemsCount = 0, returns empty array (no API call)
+     * - If itemsCount > 0, loads and caches workflow definitions
+     * - Returns cached result on subsequent calls
+     *
+     * @param categoryId - Category ID to get workflow definitions from
+     * @returns Array of workflow definition metadata
+     */
+    async getWorkflowsByCategoryId(categoryId) {
+        // ✅ Fast path: Return cached result
+        if (this.workflowsByCategory.has(categoryId)) {
+            return this.workflowsByCategory.get(categoryId);
+        }
+        // ✅ Smart optimization: Check itemsCount before querying
+        const category = await this.getCategoryById(categoryId);
+        if (category && category.itemsCount !== undefined && category.itemsCount === 0) {
+            // Category has no workflows - cache empty array and skip API call
+            const emptyArray = [];
+            this.workflowsByCategory.set(categoryId, emptyArray);
+            return emptyArray;
+        }
+        // ✅ Prevent duplicate requests
+        if (this.pendingWorkflowsRequests.has(categoryId)) {
+            return this.pendingWorkflowsRequests.get(categoryId);
+        }
+        // ✅ Load from providers
+        const requestPromise = this.loadWorkflowsFromProviders(categoryId);
+        this.pendingWorkflowsRequests.set(categoryId, requestPromise);
+        return requestPromise;
+    }
+    /**
+     * Get single workflow definition metadata by name with O(1) lookup
+     *
+     * Optimization: Uses Map for instant retrieval
+     *
+     * @param name - Workflow name (unique identifier)
+     * @returns Workflow definition metadata or undefined if not found
+     */
+    async getWorkflowByName(name) {
+        // ✅ Fast path: O(1) lookup in cache
+        if (this.workflowsByName.has(name)) {
+            return this.workflowsByName.get(name);
+        }
+        // ✅ Prevent duplicate requests
+        if (this.pendingWorkflowRequests.has(name)) {
+            return this.pendingWorkflowRequests.get(name);
+        }
+        // ✅ Load from providers
+        const requestPromise = this.loadWorkflowFromProviders(name);
+        this.pendingWorkflowRequests.set(name, requestPromise);
+        return requestPromise;
+    }
+    /**
+     * Get category ID containing a specific workflow definition
+     *
+     * Optimization: Searches cache first, loads on-demand if needed
+     */
+    async getCategoryIdByWorkflowName(workflowName) {
+        // ✅ Search in cached workflow definitions
+        for (const [categoryId, definitions] of this.workflowsByCategory.entries()) {
+            if (definitions.some(def => def.name === workflowName)) {
+                return categoryId;
+            }
+        }
+        // ✅ Try loading the workflow definition to find its category
+        const definition = await this.getWorkflowByName(workflowName);
+        if (definition && definition.category) {
+            // Try to find category by name/id
+            const categories = await this.getCategories();
+            const found = categories.find(cat => cat.id === definition.category || cat.title === definition.category);
+            if (found) {
+                return found.id;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Get category path for a workflow
+     */
+    async getCategoriesPathByWorkflowName(workflowName) {
+        const categoryId = await this.getCategoryIdByWorkflowName(workflowName);
+        if (!categoryId) {
+            throw new Error(`Workflow '${workflowName}' not found in any category`);
+        }
+        return this.getCategoriesPathById(categoryId);
+    }
+    //#endregion
+    //#region ----   Private: Data Loading   ----
+    /**
+     * Load categories from providers and cache results
+     *
+     * Optimization: Tracks provider ownership to avoid unnecessary API calls
+     * - For root (parentId = undefined): Query ALL providers
+     * - For children: Only query the provider that owns the parent
+     */
+    async loadCategoriesFromProviders(parentId) {
+        try {
+            const resolvedProviders = await Promise.allSettled(this.categoryProviders);
+            const categories = [];
+            // Determine which provider(s) to query
+            const providerIndicesToQuery = parentId
+                ? this.getProviderIndexForCategory(parentId)
+                : null; // Root: query all providers
+            for (let i = 0; i < resolvedProviders.length; i++) {
+                const p = resolvedProviders[i];
+                // Skip if we have a specific provider index and this isn't it
+                if (providerIndicesToQuery !== null && !providerIndicesToQuery.includes(i)) {
+                    continue;
+                }
+                if (p.status === 'fulfilled' && p.value && typeof p.value.getList === 'function') {
+                    try {
+                        const cats = await p.value.getList(parentId);
+                        if (Array.isArray(cats) && cats.length > 0) {
+                            categories.push(...cats);
+                            // ✅ Track ownership: This provider INDEX owns these categories
+                            cats.forEach(cat => this.categoryOwnership.set(cat.id, i));
+                        }
+                    }
+                    catch {
+                        // Continue on error - try other providers
+                    }
+                }
+            }
+            // ✅ Cache results for fast subsequent access
+            this.categoriesByParentId.set(parentId, categories);
+            categories.forEach(cat => this.categoriesById.set(cat.id, cat));
+            return categories;
+        }
+        finally {
+            this.pendingCategoriesRequests.delete(parentId);
+        }
+    }
+    /**
+     * Get the provider index that owns a specific category
+     *
+     * @returns Array with provider index, or null if ownership unknown (query all)
+     */
+    getProviderIndexForCategory(categoryId) {
+        const ownerIndex = this.categoryOwnership.get(categoryId);
+        if (ownerIndex !== undefined) {
+            return [ownerIndex];
+        }
+        // Ownership unknown - will query all providers (fallback)
+        return null;
+    }
+    /**
+     * Load workflow definitions from providers and cache results
+     *
+     * Optimization: Only queries the provider that owns the category
+     * Uses provider INDEX to match category provider with workflow provider
+     */
+    async loadWorkflowsFromProviders(categoryId) {
+        try {
+            const resolvedProviders = await Promise.allSettled(this.workflowProviders);
+            const definitions = [];
+            // ✅ Smart routing: Get provider INDEX that owns this category
+            const ownerIndex = this.categoryOwnership.get(categoryId);
+            const providerIndicesToQuery = ownerIndex !== undefined ? [ownerIndex] : null;
+            for (let i = 0; i < resolvedProviders.length; i++) {
+                const p = resolvedProviders[i];
+                // Skip if we have a specific provider index and this isn't it
+                if (providerIndicesToQuery !== null && !providerIndicesToQuery.includes(i)) {
+                    continue;
+                }
+                if (p.status === 'fulfilled' && p.value && typeof p.value.getList === 'function') {
+                    try {
+                        const defs = await p.value.getList(categoryId);
+                        if (Array.isArray(defs)) {
+                            definitions.push(...defs);
+                        }
+                    }
+                    catch {
+                        // Continue on error - try other providers
+                    }
+                }
+            }
+            // ✅ Cache results for fast subsequent access
+            this.workflowsByCategory.set(categoryId, definitions);
+            definitions.forEach(def => {
+                if (def.name) {
+                    this.workflowsByName.set(def.name, def);
+                }
+            });
+            return definitions;
+        }
+        finally {
+            this.pendingWorkflowsRequests.delete(categoryId);
+        }
+    }
+    /**
+     * Load single workflow definition from providers and cache result
+     */
+    async loadWorkflowFromProviders(name) {
+        try {
+            const resolvedProviders = await Promise.allSettled(this.workflowProviders);
+            // Try providers first
+            for (const p of resolvedProviders) {
+                if (p.status === 'fulfilled' && p.value && typeof p.value.getById === 'function') {
+                    try {
+                        const result = await p.value.getById(name);
+                        if (result) {
+                            this.workflowsByName.set(name, result);
+                            return result;
+                        }
+                    }
+                    catch {
+                        // Continue on error
+                    }
+                }
+            }
+            // Fallback: Search in cached workflow definitions
+            for (const definitions of this.workflowsByCategory.values()) {
+                const found = definitions.find(def => def.name === name);
+                if (found) {
+                    this.workflowsByName.set(name, found);
+                    return found;
+                }
+            }
+            return undefined;
+        }
+        finally {
+            this.pendingWorkflowRequests.delete(name);
+        }
+    }
+    /**
+     * Breadth-first search through category hierarchy
+     */
+    async searchCategoryInHierarchy(categoryId) {
+        const searchQueue = [undefined];
+        const searched = new Set();
+        while (searchQueue.length > 0) {
+            const parentId = searchQueue.shift();
+            if (searched.has(parentId))
+                continue;
+            searched.add(parentId);
+            const categories = await this.getCategories(parentId);
+            const found = categories.find(cat => cat.id === categoryId);
+            if (found) {
+                return found;
+            }
+            // ✅ Optimization: Only search children if childrenCount > 0
+            for (const category of categories) {
+                if (category.childrenCount > 0 && !searched.has(category.id)) {
+                    searchQueue.push(category.id);
+                }
+            }
+        }
+        return undefined;
+    }
+    //#endregion
+    //#region ----   Cache Management   ----
+    /**
+     * Check if category has children (uses cached count)
+     */
+    categoryHasChildren(categoryId) {
+        const category = this.categoriesById.get(categoryId);
+        return category ? category.childrenCount > 0 : false;
+    }
+    /**
+     * Check if category has workflows (uses cached count)
+     */
+    categoryHasWorkflows(categoryId) {
+        const category = this.categoriesById.get(categoryId);
+        return category ? (category.itemsCount ?? 0) > 0 : false;
+    }
+    /**
+     * Clear all caches
+     */
+    clearAllCache() {
+        this.categoriesById.clear();
+        this.categoriesByParentId.clear();
+        this.workflowsByCategory.clear();
+        this.workflowsByName.clear();
+        this.categoryOwnership.clear();
+        this.pendingCategoriesRequests.clear();
+        this.pendingWorkflowsRequests.clear();
+        this.pendingWorkflowRequests.clear();
+    }
+    /**
+     * Clear categories cache only
+     */
+    clearCategoriesCache() {
+        this.categoriesById.clear();
+        this.categoriesByParentId.clear();
+        this.categoryOwnership.clear();
+        this.pendingCategoriesRequests.clear();
+    }
+    /**
+     * Clear workflows cache only
+     */
+    clearWorkflowsCache() {
+        this.workflowsByCategory.clear();
+        this.workflowsByName.clear();
+        this.pendingWorkflowsRequests.clear();
+        this.pendingWorkflowRequests.clear();
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowDefinitionService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowDefinitionService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowDefinitionService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }] });
+
+// Workflow Definition Types (Storage/Database)
+
+class AXPWorkflowModule {
+    static forRoot(config) {
+        return {
+            ngModule: AXPWorkflowModule,
+            providers: [
+                {
+                    provide: 'AXPWorkflowModuleFactory',
+                    useFactory: (registry) => () => {
+                        registry.registerAction('start-workflow', AXPStartWorkflowAction);
+                        registry.registerAction('decide', AXPWorkflowDecideAction);
+                        //
+                        if (config?.functions) {
+                            for (const [key, type] of Object.entries(config.functions)) {
+                                registry.registerFunction(key, type);
+                            }
+                        }
+                        //
+                        if (config?.actions) {
+                            for (const [key, type] of Object.entries(config.actions)) {
+                                registry.registerAction(key, type);
+                            }
+                        }
+                        //
+                        if (config?.workflows) {
+                            for (const [key, type] of Object.entries(config.workflows)) {
+                                registry.registerWorkflow(key, type);
+                            }
+                        }
+                    },
+                    deps: [AXPWorkflowRegistryService],
+                    multi: true,
+                },
+                ...Object.values(config?.actions ?? { AXPStartWorkflowAction }),
+                ...Object.values(config?.functions ?? {}),
+            ],
+        };
+    }
+    static forChild(config) {
+        return {
+            ngModule: AXPWorkflowModule,
+            providers: [
+                // Built-in activities are already registered in forRoot via @NgModule providers
+                // No need to register again in forChild
+                {
+                    provide: 'AXPWorkflowModuleFactory',
+                    useFactory: (registry) => () => {
+                        registry.registerAction('start-workflow', AXPStartWorkflowAction);
+                        registry.registerAction('decide', AXPWorkflowDecideAction);
+                        //
+                        if (config?.functions) {
+                            for (const [key, type] of Object.entries(config.functions)) {
+                                registry.registerFunction(key, type);
+                            }
+                        }
+                        //
+                        if (config?.actions) {
+                            for (const [key, type] of Object.entries(config.actions)) {
+                                registry.registerAction(key, type);
+                            }
+                        }
+                        //
+                        if (config?.workflows) {
+                            for (const [key, type] of Object.entries(config.workflows)) {
+                                registry.registerWorkflow(key, type);
+                            }
+                        }
+                    },
+                    deps: [AXPWorkflowRegistryService],
+                    multi: true,
+                },
+                ...Object.values(config?.actions ?? {}),
+                ...Object.values(config?.functions ?? {}),
+            ],
+        };
+    }
+    /**
+     * @ignore
+     */
+    constructor(instances) {
+        instances?.forEach((f) => {
+            f();
+        });
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowModule, deps: [{ token: 'AXPWorkflowModuleFactory', optional: true }], target: i0.ɵɵFactoryTarget.NgModule }); }
+    static { this.ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowModule }); }
+    static { this.ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowModule, providers: [
+            AXPWorkflowLocalEngine,
+            {
+                provide: AXP_WORKFLOW_ENGINE,
+                useExisting: AXPWorkflowLocalEngine,
+            },
+            AXPWorkflowManager,
+        ] }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPWorkflowModule, decorators: [{
+            type: NgModule,
+            args: [{
+                    imports: [],
+                    exports: [],
+                    declarations: [],
+                    providers: [
+                        AXPWorkflowLocalEngine,
+                        {
+                            provide: AXP_WORKFLOW_ENGINE,
+                            useExisting: AXPWorkflowLocalEngine,
+                        },
+                        AXPWorkflowManager,
+                    ],
+                }]
+        }], ctorParameters: () => [{ type: undefined, decorators: [{
+                    type: Optional
+                }, {
+                    type: Inject,
+                    args: ['AXPWorkflowModuleFactory']
+                }] }] });
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { AXPActivityDefinitionService, AXPWorkflowAction, AXPWorkflowContext, AXPWorkflowDefinitionRegistryService, AXPWorkflowDefinitionResolver, AXPWorkflowError, AXPWorkflowEventService, AXPWorkflowExecutionService, AXPWorkflowFunction, AXPWorkflowModule, AXPWorkflowRegistryService, AXPWorkflowService, AXP_ACTIVITY_CATEGORY_PROVIDER, AXP_ACTIVITY_PROVIDER, AXP_WORKFLOW_DEFINITION_LOADER, WorkflowCoordinator, createWorkFlowEvent, ofType };
+export { AXPActivityDefinitionService, AXPWorkflowAction, AXPWorkflowContext, AXPWorkflowDefinitionService, AXPWorkflowError, AXPWorkflowEventService, AXPWorkflowFunction, AXPWorkflowLocalEngine, AXPWorkflowManager, AXPWorkflowModule, AXPWorkflowRegistryService, AXPWorkflowService, AXP_ACTIVITY_CATEGORY_PROVIDER, AXP_ACTIVITY_PROVIDER, AXP_WORKFLOW_CATEGORY_PROVIDER, AXP_WORKFLOW_DEFINITION_LOADER, AXP_WORKFLOW_ENGINE, AXP_WORKFLOW_PROVIDER, FrontendTaskExecutor, createWorkFlowEvent, ofType };
 //# sourceMappingURL=acorex-platform-workflow.mjs.map