@aifabrix/builder 2.44.0 → 2.44.2

package/lib/utils/external-system-system-test-tty.js

@@ -0,0 +1,417 @@
+/**
+ * @fileoverview System-level TTY renderer for DatasourceTestRun fan-out results (plan §17).
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+const {
+  SEP,
+  statusGlyph
+} = require('./datasource-test-run-display');
+const {
+  sectionTitle,
+  headerKeyValue,
+  formatStatusKeyValue,
+  integrationFooterLine,
+  colorRollupPrefixedLine,
+  metadata: metaGray
+} = require('./cli-test-layout-chalk');
+const {
+  formatDataQualityLines,
+  readinessLineFromDataReadiness,
+  verdictLineFromEnvelope
+} = require('./validation-report-tty-kit');
+const {
+  logCapabilitiesOverview: logCapabilitiesOverviewSection,
+  logIntegrationHealthSection: logIntegrationHealthSectionBlock
+} = require('./external-system-system-test-tty-overview');
+
+/**
+  * @param {'ok'|'warn'|'fail'|'skipped'|null} st
+  * @returns {number}
+  */
+function statusRank(st) {
+  if (st === 'fail') return 0;
+  if (st === 'warn') return 1;
+  if (st === 'ok') return 2;
+  if (st === 'skipped') return 3;
+  return 4;
+}
+
+/**
+ * Per-row status for system rollup and tables: CLI/transport failure overrides envelope-only OK.
+ * @param {{ skipped?: boolean, success?: boolean, datasourceTestRun?: { status?: string }|null }} r
+ * @returns {'ok'|'warn'|'fail'|'skipped'}
+ */
+function rollupRowStatus(r) {
+  if (r && r.skipped) return 'skipped';
+  if (r && r.success === false) return 'fail';
+  const env = r && r.datasourceTestRun;
+  return env && typeof env.status === 'string' ? env.status : 'ok';
+}
+
+/**
+  * @param {Array<{ key: string, skipped?: boolean, datasourceTestRun?: Object|null, success?: boolean }>} rows
+  * @returns {'ok'|'warn'|'fail'|'skipped'}
+  */
+function deriveSystemStatus(rows) {
+  if (!Array.isArray(rows) || rows.length === 0) return 'ok';
+  const statuses = rows.map(rollupRowStatus);
+  if (statuses.some(s => s === 'fail')) return 'fail';
+  if (statuses.some(s => s === 'warn')) return 'warn';
+  if (statuses.every(s => s === 'skipped')) return 'skipped';
+  // Mixed ok/skipped => warn per plan.
+  return statuses.every(s => s === 'ok') ? 'ok' : 'warn';
+}
+
+function bucketIssueSeverity(issue) {
+  const sev = issue && issue.severity ? String(issue.severity).toLowerCase() : '';
+  if (sev === 'error' || sev === 'critical' || sev === 'high' || sev === 'fatal') return 'fail';
+  if (sev === 'warn' || sev === 'warning' || sev === 'medium') return 'warn';
+  return null;
+}
+
+/**
+  * Minimal heuristic rollups backed by envelope fields (no engine codenames).
+  * @param {Object|null|undefined} env
+  * @returns {'ok'|'warn'|'fail'}
+  */
+function dqFromEnvelope(env) {
+  const v = env && env.validation;
+  const st = v && typeof v.status === 'string' ? String(v.status) : null;
+  if (st === 'fail') return 'fail';
+  if (st === 'warn') return 'warn';
+
+  const issues = v && Array.isArray(v.issues) ? v.issues : [];
+  if (issues.some(i => bucketIssueSeverity(i) === 'fail')) return 'fail';
+  if (issues.some(i => bucketIssueSeverity(i) === 'warn')) return 'warn';
+  return 'ok';
+}
+
+/**
+  * @param {Array} rows
+  * @returns {{ schema: 'ok'|'warn'|'fail', consistency: 'ok'|'warn'|'fail', reliability: 'ok'|'warn'|'fail' }}
+  */
+function deriveSystemDataQuality(rows) {
+  const envs = rows
+    .map(r => (r && r.datasourceTestRun && typeof r.datasourceTestRun === 'object' ? r.datasourceTestRun : null))
+    .filter(Boolean);
+  if (envs.length === 0) {
+    return { schema: 'warn', consistency: 'warn', reliability: 'warn' };
+  }
+
+  const picks = envs.map(dqFromEnvelope);
+  const agg = picks.some(x => x === 'fail') ? 'fail' : picks.some(x => x === 'warn') ? 'warn' : 'ok';
+  return { schema: agg, consistency: agg, reliability: agg };
+}
+
+/**
+  * @param {Array} rows
+  * @returns {'ready'|'partial'|'not_ready'|null}
+  */
+function deriveSystemReadiness(rows) {
+  const envs = rows
+    .map(r => (r && r.datasourceTestRun && typeof r.datasourceTestRun === 'object' ? r.datasourceTestRun : null))
+    .filter(Boolean);
+  const drs = envs
+    .map(e => e.validation && e.validation.dataReadiness)
+    .filter(Boolean);
+  if (drs.length === 0) return null;
+  if (drs.some(x => x === 'not_ready')) return 'not_ready';
+  if (drs.some(x => x === 'partial')) return 'partial';
+  return 'ready';
+}
+
+function countByStatus(rows) {
+  const counts = { ok: 0, warn: 0, fail: 0, skipped: 0 };
+  for (const r of rows) {
+    const s = rollupRowStatus(r);
+    if (counts[s] !== undefined) counts[s] += 1;
+  }
+  return counts;
+}
+
+function pickBlockingDatasourceKey(rows) {
+  const keys = rows
+    .map(r => {
+      const env = r && r.datasourceTestRun;
+      const st = rollupRowStatus(r);
+      const key =
+        env && env.datasourceKey
+          ? String(env.datasourceKey)
+          : r && r.key
+            ? String(r.key)
+            : '';
+      return { key, st };
+    })
+    .filter(x => x.key);
+  keys.sort((a, b) => {
+    const d = statusRank(a.st) - statusRank(b.st);
+    if (d !== 0) return d;
+    return a.key.localeCompare(b.key);
+  });
+  return keys.length ? keys[0].key : null;
+}
+
+function issueKey(issue) {
+  const code = issue && issue.code ? String(issue.code) : '';
+  const msg = issue && issue.message ? String(issue.message) : '';
+  return `${code}::${msg}`.toLowerCase();
+}
+
+function issueSortKey(it) {
+  return `${statusRank(it.severity)}::${it.datasourceKey}::${it.message}`.toLowerCase();
+}
+
+function extractRowIssues(row) {
+  const env = row && row.datasourceTestRun;
+  const datasourceKey = (env && env.datasourceKey) || (row && row.key) || 'datasource';
+  const issues = env && env.validation && Array.isArray(env.validation.issues) ? env.validation.issues : [];
+  const envStatus = env && typeof env.status === 'string' ? env.status : null;
+  return { datasourceKey: String(datasourceKey), issues, envStatus };
+}
+
+function toIssueItem(datasourceKey, envStatus, iss) {
+  const sev =
+    bucketIssueSeverity(iss) ||
+    (envStatus === 'fail' ? 'fail' : envStatus === 'warn' ? 'warn' : 'ok');
+  const msg = iss && iss.message ? String(iss.message) : iss && iss.code ? String(iss.code) : 'Issue';
+  return { datasourceKey, message: msg, severity: sev };
+}
+
+function collectKeyIssues(rows, cap) {
+  /** @type {{ datasourceKey: string, message: string, severity: 'fail'|'warn'|'ok' }[]} */
+  const out = [];
+  const seen = new Set();
+  for (const row of rows) {
+    const { datasourceKey, issues, envStatus } = extractRowIssues(row);
+    for (const iss of issues) {
+      const k = `${datasourceKey}::${issueKey(iss)}`;
+      if (seen.has(k)) continue;
+      seen.add(k);
+      out.push(toIssueItem(datasourceKey, envStatus, iss));
+    }
+  }
+  out.sort((a, b) => issueSortKey(a).localeCompare(issueSortKey(b)));
+  return out.slice(0, Math.max(0, cap));
+}
+
+function certificateBucket(env) {
+  const cert = env && env.certificate;
+  if (!cert || typeof cert !== 'object') return { status: null, level: null };
+  return {
+    status: cert.status ? String(cert.status) : null,
+    level: cert.level ? String(cert.level) : null
+  };
+}
+
+function systemCertStatus(rows) {
+  const certs = rows
+    .map(r => (r && r.datasourceTestRun ? certificateBucket(r.datasourceTestRun) : { status: null, level: null }))
+    .filter(c => c.status !== null);
+  if (certs.length === 0) return null;
+  if (certs.some(c => c.status === 'not_passed')) return 'not_passed';
+  return 'passed';
+}
+
+function drillDownCommand(runType, datasourceKey) {
+  if (!datasourceKey) return null;
+  if (runType === 'e2e') return `aifabrix datasource test-e2e ${datasourceKey}`;
+  if (runType === 'integration') return `aifabrix datasource test-integration ${datasourceKey}`;
+  return `aifabrix datasource test ${datasourceKey}`;
+}
+
+function logSystemHeader(results, runType, systemStatus) {
+  logger.log('');
+  logger.log(sectionTitle('Server test results'));
+  logger.log('');
+  logger.log(headerKeyValue('System:', results.systemKey));
+  logger.log(
+    headerKeyValue(
+      'Run:',
+      runType === 'e2e' ? 'test-e2e (dataplane)' : 'test-integration (dataplane)'
+    )
+  );
+  logger.log(formatStatusKeyValue(systemStatus, statusGlyph(systemStatus)));
+  logger.log('');
+}
+
+function logVerdictAndSummary(runType, systemStatus, certStatus, counts) {
+  logger.log(sectionTitle('Verdict:'));
+  logger.log(chalk.white(verdictLineFromEnvelope(systemStatus, certStatus, runType)));
+  logger.log('');
+  logger.log(sectionTitle('Summary:'));
+  logger.log(
+    chalk.white(
+      `${counts.ok + counts.warn + counts.fail} datasource(s): ${counts.ok} ok, ${counts.warn} warn, ${counts.fail} fail${counts.skipped ? `, ${counts.skipped} skipped` : ''}`
+    )
+  );
+  logger.log('');
+  logger.log(metaGray(SEP));
+  logger.log('');
+}
+
+function logDataQualityAndReadiness(rows) {
+  logger.log(sectionTitle('Data Quality:'));
+  const dq = deriveSystemDataQuality(rows);
+  const dqLines = formatDataQualityLines(dq, {
+    schema: 'structural coverage aggregated across datasources.',
+    consistency: 'issues aggregated across datasources.',
+    reliability: 'issues aggregated across datasources.'
+  });
+  dqLines.map(colorRollupPrefixedLine).forEach(l => logger.log(l));
+
+  const readiness = deriveSystemReadiness(rows);
+  const readinessLine = readinessLineFromDataReadiness(readiness);
+  if (readinessLine) {
+    logger.log('');
+    logger.log(colorRollupPrefixedLine(readinessLine));
+  }
+
+  logger.log('');
+  logger.log(metaGray(SEP));
+  logger.log('');
+}
+
+function logDatasourceTable(rows, counts, verbose) {
+  logger.log(sectionTitle('Datasources:'));
+  logger.log('');
+  if (!verbose && counts.ok > 0) {
+    logger.log(chalk.gray(`✔ ${counts.ok} datasource(s) fully ready`));
+  }
+
+  function rowStatus(r) {
+    return rollupRowStatus(r);
+  }
+
+  function readinessLabel(env, st) {
+    const ready = env && env.validation ? env.validation.dataReadiness : null;
+    if (ready === 'not_ready') return 'Not ready';
+    if (ready === 'partial') return 'Partial';
+    if (ready === 'ready') return 'Ready';
+    if (st === 'fail') return 'Not ready';
+    if (st === 'warn') return 'Partial';
+    return 'Ready';
+  }
+
+  function shouldListRow(r) {
+    if (verbose) return true;
+    const st = rowStatus(r);
+    return st === 'warn' || st === 'fail';
+  }
+
+  const listRows = rows.filter(shouldListRow);
+  for (const r of listRows) {
+    const env = r && r.datasourceTestRun;
+    const key = (env && env.datasourceKey) || (r && r.key) || 'datasource';
+    const st = rowStatus(r);
+    const readyLabel = readinessLabel(env, st);
+    logger.log(`${statusGlyph(st)} ${chalk.white(String(key).padEnd(22))} (${readyLabel})`);
+  }
+}
+
+function logBlockingDatasource(blocking) {
+  if (!blocking) return;
+  logger.log('');
+  logger.log(chalk.white(`Blocking datasource: ${blocking}`));
+}
+
+function logKeyIssuesSection(rows) {
+  const issues = collectKeyIssues(rows, 5);
+  if (issues.length === 0) return false;
+  logger.log('');
+  logger.log(metaGray(SEP));
+  logger.log('');
+  logger.log(sectionTitle('Key issues:'));
+  logger.log('');
+  let cur = null;
+  for (const it of issues) {
+    if (cur !== it.datasourceKey) {
+      cur = it.datasourceKey;
+      logger.log(chalk.white(cur));
+    }
+    logger.log(chalk.white(`- ${it.message}`));
+  }
+  return true;
+}
+
+function logCertificationSection(rows) {
+  const certSt = systemCertStatus(rows);
+  if (!certSt) return;
+  logger.log('');
+  logger.log(metaGray(SEP));
+  logger.log('');
+  logger.log(sectionTitle('Certification:'));
+  logger.log('');
+  logger.log(chalk.white(`System level: ${certSt === 'passed' ? '✔ Achieved' : '✖ Not achieved'}`));
+  logger.log('');
+  logger.log(chalk.white('Breakdown:'));
+  for (const r of rows) {
+    const env = r && r.datasourceTestRun;
+    if (!env) continue;
+    const cert = certificateBucket(env);
+    if (!cert.status) continue;
+    const g = cert.status === 'passed' ? '✔' : '✖';
+    const tier = cert.level ? cert.level : '(no level)';
+    logger.log(chalk.white(`- ${env.datasourceKey}: ${g} ${tier}`));
+  }
+}
+
+function logUseAndFooter(results, runType, systemStatus, blocking) {
+  logger.log('');
+  logger.log(metaGray(SEP));
+  logger.log('');
+  logger.log(sectionTitle('Use:'));
+  const cmd = drillDownCommand(runType, blocking);
+  logger.log(chalk.white(cmd || 'aifabrix datasource test <datasourceKey>'));
+  logger.log(
+    integrationFooterLine(
+      results.success,
+      systemStatus,
+      'All server tests passed.',
+      'Server tests completed with warnings.',
+      'Some server tests failed.'
+    )
+  );
+}
+
+/**
+  * Render system-level aggregate (plan §17) for DatasourceTestRun wrapper results.
+  * @param {Object} results
+  * @param {Object} opts
+  * @param {'integration'|'e2e'} opts.runType
+  * @param {boolean} opts.verbose
+  */
+function displaySystemAggregateDatasourceTestRuns(results, opts) {
+  const rows = Array.isArray(results.datasourceResults) ? results.datasourceResults : [];
+  const runType = opts.runType === 'e2e' ? 'e2e' : 'integration';
+  const systemStatus = deriveSystemStatus(rows);
+  const counts = countByStatus(rows);
+  const blocking = pickBlockingDatasourceKey(rows);
+  logSystemHeader(results, runType, systemStatus);
+  logVerdictAndSummary(runType, systemStatus, systemCertStatus(rows), counts);
+  logDataQualityAndReadiness(rows);
+  logDatasourceTable(rows, counts, Boolean(opts.verbose));
+  logBlockingDatasource(blocking);
+  logKeyIssuesSection(rows);
+  const ttyIo = { log: logger.log.bind(logger), chalk, metaGray, sectionTitle, statusGlyph, SEP };
+  logCapabilitiesOverviewSection(rows, ttyIo);
+  logIntegrationHealthSectionBlock(rows, runType, ttyIo);
+  logCertificationSection(rows);
+  logUseAndFooter(results, runType, systemStatus, blocking);
+}
+
+module.exports = {
+  displaySystemAggregateDatasourceTestRuns,
+  deriveSystemStatus,
+  deriveSystemDataQuality,
+  deriveSystemReadiness,
+  rollupRowStatus,
+  pickBlockingDatasourceKey,
+  collectKeyIssues,
+  systemCertStatus,
+  drillDownCommand
+};
+

