@aifabrix/builder 2.55.0 → 2.56.0

package/lib/commands/logout.js

@@ -132,11 +132,54 @@ async function clearClientTokens(options) {
   return 0;
 }
 
+function normalizeTokenType(value) {
+  const type = value && String(value).toLowerCase();
+  if (type && type !== 'device' && type !== 'client') {
+    throw new Error('--type must be either "device" or "client"');
+  }
+  return type;
+}
+
+function validateLogoutOptionCombination(options, type) {
+  if (options.app && !options.environment) {
+    throw new Error('--app requires --environment option');
+  }
+  if (type === 'client' && options.controller) {
+    throw new Error('--controller can only be used with --type device');
+  }
+  if (type === 'device' && (options.environment || options.app)) {
+    throw new Error('--environment and --app can only be used with --type client');
+  }
+}
+
+function validateLogoutSelectors(options) {
+  if ('controller' in options && options.controller !== undefined && options.controller !== null) {
+    validateControllerUrl(options.controller);
+  }
+  if ('environment' in options && options.environment !== undefined && options.environment !== null) {
+    validateEnvironmentKey(options.environment);
+  }
+}
+
+/**
+ * Validate logout option combinations and normalize the token type.
+ * @param {Object} options - Raw logout options
+ * @returns {Object} Validated options with a normalized type
+ * @throws {Error} If an option or option combination is invalid
+ */
+function normalizeLogoutOptions(options) {
+  const type = normalizeTokenType(options.type);
+  validateLogoutOptionCombination(options, type);
+  validateLogoutSelectors(options);
+  return { ...options, type };
+}
+
 /**
  * Handle logout command action
  * @async
  * @function handleLogout
  * @param {Object} options - Logout options
+ * @param {string} [options.type] - Token type to clear (device or client)
  * @param {string} [options.controller] - Clear device tokens for specific controller
  * @param {string} [options.environment] - Clear client tokens for specific environment
  * @param {string} [options.app] - Clear client tokens for specific app (requires --environment)
@@ -147,24 +190,17 @@ async function handleLogout(options) {
   const configPath = CONFIG_FILE;
   logger.log(chalk.blue('\n🔓 Clearing authentication tokens...\n'));
 
-  // Validate options
-  if (options.app && !options.environment) {
-    throw new Error('--app requires --environment option');
-  }
-
-  if ('controller' in options && options.controller !== undefined && options.controller !== null) {
-    validateControllerUrl(options.controller);
-  }
-
-  if ('environment' in options && options.environment !== undefined && options.environment !== null) {
-    validateEnvironmentKey(options.environment);
-  }
+  const normalizedOptions = normalizeLogoutOptions(options);
 
   // Clear device tokens
-  const deviceTokensCleared = await clearDeviceTokens(options);
+  const deviceTokensCleared = normalizedOptions.type === 'client'
+    ? 0
+    : await clearDeviceTokens(normalizedOptions);
 
   // Clear client tokens
-  const clientTokensCleared = await clearClientTokens(options);
+  const clientTokensCleared = normalizedOptions.type === 'device'
+    ? 0
+    : await clearClientTokens(normalizedOptions);
 
   // Summary
   const totalCleared = deviceTokensCleared + clientTokensCleared;
@@ -178,4 +214,3 @@ async function handleLogout(options) {
 }
 
 module.exports = { handleLogout };
-

package/lib/commands/repair-datasource-auto-rbac.js

@@ -34,18 +34,14 @@ function buildRenameMap(operationMap) {
   if (!operationMap || typeof operationMap !== 'object' || Array.isArray(operationMap)) return {};
   const renameMap = {};
   for (const k of Object.keys(operationMap)) {
-    // If it's already schema-valid but contains capitals, normalize to lowercase to align
-    // with RBAC permission name restrictions (external-system schema forbids A-Z).
+    // Operation keys use the capability naming contract, which allows camelCase.
+    // RBAC permission names are normalized separately when permissions are generated.
     if (/^[a-z][a-zA-Z0-9]*$/.test(k)) {
-      if (/[A-Z]/.test(k)) {
-        renameMap[k] = k.toLowerCase();
-      }
       continue;
     }
     const camel = toCamelCaseKey(k);
     if (!camel || camel === k) continue;
-    // Use lowercase key to keep RBAC permission names schema-valid.
-    renameMap[k] = camel.toLowerCase();
+    renameMap[k] = camel;
   }
   return renameMap;
 }
@@ -212,7 +208,7 @@ function normalizeAutoRbacOperationKeys(parsed, changes) {
   if (updated && Array.isArray(changes)) {
     const pairs = keysToRename.map((k) => `${k}→${renameMap[k]}`).join(', ');
     changes.push(
-      `Normalized autoRbac operation keys (permission names are lowercase per schema; kebab aliases fold into canonical keys): ${pairs}`
+      `Normalized schema-invalid autoRbac operation aliases to camelCase keys (RBAC permission names remain lowercase): ${pairs}`
     );
   }
 
@@ -224,4 +220,3 @@ module.exports = {
   toCamelCaseKey,
   toKebabAliasKey
 };
-

package/lib/commands/role-assistant.js

@@ -64,7 +64,8 @@ Subcommands:
   copy <roleKey>   Capture one Work Hub execution as a local YAML test case
 
 Package workspace (top-level commands — same digital-worker package):
-  download / validate / upload / deploy <roleKey>   Manage role-assistant/ra-<roleKey>/
+  download / validate / upload ra-<roleKey>   Manage role-assistant/ra-<roleKey>/
+  upload publishes settings and sidecars; operator Make available is a separate action
 
 Examples:
   $ aifabrix role-assistant test customer-support-bot
@@ -72,11 +73,11 @@ Examples:
   $ aifabrix role-assistant test customer-support-bot --list-cases
   $ aifabrix role-assistant test customer-support-bot --env tst --json
   $ aifabrix role-assistant copy customer-support-bot --suite 001 --reference a9f09fb8-d9eb-477f-8bb4-59e670fc82a4
-  $ aifabrix upload customer-support-bot --env dev
+  $ aifabrix upload ra-customer-support-bot --env dev
   $ aifabrix test ra-customer-support-bot
 
 Notes:
-  - Local packages live under role-assistant/ra-<roleKey>/ (bare <roleKey> in CLI args).
+  - role-assistant test/copy use bare <roleKey>; top-level package commands use ra-<roleKey>.
   - test uses the public/running worker by default; pass --publish (or upload) to refresh from local files.
   - copy writes tests/<suite>/<caseId>.yaml from a Work Hub execution id; it does not publish.
   - See: aifabrix role-assistant test -h
@@ -267,19 +268,30 @@ async function runRoleAssistantTestAction(roleKey, options, cmd) {
   const portalUrl = buildExternalSystemUiUrl(result.dataplaneUiBaseUrl, systemKey);
   const caseResult = await resolveSelectedCaseResults(systemKey, opts, result, verdict, portalUrl);
 
+  const exitCode = computeRoleAssistantExitCode(verdict, caseResult);
+
   if (opts.json) {
-    logger.log(
-      JSON.stringify(
-        buildRoleAssistantTestEnvelope(displayKey, verdict, portalUrl, result, opts, caseResult),
-        null,
-        2
-      )
+    // Large piped stdout writes on Linux are non-blocking; exiting right
+    // after console.log() can truncate the JSON before the OS write
+    // completes. Wait for the write to flush before exiting non-zero.
+    const payload = JSON.stringify(
+      logger.sanitizeValue(
+        buildRoleAssistantTestEnvelope(displayKey, verdict, portalUrl, result, opts, caseResult)
+      ),
+      null,
+      2
     );
-  } else {
-    displayRoleAssistantTestSummary(displayKey, verdict, portalUrl, result, caseResult);
+    return new Promise((resolve) => {
+      process.stdout.write(`${payload}\n`, () => {
+        if (exitCode !== 0) {
+          process.exit(exitCode);
+        }
+        resolve(exitCode);
+      });
+    });
   }
 
-  const exitCode = computeRoleAssistantExitCode(verdict, caseResult);
+  displayRoleAssistantTestSummary(displayKey, verdict, portalUrl, result, caseResult);
   if (exitCode !== 0) {
     process.exit(exitCode);
   }

package/lib/commands/upload-openapi-sync-followup.js

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Post-publish local OpenAPI sync follow-up, shared by the synchronous and
+ * qualification-async upload paths (extracted from upload.js per plan 191.0 file-size gate).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatSuccessLine, formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
+const { maybeSyncOpenApiFilesForMcp } = require('./repair-openapi-sync');
+const { exportProgrammaticOpenApiForRepair } = require('./repair-openapi-export');
+
+/**
+ * Upload local `integration/<systemKey>/openapi/*.json` specs when present so dataplane can store
+ * vendor OpenAPI keyed by each datasource `openapi.documentKey` (same behavior as repair --api OpenAPI sync).
+ * Call this **after** the external system row exists (successful publish or completed qualification):
+ * list/upload endpoints require it. First publish still succeeds because pipeline materializes
+ * internal specs from `openapi.operations` when needed.
+ *
+ * @param {string} systemKey
+ * @param {Object} manifest
+ * @param {Object} [uploadContext]
+ * @returns {Promise<void>}
+ */
+async function logAndSyncLocalOpenApiForUpload(systemKey, manifest, uploadContext = {}) {
+  const pathOptions = uploadContext.pathOptions || {};
+  const appPath = resolveExternalSystemPath(systemKey, pathOptions);
+  const ei = manifest && manifest.externalIntegration;
+  const datasourceFiles = ei && Array.isArray(ei.dataSources) ? ei.dataSources : [];
+  await exportProgrammaticOpenApiForRepair({
+    appPath,
+    systemKey,
+    datasourceFiles,
+    dryRun: false,
+    backupCtx: { dryRun: false, changedFiles: [] }
+  });
+  const openapiSyncLines = await maybeSyncOpenApiFilesForMcp({
+    enabled: true,
+    dryRun: false,
+    appPath,
+    systemKey,
+    datasourceFiles,
+    dataplaneUrl: uploadContext.dataplaneUrl,
+    authConfig: uploadContext.authConfig,
+    // Always replace SpecFile rows keyed by openapi.documentKey so vendor/full
+    // specs are not left missing while only thin internal:* slices remain.
+    force: true
+  });
+  if (!uploadContext.quiet) {
+    for (const line of openapiSyncLines) {
+      logger.log(line.startsWith('Skipped') ? formatWarningLine(line) : formatSuccessLine(line));
+    }
+  }
+}
+
+module.exports = { logAndSyncLocalOpenApiForUpload };

