@aifabrix/builder 2.45.0 → 2.46.0

package/lib/deployment/environment-poll-status.js

@@ -0,0 +1,138 @@
+/**
+ * Poll helpers for environment deploy status (deployment-by-ID).
+ *
+ * @fileoverview Parse pipeline/environments deployment poll responses and fail fast on terminal HTTP errors
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const TERMINAL_POLL_HTTP_STATUSES = new Set([400, 401, 403, 404, 410, 422]);
+
+/**
+ * @param {Object|null|undefined} response - API client response
+ * @returns {boolean}
+ */
+function isTerminalPollApiResponse(response) {
+  return Boolean(
+    response &&
+    response.success === false &&
+    typeof response.status === 'number' &&
+    TERMINAL_POLL_HTTP_STATUSES.has(response.status)
+  );
+}
+
+/**
+ * @param {Object|null|undefined} response - Successful API client response
+ * @returns {Object|null} Deployment record or null
+ */
+function extractDeploymentRecord(response) {
+  if (!response || response.success === false) {
+    return null;
+  }
+  if (response?.data?.data) {
+    return response.data.data;
+  }
+  if (response?.data && typeof response.data === 'object' && response.data.status) {
+    return response.data;
+  }
+  return null;
+}
+
+/**
+ * @param {Object|null|undefined} pipelineRes
+ * @param {Object|null|undefined} envRes
+ * @returns {Error}
+ */
+/**
+ * @param {string} requestedEnvKey
+ * @param {Error} error
+ * @returns {Error}
+ */
+function enrichPollTerminalError(requestedEnvKey, error) {
+  if (!error?.pollTerminal || error.status !== 404) {
+    return error;
+  }
+  const base = error.message || '';
+  if (!base.includes('Environment with key')) {
+    return error;
+  }
+  error.message =
+    `${base}\n\n` +
+    'The deployment may have been created under a different environment key ' +
+    '(for example evaluation-mode fallback to miso). Check controller logs for ' +
+    `effectiveEnvironmentKey, register '${requestedEnvKey}' in the controller, or run ` +
+    'aifabrix env deploy miso.';
+  return error;
+}
+
+function buildPollStatusError(pipelineRes, envRes) {
+  const terminal = [pipelineRes, envRes].filter(isTerminalPollApiResponse);
+  const source = terminal[0] || pipelineRes || envRes;
+  const message = source?.formattedError || source?.error || 'Unable to retrieve deployment status';
+  const err = new Error(message);
+  err.pollTerminal = true;
+  if (typeof source?.status === 'number') {
+    err.status = source.status;
+  }
+  return err;
+}
+
+/**
+ * Fetches deployment status by ID (pipeline endpoint first, then environments).
+ *
+ * @async
+ * @param {Function} getPipelineDeployment - pipeline.api getPipelineDeployment
+ * @param {Function} getDeployment - deployments.api getDeployment
+ * @param {string} controllerUrl
+ * @param {string} envKey
+ * @param {string} deploymentId
+ * @param {Object} apiAuthConfig
+ * @returns {Promise<Object|null>} Deployment record or null when status is not yet available (retry)
+ * @throws {Error} When both endpoints return a terminal HTTP error (e.g. environment not found)
+ */
+async function fetchDeploymentStatusById(
+  getPipelineDeployment,
+  getDeployment,
+  controllerUrl,
+  envKey,
+  deploymentId,
+  apiAuthConfig
+) {
+  let pipelineRes;
+  let envRes;
+
+  try {
+    pipelineRes = await getPipelineDeployment(controllerUrl, envKey, deploymentId, apiAuthConfig);
+    const fromPipeline = extractDeploymentRecord(pipelineRes);
+    if (fromPipeline) {
+      return fromPipeline;
+    }
+  } catch (err) {
+    pipelineRes = { success: false, error: err?.message || String(err) };
+  }
+
+  try {
+    envRes = await getDeployment(controllerUrl, envKey, deploymentId, apiAuthConfig);
+    const fromEnv = extractDeploymentRecord(envRes);
+    if (fromEnv) {
+      return fromEnv;
+    }
+  } catch (err) {
+    envRes = { success: false, error: err?.message || String(err) };
+  }
+
+  if (isTerminalPollApiResponse(pipelineRes) || isTerminalPollApiResponse(envRes)) {
+    throw buildPollStatusError(pipelineRes, envRes);
+  }
+
+  return null;
+}
+
+module.exports = {
+  TERMINAL_POLL_HTTP_STATUSES,
+  isTerminalPollApiResponse,
+  extractDeploymentRecord,
+  enrichPollTerminalError,
+  buildPollStatusError,
+  fetchDeploymentStatusById
+};