package/lib/utils/paths.js

@@ -332,9 +332,23 @@ function getAppPath(appName, appType) {
 
 /**
  * Base directory for integration/builder: project root when cwd is inside project, else cwd.
+ * When `aifabrix-work` / `AIFABRIX_WORK` points at a repo that contains `integration/`, use that
+ * root even if cwd is elsewhere (e.g. global CLI install + cwd under `integration/<app>/`).
  * @returns {string} Directory to resolve integration/ and builder/ from
  */
 function getIntegrationBuilderBaseDir() {
+  const work = getAifabrixWork();
+  if (work) {
+    const workNorm = path.resolve(work);
+    const integrationUnderWork = path.join(workNorm, 'integration');
+    try {
+      if (fs.existsSync(integrationUnderWork)) {
+        return workNorm;
+      }
+    } catch {
+      // ignore fs errors
+    }
+  }
   const root = getProjectRoot();
   const cwd = path.resolve(process.cwd());
   const rootNorm = path.resolve(root);

package/lib/utils/url-declarative-resolve-load-doc.js

@@ -8,10 +8,50 @@ const path = require('path');
 const yaml = require('js-yaml');
 const fsRealSync = require('../internal/fs-real-sync');
 
+/**
+ * @param {string} cfgPath
+ * @returns {object|null}
+ */
+function tryReadApplicationYamlAt(cfgPath) {
+  try {
+    if (!fsRealSync.existsSync(cfgPath)) {
+      return null;
+    }
+    const raw = fsRealSync.readFileSync(cfgPath, 'utf8');
+    const doc = yaml.load(raw);
+    return doc && typeof doc === 'object' ? doc : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Prefer projectRoot/builder (fixtures, tests); then {@link pathsUtil.getBuilderPath} (global npm).
+ * @param {string} appKey
+ * @param {object} pathsUtil
+ * @returns {string[]}
+ */
+function collectApplicationYamlPathsForUrlResolve(appKey, pathsUtil) {
+  const list = [];
+  const root = pathsUtil.getProjectRoot();
+  if (root) {
+    list.push(path.resolve(path.join(root, 'builder', appKey, 'application.yaml')));
+  }
+  try {
+    const viaBuilder = path.resolve(path.join(pathsUtil.getBuilderPath(appKey), 'application.yaml'));
+    if (!list.length || path.resolve(list[0]) !== viaBuilder) {
+      list.push(viaBuilder);
+    }
+  } catch {
+    /* ignore getBuilderPath errors */
+  }
+  return list;
+}
+
 /**
  * @param {string} appKey
  * @param {Object} ctx
- * @param {object} pathsUtil - paths module (getProjectRoot)
+ * @param {object} pathsUtil - paths module (getProjectRoot, getBuilderPath)
  * @returns {object|null}
  */
 function loadApplicationYamlDocForUrlResolve(appKey, ctx, pathsUtil) {
@@ -19,28 +59,18 @@ function loadApplicationYamlDocForUrlResolve(appKey, ctx, pathsUtil) {
     const current = ctx.currentAppKey || '';
     if (appKey === current && ctx.variablesPath) {
       const vp = path.resolve(String(ctx.variablesPath));
-      try {
-        const raw = fsRealSync.readFileSync(vp, 'utf8');
-        const doc = yaml.load(raw);
-        if (doc && typeof doc === 'object') {
-          return doc;
-        }
-      } catch {
-        // Fall through to builder-relative resolution
+      const fromVars = tryReadApplicationYamlAt(vp);
+      if (fromVars) {
+        return fromVars;
       }
     }
-    const root = pathsUtil.getProjectRoot();
-    if (!root) {
-      return null;
-    }
-    const cfgPath = path.resolve(path.join(root, 'builder', appKey, 'application.yaml'));
-    try {
-      const raw = fsRealSync.readFileSync(cfgPath, 'utf8');
-      const doc = yaml.load(raw);
-      return doc && typeof doc === 'object' ? doc : null;
-    } catch {
-      return null;
+    for (const cfgPath of collectApplicationYamlPathsForUrlResolve(appKey, pathsUtil)) {
+      const doc = tryReadApplicationYamlAt(cfgPath);
+      if (doc) {
+        return doc;
+      }
     }
+    return null;
   } catch {
     return null;
   }

package/lib/utils/urls-local-registry.js

@@ -156,19 +156,12 @@ function mergeDocIntoRegistry(merged, doc, folderName) {
 }
 
 /**
- * Merge scan results into registry (does not remove stale keys).
- * @param {string|null} projectRoot - getProjectRoot() or null
- * @returns {Object} Updated registry
+ * @param {Object} merged
+ * @param {string} builderDir
  */
-function refreshUrlsLocalRegistryFromBuilder(projectRoot) {
-  const root = projectRoot || pathsUtil.getProjectRoot();
-  const merged = { ...readUrlsLocalRegistrySync() };
-  if (!root) {
-    return writeMergedRegistry(merged);
-  }
-  const builderDir = path.join(root, 'builder');
-  if (!fsRealSync.existsSync(builderDir) || !fsRealSync.statSync(builderDir).isDirectory()) {
-    return writeMergedRegistry(merged);
+function mergeBuilderDirIntoRegistry(merged, builderDir) {
+  if (!builderDir || !fsRealSync.existsSync(builderDir) || !fsRealSync.statSync(builderDir).isDirectory()) {
+    return;
   }
   for (const ent of fsRealSync.readdirSync(builderDir, { withFileTypes: true })) {
     if (!ent.isDirectory()) {
@@ -180,6 +173,37 @@ function refreshUrlsLocalRegistryFromBuilder(projectRoot) {
     }
     mergeDocIntoRegistry(merged, doc, ent.name);
   }
+}
+
+/**
+ * Merge scan results into registry (does not remove stale keys).
+ * @param {string|null} projectRoot - getProjectRoot() or null (same semantics as projectRoot || getProjectRoot())
+ * @returns {Object} Updated registry
+ */
+function refreshUrlsLocalRegistryFromBuilder(projectRoot) {
+  const root = projectRoot || pathsUtil.getProjectRoot();
+  const merged = { ...readUrlsLocalRegistrySync() };
+  if (!root) {
+    return writeMergedRegistry(merged);
+  }
+  // Published npm tarball omits builder/ under the package root (.npmignore). Global installs must
+  // still refresh from the real builder tree (AIFABRIX_BUILDER_DIR or integration base + builder).
+  const legacyBuilderDir = path.join(root, 'builder');
+  const effectiveBuilderDir = pathsUtil.getBuilderRoot();
+  const builderDirs = [legacyBuilderDir];
+  try {
+    if (
+      effectiveBuilderDir &&
+      path.resolve(effectiveBuilderDir) !== path.resolve(legacyBuilderDir)
+    ) {
+      builderDirs.push(effectiveBuilderDir);
+    }
+  } catch {
+    /* ignore path resolution errors */
+  }
+  for (const builderDir of builderDirs) {
+    mergeBuilderDirIntoRegistry(merged, builderDir);
+  }
   return writeMergedRegistry(merged);
 }
 

package/lib/utils/validation-run-poll.js

@@ -4,6 +4,8 @@
  * @version 2.0.0
  */
 
+const chalk = require('chalk');
+const logger = require('./logger');
 const { getValidationRunWithTransportRetry } = require('./validation-run-post-retry');
 
 const INITIAL_INTERVAL_MS = 2000;
@@ -23,6 +25,19 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+function maybeLogPollProgress(envelope, verbosePoll, lastProgressLogAtRef) {
+  if (!verbosePoll || !envelope || typeof envelope !== 'object') return;
+  const now = Date.now();
+  if (now - lastProgressLogAtRef[0] < 5000) return;
+  lastProgressLogAtRef[0] = now;
+  const st = envelope.status !== undefined && envelope.status !== null ? String(envelope.status) : '?';
+  const c =
+    envelope.reportCompleteness !== undefined && envelope.reportCompleteness !== null
+      ? String(envelope.reportCompleteness)
+      : '?';
+  logger.log(chalk.gray(`  Polling validation run… completeness=${c} status=${st}`));
+}
+
 /**
  * Whether polling should stop on this envelope.
  * @param {Object} envelope - DatasourceTestRun-like
@@ -42,6 +57,8 @@ function isTerminalReportCompleteness(envelope) {
  * @param {string} opts.testRunId
  * @param {number} opts.budgetMs - Remaining wall-clock budget for polls only (POST excluded)
  * @param {typeof getValidationRunWithTransportRetry} [opts.fetchRun] - Inject for tests (default: GET with transport retry)
+ * @param {boolean} [opts.verbosePoll] - Log throttled progress (plan §3.13)
+ * @param {number} [opts.pollRequestTimeoutMs] - Per-GET HTTP timeout (match validation aggregate budget)
  * @returns {Promise<{ envelope: Object|null, timedOut: boolean, lastApiResult: Object|null }>}
  */
 async function pollValidationRunUntilComplete(opts) {
@@ -50,18 +67,22 @@ async function pollValidationRunUntilComplete(opts) {
     authConfig,
     testRunId,
     budgetMs,
-    fetchRun = getValidationRunWithTransportRetry
+    fetchRun = getValidationRunWithTransportRetry,
+    verbosePoll = false,
+    pollRequestTimeoutMs
   } = opts;
+  const pollTransportOpts =
+    Number.isFinite(pollRequestTimeoutMs) && pollRequestTimeoutMs > 0
+      ? { timeoutMs: pollRequestTimeoutMs }
+      : {};
   const deadline = Date.now() + Math.max(0, budgetMs);
   let attempt = 0;
   let lastApiResult = null;
   let envelope = null;
+  const lastProgressLogAtRef = [0];
 
   while (Date.now() < deadline) {
-    const remaining = deadline - Date.now();
-    if (remaining <= 0) break;
-
-    lastApiResult = await fetchRun(dataplaneUrl, authConfig, testRunId);
+    lastApiResult = await fetchRun(dataplaneUrl, authConfig, testRunId, pollTransportOpts);
     if (!lastApiResult.success) {
       return { envelope: null, timedOut: false, lastApiResult };
     }
@@ -70,6 +91,8 @@ async function pollValidationRunUntilComplete(opts) {
       return { envelope, timedOut: false, lastApiResult };
     }
 
+    maybeLogPollProgress(envelope, verbosePoll, lastProgressLogAtRef);
+
     const delay = Math.min(nextPollDelayMs(attempt), Math.max(0, deadline - Date.now()));
     attempt += 1;
     if (delay > 0) {