package/lib/commands/upload-qualification-client.js

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview Resumable Dataplane qualification upload: accept, --wait/--no-wait, poll, resume.
+ * Mirrors dev-host-ops.js's job id + wait/no-wait contract (plan 191.0 task 1). Never invents
+ * qualification truth — accept/poll surface exactly what Dataplane returns.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatSuccessLine, formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const { formatApiError } = require('../utils/api-error-handler');
+const { uploadApplicationViaPipelineWithAuthRetry } = require('../utils/pipeline-upload-auth-retry');
+const { pollQualificationJobUntilTerminal } = require('./upload-qualification-poll');
+const { createQualificationPollHandlers } = require('../utils/qualification-poll-ui');
+
+/**
+ * Ctrl-C / disconnect during polling must detach without corrupting truth (plan 191.0 task 4):
+ * the qualification job keeps running on Dataplane regardless of whether this CLI process exits.
+ * This only makes that safe fact visible, printing the resume command before exiting 130.
+ * @param {string} jobId
+ * @param {string} systemKey
+ * @returns {() => void} Call to remove the listeners once polling finishes normally.
+ */
+function registerUploadInterruptHint(jobId, systemKey) {
+  const onSignal = () => {
+    logger.log(
+      formatWarningLine(
+        `Interrupted — upload job ${jobId} is still running, unaffected. Resume with: aifabrix upload ${systemKey} --resume ${jobId}`
+      )
+    );
+    process.exit(130);
+  };
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+  return () => {
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+  };
+}
+
+/**
+ * Submit the candidate for durable Dataplane qualification (async). Always returns quickly —
+ * a 202 accept, or the current state when an equivalent job is already in flight — never blocks
+ * for the ladder to finish.
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {Object} payload
+ * @param {string} systemKey
+ * @param {Object} [options] - Forwarded to uploadApplicationViaPipeline (e.g. timeoutMs, ignored when async)
+ * @returns {Promise<{jobId: string, state: string, resumed: boolean, candidateFingerprint: string}>}
+ */
+async function acceptQualificationUpload(dataplaneUrl, authConfig, payload, systemKey, options = {}) {
+  const res = await uploadApplicationViaPipelineWithAuthRetry(dataplaneUrl, authConfig, payload, systemKey, {
+    ...options,
+    async: true
+  });
+  if (res?.success === false) {
+    const err = new Error(formatApiError(res, dataplaneUrl));
+    const status = Number(res.status || res.statusCode);
+    err.statusCode = status >= 400 && status < 600 ? status : 400;
+    throw err;
+  }
+  return res.data;
+}
+
+/**
+ * Poll an existing qualification job id to terminal state (resume without re-uploading).
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} jobId
+ * @param {string} systemKey - For the printed resume hint if interrupted mid-poll.
+ * @param {{ json?: boolean, silent?: boolean, timeoutMs?: number|string }} [options] - `timeoutMs`
+ *   bounds only how long this CLI process waits (CLI `--timeout`); Dataplane keeps running the
+ *   job regardless, so timing out returns a resumable jobId, never a fabricated failure.
+ * @returns {Promise<Object>} Terminal job status
+ */
+async function resumeQualificationUpload(dataplaneUrl, authConfig, jobId, systemKey, options = {}) {
+  const pollUi = options.json || options.silent
+    ? createQualificationPollHandlers(jobId, { silent: true })
+    : createQualificationPollHandlers(jobId, { verbose: options.verbose === true });
+  const unregisterInterruptHint = registerUploadInterruptHint(jobId, systemKey);
+  try {
+    return await pollQualificationJobUntilTerminal(
+      dataplaneUrl,
+      authConfig,
+      jobId,
+      pollUi,
+      options.timeoutMs !== undefined ? Number(options.timeoutMs) : undefined
+    );
+  } finally {
+    pollUi.finish();
+    unregisterInterruptHint();
+  }
+}
+
+/**
+ * Accept then, unless `--no-wait`, poll to terminal. On `--no-wait`, prints/returns the
+ * resumable job id immediately and never blocks.
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {Object} payload
+ * @param {string} systemKey
+ * @param {{ wait?: boolean, json?: boolean, timeoutMs?: number|string }} [options]
+ * @returns {Promise<{jobId: string, candidateFingerprint: string, terminal: Object|null}>}
+ */
+async function runQualificationUpload(dataplaneUrl, authConfig, payload, systemKey, options = {}) {
+  const accepted = await acceptQualificationUpload(dataplaneUrl, authConfig, payload, systemKey, options);
+  const wait = options.wait !== false;
+  if (!wait) {
+    if (options.json) {
+      logger.log(JSON.stringify({ ...accepted, terminal: null }, null, 2));
+    } else {
+      logger.log(
+        formatSuccessLine(
+          `Upload queued (job ${accepted.jobId}). Resume with: aifabrix upload ${systemKey} --resume ${accepted.jobId}`
+        )
+      );
+    }
+    return { ...accepted, terminal: null };
+  }
+  const terminal = await resumeQualificationUpload(dataplaneUrl, authConfig, accepted.jobId, systemKey, options);
+  return { ...accepted, terminal };
+}
+
+module.exports = {
+  acceptQualificationUpload,
+  resumeQualificationUpload,
+  runQualificationUpload
+};

