@wildo-ai/saas-backend-lib 1.0.1

package/src/config/services/application-startup-config-validator.backend.service.ts

@@ -0,0 +1,611 @@
+import { inject, injectable } from 'inversify';
+import {
+  AuthUtils,
+  ErrorCustomMessageReference,
+  ErrorType,
+  FlowsActors_Agent_Status,
+  type AppConfiguration_Shared_Auth,
+  type ConfigurationValidationIssue,
+  type ConfigurationValidationResult,
+  ConfigurationValidationDomain,
+  ConfigurationValidationSeverity,
+  buildValidationResult,
+  issueError,
+} from '@wildo-ai/saas-models';
+import {
+  APPLICATION_ENVIRONMENT,
+  CLIRuntime_AuthMode,
+  ExternalProvider_ExchangeProtocol_Kind,
+} from '@wildo-ai/external-connectors-models';
+import { FileStorageAccepted } from '@wildo-ai/zod-decorators';
+import { assessCLIRuntimeOperationSupport } from '~wildo-backend-lib/flows-actors/utils/cli-runtime-operation-support.backend.utils';
+import type { AppConfiguration } from '~wildo-backend-lib/config/models/app-config.backend.schemas';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { ExternalProvidersRegistryBackendService } from '~wildo-backend-lib/external-providers/services/external-providers-registry.backend.service';
+import { FlowsActorsRegistryService } from '~wildo-backend-lib/flows-actors/services/flows-actors-registry.service';
+import { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+import { FileFieldDetectionBackendService } from '~wildo-backend-lib/files/services/file-field-detection.backend.service';
+import { FileStorageRouterBackendService } from '~wildo-backend-lib/files/storage/file-storage-router.backend.service';
+import { ClamAVScannerBackendService } from '~wildo-backend-lib/files/scanning/clamav-scanner.backend.service';
+import { YaraScannerBackendService } from '~wildo-backend-lib/files/scanning/yara-scanner.backend.service';
+import { WeaviateVectorStoreBackendService } from '~wildo-backend-lib/files/rag/weaviate-vector-store.backend.service';
+
+/**
+ * Startup-only governance rules for application configuration.
+ *
+ * Two phases:
+ *
+ * 1. `validate(config)` — pre-registry checks on the raw AppConfiguration
+ *    (auth consistency, frontend service bindings, etc.)
+ *
+ * 2. `validateInitializedRuntimeContracts()` — post-registry cross-checks
+ *    that need the fully resolved registry (z_file() vs storage providers,
+ *    CLI-runtime agents, etc.). Uses the collector pattern: each validator
+ *    returns `ConfigurationValidationIssue[]`, the runner consolidates,
+ *    logs warnings, and throws on errors.
+ *
+ * Frontend will adopt the same `ConfigurationValidationIssue` contract
+ * for its own post-registry checks (feature gating, launcher coherence, etc.).
+ */
+@injectable()
+export class ApplicationStartupConfigValidatorService {
+  private logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService)
+    private readonly externalProvidersRegistry: ExternalProvidersRegistryBackendService,
+    @inject(SAAS_SERVICE_TYPES.FlowsActorsRegistryService)
+    private readonly flowsActorsRegistry: FlowsActorsRegistryService,
+    @inject(SAAS_SERVICE_TYPES.ResourceRegistryService)
+    private readonly resourcesRegistry: ResourcesRegistryBackendService,
+    @inject(SAAS_SERVICE_TYPES.FileFieldDetectionService)
+    private readonly fileFieldDetection: FileFieldDetectionBackendService,
+    @inject(SAAS_SERVICE_TYPES.FileStorageRouter)
+    private readonly fileStorageRouter: FileStorageRouterBackendService,
+    @inject(SAAS_SERVICE_TYPES.ClamAVScannerService)
+    private readonly clamavScanner: ClamAVScannerBackendService,
+    @inject(SAAS_SERVICE_TYPES.YaraScannerService)
+    private readonly yaraScanner: YaraScannerBackendService,
+    @inject(SAAS_SERVICE_TYPES.WeaviateVectorStoreService)
+    private readonly weaviateVectorStore: WeaviateVectorStoreBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('ApplicationStartupConfigValidatorService');
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Phase 1: pre-registry config checks
+  // ─────────────────────────────────────────────────────────────────────────
+
+  public validate(config: AppConfiguration): void {
+    this.assertNoRemovedGlobalAuthFields(config.auth);
+    this.validateFrontendServiceRuntimeBindings(config);
+    this.validateUserTypeAuthConsistency(config);
+    this.warnOnMultipleDefaultUserTypes(config);
+    this.warnOnDuplicateClaimedDomains(config);
+    this.warnOnBroadAutoLinkSSO(config);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Phase 2: post-registry cross-checks (collector pattern)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Run all post-registry validators, collect issues, then report.
+   *
+   * To add a new cross-check:
+   *   1. Write a private method returning `ConfigurationValidationIssue[]`
+   *   2. Add its call to the `validators` array below
+   *   3. The runner handles logging warnings and throwing on errors
+   */
+  public validateInitializedRuntimeContracts(): ConfigurationValidationResult {
+    const validators: (() => ConfigurationValidationIssue[])[] = [
+      () => this.collectStorageIssues(),
+      () => this.collectScanningIssues(),
+      () => this.collectYaraIssues(),
+      () => this.collectRAGIssues(),
+      () => this.collectCLIRuntimeAgentIssues(),
+    ];
+
+    const allIssues: ConfigurationValidationIssue[] = [];
+    for (const validator of validators) {
+      allIssues.push(...validator());
+    }
+
+    const result = buildValidationResult(allIssues);
+    this.reportValidationResult(result);
+    return result;
+  }
+
+  /**
+   * Log warnings and throw a consolidated error if any ERROR-severity
+   * issues were collected.
+   */
+  private reportValidationResult(result: ConfigurationValidationResult): void {
+    const warnings = result.issues.filter((i) => i.severity === ConfigurationValidationSeverity.WARNING);
+    const errors = result.issues.filter((i) => i.severity === ConfigurationValidationSeverity.ERROR);
+
+    for (const warning of warnings) {
+      this.logger.warn(`[${warning.domain}] ${warning.message}`, warning.context);
+    }
+
+    if (errors.length === 0) {
+      if (warnings.length > 0) {
+        this.logDebug(`Post-registry validation completed with ${warnings.length} warning(s)`);
+      }
+      return;
+    }
+
+    const errorMessages = errors.map((e) => `  [${e.domain}] ${e.message}`).join('\n');
+
+    throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+      customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+      context: {
+        message:
+          `Post-registry configuration validation failed with ${errors.length} error(s):\n` +
+          errorMessages,
+        errorCount: errors.length,
+        warningCount: warnings.length,
+        domains: [...new Set(errors.map((e) => e.domain))],
+      },
+    });
+  }
+
+  private assertNoRemovedGlobalAuthFields(auth: AppConfiguration_Shared_Auth): void {
+    const rawAuth = auth as Record<string, unknown> | undefined;
+    const removedFields = [
+      'mfaPolicy',
+      'authMethodsEnabled',
+      'autoLinkByEmail',
+      'registration',
+      'passwordPolicy',
+      'methodManagement',
+      'sessionDurationMinutes',
+      'magicLink',
+      'smsOtp',
+    ] as const;
+
+    const foundDeprecated = removedFields.filter((field) => rawAuth && field in rawAuth);
+    if (foundDeprecated.length === 0) {
+      return;
+    }
+
+    throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+      customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+      context: {
+        message:
+          `Deprecated auth config fields detected: ${foundDeprecated.join(', ')}. ` +
+          `These fields were removed in W6.8. Migrate them to userTypes[typeName].auth.* ` +
+          `(see entity-identity-config.shared.schemas.ts → UserTypeAuthPolicySchema). ` +
+          `Remove them from your auth config and configure per-user-type auth policies instead.`,
+      },
+    });
+  }
+
+  private validateUserTypeAuthConsistency(config: AppConfiguration): void {
+    const userTypes = config.userTypes ?? {};
+    const frontendServices = config.frontendServices ?? {};
+
+    for (const [typeName, typeDef] of Object.entries(userTypes)) {
+      const typeAuth = (typeDef as Record<string, any>)?.auth;
+      if (!typeAuth) {
+        continue;
+      }
+
+      if (typeAuth.mfaPolicy?.requireMFA) {
+        const secondFactorMethods = AuthUtils.getSecondFactorMethods();
+        const hasEnabled = secondFactorMethods.some((method) => !!typeAuth.authMethodsEnabled?.[method]);
+        if (!hasEnabled) {
+          throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+            customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+            context: {
+              message:
+                `Config deadlock: userTypes.${typeName}.auth.mfaPolicy.requireMFA is true ` +
+                `but no second-factor method is enabled in authMethodsEnabled. ` +
+                `Enable at least one of: ${secondFactorMethods.join(', ')}`,
+            },
+          });
+        }
+      }
+
+      const acceptableMethods = typeAuth.mfaPolicy?.acceptableMFAMethods ?? [];
+      for (const method of acceptableMethods) {
+        if (!typeAuth.authMethodsEnabled?.[method]) {
+          this.logger.warn(
+            `userTypes.${typeName}: acceptableMFAMethods includes '${method}' but it is not enabled in authMethodsEnabled`,
+          );
+        }
+      }
+
+      if (typeAuth.mfaPolicy?.requireMFA && typeAuth.mfaPolicy?.enrollmentGracePeriodDays === 0) {
+        const emailVerification = (typeAuth.registration as Record<string, any> | undefined)?.emailVerification;
+        if (emailVerification === 'deferred') {
+          this.logger.warn(
+            `userTypes.${typeName}: enrollmentGracePeriodDays=0 with emailVerification=deferred — users must enroll MFA immediately on deferred-verified accounts (valid but poor UX)`,
+          );
+        }
+      }
+
+      const registrationMode = (typeAuth.registration as Record<string, any> | undefined)?.mode;
+      if (!registrationMode) {
+        continue;
+      }
+
+      for (const [frontendServiceName, frontendServiceConfig] of Object.entries(frontendServices)) {
+        const userManagement = (frontendServiceConfig as Record<string, any>)?.usersManagement?.[typeName];
+        if (!userManagement) {
+          continue;
+        }
+
+        if (registrationMode === 'disabled' && userManagement.register) {
+          this.logger.warn(
+            `userTypes.${typeName}: registration.mode='disabled' but frontendServices.${frontendServiceName}.usersManagement.${typeName}.register=true — registration will be blocked at API level`,
+          );
+        }
+        if (registrationMode !== 'disabled' && !userManagement.register) {
+          this.logger.warn(
+            `userTypes.${typeName}: registration.mode='${registrationMode}' but frontendServices.${frontendServiceName}.usersManagement.${typeName}.register=false — registration will be blocked at frontend service level`,
+          );
+        }
+      }
+    }
+  }
+
+  private validateFrontendServiceRuntimeBindings(config: AppConfiguration): void {
+    const frontendServices = Object.entries(config.frontendServices ?? {});
+    if (frontendServices.length === 0) {
+      return;
+    }
+
+    for (const [frontendServiceName, frontendServiceConfig] of frontendServices) {
+      const runtimeEndpoint = config.runtime?.endPoints?.[frontendServiceName];
+      if (!runtimeEndpoint?.publicUrl || !runtimeEndpoint?.internalUrl) {
+        throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+          context: {
+            message:
+              `frontendServices.${frontendServiceName} is declared but runtime.endPoints.${frontendServiceName} ` +
+              `is missing a matching publicUrl/internalUrl binding. Runtime topology must materialize every declared frontend service.`,
+            frontendServiceName,
+          },
+        });
+      }
+    }
+  }
+
+  private warnOnMultipleDefaultUserTypes(config: AppConfiguration): void {
+    for (const [frontendServiceName, frontendServiceConfig] of Object.entries(config.frontendServices ?? {})) {
+      const userManagement = (frontendServiceConfig as Record<string, any>)?.usersManagement ?? {};
+      const defaultEntries = Object.entries(userManagement).filter(([, value]) => (value as Record<string, any>)?.isDefault);
+      if (defaultEntries.length > 1) {
+        this.logger.warn(
+          `frontendServices.${frontendServiceName}: multiple isDefault:true entries in usersManagement: ${defaultEntries.map(([key]) => key).join(', ')}. Only the first will be used for user-type resolution.`,
+        );
+      }
+    }
+  }
+
+  private warnOnDuplicateClaimedDomains(config: AppConfiguration): void {
+    const domainClaimMap = new Map<string, string[]>();
+
+    for (const [orgTypeName, orgTypeDef] of Object.entries(config.organizationTypes ?? {})) {
+      const claimedDomains = (orgTypeDef as Record<string, any>)?.sso?.claimedDomains as string[] | undefined;
+      if (!claimedDomains) {
+        continue;
+      }
+
+      for (const domain of claimedDomains) {
+        const normalizedDomain = domain.toLowerCase();
+        const orgTypes = domainClaimMap.get(normalizedDomain) ?? [];
+        orgTypes.push(orgTypeName);
+        domainClaimMap.set(normalizedDomain, orgTypes);
+      }
+    }
+
+    for (const [domain, orgTypeNames] of domainClaimMap.entries()) {
+      if (orgTypeNames.length > 1) {
+        this.logger.warn(
+          `E-VER-9: Domain "${domain}" is claimed by multiple organization types: ${orgTypeNames.join(', ')}. Domain-to-org resolution will be non-deterministic.`,
+        );
+      }
+    }
+  }
+
+  private warnOnBroadAutoLinkSSO(config: AppConfiguration): void {
+    const ssoProviders = config.auth?.ssoProviders ?? {};
+    const socialProvidersWithEmptyDomains = Object.entries(ssoProviders)
+      .filter(([, providerConfig]) => {
+        const typedConfig = providerConfig as Record<string, any>;
+        return typedConfig.enabled !== false && (!typedConfig.allowedDomains || typedConfig.allowedDomains.length === 0);
+      })
+      .map(([providerName]) => providerName);
+
+    if (socialProvidersWithEmptyDomains.length === 0) {
+      return;
+    }
+
+    for (const [typeName, typeDef] of Object.entries(config.userTypes ?? {})) {
+      const autoLinkByEmail = (typeDef as Record<string, any>)?.auth?.autoLinkByEmail;
+      if (autoLinkByEmail === true || autoLinkByEmail === undefined) {
+        this.logger.warn(
+          `E-VER-11: userTypes.${typeName}.auth.autoLinkByEmail is true (or defaulted) and SSO providers [${socialProvidersWithEmptyDomains.join(', ')}] have empty allowedDomains. Any verified email from these IdPs can auto-link to existing accounts.`,
+        );
+      }
+    }
+  }
+
+  // ─── Storage ────────────────────────────────────────────────────────────
+
+  private collectStorageIssues(): ConfigurationValidationIssue[] {
+    const allResourceTypes = this.resourcesRegistry.getResourceTypes();
+    if (allResourceTypes.length === 0) {
+      return [];
+    }
+
+    const envHints: Record<string, string> = {
+      [FileStorageAccepted.WILDO_MANAGED]: 'STORAGE_ENDPOINT, STORAGE_ACCESS_KEY, STORAGE_SECRET_KEY',
+      [FileStorageAccepted.LOCAL_DIRECTORY]: 'STORAGE_LOCAL_BASE_DIR',
+    };
+
+    const issues: ConfigurationValidationIssue[] = [];
+
+    for (const resourceType of allResourceTypes) {
+      let fileFields;
+      try {
+        fileFields = this.fileFieldDetection.detectFileFields(resourceType);
+      } catch {
+        continue;
+      }
+
+      for (const field of fileFields) {
+        const accepted = field.fileMetadata.storageAccepted;
+        const fieldRef = `${resourceType}.${field.fieldName}`;
+
+        if (!accepted || accepted.length === 0) {
+          const provider = this.fileStorageRouter.getProviderById(FileStorageAccepted.WILDO_MANAGED);
+          if (!provider || !provider.isConfigured()) {
+            const hint = envHints[FileStorageAccepted.WILDO_MANAGED];
+            issues.push(issueError(
+              ConfigurationValidationDomain.STORAGE,
+              `${fieldRef}: no storageAccepted specified and default WILDO_MANAGED is not configured — set ${hint}`,
+              { fieldRef, storageAccepted: [FileStorageAccepted.WILDO_MANAGED] },
+            ));
+          }
+        } else {
+          const hasSatisfied = accepted.some((provId) => {
+            const p = this.fileStorageRouter.getProviderById(provId);
+            return p?.isConfigured() ?? false;
+          });
+          if (!hasSatisfied) {
+            const hints = accepted.map((p) => envHints[p] ?? p).join(' or ');
+            issues.push(issueError(
+              ConfigurationValidationDomain.STORAGE,
+              `${fieldRef}: accepts [${accepted.join(', ')}] but none are configured — set ${hints}`,
+              { fieldRef, storageAccepted: [...accepted] },
+            ));
+          }
+        }
+      }
+    }
+
+    return issues;
+  }
+
+  // ─── Scanning (ClamAV) ──────────────────────────────────────────────────
+
+  private collectScanningIssues(): ConfigurationValidationIssue[] {
+    const issues: ConfigurationValidationIssue[] = [];
+    const allResourceTypes = this.resourcesRegistry.getResourceTypes();
+    const fieldsRequiringScan: string[] = [];
+
+    for (const resourceType of allResourceTypes) {
+      let fileFields;
+      try {
+        fileFields = this.fileFieldDetection.detectFileFields(resourceType);
+      } catch {
+        continue;
+      }
+
+      for (const field of fileFields) {
+        if (field.fileMetadata.scanPolicy === 'required') {
+          fieldsRequiringScan.push(`${resourceType}.${field.fieldName}`);
+        }
+      }
+    }
+
+    if (fieldsRequiringScan.length === 0) {
+      return issues;
+    }
+
+    if (!this.clamavScanner.isConfigured()) {
+      issues.push(issueError(
+        ConfigurationValidationDomain.STORAGE,
+        `${fieldsRequiringScan.length} z_file() field(s) declare scanPolicy: 'required' but ClamAV is not configured — set CLAMAV_HOST and CLAMAV_PORT`,
+        { fields: fieldsRequiringScan, hint: 'Set CLAMAV_HOST env var or remove scanPolicy from z_file() declarations' },
+      ));
+    }
+
+    return issues;
+  }
+
+  // ─── YARA (platform-level pattern scanning) ─────────────────────────
+
+  private collectYaraIssues(): ConfigurationValidationIssue[] {
+    const issues: ConfigurationValidationIssue[] = [];
+
+    if (!this.yaraScanner.isExplicitlyEnabled()) return issues;
+
+    if (!this.yaraScanner.isConfigured()) {
+      issues.push(issueError(
+        ConfigurationValidationDomain.STORAGE,
+        'YARA_ENABLED is true but YARA_HOST is not set — the YARA scanner service is unreachable',
+        { hint: 'Set YARA_HOST to the YARA scanner Docker service hostname (e.g., yara-scanner)' },
+      ));
+    }
+
+    return issues;
+  }
+
+  // ─── RAG (Weaviate) ────────────────────────────────────────────────────
+
+  private collectRAGIssues(): ConfigurationValidationIssue[] {
+    const issues: ConfigurationValidationIssue[] = [];
+    const allResourceTypes = this.resourcesRegistry.getResourceTypes();
+    const fieldsRequiringRAG: string[] = [];
+
+    for (const resourceType of allResourceTypes) {
+      let fileFields;
+      try {
+        fileFields = this.fileFieldDetection.detectFileFields(resourceType);
+      } catch {
+        continue;
+      }
+
+      for (const field of fileFields) {
+        if (field.fileMetadata.rag?.enabled === true) {
+          fieldsRequiringRAG.push(`${resourceType}.${field.fieldName}`);
+        }
+      }
+    }
+
+    if (fieldsRequiringRAG.length === 0) {
+      return issues;
+    }
+
+    if (!this.weaviateVectorStore.isConfigured()) {
+      issues.push(issueError(
+        ConfigurationValidationDomain.STORAGE,
+        `${fieldsRequiringRAG.length} z_file() field(s) declare rag.enabled but Weaviate is not configured — set WEAVIATE_HOST`,
+        { fields: fieldsRequiringRAG, hint: 'Set WEAVIATE_HOST env var or remove rag.enabled from z_file() declarations' },
+      ));
+    }
+
+    return issues;
+  }
+
+  // ─── CLI Runtime Agents ─────────────────────────────────────────────────
+
+  private collectCLIRuntimeAgentIssues(): ConfigurationValidationIssue[] {
+    const applicationEnv = (process.env.APPLICATION_ENV ?? APPLICATION_ENVIRONMENT.DEVELOPMENT) as APPLICATION_ENVIRONMENT;
+    const platformEnvironmentId = process.env.PLATFORM_ENVIRONMENT_ID;
+    const agents = Object.values(this.flowsActorsRegistry.getRegistry().agents);
+    const issues: ConfigurationValidationIssue[] = [];
+
+    for (const agent of agents) {
+      if (
+        agent.status !== FlowsActors_Agent_Status.ACTIVE
+        || !agent.config.executionProfileRef
+      ) {
+        continue;
+      }
+
+      const providerRef = agent.config.providerRef;
+      const executionProfileRef = agent.config.executionProfileRef;
+      const operationKey = agent.config.operationKey;
+      const model = agent.config.model;
+      const agentCtx = { agentRef: agent.ref, providerRef, executionProfileRef };
+
+      if (!this.externalProvidersRegistry.isProviderEnabled(providerRef, ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER)) {
+        issues.push(issueError(
+          ConfigurationValidationDomain.AGENTS,
+          `Agent '${agent.ref}': provider '${providerRef}' has no enabled semantic LLM protocol`,
+          agentCtx,
+        ));
+        continue;
+      }
+
+      const llmProtocol = this.externalProvidersRegistry.getCachedProtocol(
+        providerRef,
+        ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER,
+      );
+      if (!llmProtocol || !('operations' in llmProtocol) || !llmProtocol.operations[operationKey]) {
+        issues.push(issueError(
+          ConfigurationValidationDomain.AGENTS,
+          `Agent '${agent.ref}': LLM operation '${operationKey}' not available on provider '${providerRef}'`,
+          { ...agentCtx, operationKey },
+        ));
+        continue;
+      }
+
+      if (!this.externalProvidersRegistry.isProviderEnabled(providerRef, ExternalProvider_ExchangeProtocol_Kind.CLI_RUNTIME)) {
+        issues.push(issueError(
+          ConfigurationValidationDomain.AGENTS,
+          `Agent '${agent.ref}': provider '${providerRef}' has no enabled CLI runtime transport`,
+          agentCtx,
+        ));
+        continue;
+      }
+
+      const cliRuntimeProfile = this.externalProvidersRegistry.getCachedCLIRuntimeProfile(providerRef);
+      const cliExecutionProfile = this.externalProvidersRegistry.getCLIRuntimeExecutionProfile(
+        providerRef,
+        executionProfileRef,
+      );
+
+      if (!cliRuntimeProfile || !cliExecutionProfile) {
+        issues.push(issueError(
+          ConfigurationValidationDomain.AGENTS,
+          `Agent '${agent.ref}': CLI runtime metadata or execution profile '${executionProfileRef}' not found`,
+          agentCtx,
+        ));
+        continue;
+      }
+
+      const operationSupport = assessCLIRuntimeOperationSupport(
+        cliRuntimeProfile,
+        cliExecutionProfile,
+        operationKey,
+      );
+      if (!operationSupport.supported) {
+        issues.push(issueError(
+          ConfigurationValidationDomain.AGENTS,
+          `Agent '${agent.ref}': ${operationSupport.message ?? `operation '${operationKey}' not supported by CLI runtime`}`,
+          { ...agentCtx, operationKey, supportedOperationKeys: cliRuntimeProfile.supportedOperationKeys },
+        ));
+      }
+
+      if (!cliRuntimeProfile.supportedModels.includes(model)) {
+        issues.push(issueError(
+          ConfigurationValidationDomain.AGENTS,
+          `Agent '${agent.ref}': model '${model}' not declared by CLI runtime profile (supported: ${cliRuntimeProfile.supportedModels.join(', ')})`,
+          { ...agentCtx, model, supportedModels: cliRuntimeProfile.supportedModels },
+        ));
+      }
+
+      if (!cliExecutionProfile.allowedApplicationEnvironments.includes(applicationEnv)) {
+        issues.push(issueError(
+          ConfigurationValidationDomain.AGENTS,
+          `Agent '${agent.ref}': not allowed in application environment '${applicationEnv}'`,
+          { ...agentCtx, applicationEnv, allowedApplicationEnvironments: cliExecutionProfile.allowedApplicationEnvironments },
+        ));
+      }
+
+      if (
+        cliExecutionProfile.allowedPlatformEnvironmentIds?.length
+        && (!platformEnvironmentId || !cliExecutionProfile.allowedPlatformEnvironmentIds.includes(platformEnvironmentId))
+      ) {
+        issues.push(issueError(
+          ConfigurationValidationDomain.AGENTS,
+          `Agent '${agent.ref}': not allowed in platform environment '${platformEnvironmentId ?? '(unset)'}'`,
+          { ...agentCtx, platformEnvironmentId, allowedPlatformEnvironmentIds: cliExecutionProfile.allowedPlatformEnvironmentIds },
+        ));
+      }
+
+      if (
+        cliExecutionProfile.authMode === CLIRuntime_AuthMode.SECRET_REF_ENV_INJECTION
+        && !this.externalProvidersRegistry.getCLIRuntimeExecutionProfileSecret(providerRef, executionProfileRef)
+      ) {
+        issues.push(issueError(
+          ConfigurationValidationDomain.AGENTS,
+          `Agent '${agent.ref}': CLI runtime secret '${cliExecutionProfile.secretRef}' could not be resolved at startup`,
+          { ...agentCtx, secretRef: cliExecutionProfile.secretRef },
+        ));
+      }
+    }
+
+    return issues;
+  }
+}