@wildo-ai/saas-backend-lib 1.0.1

package/src/guidance/services/lifecycle-evaluator.backend.service.ts

@@ -0,0 +1,908 @@
+import 'reflect-metadata';
+import { injectable, inject } from 'inversify';
+import type { Model } from 'mongoose';
+import {
+  CoreWebSocketEvent,
+  CoreResourceType,
+  LifecycleStage,
+  LifecycleScope,
+  LIFECYCLE_VALID_TRANSITIONS,
+  LIFECYCLE_DORMANCY_SOURCE_STAGES,
+  LIFECYCLE_ENGAGEMENT_ELIGIBLE_STAGES,
+  LIFECYCLE_SCOPE_TO_RESOURCE,
+  LIFECYCLE_TO_PROGRESSION_RESOURCE,
+  LIFECYCLE_TO_GUIDANCE_RESOURCE,
+  GUIDANCE_STATE_RESOURCE_TYPES,
+  ActivationCriterionType,
+  OnboardingStatus,
+  createInitialLifecycleState,
+  isWildoBackendError,
+} from '@wildo-ai/saas-models';
+import type {
+  LifecycleState,
+  LifecycleConfig,
+  ActivationCriteria,
+  ActivationCriterion,
+  EngagementThreshold,
+  ProgressionState,
+  GuidanceState,
+  MilestoneLifecycleTransition,
+  WS_LifecycleStageChangedPayload,
+} from '@wildo-ai/saas-models';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import type { WebSocketService, WebSocketMessage } from '~wildo-backend-lib/requests/service/websocket.service';
+import type { RepositoriesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';
+
+/**
+ * Internal-only operation context for repository calls that bypass contextual
+ * filtering and enrichment. Used by system-level evaluators that operate
+ * outside the normal request pipeline.
+ */
+function internalOpCtx(resourceType: CoreResourceType, op: string): { operation: { resourceIdentifier: CoreResourceType; operationIdentifier: string } } {
+  return { operation: { resourceIdentifier: resourceType, operationIdentifier: op } };
+}
+
+type SignedUpActivationTransition = {
+  from: LifecycleStage.SIGNED_UP;
+  to: LifecycleStage.ACTIVATED;
+  trigger: string;
+};
+
+/**
+ * Lifecycle Evaluator Backend Service
+ *
+ * Pipeline integration entry point for lifecycle state evaluation.
+ * Called fire-and-forget after milestone evaluation in the operation pipeline.
+ *
+ * Handles:
+ * - Activity tracking (debounced per scope:id, ~30 min)
+ * - Reactivation detection (DORMANT → REACTIVATED on any operation)
+ * - Engagement evaluation (ACTIVATED/REACTIVATED → ENGAGED if threshold met)
+ * - Activation criteria evaluation (SIGNED_UP → ACTIVATED via milestone achievements)
+ * - Dormancy transitions (called by dormancy detection batch)
+ * - On-read reactivation (called by READ POSTFIX custom implementation)
+ */
+@injectable()
+export class LifecycleEvaluatorBackendService {
+
+  /** Debounce cache: scope:scopeId → last write timestamp (in-memory, per-instance) */
+  private activityDebounceCache = new Map<string, number>();
+
+  private logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  private lifecycleConfig: LifecycleConfig | undefined;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.WebSocketService) private readonly webSocketService: WebSocketService,
+    @inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService) private readonly repositoriesRegistry: RepositoriesRegistryHandlerBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('LifecycleEvaluator');
+    this.logger.setDebugTypeLogging('LifecycleEvaluator', false);
+  }
+
+  /** Called at startup to inject lifecycle config from app config */
+  public setLifecycleConfig(config: LifecycleConfig | undefined): void {
+    this.lifecycleConfig = config;
+  }
+
+  // =====================================================
+  // Pipeline Integration: onOperation
+  // =====================================================
+
+  /**
+   * Pipeline integration: called fire-and-forget on every operation.
+   * Handles: activity tracking (debounced), reactivation detection, engagement evaluation.
+   * Updates ALL applicable scopes (user always, org if present).
+   */
+  public async onOperation(params: {
+    userId: string;
+    organizationId?: string;
+    operationIdentifier: string;
+    resourceIdentifier: string;
+    executionContext: unknown;
+  }): Promise<void> {
+    if (!this.lifecycleConfig) return;
+    if (!this.lifecycleConfig.enabled) return;
+    const config = this.lifecycleConfig;
+
+    const applicableScopes = this.resolveApplicableScopes({
+      userId: params.userId,
+      organizationId: params.organizationId,
+    });
+    for (const { scope, resourceType, scopeId } of applicableScopes) {
+      try {
+        await this.evaluateScopeOnOperation(scope, resourceType, scopeId, params, config);
+      } catch (error) {
+        this.logger.warn(`Lifecycle evaluation failed for scope ${scope}`, {
+          scopeId, resourceType, error: String(error),
+        });
+      }
+    }
+  }
+
+  /** Evaluate a single scope on operation — activity + reactivation + engagement + guidance-based activation. */
+  private async evaluateScopeOnOperation(
+    scope: LifecycleScope,
+    resourceType: CoreResourceType,
+    scopeId: string,
+    params: { operationIdentifier: string; resourceIdentifier: string; executionContext: unknown },
+    config: LifecycleConfig,
+  ): Promise<void> {
+    // Ensure state document exists (auto-create on first access)
+    await this.loadOrCreateLifecycleState(resourceType, scopeId);
+
+    const now = new Date();
+    const transitions: Array<{ from: LifecycleStage; to: LifecycleStage; trigger: string }> = [];
+
+    // 1. Reactivation: DORMANT → REACTIVATED (atomic conditional — guard on currentStage)
+    const reactivated = await this.repositoriesRegistry.atomicConditionalUpdate<LifecycleState>(
+      resourceType,
+      { _id: scopeId, currentStage: LifecycleStage.DORMANT },
+      {
+        $set: {
+          currentStage: LifecycleStage.REACTIVATED,
+          stageEnteredAt: now,
+          lastActiveAt: now,
+          'engagement.operationsSinceActivation': 0,
+          'engagement.activeDates': [],
+        },
+        $push: {
+          stageHistory: {
+            $each: [{ stage: LifecycleStage.REACTIVATED, enteredAt: now, trigger: `operation:${params.operationIdentifier}` }],
+            $position: 0,
+            $slice: 20,
+          },
+        },
+        $addToSet: { stagesVisited: LifecycleStage.REACTIVATED },
+      },
+    );
+
+    if (reactivated) {
+      // Close previous stageHistory entry's exitedAt (now at index 1 after $push prepend)
+      await this.repositoriesRegistry.atomicConditionalUpdate(
+        resourceType,
+        { _id: scopeId, 'stageHistory.1': { $exists: true }, 'stageHistory.1.exitedAt': { $exists: false } },
+        { $set: { 'stageHistory.1.exitedAt': now } },
+      );
+      transitions.push({
+        from: LifecycleStage.DORMANT,
+        to: LifecycleStage.REACTIVATED,
+        trigger: `operation:${params.operationIdentifier}`,
+      });
+    }
+
+    // 2. Engagement: atomic increment of counter + activity date (prevents counter loss under concurrency)
+    const todayStr = now.toISOString().slice(0, 10);
+    const engagementUpdate: Record<string, unknown> = {
+      $inc: { 'engagement.operationsSinceActivation': 1 },
+      $addToSet: { 'engagement.activeDates': todayStr },
+    };
+
+    // Debounced activity tracking — defer cache set until DB write confirmed
+    const debounceKey = `${scope}:${scopeId}`;
+    const shouldUpdateLastActive = this.shouldUpdateActivity(debounceKey);
+    if (shouldUpdateLastActive) {
+      engagementUpdate.$set = { lastActiveAt: now };
+    }
+
+    const stateAfterEngagement = await this.repositoriesRegistry.atomicConditionalUpdate<LifecycleState>(
+      resourceType,
+      { _id: scopeId, currentStage: { $in: LIFECYCLE_ENGAGEMENT_ELIGIBLE_STAGES } },
+      engagementUpdate,
+    );
+
+    if (stateAfterEngagement && shouldUpdateLastActive) {
+      this.activityDebounceCache.set(debounceKey, now.getTime());
+    }
+
+    // 3. If engagement threshold configured and met, atomically transition to ENGAGED
+    if (stateAfterEngagement && config.engagementThreshold) {
+      const validTargets = LIFECYCLE_VALID_TRANSITIONS[stateAfterEngagement.currentStage];
+      if (validTargets.includes(LifecycleStage.ENGAGED) &&
+          this.isEngagementThresholdMet(stateAfterEngagement, config.engagementThreshold)) {
+        const fromStage = stateAfterEngagement.currentStage;
+        const engaged = await this.repositoriesRegistry.atomicConditionalUpdate<LifecycleState>(
+          resourceType,
+          { _id: scopeId, currentStage: fromStage },
+          {
+            $set: {
+              currentStage: LifecycleStage.ENGAGED,
+              stageEnteredAt: now,
+            },
+            $push: {
+              stageHistory: {
+                $each: [{ stage: LifecycleStage.ENGAGED, enteredAt: now, trigger: 'engagement_threshold' }],
+                $position: 0,
+                $slice: 20,
+              },
+            },
+            $addToSet: { stagesVisited: LifecycleStage.ENGAGED },
+          },
+        );
+
+        if (engaged) {
+          // Close previous stageHistory entry's exitedAt
+          await this.repositoriesRegistry.atomicConditionalUpdate(
+            resourceType,
+            { _id: scopeId, 'stageHistory.1': { $exists: true }, 'stageHistory.1.exitedAt': { $exists: false } },
+            { $set: { 'stageHistory.1.exitedAt': now } },
+          );
+          transitions.push({
+            from: fromStage,
+            to: LifecycleStage.ENGAGED,
+            trigger: 'engagement_threshold',
+          });
+        }
+      }
+    } else if (!stateAfterEngagement && shouldUpdateLastActive) {
+      // If not in engagement-eligible stage (e.g. ENGAGED, SIGNED_UP), still update lastActiveAt
+      await this.repositoriesRegistry.atomicConditionalUpdate(
+        resourceType,
+        { _id: scopeId },
+        { $set: { lastActiveAt: now } },
+      );
+      this.activityDebounceCache.set(debounceKey, now.getTime());
+    }
+
+    // 4. Push WS events for each transition
+    for (const transition of transitions) {
+      await this.pushStageChanged(transition, scope, scopeId, resourceType);
+    }
+
+    // 5. Guidance-based activation: when a guidance state resource is updated and
+    // activation criteria include GUIDANCE_COMPLETED, evaluate for SIGNED_UP → ACTIVATED
+    if (config.activationCriteria &&
+        GUIDANCE_STATE_RESOURCE_TYPES.has(params.resourceIdentifier as CoreResourceType)) {
+      await this.evaluateGuidanceBasedActivation(scope, resourceType, scopeId, config);
+    }
+  }
+
+  // =====================================================
+  // Guidance-Based Activation (triggered by guidance state updates)
+  // =====================================================
+
+  /** Evaluate activation criteria after a guidance state resource was updated.
+   *  Handles GUIDANCE_COMPLETED criteria for SIGNED_UP → ACTIVATED.
+   *  Uses atomicConditionalUpdate with currentStage guard to prevent double-activation
+   *  if both onMilestoneAchieved and this method fire concurrently. */
+  private async evaluateGuidanceBasedActivation(
+    scope: LifecycleScope,
+    resourceType: CoreResourceType,
+    scopeId: string,
+    config: LifecycleConfig,
+  ): Promise<void> {
+    const state = await this.loadLifecycleState(resourceType, scopeId);
+    if (!state || state.currentStage !== LifecycleStage.SIGNED_UP) return;
+
+    const validTargets = LIFECYCLE_VALID_TRANSITIONS[LifecycleStage.SIGNED_UP];
+    if (!validTargets.includes(LifecycleStage.ACTIVATED)) return;
+
+    const result = await this.evaluateActivationCriteria(
+      config.activationCriteria!,
+      scope,
+      scopeId,
+    );
+    const mergedCriteriaMet = { ...state.activationCriteriaMet, ...result.criteriaMet };
+
+    if (result.met) {
+      const transition: SignedUpActivationTransition = {
+        from: LifecycleStage.SIGNED_UP,
+        to: LifecycleStage.ACTIVATED,
+        trigger: 'guidance_completed',
+      };
+      const activated = await this.tryActivateSignedUpLifecycleState(
+        resourceType,
+        scopeId,
+        transition,
+        mergedCriteriaMet,
+      );
+      if (activated) {
+        await this.pushStageChanged(transition, scope, scopeId, resourceType, mergedCriteriaMet);
+      }
+    } else if (Object.keys(result.criteriaMet).length > 0) {
+      state.activationCriteriaMet = mergedCriteriaMet;
+      await this.updateLifecycleState(resourceType, scopeId, state);
+    }
+  }
+
+  // =====================================================
+  // Milestone Achievement: Activation Criteria
+  // =====================================================
+
+  /**
+   * Called by MilestoneEvaluatorBackendService after a milestone is achieved.
+   * Handles: SIGNED_UP → ACTIVATED transition via activation criteria.
+   * Evaluates all applicable scopes.
+   */
+  public async onMilestoneAchieved(params: {
+    milestoneIdentifier: string;
+    milestoneLifecycleTransition?: MilestoneLifecycleTransition;
+    userId: string;
+    organizationId?: string;
+  }): Promise<void> {
+    if (!this.lifecycleConfig?.enabled) return;
+
+    const applicableScopes = this.resolveApplicableScopes({
+      userId: params.userId,
+      organizationId: params.organizationId,
+    });
+
+    for (const { scope, resourceType, scopeId } of applicableScopes) {
+      try {
+        // Use loadOrCreate (not loadOnly) because on the very first operation,
+        // milestone evaluation fires before lifecycle activity check in the pipeline.
+        // Without auto-create here, the first milestone achievement would be missed.
+        const state = await this.loadOrCreateLifecycleState(resourceType, scopeId);
+        if (state.currentStage !== LifecycleStage.SIGNED_UP) continue;
+
+        // Validate transition via const map
+        const validTargets = LIFECYCLE_VALID_TRANSITIONS[LifecycleStage.SIGNED_UP];
+        if (!validTargets.includes(LifecycleStage.ACTIVATED)) continue;
+
+        let shouldActivate = false;
+        let criteriaMet: Record<string, boolean> = {};
+
+        // Config-level compound criteria take precedence
+        if (this.lifecycleConfig.activationCriteria) {
+          const result = await this.evaluateActivationCriteria(
+            this.lifecycleConfig.activationCriteria,
+            scope,
+            scopeId,
+          );
+          shouldActivate = result.met;
+          criteriaMet = result.criteriaMet;
+          // Persist per-criterion results regardless of activation outcome
+          state.activationCriteriaMet = { ...state.activationCriteriaMet, ...criteriaMet };
+        } else if (params.milestoneLifecycleTransition?.from === 'SIGNED_UP' &&
+                   params.milestoneLifecycleTransition?.to === 'ACTIVATED') {
+          shouldActivate = true;
+        }
+
+        if (shouldActivate) {
+          const transition: SignedUpActivationTransition = {
+            from: LifecycleStage.SIGNED_UP,
+            to: LifecycleStage.ACTIVATED,
+            trigger: `milestone:${params.milestoneIdentifier}`,
+          };
+          const mergedCriteriaMet = { ...state.activationCriteriaMet, ...criteriaMet };
+          const activated = await this.tryActivateSignedUpLifecycleState(
+            resourceType,
+            scopeId,
+            transition,
+            mergedCriteriaMet,
+          );
+          if (activated) {
+            await this.pushStageChanged(transition, scope, scopeId, resourceType, mergedCriteriaMet);
+          }
+        } else if (Object.keys(criteriaMet).length > 0) {
+          // Persist partial criteria progress even if not fully activated yet
+          await this.updateLifecycleState(resourceType, scopeId, state);
+        }
+      } catch (error) {
+        this.logger.warn(`Activation evaluation failed for scope ${scope}`, {
+          scopeId, resourceType, error: String(error),
+        });
+      }
+    }
+  }
+
+  // =====================================================
+  // Dormancy Detection (called by batch)
+  // =====================================================
+
+  /**
+   * Called by dormancy detection batch.
+   * Transitions a specific entity to DORMANT. Validates via LIFECYCLE_VALID_TRANSITIONS.
+   */
+  public async transitionToDormant(
+    scopeResourceType: CoreResourceType,
+    scopeId: string,
+    executionContext: unknown,
+    cutoffDate?: Date,
+  ): Promise<void> {
+    // Re-read fresh state (batch query snapshot may be stale)
+    const state = await this.loadLifecycleState(scopeResourceType, scopeId);
+    if (!state) return;
+
+    // Validate via const — only DORMANCY_SOURCE_STAGES can go dormant
+    if (!(LIFECYCLE_DORMANCY_SOURCE_STAGES as readonly LifecycleStage[]).includes(state.currentStage)) return;
+
+    // Double-check via transition map
+    const validTargets = LIFECYCLE_VALID_TRANSITIONS[state.currentStage];
+    if (!validTargets.includes(LifecycleStage.DORMANT)) return;
+
+    // Re-verify lastActiveAt hasn't been updated since batch query
+    if (cutoffDate && state.lastActiveAt && new Date(state.lastActiveAt) > cutoffDate) {
+      this.logger.info('Skipping dormancy — user became active since batch query', { scopeId });
+      return;
+    }
+
+    // Resolve scope from resource type
+    const scope = this.resolveScope(scopeResourceType);
+
+    const now = new Date();
+    const transition = {
+      from: state.currentStage,
+      to: LifecycleStage.DORMANT,
+      trigger: 'dormancy_cron',
+    };
+    const updatedState = this.applyTransition(state, transition, now);
+    await this.updateLifecycleState(scopeResourceType, scopeId, updatedState);
+    await this.pushStageChanged(transition, scope, scopeId, scopeResourceType);
+  }
+
+  // =====================================================
+  // On-Read Reactivation (called by custom impl)
+  // =====================================================
+
+  /**
+   * Called by READ POSTFIX custom implementation on lifecycle state resources.
+   * Detects dormant user returning → triggers reactivation for instant UX.
+   */
+  public async handleReactivation(
+    scopeResourceType: CoreResourceType,
+    scopeId: string,
+    executionContext: unknown,
+  ): Promise<void> {
+    const state = await this.loadLifecycleState(scopeResourceType, scopeId);
+    if (!state || state.currentStage !== LifecycleStage.DORMANT) return;
+
+    const validTargets = LIFECYCLE_VALID_TRANSITIONS[LifecycleStage.DORMANT];
+    if (!validTargets.includes(LifecycleStage.REACTIVATED)) return;
+
+    // Resolve scope from resource type
+    const scope = this.resolveScope(scopeResourceType);
+
+    const now = new Date();
+    const transition = {
+      from: LifecycleStage.DORMANT,
+      to: LifecycleStage.REACTIVATED,
+      trigger: 'on_read_reactivation',
+    };
+    const updatedState = this.applyTransition(state, transition, now);
+    updatedState.lastActiveAt = now;
+    await this.updateLifecycleState(scopeResourceType, scopeId, updatedState);
+    await this.pushStageChanged(transition, scope, scopeId, scopeResourceType);
+  }
+
+  // =====================================================
+  // Private Helpers
+  // =====================================================
+
+  /** Resolve all applicable scopes for this operation context. */
+  private resolveApplicableScopes(params: {
+    userId: string;
+    organizationId?: string;
+  }): Array<{ scope: LifecycleScope; resourceType: CoreResourceType; scopeId: string }> {
+    const scopes: Array<{ scope: LifecycleScope; resourceType: CoreResourceType; scopeId: string }> = [];
+    scopes.push({
+      scope: LifecycleScope.USER,
+      resourceType: CoreResourceType.USER_LIFECYCLE_STATE,
+      scopeId: params.userId,
+    });
+    if (params.organizationId) {
+      scopes.push({
+        scope: LifecycleScope.ORGANIZATION,
+        resourceType: CoreResourceType.ORGANIZATION_LIFECYCLE_STATE,
+        scopeId: params.organizationId,
+      });
+    }
+    return scopes;
+  }
+
+  /** Resolve LifecycleScope from a resource type */
+  private resolveScope(resourceType: CoreResourceType): LifecycleScope {
+    for (const [scope, rt] of Object.entries(LIFECYCLE_SCOPE_TO_RESOURCE)) {
+      if (rt === resourceType) return scope as LifecycleScope;
+    }
+    this.logger.warn('resolveScope: unknown lifecycle resource type, defaulting to USER', { resourceType });
+    return LifecycleScope.USER;
+  }
+
+  private applyTransition(
+    state: LifecycleState,
+    transition: { from: LifecycleStage; to: LifecycleStage; trigger: string },
+    now: Date,
+  ): LifecycleState {
+    const validTargets = LIFECYCLE_VALID_TRANSITIONS[transition.from];
+    if (!validTargets.includes(transition.to)) {
+      throw new Error(`Invalid lifecycle transition: ${transition.from} → ${transition.to}`);
+    }
+
+    // Close current stage in history
+    const updatedHistory = [...state.stageHistory];
+    if (updatedHistory.length > 0 && !updatedHistory[0].exitedAt) {
+      updatedHistory[0] = { ...updatedHistory[0], exitedAt: now };
+    }
+    // Add new stage entry (most recent first, cap at 20)
+    updatedHistory.unshift({
+      stage: transition.to,
+      enteredAt: now,
+      trigger: transition.trigger,
+    });
+    if (updatedHistory.length > 20) updatedHistory.pop();
+
+    const existingVisited = state.stagesVisited ?? [];
+    const stagesVisited = existingVisited.includes(transition.to)
+      ? existingVisited
+      : [...existingVisited, transition.to];
+
+    const result: LifecycleState = {
+      ...state,
+      currentStage: transition.to,
+      stageEnteredAt: now,
+      stageHistory: updatedHistory,
+      stagesVisited,
+    };
+
+    if (transition.to === LifecycleStage.REACTIVATED) {
+      result.engagement = { ...state.engagement, operationsSinceActivation: 0, activeDates: [] };
+    }
+
+    return result;
+  }
+
+  /**
+   * Atomically commit the canonical SIGNED_UP → ACTIVATED transition.
+   * This keeps milestone-driven and guidance-driven activation on the same
+   * compare-and-set path so concurrent activations cannot double-transition.
+   */
+  private async tryActivateSignedUpLifecycleState(
+    resourceType: CoreResourceType,
+    scopeId: string,
+    transition: SignedUpActivationTransition,
+    activationCriteriaMet: Record<string, boolean>,
+  ): Promise<boolean> {
+    const now = new Date();
+    const mongooseModel = this.getLifecycleMongooseModel(resourceType);
+    if (!mongooseModel) {
+      return false;
+    }
+
+    const committed = await mongooseModel.findOneAndUpdate(
+      { _id: scopeId, currentStage: LifecycleStage.SIGNED_UP },
+      [
+        {
+          $set: {
+            currentStage: LifecycleStage.ACTIVATED,
+            stageEnteredAt: now,
+            lastActiveAt: now,
+            activationCriteriaMet,
+            stageHistory: {
+              $let: {
+                vars: {
+                  currentHistory: { $ifNull: ['$stageHistory', []] },
+                },
+                in: {
+                  $concatArrays: [
+                    [{ stage: LifecycleStage.ACTIVATED, enteredAt: now, trigger: transition.trigger }],
+                    {
+                      $cond: [
+                        { $gt: [{ $size: '$$currentHistory' }, 0] },
+                        [{
+                          $mergeObjects: [
+                            { $arrayElemAt: ['$$currentHistory', 0] },
+                            { exitedAt: now },
+                          ],
+                        }],
+                        [],
+                      ],
+                    },
+                    { $slice: ['$$currentHistory', 1, 18] },
+                  ],
+                },
+              },
+            },
+            stagesVisited: {
+              $let: {
+                vars: {
+                  existingStages: { $ifNull: ['$stagesVisited', []] },
+                },
+                in: {
+                  $cond: [
+                    { $in: [LifecycleStage.ACTIVATED, '$$existingStages'] },
+                    '$$existingStages',
+                    { $concatArrays: ['$$existingStages', [LifecycleStage.ACTIVATED]] },
+                  ],
+                },
+              },
+            },
+          },
+        },
+      ],
+      { new: true },
+    ).exec();
+
+    return !!committed;
+  }
+
+  private getLifecycleMongooseModel(resourceType: CoreResourceType): Model<any> | null {
+    const repository = this.repositoriesRegistry.getRepository(resourceType);
+    const mongooseModel = (repository as any)?.mongooseModel;
+    if (!mongooseModel) {
+      this.logDebug('No mongoose model found for lifecycle resource', { resourceType });
+      return null;
+    }
+    return mongooseModel as Model<any>;
+  }
+
+  private shouldUpdateActivity(debounceKey: string): boolean {
+    const debounceMs = (this.lifecycleConfig?.activityDebounceMinutes ?? 30) * 60_000;
+    const lastWrite = this.activityDebounceCache.get(debounceKey);
+    return !lastWrite || (Date.now() - lastWrite) > debounceMs;
+  }
+
+  /**
+   * Note: `daysSinceStageEntry` measures time since the *current* stage was
+   * entered (could be REACTIVATED, not ACTIVATED). Engagement counters are
+   * reset on reactivation (in `applyTransition`), so the threshold evaluation
+   * is accurate for each activation/reactivation cycle.
+   */
+  private isEngagementThresholdMet(
+    state: LifecycleState,
+    threshold: EngagementThreshold,
+  ): boolean {
+    const daysSinceStageEntry = Math.floor(
+      (Date.now() - new Date(state.stageEnteredAt).getTime()) / (1000 * 60 * 60 * 24)
+    );
+    return daysSinceStageEntry <= threshold.withinDays &&
+           state.engagement.operationsSinceActivation >= threshold.minOperations;
+  }
+
+  private async evaluateActivationCriteria(
+    criteria: ActivationCriteria,
+    scope: LifecycleScope,
+    scopeId: string,
+  ): Promise<{ met: boolean; criteriaMet: Record<string, boolean> }> {
+    const criteriaMet: Record<string, boolean> = {};
+
+    // Pre-load cross-system state once per type to avoid redundant DB reads
+    const needsProgression = criteria.criteria.some(c => c.criterionType === ActivationCriterionType.MILESTONE);
+    const needsGuidance = criteria.criteria.some(c => c.criterionType === ActivationCriterionType.GUIDANCE_COMPLETED);
+
+    const [progressionState, guidanceState] = await Promise.all([
+      needsProgression ? this.loadProgressionState(LIFECYCLE_TO_PROGRESSION_RESOURCE[scope], scopeId) : null,
+      needsGuidance ? this.loadGuidanceState(LIFECYCLE_TO_GUIDANCE_RESOURCE[scope], scopeId) : null,
+    ]);
+
+    const results = criteria.criteria.map(criterion =>
+      this.evaluateSingleCriterion(criterion, progressionState, guidanceState, criteriaMet),
+    );
+
+    const met = criteria.mode === 'ANY'
+      ? results.some(Boolean)
+      : results.every(Boolean);
+
+    return { met, criteriaMet };
+  }
+
+  private evaluateSingleCriterion(
+    criterion: ActivationCriterion,
+    progressionState: ProgressionState | null,
+    guidanceState: GuidanceState | null,
+    criteriaMet: Record<string, boolean>,
+  ): boolean {
+    switch (criterion.criterionType) {
+      case ActivationCriterionType.MILESTONE: {
+        if (!progressionState) return false;
+        const isMet = !!progressionState.milestonesAchieved[criterion.milestoneRef];
+        criteriaMet[criterion.milestoneRef] = isMet;
+        return isMet;
+      }
+      case ActivationCriterionType.GUIDANCE_COMPLETED: {
+        if (!guidanceState) return false;
+        const flowState = guidanceState.flows[criterion.guidanceFlowRef];
+        const isMet = flowState?.status === OnboardingStatus.COMPLETED;
+        criteriaMet[criterion.guidanceFlowRef] = isMet;
+        return isMet;
+      }
+    }
+  }
+
+  // =====================================================
+  // State Persistence
+  // =====================================================
+
+  private async loadOrCreateLifecycleState(
+    resourceType: CoreResourceType,
+    scopeId: string,
+  ): Promise<LifecycleState> {
+    try {
+      const repository = this.repositoriesRegistry.getRepository(resourceType);
+      if (!repository) {
+        this.logDebug('No repository found for lifecycle state', { resourceType });
+        return createInitialLifecycleState();
+      }
+
+      const existing = await repository.read<LifecycleState>(
+        internalOpCtx(resourceType, 'read') as any,
+        scopeId,
+        { excludeContextualFilter: true },
+      );
+
+      if (existing) {
+        return existing;
+      }
+
+      // Auto-create on first access (handle concurrent create race)
+      this.logDebug('Creating new lifecycle state', { resourceType, scopeId });
+      const defaultState = createInitialLifecycleState();
+      try {
+        await repository.create(
+          internalOpCtx(resourceType, 'create') as any,
+          defaultState,
+          { excludeContextualFilter: true, excludeContextEnrichment: true },
+        );
+      } catch {
+        // Duplicate key from concurrent create — re-read
+        const raceWinner = await repository.read<LifecycleState>(
+          internalOpCtx(resourceType, 'read') as any,
+          scopeId,
+          { excludeContextualFilter: true },
+        );
+        if (raceWinner) return raceWinner;
+      }
+      return defaultState;
+    } catch (error) {
+      this.logger.warn('Failed to load lifecycle state, falling back to default', {
+        resourceType,
+        scopeId,
+        error: isWildoBackendError(error) ? String(error) : (error instanceof Error ? error.message : String(error)),
+      });
+      return createInitialLifecycleState();
+    }
+  }
+
+  private async loadLifecycleState(
+    resourceType: CoreResourceType,
+    scopeId: string,
+  ): Promise<LifecycleState | null> {
+    try {
+      const repository = this.repositoriesRegistry.getRepository(resourceType);
+      if (!repository) return null;
+
+      return await repository.read<LifecycleState>(
+        internalOpCtx(resourceType, 'read') as any,
+        scopeId,
+        { excludeContextualFilter: true },
+      );
+    } catch (error) {
+      this.logDebug('Failed to load lifecycle state', {
+        resourceType,
+        scopeId,
+        error: isWildoBackendError(error) ? String(error) : (error instanceof Error ? error.message : String(error)),
+      });
+      return null;
+    }
+  }
+
+  private async updateLifecycleState(
+    resourceType: CoreResourceType,
+    scopeId: string,
+    state: LifecycleState,
+  ): Promise<void> {
+    try {
+      const repository = this.repositoriesRegistry.getRepository(resourceType);
+      if (!repository) return;
+
+      await repository.update(
+        internalOpCtx(resourceType, 'update') as any,
+        scopeId,
+        state,
+        { excludeContextualFilter: true, excludeContextEnrichment: true },
+      );
+    } catch (error) {
+      this.logger.warn('Failed to persist lifecycle state', {
+        resourceType,
+        scopeId,
+        error: isWildoBackendError(error) ? String(error) : (error instanceof Error ? error.message : String(error)),
+      });
+    }
+  }
+
+  private async loadProgressionState(
+    resourceType: CoreResourceType,
+    scopeId: string,
+  ): Promise<ProgressionState | null> {
+    try {
+      const repository = this.repositoriesRegistry.getRepository(resourceType);
+      if (!repository) return null;
+
+      return await repository.read<ProgressionState>(
+        internalOpCtx(resourceType, 'read') as any,
+        scopeId,
+        { excludeContextualFilter: true },
+      );
+    } catch (error) {
+      this.logDebug('Failed to load progression state for activation criteria', {
+        resourceType,
+        scopeId,
+        error: isWildoBackendError(error) ? String(error) : (error instanceof Error ? error.message : String(error)),
+      });
+      return null;
+    }
+  }
+
+  private async loadGuidanceState(
+    resourceType: CoreResourceType,
+    scopeId: string,
+  ): Promise<GuidanceState | null> {
+    try {
+      const repository = this.repositoriesRegistry.getRepository(resourceType);
+      if (!repository) return null;
+
+      return await repository.read<GuidanceState>(
+        internalOpCtx(resourceType, 'read') as any,
+        scopeId,
+        { excludeContextualFilter: true },
+      );
+    } catch (error) {
+      this.logDebug('Failed to load guidance state for activation criteria', {
+        resourceType,
+        scopeId,
+        error: isWildoBackendError(error) ? String(error) : (error instanceof Error ? error.message : String(error)),
+      });
+      return null;
+    }
+  }
+
+  /** Sanitize trigger for WS payload — hide internal operation identifiers */
+  private sanitizeTrigger(trigger: string): string {
+    if (trigger.startsWith('operation:')) return 'operation';
+    if (trigger.startsWith('milestone:')) return 'milestone';
+    return trigger;
+  }
+
+  // =====================================================
+  // WebSocket Event Dispatch
+  // =====================================================
+
+  private async pushStageChanged(
+    transition: { from: LifecycleStage; to: LifecycleStage; trigger: string },
+    scope: LifecycleScope,
+    scopeId: string,
+    resourceType: CoreResourceType,
+    activationCriteriaMet?: Record<string, boolean>,
+  ): Promise<void> {
+    const wsPayload: WS_LifecycleStageChangedPayload = {
+      previousStage: transition.from,
+      newStage: transition.to,
+      scope,
+      trigger: this.sanitizeTrigger(transition.trigger),
+      changedAt: new Date(),
+      ...(activationCriteriaMet ? { activationCriteriaMet } : {}),
+    };
+
+    const wsMessage: WebSocketMessage = {
+      type: CoreWebSocketEvent.LIFECYCLE_STAGE_CHANGED,
+      payload: wsPayload,
+      timestamp: new Date(),
+    };
+
+    try {
+      switch (scope) {
+        case LifecycleScope.USER:
+          await this.webSocketService.sendToUser(scopeId, wsMessage);
+          break;
+        case LifecycleScope.ORGANIZATION:
+          await this.webSocketService.sendToOrganization(scopeId, wsMessage);
+          break;
+      }
+
+      this.logDebug('Dispatched LIFECYCLE_STAGE_CHANGED event', {
+        from: transition.from,
+        to: transition.to,
+        scope,
+        trigger: transition.trigger,
+      });
+    } catch (error) {
+      this.logger.warn('Failed to dispatch lifecycle stage changed event', {
+        scope,
+        scopeId,
+        error: isWildoBackendError(error) ? String(error) : (error instanceof Error ? error.message : String(error)),
+      });
+    }
+  }
+}