package/lib/commands/upload-qualification-followups.js

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Post-qualification follow-ups for the async upload path: credential push,
+ * local OpenAPI sync, sidecar governance/evidence sync, probe and a qualification-specific
+ * summary (plan 191.0 task 1).
+ *
+ * Note: this intentionally does not reconstruct the legacy tiered datasource-readiness summary
+ * (`logUploadReadinessSummary`) that the synchronous path shows — that summary classifies real
+ * server-assigned datasource state (status/isActive/mcpContract) which requires a fresh
+ * Dataplane fetch+remap not yet ported to this path. The qualification summary below reports
+ * what Dataplane actually returned instead of approximating server state from local data.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatSuccessLine, metadata, sectionTitle } = require('../utils/cli-test-layout-chalk');
+const { pushAndLogCredentialSecrets } = require('./upload-credential-push-log');
+const { finalizeUploadPublishResult } = require('./upload-data-sync-finalize');
+const { runUploadSidecarFollowups } = require('./upload-sidecar-followups');
+const { logAndSyncLocalOpenApiForUpload } = require('./upload-openapi-sync-followup');
+const { maybeRunUploadProbe } = require('./upload-probe');
+
+/**
+ * @param {string} systemKey
+ * @param {Object} _accepted - Machine-readable qualification identity (not shown in CLI output)
+ * @param {Object} job - Terminal PublishJobStatusResponse data
+ * @param {Object} options
+ */
+function logQualifiedUploadSummary(systemKey, _accepted, job, options) {
+  if (options.suppressSummary === true || options.json === true) {
+    return;
+  }
+  logger.log('');
+  logger.log(sectionTitle('Upload complete'));
+  logger.log(metadata(`System: ${systemKey}`));
+  if (options.verbose === true) {
+    logger.log(metadata(`Job: ${job.jobId}`));
+    const certificateIds = job.result && Array.isArray(job.result.certificateIds) ? job.result.certificateIds : [];
+    if (certificateIds.length > 0) {
+      logger.log(metadata(`Certificates: ${certificateIds.join(', ')}`));
+    }
+  }
+  logger.log(formatSuccessLine(`${systemKey} uploaded successfully.`));
+}
+
+/**
+ * Runs the same downstream follow-ups as the synchronous publish path (credential push, local
+ * OpenAPI sync, sidecar governance/evidence sync, optional probe) once a qualification job has
+ * reached `completed`, then finalizes with the same result-envelope shape as the sync path.
+ * @param {string} systemKey
+ * @param {Object} options
+ * @param {Object} manifest
+ * @param {Object} payload
+ * @param {{ dataplaneUrl: string, authConfig: Object, environment: string, accepted: Object, job: Object }} ctx
+ * @returns {Promise<Object>}
+ */
+async function completeQualifiedUpload(systemKey, options, manifest, payload, ctx) {
+  const quietCompact = options.minimal === true && options.verbose !== true;
+  const pushMeta = await pushAndLogCredentialSecrets(ctx.dataplaneUrl, ctx.authConfig, systemKey, payload, {
+    json: options.json === true,
+    pathOptions: options.pathOptions,
+    suppressCredentialLog: quietCompact,
+    excludeSecretKeys: options.excludeSecretKeys
+  });
+  await logAndSyncLocalOpenApiForUpload(systemKey, manifest, {
+    dataplaneUrl: ctx.dataplaneUrl,
+    authConfig: ctx.authConfig,
+    pathOptions: options.pathOptions,
+    quiet: quietCompact
+  });
+  const sidecar = await runUploadSidecarFollowups({
+    systemKey,
+    options,
+    payload,
+    dataplaneUrl: ctx.dataplaneUrl,
+    authConfig: ctx.authConfig,
+    environment: ctx.environment
+  });
+  logQualifiedUploadSummary(systemKey, ctx.accepted, ctx.job, options);
+  if (options.probe === true) {
+    await maybeRunUploadProbe(ctx.dataplaneUrl, systemKey, ctx.authConfig, options.probeTimeout, {
+      compact: quietCompact
+    });
+  }
+  return finalizeUploadPublishResult(
+    {
+      dataplaneUrl: ctx.dataplaneUrl,
+      authConfig: ctx.authConfig,
+      environment: ctx.environment,
+      uploadSkipped: false,
+      sidecar,
+      credentialPush: pushMeta.credentialPush,
+      configPush: pushMeta.configPush,
+      jobId: ctx.job.jobId,
+      candidateFingerprint: ctx.accepted.candidateFingerprint
+    },
+    payload,
+    options
+  );
+}
+
+module.exports = { completeQualifiedUpload, logQualifiedUploadSummary };

