@wildo-ai/saas-backend-lib 1.0.1

package/src/features/services/feature-resolution.backend.service.ts

@@ -0,0 +1,652 @@
+/**
+ * Feature Resolution Backend Service
+ *
+ * Resolves effective features for a given execution context by walking the scope hierarchy
+ * and merging multiple sources: defaults → profile → provider-derived → billing-derived → manual overrides.
+ *
+ * The output is a CONSOLIDATED ResolvedFeatures object that merges ALL applicable scope levels.
+ * The gate service checks this single object — no per-scope lookup at gate time.
+ *
+ * Cache: Redis with configurable TTL. Key format: `features:{scopeType}:{entityId}`.
+ */
+
+import { injectable, inject } from 'inversify';
+import type { Container } from 'inversify';
+import {
+  FEATURES_UNLIMITED,
+  FeatureValueType,
+  ResourcePrimaryScope,
+  EngineCapability,
+  ExecutionContext_ExecutionType,
+  type ResolvedFeatures,
+  type ResolvedFeaturesWithUsage,
+  type ScopeFeatures,
+  type ScopeFeaturesWithOverrides,
+} from '@wildo-ai/saas-models';
+import {
+  CoreResourceType,
+  CoreResourceOperation,
+} 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 { RedisService } from '~wildo-backend-lib/databases/services/redis.service';
+import type { FeatureDefinitionRegistryBackendService } from './feature-definition-registry.backend.service';
+import type { CapabilityBindingsBackendService } from '~wildo-backend-lib/external-providers/services/feature-bindings.backend.service';
+import type { ServicesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';
+import type { ExecutionContextCreatorBackendService } from '~wildo-backend-lib/runtime/services/execution-context-creator.backend.service';
+import type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+import type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import { mergeLimit } from '~wildo-backend-lib/billing/services/billing.utils';
+import type { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';
+
+// =====================================================
+// Cache Configuration
+// =====================================================
+
+/** Default TTL values (in seconds) for different scope types */
+const DEFAULT_CACHE_TTL: Record<string, number> = {
+  [ResourcePrimaryScope.APPLICATION]: 3600,    // 1 hour (changes only on provider binding changes)
+  [ResourcePrimaryScope.ORGANIZATIONS]: 300,   // 5 minutes
+  [ResourcePrimaryScope.USER_SELF]: 300,       // 5 minutes
+};
+
+/** Sentinel entity ID for application-scope features */
+const APP_SCOPE_ENTITY_ID = '__global__';
+
+// =====================================================
+// Merge Utilities
+// =====================================================
+
+/**
+ * Merge two ScopeFeatures objects (union for features, most permissive for limits).
+ */
+function mergeScopeFeatures(base: ScopeFeatures, overlay: ScopeFeatures): ScopeFeatures {
+  // Features: union (deduplicated)
+  const mergedFeatures = [...new Set([...base.features, ...overlay.features])];
+
+  // Limits: most permissive value wins
+  const mergedLimits = { ...base.limits };
+  for (const [key, value] of Object.entries(overlay.limits)) {
+    if (key in mergedLimits) {
+      mergedLimits[key] = mergeLimit(mergedLimits[key], value);
+    } else {
+      mergedLimits[key] = value;
+    }
+  }
+
+  return { features: mergedFeatures, limits: mergedLimits };
+}
+
+// =====================================================
+// Feature Resolution Service
+// =====================================================
+
+@injectable()
+export class FeatureResolutionBackendService {
+  private logDebug: (message: string, context?: Record<string, unknown>) => void;
+  private _servicesRegistry: ServicesRegistryHandlerBackendService | null = null;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.RedisService) private readonly redisService: RedisService,
+    @inject(SAAS_SERVICE_TYPES.FeatureDefinitionRegistryService) private readonly featureRegistry: FeatureDefinitionRegistryBackendService,
+    @inject(SAAS_SERVICE_TYPES.CapabilityBindingsService) private readonly capabilityBindings: CapabilityBindingsBackendService,
+    @inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly appConfigService: AppConfigurationService,
+    @inject('Container') private readonly container: Container,
+    @inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService) private readonly executionContextCreator: ExecutionContextCreatorBackendService,
+    @inject(SAAS_SERVICE_TYPES.ResourceRegistryService) private readonly resourcesRegistry: ResourcesRegistryBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('FeatureResolutionBackendService');
+  }
+
+  private get servicesRegistry(): ServicesRegistryHandlerBackendService {
+    if (!this._servicesRegistry) {
+      this._servicesRegistry = this.container.get<ServicesRegistryHandlerBackendService>(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService);
+    }
+    return this._servicesRegistry;
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // Public API
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Resolve effective features for the current execution context.
+   * Walks the scope hierarchy based on ExecutionType and returns a CONSOLIDATED result.
+   */
+  async resolve(executionContext: ExecutionContext<any>): Promise<ResolvedFeatures> {
+    const execType = executionContext.executionType;
+
+    // Internal calls bypass feature resolution entirely
+    if (execType === ExecutionContext_ExecutionType.INTERNALLY_INITIATED_REQUEST) {
+      this.logDebug('Internal call — returning all features enabled');
+      return this.buildAllFeaturesEnabled();
+    }
+
+    // Public executions get minimal features (defaults only, no scope)
+    if (execType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+      this.logDebug('Public execution — returning defaults only');
+      return this.buildDefaults(ResourcePrimaryScope.APPLICATION);
+    }
+
+    // Determine scope chain based on execution type
+    const scopeChain = this.buildScopeChain(executionContext);
+    this.logDebug('Resolving features for scope chain', { execType, scopeChain: scopeChain.map(s => s.scopeType) });
+
+    // Walk the scope chain, layering features at each level
+    let consolidated: ScopeFeatures = { features: [], limits: {} };
+
+    for (const scope of scopeChain) {
+      const scopeResolved = await this.resolveForScopeInternal(scope.scopeType, scope.entityId, consolidated);
+      consolidated = scopeResolved;
+    }
+
+    this.logDebug('Resolution complete', {
+      featuresCount: consolidated.features.length,
+      limitsCount: Object.keys(consolidated.limits).length,
+    });
+
+    // Cache on the context to avoid re-resolution within the same request
+    executionContext.setResolvedFeatures(consolidated);
+
+    return consolidated;
+  }
+
+  /**
+   * Resolve effective features for a specific scope entity (standalone, not context-aware).
+   * Does NOT walk the scope hierarchy — resolves a single scope starting from defaults.
+   */
+  async resolveForScope(scopeType: ResourcePrimaryScope, scopeEntityId: string): Promise<ResolvedFeatures> {
+    return this.resolveForScopeInternal(scopeType, scopeEntityId, { features: [], limits: {} });
+  }
+
+  /**
+   * Check if a boolean feature is enabled for the given execution context.
+   */
+  async isFeatureEnabled(featureId: string, executionContext: ExecutionContext<any>): Promise<boolean> {
+    const resolved = await this.resolve(executionContext);
+    return resolved.features.includes(featureId);
+  }
+
+  /**
+   * Get the limit value for a LIMIT feature.
+   * Returns FEATURES_UNLIMITED if the feature is not found (permissive default).
+   */
+  async getLimit(featureId: string, executionContext: ExecutionContext<any>): Promise<number> {
+    const resolved = await this.resolve(executionContext);
+    return resolved.limits[featureId] ?? FEATURES_UNLIMITED;
+  }
+
+  /**
+   * Get resolved features WITH current usage placeholder.
+   * Actual usage population is done in FeaturesControllerBackendService, which injects
+   * FeatureGateBackendService directly (no circular dependency at the controller level).
+   */
+  async resolveWithUsage(executionContext: ExecutionContext<any>): Promise<ResolvedFeaturesWithUsage> {
+    const resolved = await this.resolve(executionContext);
+    return {
+      ...resolved,
+      currentUsage: {},
+    };
+  }
+
+  /**
+   * Invalidate cached features for a scope entity.
+   * Call on: feature override changes, subscription changes, provider binding changes.
+   */
+  async invalidateCache(scopeType: ResourcePrimaryScope, entityId: string): Promise<void> {
+    const cacheKey = this.buildCacheKey(scopeType, entityId);
+    this.logDebug('Invalidating feature cache', { cacheKey });
+    await this.redisService.del(cacheKey);
+  }
+
+  /**
+   * Invalidate cached features for all scope levels of an execution context.
+   * Convenience method for when a change affects the entire resolution chain.
+   */
+  async invalidateCacheForContext(executionContext: ExecutionContext<any>): Promise<void> {
+    const scopeChain = this.buildScopeChain(executionContext);
+    for (const scope of scopeChain) {
+      await this.invalidateCache(scope.scopeType, scope.entityId);
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // Internal Resolution
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Resolve features for a single scope level, starting from a base (parent scope's features).
+   * Checks cache first, then resolves from sources if cache miss.
+   */
+  private async resolveForScopeInternal(
+    scopeType: ResourcePrimaryScope,
+    entityId: string,
+    parentFeatures: ScopeFeatures,
+  ): Promise<ScopeFeatures> {
+    const cacheKey = this.buildCacheKey(scopeType, entityId);
+
+    // Check cache
+    const cached = await this.redisService.get<ScopeFeatures>(cacheKey);
+    if (cached) {
+      this.logDebug('Cache hit', { cacheKey });
+      // Merge cached scope-level features with parent and then prune across the
+      // full effective layer so child-scope overrides can depend on parent
+      // entitlements.
+      return this.mergeAndPruneEffectiveFeatures(parentFeatures, cached);
+    }
+
+    this.logDebug('Cache miss — resolving', { scopeType, entityId });
+
+    // Step A: Start with feature definition defaults
+    let scopeFeatures = this.buildDefaults(scopeType);
+
+    // Step B: Layer config profile (when billing is disabled)
+    scopeFeatures = this.applyProfile(scopeFeatures, scopeType);
+
+    // Step C: Layer provider-derived features (APPLICATION scope only)
+    if (scopeType === ResourcePrimaryScope.APPLICATION) {
+      scopeFeatures = this.applyProviderDerivedFeatures(scopeFeatures);
+    }
+
+    // Steps D + E: Layer billing-derived features AND apply manual overrides.
+    // Both come from the same scope features document (single DB read).
+    // Billing sync writes to `features`/`limits`; admin overrides live in `manualOverrides`.
+    scopeFeatures = await this.applyBillingAndManualOverrides(scopeType, entityId, scopeFeatures);
+
+    // Cache the raw scope-level result before parent merge. Dependency pruning
+    // must run on the full effective set so child-scope features can depend on
+    // app/org features from broader scope layers.
+    const ttl = DEFAULT_CACHE_TTL[scopeType] ?? 300;
+    await this.redisService.set(cacheKey, scopeFeatures, { ttl });
+    this.logDebug('Cached scope features', { cacheKey, ttl });
+
+    // Merge with parent scope features and then prune across the full effective set.
+    return this.mergeAndPruneEffectiveFeatures(parentFeatures, scopeFeatures);
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // Resolution Steps
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Step A: Build defaults from feature definitions.
+   * Boolean features with defaultValue=true → enabled.
+   * Limit features → default numeric value.
+   */
+  private buildDefaults(scopeType: ResourcePrimaryScope): ScopeFeatures {
+    const definitions = this.featureRegistry.getAllDefinitions();
+    const features: string[] = [];
+    const limits: Record<string, number> = {};
+
+    for (const def of definitions) {
+      if (!this.isDefinitionApplicableToScope(def.identifier, scopeType)) {
+        continue;
+      }
+      if (def.valueType === FeatureValueType.BOOLEAN && def.defaultValue === true) {
+        features.push(def.identifier);
+      }
+      if (def.valueType === FeatureValueType.LIMIT && typeof def.defaultValue === 'number') {
+        limits[def.identifier] = def.defaultValue;
+      }
+    }
+
+    return { features, limits };
+  }
+
+  /**
+   * Step B: Apply config profile.
+   * When billing is DISABLED: applies the defaultProfile from FeatureConfiguration.
+   * When billing is ENABLED: profiles are NOT used (features come from subscriptions).
+   */
+  private applyProfile(base: ScopeFeatures, scopeType: ResourcePrimaryScope): ScopeFeatures {
+    const config = this.featureRegistry.getConfiguration();
+    if (!config?.defaultProfile || !config?.profiles) return base;
+    if (this.appConfigService.config?.billing?.enabled) return base;
+
+    const profile = config.profiles[config.defaultProfile];
+    if (!profile) return base;
+
+    this.logDebug('Applying profile', { profileKey: config.defaultProfile });
+    return mergeScopeFeatures(base, this.filterScopeFeaturesForScope(profile, scopeType));
+  }
+
+  /**
+   * Step C: Layer provider-derived features (APPLICATION scope only).
+   * Checks CapabilityBindingsBackendService for all EngineCapabilities with active providers.
+   * Each bound EngineCapability becomes an enabled boolean feature.
+   */
+  private applyProviderDerivedFeatures(base: ScopeFeatures): ScopeFeatures {
+    const providerFeatures: string[] = [];
+
+    for (const capability of Object.values(EngineCapability)) {
+      if (this.capabilityBindings.isCapabilityAvailable(capability)) {
+        providerFeatures.push(capability);
+      }
+    }
+
+    if (providerFeatures.length === 0) return base;
+
+    this.logDebug('Provider-derived features', { count: providerFeatures.length });
+    return mergeScopeFeatures(base, { features: providerFeatures, limits: {} });
+  }
+
+  /**
+   * Steps D + E: Read the scope features document and apply billing-derived features
+   * AND manual overrides in a single DB read.
+   *
+   * The scope features document (e.g., ORGANIZATION_FEATURES) has:
+   * - `features` / `limits`: written by BillingFeatureSyncBackendService on subscription changes
+   * - `manualOverrides`: written by admin actions (ENABLE_FEATURE, DISABLE_FEATURE, etc.)
+   *
+   * Resolution order:
+   * 1. Merge billing-derived `features`/`limits` onto base (union/most-permissive)
+   * 2. Apply manual overrides on top (addedFeatures, removedFeatures, limitOverrides)
+   *    → Manual overrides always win.
+   */
+  private async applyBillingAndManualOverrides(
+    scopeType: ResourcePrimaryScope,
+    entityId: string,
+    base: ScopeFeatures,
+  ): Promise<ScopeFeatures> {
+    // APPLICATION scope has no entity-level features document
+    if (scopeType === ResourcePrimaryScope.APPLICATION) return base;
+
+    const scopeDoc = await this.getScopeFeatureDocument(scopeType, entityId);
+    if (!scopeDoc) return base;
+
+    // Step D: Merge billing-derived features (stored in the document's `features`/`limits`)
+    let result = mergeScopeFeatures(base, this.filterScopeFeaturesForScope({
+      features: scopeDoc.features ?? [],
+      limits: scopeDoc.limits ?? {},
+    }, scopeType));
+
+    // Step E: Apply manual overrides on top (always win)
+    if (scopeDoc.manualOverrides) {
+      result = this.applyOverridesFromDocument(result, scopeDoc.manualOverrides);
+    }
+
+    return this.filterScopeFeaturesForScope(result, scopeType);
+  }
+
+  /**
+   * Read the scope features document for a given scope entity.
+   * Returns null if no document exists (entity has no features record yet).
+   *
+   * Uses READ operation (not LIST) because all scope features resources
+   * have READ configured, while USER_FEATURES does not expose LIST. The repository's `read` method accepts a filter
+   * object (uses MongoDB `findOne` internally), which is exactly what we need.
+   */
+  private async getScopeFeatureDocument(
+    scopeType: ResourcePrimaryScope,
+    entityId: string,
+  ): Promise<ScopeFeaturesWithOverrides | null> {
+    const resourceType = this.getScopeFeaturesResourceType(scopeType);
+    if (!resourceType) return null;
+
+    const foreignKeyField = this.getScopeForeignKeyField(scopeType);
+
+    try {
+      const operationPath = this.resourcesRegistry.getOperationPathDefault(resourceType, CoreResourceOperation.READ);
+      const ctx = await this.executionContextCreator.createForInternalOperation({
+        operation: operationPath,
+        contextResourcesFieldIdentifier: new Map(),
+        initiatorIds: null,
+        initiatorRoles: [],
+      });
+
+      // Use read with a filter object (not an ID) — repository findOne under the hood
+      return await this.servicesRegistry.read<ScopeFeaturesWithOverrides>(
+        resourceType, ctx, { [foreignKeyField]: entityId },
+      );
+    } catch (error) {
+      // Expected when no features document exists yet for this entity
+      this.logDebug('No scope features document found (or read failed)', {
+        scopeType, entityId, error: (error as Error).message,
+      });
+      return null;
+    }
+  }
+
+  /**
+   * Map scope type to the corresponding features resource type.
+   */
+  private getScopeFeaturesResourceType(scopeType: ResourcePrimaryScope): CoreResourceType | null {
+    switch (scopeType) {
+      case ResourcePrimaryScope.ORGANIZATIONS:
+        return CoreResourceType.ORGANIZATION_FEATURES;
+      case ResourcePrimaryScope.USER_SELF:
+        return CoreResourceType.USER_FEATURES;
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Map scope type to the foreign key field name used in the features resource.
+   */
+  private getScopeForeignKeyField(scopeType: ResourcePrimaryScope): string {
+    switch (scopeType) {
+      case ResourcePrimaryScope.ORGANIZATIONS:
+        return 'organizationId';
+      case ResourcePrimaryScope.USER_SELF:
+        return 'userId';
+      default:
+        return 'entityId';
+    }
+  }
+
+  /**
+   * Apply manual overrides from a ScopeFeaturesWithOverrides document.
+   * Manual overrides always win: addedFeatures are unioned, removedFeatures are excluded,
+   * limitOverrides directly replace computed values.
+   */
+  private applyOverridesFromDocument(
+    base: ScopeFeatures,
+    overrides: ScopeFeaturesWithOverrides['manualOverrides'],
+  ): ScopeFeatures {
+    let features = [...base.features];
+    const limits = { ...base.limits };
+
+    // Add manually added features
+    if (overrides.addedFeatures?.length) {
+      features = [...new Set([...features, ...overrides.addedFeatures])];
+    }
+
+    // Remove manually removed features
+    if (overrides.removedFeatures?.length) {
+      const removedSet = new Set(overrides.removedFeatures);
+      features = features.filter(f => !removedSet.has(f));
+    }
+
+    // Apply limit overrides (always win)
+    if (overrides.limitOverrides) {
+      for (const [key, value] of Object.entries(overrides.limitOverrides)) {
+        limits[key] = value;
+      }
+    }
+
+    return { features, limits };
+  }
+
+  private mergeAndPruneEffectiveFeatures(
+    parentFeatures: ScopeFeatures,
+    scopeFeatures: ScopeFeatures,
+  ): ScopeFeatures {
+    return this.pruneDependencies(mergeScopeFeatures(parentFeatures, scopeFeatures));
+  }
+
+  /**
+   * Keep every resolution source honest about the shared `applicableScopes`
+   * contract so defaults, profiles, and persisted scope docs cannot leak
+   * app-only or org-only feature ids into the wrong resolution layer.
+   */
+  private filterScopeFeaturesForScope(
+    scopeFeatures: ScopeFeatures,
+    scopeType: ResourcePrimaryScope,
+  ): ScopeFeatures {
+    const filteredFeatures = scopeFeatures.features.filter(featureId =>
+      this.isDefinitionApplicableToScope(featureId, scopeType),
+    );
+    const filteredLimits = Object.fromEntries(
+      Object.entries(scopeFeatures.limits).filter(([featureId]) =>
+        this.isDefinitionApplicableToScope(featureId, scopeType),
+      ),
+    );
+
+    return {
+      features: filteredFeatures,
+      limits: filteredLimits,
+    };
+  }
+
+  private isDefinitionApplicableToScope(
+    featureId: string,
+    scopeType: ResourcePrimaryScope,
+  ): boolean {
+    const definition = this.featureRegistry.getDefinition(featureId);
+    if (!definition?.applicableScopes || definition.applicableScopes.length === 0) {
+      return true;
+    }
+    return definition.applicableScopes.includes(scopeType);
+  }
+
+  /**
+   * Step F: Prune features whose dependencies are not met.
+   * A feature is disabled if any of its dependencies is not in the enabled set.
+   *
+   * Uses iterative pruning (not single-pass) to handle transitive dependencies:
+   * If A depends on B and B depends on C, removing C must also remove B and then A.
+   * Loops until no more features are pruned (stable set).
+   */
+  private pruneDependencies(resolved: ScopeFeatures): ScopeFeatures {
+    let currentFeatures = [...resolved.features];
+    let changed = true;
+
+    while (changed) {
+      changed = false;
+      const enabledSet = new Set(currentFeatures);
+      const nextFeatures: string[] = [];
+
+      for (const featureId of currentFeatures) {
+        const def = this.featureRegistry.getDefinition(featureId);
+        if (!def || !def.dependencies || def.dependencies.length === 0) {
+          nextFeatures.push(featureId);
+          continue;
+        }
+
+        const allDepsMet = def.dependencies.every(dep => enabledSet.has(dep));
+        if (allDepsMet) {
+          nextFeatures.push(featureId);
+        } else {
+          changed = true;
+          this.logDebug('Feature pruned (unmet dependencies)', {
+            featureId,
+            missingDeps: def.dependencies.filter(d => !enabledSet.has(d)),
+          });
+        }
+      }
+
+      currentFeatures = nextFeatures;
+    }
+
+    return { features: currentFeatures, limits: resolved.limits };
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // Scope Chain Builder
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Build the scope chain to resolve based on execution type.
+   * Returns scope levels from broadest (app) to most specific (user).
+   */
+  private buildScopeChain(executionContext: ExecutionContext<any>): Array<{ scopeType: ResourcePrimaryScope; entityId: string }> {
+    const execType = executionContext.executionType;
+    const chain: Array<{ scopeType: ResourcePrimaryScope; entityId: string }> = [];
+
+    // App-level features are always the first layer
+    chain.push({
+      scopeType: ResourcePrimaryScope.APPLICATION,
+      entityId: APP_SCOPE_ENTITY_ID,
+    });
+
+    switch (execType) {
+      case ExecutionContext_ExecutionType.USER_REQUEST: {
+        // JWT: app → org → user
+        const orgId = executionContext.organizationId;
+        if (orgId) {
+          chain.push({ scopeType: ResourcePrimaryScope.ORGANIZATIONS, entityId: orgId });
+        }
+        const userId = executionContext.userId;
+        if (userId) {
+          chain.push({ scopeType: ResourcePrimaryScope.USER_SELF, entityId: userId });
+        }
+        break;
+      }
+
+      case ExecutionContext_ExecutionType.ORG_API_KEY: {
+        // Org API key: app → org (no user)
+        const orgId = executionContext.organizationId;
+        if (orgId) {
+          chain.push({ scopeType: ResourcePrimaryScope.ORGANIZATIONS, entityId: orgId });
+        } else {
+          this.logger.warn('ORG_API_KEY execution without organizationId — org features skipped');
+        }
+        break;
+      }
+
+      case ExecutionContext_ExecutionType.APP_API_KEY: {
+        // App API key: app only (no org or user)
+        break;
+      }
+
+      case ExecutionContext_ExecutionType.CONSUMABLE_TOKEN: {
+        // Consumable token: app → org (if org context available)
+        const orgId = executionContext.organizationId;
+        if (orgId) {
+          chain.push({ scopeType: ResourcePrimaryScope.ORGANIZATIONS, entityId: orgId });
+        }
+        break;
+      }
+
+      default:
+        this.logDebug('Unknown execution type for scope chain', { execType });
+    }
+
+    return chain;
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // Helpers
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Build a cache key for a scope entity.
+   * Format: `features:{scopeType}:{entityId}`
+   */
+  private buildCacheKey(scopeType: ResourcePrimaryScope, entityId: string): string {
+    return `features:${scopeType}:${entityId}`;
+  }
+
+  /**
+   * Build a ResolvedFeatures with ALL features enabled and all limits set to UNLIMITED.
+   * Used for internal/system calls that bypass feature gating.
+   */
+  private buildAllFeaturesEnabled(): ResolvedFeatures {
+    const definitions = this.featureRegistry.getAllDefinitions();
+    const features: string[] = [];
+    const limits: Record<string, number> = {};
+
+    for (const def of definitions) {
+      features.push(def.identifier);
+      if (def.valueType === FeatureValueType.LIMIT) {
+        limits[def.identifier] = FEATURES_UNLIMITED;
+      }
+    }
+
+    return { features, limits };
+  }
+
+  // NOTE: Configuration (profiles, etc.) is accessed via this.featureRegistry.getConfiguration()
+}