package/lib/deployment/environment.js

@@ -25,6 +25,7 @@ const {
   buildEnvironmentConfigFromPreset,
   loadAndValidateEnvironmentDeployConfig
 } = require('./environment-config');
+const { fetchDeploymentStatusById, enrichPollTerminalError } = require('./environment-poll-status');
 
 /**
  * Validates environment deployment prerequisites
@@ -161,31 +162,24 @@ async function sendEnvironmentDeployment(controllerUrl, envKey, authConfig, opti
 }
 
 /**
- * Fetches deployment status by ID (pipeline endpoint first, then environments)
- * Mirrors miso-controller manual test: GET pipeline/deployments/:id then GET environments/deployments/:id
+ * Fetches deployment status by ID (pipeline endpoint first, then environments).
  * @async
  * @param {string} controllerUrl - Controller URL
  * @param {string} envKey - Environment key
  * @param {string} deploymentId - Deployment ID
  * @param {Object} apiAuthConfig - Auth config { type: 'bearer', token }
- * @returns {Promise<Object|null>} Deployment record (status, progress, etc.) or null
+ * @returns {Promise<Object|null>} Deployment record or null when still in progress
+ * @throws {Error} On terminal poll errors (e.g. environment or deployment not found)
  */
 async function getDeploymentStatusById(controllerUrl, envKey, deploymentId, apiAuthConfig) {
-  try {
-    const pipelineRes = await getPipelineDeployment(controllerUrl, envKey, deploymentId, apiAuthConfig);
-    if (pipelineRes?.data?.data) return pipelineRes.data.data;
-    if (pipelineRes?.data && typeof pipelineRes.data === 'object' && pipelineRes.data.status) return pipelineRes.data;
-  } catch {
-    // Fallback to environments endpoint
-  }
-  try {
-    const envRes = await getDeployment(controllerUrl, envKey, deploymentId, apiAuthConfig);
-    if (envRes?.data?.data) return envRes.data.data;
-    if (envRes?.data && typeof envRes.data === 'object' && envRes.data.status) return envRes.data;
-  } catch {
-    // Ignore
-  }
-  return null;
+  return fetchDeploymentStatusById(
+    getPipelineDeployment,
+    getDeployment,
+    controllerUrl,
+    envKey,
+    deploymentId,
+    apiAuthConfig
+  );
 }
 
 /**
@@ -218,6 +212,33 @@ function processDeploymentStatusResponse(deployment, validatedEnvKey) {
   return null;
 }
 
+/**
+ * @param {number} attempt
+ * @param {number} maxAttempts
+ * @param {Object|null} deployment
+ */
+function logPollAttemptProgress(attempt, maxAttempts, deployment) {
+  const progress = deployment?.progress ?? 0;
+  const statusLabel = deployment?.status ?? 'pending';
+  logger.log(chalk.gray(`   Attempt ${attempt}/${maxAttempts}... Status: ${statusLabel} (${progress}%)`));
+}
+
+/**
+ * @param {Error} error
+ * @param {string} validatedEnvKey
+ * @throws {Error}
+ */
+function handlePollIterationError(error, validatedEnvKey) {
+  const msg = error?.message || '';
+  const isDeploymentFailed =
+    msg.includes('Environment deployment failed') ||
+    (msg.includes('failed') && !error.pollTerminal);
+  if (error.pollTerminal || isDeploymentFailed) {
+    throw enrichPollTerminalError(validatedEnvKey, error);
+  }
+  logger.log(chalk.yellow(`   ⚠ Status check failed (will retry): ${msg}`));
+}
+
 /**
  * Polls environment deployment status
  * @async
@@ -231,44 +252,31 @@ function processDeploymentStatusResponse(deployment, validatedEnvKey) {
 async function pollEnvironmentStatus(deploymentId, controllerUrl, envKey, authConfig, options = {}) {
   const validatedUrl = validateControllerUrl(controllerUrl);
   const validatedEnvKey = validateEnvironmentKey(envKey);
-
   const pollInterval = options.pollInterval || 5000;
   const maxAttempts = options.maxAttempts || 60;
+  const apiAuthConfig = { type: 'bearer', token: authConfig.token };
 
   logger.log(chalk.blue(`⏳ Polling environment status (${pollInterval}ms intervals)...`));
 
-  // Use centralized API client
-  const apiAuthConfig = { type: 'bearer', token: authConfig.token };
-
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     try {
       await new Promise(resolve => setTimeout(resolve, pollInterval));
-
       const deployment = await getDeploymentStatusById(
         validatedUrl,
         validatedEnvKey,
         deploymentId,
         apiAuthConfig
       );
-      const progress = deployment?.progress ?? 0;
-      const statusLabel = deployment?.status ?? 'pending';
-      if (attempt <= maxAttempts) {
-        logger.log(chalk.gray(`   Attempt ${attempt}/${maxAttempts}... Status: ${statusLabel} (${progress}%)`));
-      }
+      logPollAttemptProgress(attempt, maxAttempts, deployment);
       const statusResult = processDeploymentStatusResponse(deployment, validatedEnvKey);
       if (statusResult) {
         return statusResult;
       }
     } catch (error) {
-      // If it's a terminal error (not a timeout), throw it
-      if (error.message && error.message.includes('failed')) {
-        throw error;
-      }
-      // Otherwise, continue polling
+      handlePollIterationError(error, validatedEnvKey);
     }
   }
 
-  // Timeout
   throw new Error(`Environment deployment timeout after ${maxAttempts} attempts. Check controller logs for status.`);
 }
 

package/lib/external-system/download.js

@@ -437,30 +437,24 @@ function logDownloadCommandHeader(systemKey) {
 }
 
 /**
- * Downloads external system from dataplane to local development structure
+ * Downloads external system from dataplane to local development structure.
  * @async
- * @function downloadExternalSystem
- * @param {string} systemKey - System key or ID
- * @param {Object} options - Download options
- * @param {string} [options.format] - Output format: 'yaml' (default) or 'json' (runs convert after split)
- * @param {string} [options.environment] - Environment (dev, tst, pro)
- * @param {string} [options.controller] - Controller URL
- * @param {boolean} [options.dryRun] - Show what would be downloaded without actually downloading
- * @param {boolean} [options.force] - Overwrite existing README.md without prompting
- * @returns {Promise<void>} Resolves when download completes
- * @throws {Error} If download fails
+ * @param {string} systemKey
+ * @param {Object} [options]
+ * @returns {Promise<void>}
  */
 async function downloadExternalSystem(systemKey, options = {}) {
   validateSystemKeyFormat(systemKey);
-
   const format = (options.format || 'yaml').toLowerCase();
 
   try {
     logDownloadCommandHeader(systemKey);
-
     const config = await getConfig();
-    const { authConfig, dataplaneUrl } = await setupAuthenticationAndDataplane(systemKey, options, config);
-
+    const { authConfig, dataplaneUrl } = await setupAuthenticationAndDataplane(
+      systemKey,
+      options,
+      config
+    );
     if (options.dryRun) {
       handleDryRun(systemKey, dataplaneUrl);
       return;
@@ -468,15 +462,22 @@ async function downloadExternalSystem(systemKey, options = {}) {
 
     const manifest = await downloadFullManifest(dataplaneUrl, systemKey, authConfig);
     validateAndLogDownloadedData(manifest.application, manifest.dataSources);
-
     const finalPath = getIntegrationPath(systemKey);
-    const splitOptions = await resolveDownloadSplitOptions(finalPath, options);
-    await processDownloadedSystem(systemKey, manifest, splitOptions);
-
+    await processDownloadedSystem(
+      systemKey,
+      manifest,
+      await resolveDownloadSplitOptions(finalPath, options)
+    );
+    const { downloadGovernanceScenarioPacksFromManifest } = require('../lifecycle/scenario-upload');
+    await downloadGovernanceScenarioPacksFromManifest(
+      systemKey,
+      manifest,
+      dataplaneUrl,
+      authConfig
+    );
     if (format === 'json') {
       await runConvertToJsonIfRequested(systemKey);
     }
-
     displayDownloadSuccess(systemKey, finalPath, manifest.dataSources.length);
   } catch (error) {
     throw new Error(`Failed to download external system: ${error.message}`);

package/lib/external-system/generator.js

@@ -26,7 +26,7 @@ handlebars.registerHelper('json', (obj) => JSON.stringify(obj));
  * Build authentication object per schema authenticationVariablesByMethod.
  * Security values use canonical kv://<systemKey>/<segment> paths (segment from getKvPathSegmentForSecurityKey).
  * @param {string} systemKey - External system key
- * @param {string} authType - Auth method (oauth2, aad, apikey, basic, queryParam, oidc, hmac, none)
+ * @param {string} authType - Auth method (oauth2, aad, apikey, bearerToken, basic, queryParam, oidc, hmac, none)
  * @returns {{ method: string, variables: Object, security: Object }} Authentication object
  */
 function buildAuthenticationFromMethod(systemKey, authType) {
@@ -50,6 +50,10 @@ function buildAuthenticationFromMethod(systemKey, authType) {
       variables: { baseUrl: base, headerName: 'X-API-Key' },
       security: { apiKey: kvPath('apiKey') }
     },
+    bearerToken: {
+      variables: { baseUrl: base, headerName: 'Authorization', prefix: 'Bearer' },
+      security: { token: kvPath('token') }
+    },
     basic: {
       variables: { baseUrl: base },
       security: { username: kvPath('username'), password: kvPath('password') }

package/lib/external-system/integration-auth-context.js

@@ -0,0 +1,45 @@
+/**
+ * Reuse dataplane auth resolved during sync/upload across verify and test commands.
+ *
+ * @fileoverview Integration auth context helpers
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { setupIntegrationTestAuth } = require('./test-auth');
+const { getConfig } = require('../core/config');
+
+/**
+ * @param {Object} options
+ * @returns {Object}
+ */
+function integrationAuthOptions(options) {
+  const base = {
+    environment: options.env,
+    silentResolve: options.silentResolve === true
+  };
+  if (options.authConfig && options.dataplaneUrl) {
+    return { ...base, authConfig: options.authConfig, dataplaneUrl: options.dataplaneUrl };
+  }
+  return base;
+}
+
+/**
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<{ authConfig: Object, dataplaneUrl: string }>}
+ */
+async function resolveIntegrationAuth(systemKey, options) {
+  if (options.authConfig && options.dataplaneUrl) {
+    return { authConfig: options.authConfig, dataplaneUrl: options.dataplaneUrl };
+  }
+  const configObj = await getConfig();
+  return setupIntegrationTestAuth(systemKey, integrationAuthOptions(options), configObj);
+}
+
+module.exports = {
+  integrationAuthOptions,
+  resolveIntegrationAuth
+};

package/lib/external-system/test-auth.js

@@ -26,9 +26,14 @@ const { resolveControllerUrl } = require('../utils/controller-url');
  * @throws {Error} If authentication fails
  */
 async function setupIntegrationTestAuth(appName, options, _config) {
+  const opts = options && typeof options === 'object' ? options : {};
+  if (opts.authConfig && opts.dataplaneUrl) {
+    return { authConfig: opts.authConfig, dataplaneUrl: opts.dataplaneUrl };
+  }
+
   const { resolveEnvironment } = require('../core/config');
-  const environment = (options && options.environment && typeof options.environment === 'string' && options.environment.trim())
-    ? options.environment.trim()
+  const environment = (opts.environment && typeof opts.environment === 'string' && opts.environment.trim())
+    ? opts.environment.trim()
     : await resolveEnvironment();
   const controllerUrl = await resolveControllerUrl();
   const authConfig = await getDeploymentAuth(controllerUrl, environment, appName);
@@ -38,10 +43,12 @@ async function setupIntegrationTestAuth(appName, options, _config) {
   }
 
   let dataplaneUrl;
-  if (options && options.dataplane && typeof options.dataplane === 'string' && options.dataplane.trim()) {
-    dataplaneUrl = options.dataplane.trim();
+  if (opts.dataplane && typeof opts.dataplane === 'string' && opts.dataplane.trim()) {
+    dataplaneUrl = opts.dataplane.trim();
   } else {
-    dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig);
+    dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig, {
+      silent: opts.silentResolve === true
+    });
   }
 
   return { authConfig, dataplaneUrl };

package/lib/external-system/test-system-level.js

@@ -16,7 +16,7 @@ const { getIntegrationPath } = require('../utils/paths');
 const { runUnifiedDatasourceValidation } = require('../datasource/unified-validation-run');
 
 async function runOneDatasourceKey(appName, datasourceKey, opts) {
-  const { environment, runType, debug, timeoutMs } = opts;
+  const { environment, runType, debug, timeoutMs, authConfig, dataplaneUrl } = opts;
   try {
     const uni = await runUnifiedDatasourceValidation(datasourceKey, {
       app: appName,
@@ -26,7 +26,9 @@ async function runOneDatasourceKey(appName, datasourceKey, opts) {
       verbose: false,
       timeout: timeoutMs,
       async: true,
-      noAsync: false
+      noAsync: false,
+      authConfig,
+      dataplaneUrl
     });
 
     if (uni.apiError) {
@@ -89,7 +91,17 @@ async function maybeWriteSystemRunLog(appName, systemKey, datasourceKeys, runTyp
  * @param {number} [params.timeout] - Request timeout
  * @returns {Promise<{success: boolean, datasourceResults: Object[]}>}
  */
-async function runSystemLevelTest({ appName, systemKey, datasourceKeys, environment, runType, debug, timeout }) {
+async function runSystemLevelTest({
+  appName,
+  systemKey,
+  datasourceKeys,
+  environment,
+  runType,
+  debug,
+  timeout,
+  authConfig,
+  dataplaneUrl
+}) {
   if (!Array.isArray(datasourceKeys) || datasourceKeys.length === 0) {
     return { success: true, datasourceResults: [] };
   }
@@ -100,7 +112,16 @@ async function runSystemLevelTest({ appName, systemKey, datasourceKeys, environm
     // Keep sequential to avoid spiking external APIs / dataplane concurrency in CLI runs.
     // (Plan allows parallel later, but UX needs stable logs first.)
     // eslint-disable-next-line no-await-in-loop -- intentional sequential execution
-    results.push(await runOneDatasourceKey(appName, key, { environment, runType, debug, timeoutMs }));
+    results.push(
+      await runOneDatasourceKey(appName, key, {
+        environment,
+        runType,
+        debug,
+        timeoutMs,
+        authConfig,
+        dataplaneUrl
+      })
+    );
   }
 
   const success = results.every(r => r.success);

package/lib/external-system/test.js

@@ -38,6 +38,7 @@ const {
 } = require('./test-execution');
 const { runSystemLevelTest } = require('./test-system-level');
 const { shouldUseSystemLevelIntegrationCall } = require('./integration-test-dispatch');
+const { cliOptsSkipSync } = require('../utils/cli-sync-options');
 
 /**
  * Loads and parses application config file
@@ -412,7 +413,8 @@ function determineDatasourcesToTest(datasourceFiles, datasourceFilter) {
  * @param {string} [options.controller] - Controller URL
  * @param {boolean} [options.verbose] - Show detailed test output
  * @param {number} [options.timeout] - Request timeout in milliseconds
- * @param {boolean} [options.sync] - When true, run full `aifabrix upload`-equivalent publish before tests
+ * @param {boolean} [options.noSync] - When true, skip publish (exercise dataplane config already deployed)
+ * @param {boolean} [options.sync] - Legacy explicit sync; ignored when `noSync` / `--no-sync` is set
  * @returns {Promise<Object>} Integration test results
  * @throws {Error} If testing fails
  */
@@ -457,13 +459,11 @@ async function testExternalSystemIntegration(appName, options = {}) {
 
     const { systemKey, authConfig, dataplaneUrl, datasourcesToTest, customPayload } = await prepareIntegrationTestEnvironment(appName, options);
 
-    if (options.sync === true) {
+    if (!cliOptsSkipSync(options)) {
       logger.log(chalk.cyan('Syncing local config to dataplane…'));
       const { uploadExternalSystem } = require('../commands/upload');
-      await uploadExternalSystem(systemKey, {
-        verbose: !!options.verbose,
-        minimal: true
-      });
+      const { buildMinimalUploadSyncOptions } = require('../utils/upload-sync-options');
+      await uploadExternalSystem(systemKey, buildMinimalUploadSyncOptions(options));
       logger.log(formatSuccessLine('Sync complete'));
     }
 
@@ -486,7 +486,9 @@ async function testExternalSystemIntegration(appName, options = {}) {
           environment: options.environment,
           runType: 'integration',
           debug: options.debug,
-          timeout
+          timeout,
+          authConfig,
+          dataplaneUrl
         });
         results.success = systemResult.success;
         results.datasourceResults = systemResult.datasourceResults;

package/lib/generator/external-controller-manifest.js

@@ -22,6 +22,19 @@ const { loadVariables, loadRbac } = require('./helpers');
  * @param {Object} systemJson - System JSON object
  * @param {Object|null} rbac - RBAC configuration
  */
+/**
+ * Maps legacy integration auth method names to schema 1.3.0 values before upload/deploy.
+ * @param {Object} systemJson - System JSON object (mutated in place)
+ */
+function normalizeLegacyAuthMethod(systemJson) {
+  const auth = systemJson && systemJson.authentication;
+  if (!auth || typeof auth !== 'object') return;
+  const method = String(auth.method || '').trim().toLowerCase();
+  if (method === 'bearerkey') {
+    auth.method = 'bearerToken';
+  }
+}
+
 function mergeRbacIntoSystemJson(systemJson, rbac) {
   if (!rbac) {
     return;
@@ -78,6 +91,7 @@ function extractAppMetadata(variables, appName) {
  */
 async function loadSystemWithRbac(appPath, schemaBasePath, systemFile) {
   const systemJson = await loadSystemFile(appPath, schemaBasePath, systemFile);
+  normalizeLegacyAuthMethod(systemJson);
   const rbacPath = resolveRbacPath(appPath);
   const rbac = rbacPath ? loadRbac(rbacPath) : null;
   mergeRbacIntoSystemJson(systemJson, rbac);
@@ -187,6 +201,7 @@ function toDeployJsonShape(manifest) {
 }
 
 module.exports = {
+  normalizeLegacyAuthMethod,
   generateControllerManifest,
   toDeployJsonShape
 };

package/lib/governance/governance-cli-errors.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Governance CLI error messages (424.0).
+ */
+
+'use strict';
+
+/**
+ * @param {Error|string} err
+ * @returns {boolean}
+ */
+function isGovernancePackNotFoundError(err) {
+  const raw = (err && err.message) || String(err);
+  return /not found/i.test(raw) || /\b404\b/.test(raw);
+}
+
+/**
+ * @param {Error|string} err
+ * @returns {boolean}
+ */
+function isGovernanceCoverageSchemaError(err) {
+  const raw = (err && err.message) || String(err);
+  return (
+    raw.includes('\'coverage\' is a required property') || /spec\.coverage/i.test(raw)
+  );
+}
+
+/**
+ * Short, non-duplicative CLI message from a dataplane governance API error.
+ * @param {Error|string} err
+ * @returns {string}
+ */
+function shortGovernanceApiError(err) {
+  const raw = ((err && err.message) || String(err)).trim();
+  if (isGovernancePackNotFoundError(err)) {
+    return 'No active pack on dataplane';
+  }
+  if (isGovernanceCoverageSchemaError(err)) {
+    return 'Pack missing spec.coverage (424.0 schema)';
+  }
+  const firstLine = raw.split('\n').find(line => line.trim()) || raw;
+  if (/^Governance scenario pack not found/i.test(firstLine)) {
+    return 'No active pack on dataplane';
+  }
+  return firstLine.length > 100 ? `${firstLine.slice(0, 97)}...` : firstLine;
+}
+
+/**
+ * User-facing hint after a failed governance pack upload (validation).
+ * @param {string} systemKey
+ * @returns {string}
+ */
+function governanceUploadSchemaHint(systemKey) {
+  return (
+    'Scenario pack does not meet the 424.0 schema. Use dataplane-first generation:\n' +
+    `  aifabrix governance generate ${systemKey} --subject-email <email>\n` +
+    'Or: aifabrix verify-governance ' +
+    `${systemKey} --subject-email <email>`
+  );
+}
+
+/**
+ * Clarify subject-resolution 400s (dataplane reachable; User row missing).
+ * @param {Error} err
+ * @param {{ subjectEmails?: string[] }} [context]
+ * @returns {Error}
+ */
+function enrichUnresolvableGovernanceSubjectsError(err, context = {}) {
+  const hay = `${err.message || ''} ${err.formatted || ''}`;
+  if (!hay.includes('No resolvable subjects')) {
+    return err;
+  }
+  const emails = Array.isArray(context.subjectEmails)
+    ? context.subjectEmails.filter(Boolean)
+    : [];
+  const lines = [
+    '',
+    'The dataplane is reachable. This is not a network or controller error.',
+    'Pack generation needs --subject-email values that match existing dataplane User rows.',
+    emails.length > 0 ? `Subject email(s) you passed: ${emails.join(', ')}` : null,
+    'Check:',
+    '  aifabrix identity user list --search <email>',
+    'If the user is missing, apply your identity CSV first:',
+    '  aifabrix identity apply --file integration/<systemKey>/fixtures/<users>.csv --filter-prefix <systemKey>',
+    '  aifabrix identity sync -e dev --purge-cache'
+  ].filter(line => line !== null);
+  err.formatted = `${err.formatted || err.message}${lines.join('\n')}`;
+  return err;
+}
+
+module.exports = {
+  isGovernancePackNotFoundError,
+  isGovernanceCoverageSchemaError,
+  shortGovernanceApiError,
+  governanceUploadSchemaHint,
+  enrichUnresolvableGovernanceSubjectsError
+};