package/lib/commands/upload-qualification-poll.js

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Poll a Dataplane qualification (publish) job until terminal (plan 191.0 task 1).
+ * Never invents success and never marks the candidate failed just because the CLI stopped polling —
+ * timing out returns a resumable jobId instead.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getPublishJobStatus } = require('../api/pipeline.api');
+const { formatApiError } = require('../utils/api-error-handler');
+
+const POLL_INTERVAL_MS = 3000;
+const POLL_TIMEOUT_MS = 30 * 60 * 1000;
+const TRANSIENT_HTTP_STATUSES = new Set([502, 503, 504]);
+const MAX_TRANSIENT_POLL_ERRORS = 20;
+
+const GOVERNANCE_SCENARIOS_MISSING = 'GOVERNANCE_SCENARIOS_MISSING';
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Convert repeated server error codes into one user-facing qualification failure.
+ * The raw job remains attached to the thrown error for JSON/programmatic callers.
+ * @param {Object} job
+ * @returns {{ message: string, userFacing: boolean }}
+ */
+function formatQualificationJobFailure(job) {
+  const raw = String(job && job.error ? job.error : '').trim();
+  const parts = raw.split(';').map((part) => part.trim()).filter(Boolean);
+  const missingCount = parts.filter((part) => part === GOVERNANCE_SCENARIOS_MISSING).length;
+  if (missingCount > 0 && missingCount === parts.length) {
+    const scope = `${missingCount} datasource${missingCount === 1 ? '' : 's'}`;
+    return {
+      message: `Governance checks could not run because scenario packs are missing for ${scope}.`,
+      userFacing: true
+    };
+  }
+  const unique = [...new Set(parts)];
+  return {
+    message: unique.join('; ') || `Upload checks failed for job ${job && job.jobId ? job.jobId : ''}`.trim(),
+    userFacing: false
+  };
+}
+
+/**
+ * @param {number|string} status
+ * @returns {boolean}
+ */
+function isTransientQualificationPollError(status) {
+  return TRANSIENT_HTTP_STATUSES.has(Number(status));
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} jobId
+ * @param {Object} [pollUi]
+ * @returns {Promise<Object>} Raw job status data
+ */
+async function fetchQualificationJobWithRetry(dataplaneUrl, authConfig, jobId, pollUi = {}) {
+  const started = Date.now();
+  for (let attempt = 0; attempt <= MAX_TRANSIENT_POLL_ERRORS; attempt += 1) {
+    const res = await getPublishJobStatus(dataplaneUrl, authConfig, jobId);
+    if (res?.success !== false) {
+      return res.data;
+    }
+    if (!isTransientQualificationPollError(res.status)) {
+      const err = new Error(formatApiError(res, dataplaneUrl));
+      const status = Number(res.status);
+      err.statusCode = status >= 400 && status < 600 ? status : 400;
+      throw err;
+    }
+    if (attempt >= MAX_TRANSIENT_POLL_ERRORS) {
+      throw new Error(
+        `The upload service returned HTTP ${res.status} repeatedly while waiting for job ${jobId}.`
+      );
+    }
+    if (typeof pollUi.onTransientError === 'function') {
+      pollUi.onTransientError(res.status, Date.now() - started);
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new Error(`Failed to check upload job ${jobId} after transient retries`);
+}
+
+/**
+ * Poll a Dataplane qualification job to terminal state (completed|failed). The timeout only
+ * bounds how long *this CLI process* waits — Dataplane keeps running the job regardless; timing
+ * out returns a resumable jobId, never a fabricated failure (plan 191.0 task 4).
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} jobId
+ * @param {Object} [pollUi] - { onPollProgress(job), onTransientError(status, elapsedMs) }
+ * @param {number} [timeoutMs] - Defaults to POLL_TIMEOUT_MS (30 min); CLI `--timeout` overrides it.
+ * @returns {Promise<Object>} Terminal job status data (state: 'completed')
+ * @throws {Error} With `.jobId` set, when the job fails or the CLI-side wait times out (resumable).
+ */
+async function pollQualificationJobUntilTerminal(
+  dataplaneUrl,
+  authConfig,
+  jobId,
+  pollUi = {},
+  timeoutMs = POLL_TIMEOUT_MS
+) {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    const job = await fetchQualificationJobWithRetry(dataplaneUrl, authConfig, jobId, pollUi);
+    if (typeof pollUi.onPollProgress === 'function') {
+      pollUi.onPollProgress(job);
+    }
+    if (job.state === 'failed') {
+      const failure = formatQualificationJobFailure(job);
+      const err = new Error(failure.message);
+      err.jobId = jobId;
+      err.job = job;
+      err.skipDoctor = failure.userFacing;
+      throw err;
+    }
+    if (job.state === 'completed') {
+      return job;
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  const timeoutErr = new Error(
+    `Timed out waiting for upload job ${jobId}. It is still running — resume with: aifabrix upload <systemKey> --resume ${jobId}`
+  );
+  timeoutErr.jobId = jobId;
+  timeoutErr.resumable = true;
+  throw timeoutErr;
+}
+
+module.exports = {
+  POLL_INTERVAL_MS,
+  POLL_TIMEOUT_MS,
+  isTransientQualificationPollError,
+  fetchQualificationJobWithRetry,
+  formatQualificationJobFailure,
+  pollQualificationJobUntilTerminal
+};