@aifabrix/builder 2.44.3 → 2.44.4

package/lib/schema/type/document-storage.json

@@ -7,12 +7,12 @@
     "key": "document-storage-schema",
     "name": "Document Storage Configuration Schema",
     "description": "JSON schema for validating document storage configurations",
-    "version": "1.3.0",
+    "version": "1.7.0",
     "type": "schema",
     "category": "document-storage",
     "author": "AI Fabrix Team",
     "createdAt": "2026-01-02T00:00:00Z",
-    "updatedAt": "2026-04-22T00:00:00Z",
+    "updatedAt": "2026-05-01T00:00:00Z",
     "compatibility": {
       "minVersion": "1.0.0",
       "maxVersion": "2.0.0",
@@ -71,6 +71,38 @@
           "Added optional parameterLookupCoalesceNestedItemScope (boolean, default true) for manifest-controlled binary parameter lookup enrichment"
         ],
         "breaking": false
+      },
+      {
+        "version": "1.4.0",
+        "date": "2026-04-26T00:00:00Z",
+        "changes": [
+          "Added optional maxBinaryFetchesPerSync (integer >= 1) to cap binary fetch+store operations per sync run"
+        ],
+        "breaking": false
+      },
+      {
+        "version": "1.5.0",
+        "date": "2026-04-27T00:00:00Z",
+        "changes": [
+          "ingestAfterSync: post-sync chunk+embed no longer waits on trust (eligibility/schema gates unchanged)"
+        ],
+        "breaking": false
+      },
+      {
+        "version": "1.6.0",
+        "date": "2026-04-28T00:00:00Z",
+        "changes": [
+          "Added documentStorage.changeDetection.ignoreMetadataKeys / ignoreMetadataPaths for stable contentHash when volatile metadata changes"
+        ],
+        "breaking": false
+      },
+      {
+        "version": "1.7.0",
+        "date": "2026-05-01T00:00:00Z",
+        "changes": [
+          "Added optional maxBinaryFetchConcurrency (integer >= 1, default 1) to bound parallel binary fetches in two-phase sync phase 3"
+        ],
+        "breaking": false
       }
     ]
   },
@@ -95,7 +127,18 @@
     "ingestAfterSync": {
       "type": "boolean",
       "default": false,
-      "description": "When true, chunk and embed each document after store during sync so vector search returns hits immediately. When false, ingestion runs later (e.g. Celery task or on approval). Set true for E2E tests that validate vector step."
+      "description": "When true, chunk and embed each document after store during sync without requiring trust promotion first; eligibility (validation/schema/dimensions) still enforced. When false, ingestion runs later."
+    },
+    "maxBinaryFetchesPerSync": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "When set, caps binary fetch + store operations per sync run (metadata list may still return more rows). Optional for fast integration/E2E; omit in production for full sync."
+    },
+    "maxBinaryFetchConcurrency": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 1,
+      "description": "Maximum concurrent binary CIP/HTTP fetches during two-phase sync phase 3. Default 1 (sequential). Increase cautiously; external APIs may throttle."
     },
     "binaryOperationRef": {
       "type": "string",
@@ -133,6 +176,22 @@
       "default": true,
       "description": "When true, binary parameterMapping and HTTP path templates use a lookup view that merges metadata and coalesces storage-scope ids from a nested item parentReference when the row's parentReference omits them. Set false for strict manifest-only paths."
     },
+    "jsonNestedDownloadUrlKeys": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Optional JSON object key names (exact match) searched depth-first when a binary GET returns JSON without bytes; requires preAuthenticatedDownloadUrlHostSuffixAllowlist. Merged into binaryOperation when using binaryOperationRef."
+    },
+    "preAuthenticatedDownloadUrlHostSuffixAllowlist": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Substrings the discovered follow-up URL must contain (case-insensitive) before an unauthenticated GET. Required when jsonNestedDownloadUrlKeys is set."
+    },
     "processing": {
       "type": "object",
       "properties": {
@@ -219,6 +278,27 @@
         }
       },
       "additionalProperties": false
+    },
+    "changeDetection": {
+      "type": "object",
+      "description": "Optional configuration to ignore volatile metadata keys/paths during contentHash / change detection only.",
+      "properties": {
+        "ignoreMetadataKeys": {
+          "type": "array",
+          "description": "Top-level metadata keys to ignore when computing contentHash / change detection.",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true,
+          "default": []
+        },
+        "ignoreMetadataPaths": {
+          "type": "array",
+          "description": "Optional dot-path patterns to ignore (e.g. 'analytics.*', 'versions').",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true,
+          "default": []
+        }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": false

package/lib/utils/configuration-env-resolver.js

@@ -113,6 +113,43 @@ function resolveConfigurationValues(configArray, envMap, secrets, systemKey) {
   }
 }
 
+/**
+ * Collects `configuration[]` entry names with `location: "variable"` whose values look
+ * resolved for publish (literal strings: no `{{`, not `kv://`, non-empty). Used after
+ * `resolveConfigurationValues` mutates the upload payload.
+ *
+ * @param {{ application?: { configuration?: unknown[] }, dataSources?: unknown[] }} payload - Pipeline upload payload
+ * @returns {string[]} Unique names in encounter order (application first, then dataSources)
+ */
+function collectResolvedVariableConfigurationNames(payload) {
+  const out = [];
+  const seen = new Set();
+
+  function consider(arr) {
+    if (!Array.isArray(arr)) return;
+    for (const item of arr) {
+      if (!item || typeof item !== 'object') continue;
+      if (String(item.location || '').toLowerCase() !== 'variable') continue;
+      const name = item.name && String(item.name).trim();
+      if (!name || seen.has(name)) continue;
+      const val = item.value;
+      if (typeof val !== 'string') continue;
+      const trimmed = val.trim();
+      if (!trimmed) continue;
+      if (trimmed.startsWith('kv://')) continue;
+      if (trimmed.includes('{{')) continue;
+      seen.add(name);
+      out.push(name);
+    }
+  }
+
+  consider(payload?.application?.configuration);
+  for (const ds of payload?.dataSources || []) {
+    consider(ds?.configuration);
+  }
+  return out;
+}
+
 /**
  * Returns the set of variable names (keys) defined in env.template content.
  *
@@ -175,6 +212,7 @@ async function retemplateConfigurationForDownload(systemKey, configArray) {
 module.exports = {
   buildResolvedEnvMapForIntegration,
   resolveConfigurationValues,
+  collectResolvedVariableConfigurationNames,
   getEnvTemplateVariableNames,
   retemplateConfigurationFromEnvTemplate,
   retemplateConfigurationForDownload,

package/lib/utils/dataplane-resolver.js

@@ -17,11 +17,12 @@ const { discoverDataplaneUrl } = require('../commands/wizard-dataplane');
  * @param {string} controllerUrl - Controller URL
  * @param {string} environment - Environment key
  * @param {Object} authConfig - Authentication configuration
+ * @param {{ silent?: boolean }} [opts] - Passed to discoverDataplaneUrl
  * @returns {Promise<string>} Resolved dataplane URL
  * @throws {Error} If dataplane URL cannot be resolved
  */
-async function resolveDataplaneUrl(controllerUrl, environment, authConfig) {
-  return await discoverDataplaneUrl(controllerUrl, environment, authConfig);
+async function resolveDataplaneUrl(controllerUrl, environment, authConfig, opts = {}) {
+  return await discoverDataplaneUrl(controllerUrl, environment, authConfig, opts);
 }
 
 module.exports = {

package/lib/utils/datasource-test-run-capacity-operations.js

@@ -0,0 +1,149 @@
+/**
+ * @fileoverview Capacity scenario outcome lines for DatasourceTestRun TTY (shared by header + debug appendix).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const { successGlyph, failureGlyph } = require('./cli-test-layout-chalk');
+const {
+  getCipCapacityDisplayConfig,
+  standardOperationRank,
+  parseCapacityDetailKey
+} = require('./load-cip-capacity-display-config');
+
+/**
+ * @param {string} op
+ * @returns {string}
+ */
+function formatCapacityOperationLabel(op) {
+  const { aliases } = getCipCapacityDisplayConfig();
+  return (aliases && aliases[op]) || op;
+}
+
+/**
+ * @param {Object} envelope
+ * @returns {object|null}
+ */
+function findCapacityStep(envelope) {
+  const dbg = envelope && envelope.debug;
+  const e2e = dbg && dbg.e2eAsyncDebug;
+  const stepDebug = e2e && Array.isArray(e2e.stepDebug) ? e2e.stepDebug : [];
+  return stepDebug.find(s => s && String(s.name) === 'capacity') || null;
+}
+
+/**
+ * @param {object[]} rows
+ * @param {string} datasourceKey
+ * @returns {object[]}
+ */
+function filterCapacityDatasourceRows(rows, datasourceKey) {
+  if (!datasourceKey) return rows;
+  const matched = rows.filter(r => r && String(r.key) === datasourceKey);
+  return matched.length ? matched : rows;
+}
+
+/**
+ * @param {object[]} dsRows
+ * @returns {Map<string, { ok: boolean, error: string, minIndex: number }>}
+ */
+function mergeCapacityDetailsByOp(dsRows) {
+  /** @type {Map<string, { ok: boolean, error: string, minIndex: number }>} */
+  const byOp = new Map();
+  for (const ds of dsRows) {
+    const details = ds && Array.isArray(ds.capabilityDetails) ? ds.capabilityDetails : [];
+    for (const row of details) {
+      if (!row || row.key === undefined || row.key === null) continue;
+      const parsed = parseCapacityDetailKey(String(row.key));
+      if (!parsed) continue;
+      const { op, index } = parsed;
+      const ok = row.success !== false && !row.error;
+      const err = row.error ? String(row.error) : '';
+      const prev = byOp.get(op);
+      if (!prev) {
+        byOp.set(op, { ok, error: ok ? '' : err, minIndex: index });
+      } else {
+        byOp.set(op, {
+          ok: prev.ok && ok,
+          error: prev.error || err,
+          minIndex: Math.min(prev.minIndex, index)
+        });
+      }
+    }
+  }
+  return byOp;
+}
+
+/**
+ * @param {string[]} standardOrder
+ * @param {Map<string, { minIndex: number }>} byOp
+ * @returns {(a: string, b: string) => number}
+ */
+function capacityOpComparator(standardOrder, byOp) {
+  return (a, b) => {
+    const ia = byOp.get(a).minIndex;
+    const ib = byOp.get(b).minIndex;
+    if (ia !== ib) return ia - ib;
+    const ra = standardOperationRank(standardOrder, a);
+    const rb = standardOperationRank(standardOrder, b);
+    if (ra !== rb) return ra - rb;
+    return a.localeCompare(b);
+  };
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Map<string, { ok: boolean, error: string }>} byOp
+ * @param {string[]} opsSorted
+ */
+function appendCapacityOperationsLines(lines, byOp, opsSorted) {
+  lines.push('');
+  lines.push(chalk.blue.bold('Capacity operations:'));
+  for (const op of opsSorted) {
+    const row = byOp.get(op);
+    const label = formatCapacityOperationLabel(op);
+    const sym = row.ok ? successGlyph() : failureGlyph();
+    const tail = row.ok ? '' : chalk.red(` — ${row.error || 'failed'}`);
+    lines.push(`  ${sym} ${chalk.white(label)}${tail}`);
+  }
+}
+
+/**
+ * List capacity scenario outcomes from the capacity step (order: scenario index `#`, then schema op order).
+ * @param {string[]} lines
+ * @param {Object} envelope
+ */
+function pushCapacityOperationsSummaryLines(lines, envelope) {
+  const capStep = findCapacityStep(envelope);
+  if (!capStep || !capStep.evidence || !Array.isArray(capStep.evidence.datasources)) return;
+
+  const dk =
+    envelope && envelope.datasourceKey !== undefined && envelope.datasourceKey !== null
+      ? String(envelope.datasourceKey)
+      : '';
+  const dsRows = filterCapacityDatasourceRows(capStep.evidence.datasources, dk);
+  const byOp = mergeCapacityDetailsByOp(dsRows);
+  if (!byOp.size) return;
+
+  const { standardOrder } = getCipCapacityDisplayConfig();
+  const opsSorted = Array.from(byOp.keys()).sort(capacityOpComparator(standardOrder, byOp));
+  appendCapacityOperationsLines(lines, byOp, opsSorted);
+}
+
+/**
+ * @param {string} capacityKey
+ * @returns {string|null}
+ */
+function parseCapacityScenarioOp(capacityKey) {
+  const p = parseCapacityDetailKey(String(capacityKey));
+  return p ? p.op : null;
+}
+
+module.exports = {
+  pushCapacityOperationsSummaryLines,
+  formatCapacityOperationLabel,
+  parseCapacityScenarioOp,
+  parseCapacityDetailKey
+};

package/lib/utils/datasource-test-run-debug-display.js

@@ -6,6 +6,12 @@
 
 const { SEP, appendReferenceLayoutLines } = require('./datasource-test-run-display');
 const { buildDebugEnvelopeSlice } = require('./datasource-test-run-debug-slice');
+const {
+  pushCapacityOperationsSummaryLines,
+  parseCapacityScenarioOp,
+  parseCapacityDetailKey,
+  formatCapacityOperationLabel
+} = require('./datasource-test-run-capacity-operations');
 
 const FULL_MAX_BYTES_PER_STRING = 8192;
 const RAW_MAX_STRING_TTY = 65536;
@@ -74,9 +80,140 @@ function redactDebugText(text) {
     .replace(/("authorization"\s*:\s*")[^"]*(")/g, '$1[REDACTED]$2');
 }
 
+function getBestEffortStepList(envelope) {
+  const v = envelope && envelope.validation;
+  const metrics = v && v.metricsOutput;
+  const steps = metrics && Array.isArray(metrics.steps) ? metrics.steps : [];
+  if (steps.length) return steps;
+  const dbg = envelope && envelope.debug;
+  const stepDebug =
+    dbg && dbg.e2eAsyncDebug && Array.isArray(dbg.e2eAsyncDebug.stepDebug) ? dbg.e2eAsyncDebug.stepDebug : [];
+  return stepDebug;
+}
+
+function findStepByName(steps, name) {
+  return steps.find(s => s && String(s.name || s.step) === name);
+}
+
+function sumNumber(rows, key) {
+  return rows.reduce((acc, r) => acc + (Number(r && r[key]) || 0), 0);
+}
+
+function appendE2eWorkerHeadLine(lines, timing) {
+  const work = timing.durationSeconds;
+  if (work === undefined || work === null || work === '') return;
+  const w = Number(work);
+  if (Number.isNaN(w)) return;
+  let head = `E2E worker: ~${w.toFixed(3)}s`;
+  const wall = timing.wallClockSeconds;
+  if (wall !== undefined && wall !== null && wall !== '') {
+    const wl = Number(wall);
+    if (!Number.isNaN(wl)) {
+      head += ` (wall ~${wl.toFixed(3)}s)`;
+    }
+  }
+  lines.push(head);
+}
+
+function appendE2eStepDurationLines(lines, timing) {
+  const sd = timing.stepDurations;
+  if (!Array.isArray(sd) || !sd.length) return;
+  for (const row of sd) {
+    if (!row || typeof row !== 'object') continue;
+    const step = row.step !== undefined && row.step !== null ? String(row.step) : '?';
+    const sec =
+      row.durationSeconds !== undefined && row.durationSeconds !== null
+        ? Number(row.durationSeconds)
+        : NaN;
+    if (!Number.isNaN(sec)) {
+      lines.push(`  ${step}: ~${sec.toFixed(3)}s`);
+    }
+  }
+}
+
+function getFirstSyncJobPhaseTimings(e2e) {
+  const stepDebug = Array.isArray(e2e.stepDebug) ? e2e.stepDebug : [];
+  const syncStep = stepDebug.find(s => s && String(s.name) === 'sync');
+  const jobs = syncStep && syncStep.evidence && syncStep.evidence.jobs;
+  const first = Array.isArray(jobs) && jobs.length ? jobs[0] : null;
+  const audit = first && first.audit;
+  const pt = audit && typeof audit === 'object' ? audit.phaseTimingsSeconds : null;
+  return pt && typeof pt === 'object' ? pt : null;
+}
+
+function formatPhaseTimingParts(phaseTimings) {
+  const order = ['phase1', 'phase2', 'phase3', 'phase4'];
+  const parts = [];
+  for (const k of order) {
+    const raw = phaseTimings[k];
+    if (raw === undefined || raw === null) continue;
+    const v = Number(raw);
+    if (!Number.isNaN(v)) {
+      parts.push(`${k} ~${v.toFixed(3)}s`);
+    }
+  }
+  return parts;
+}
+
+function appendSyncPhaseTimingsFromE2e(lines, e2e) {
+  const phaseTimings = getFirstSyncJobPhaseTimings(e2e);
+  if (!phaseTimings) return;
+  const parts = formatPhaseTimingParts(phaseTimings);
+  if (parts.length) {
+    lines.push(`Sync phases (first job): ${parts.join(', ')}`);
+  }
+}
+
+/**
+ * E2E poll envelope: `debug.e2eAsyncDebug` from dataplane run store (timing + stepDebug).
+ * @param {string[]} lines
+ * @param {Object} envelope
+ */
+function pushE2eTimingSummaryLines(lines, envelope) {
+  const dbg = envelope && envelope.debug;
+  const e2e = dbg && dbg.e2eAsyncDebug;
+  if (!e2e || typeof e2e !== 'object') return;
+
+  const timing = e2e.timing;
+  if (timing && typeof timing === 'object') {
+    appendE2eWorkerHeadLine(lines, timing);
+    appendE2eStepDurationLines(lines, timing);
+  }
+  appendSyncPhaseTimingsFromE2e(lines, e2e);
+}
+
+function pushSyncSummaryLines(lines, envelope) {
+  const steps = getBestEffortStepList(envelope);
+  const syncStep = findStepByName(steps, 'sync');
+  const syncStatusStep = findStepByName(steps, 'sync_status');
+  const persistenceStep = findStepByName(steps, 'persistence');
+
+  if (syncStep && syncStep.evidence && Array.isArray(syncStep.evidence.jobs)) {
+    const jobs = syncStep.evidence.jobs;
+    const processed = sumNumber(jobs, 'recordsProcessed');
+    const total = sumNumber(jobs, 'totalRecords');
+    lines.push(`Sync: ${processed}/${total} processed`);
+  }
+  if (syncStatusStep && syncStatusStep.evidence && Array.isArray(syncStatusStep.evidence.datasources)) {
+    const rows = syncStatusStep.evidence.datasources;
+    const total = sumNumber(rows, 'totalRecords');
+    const active = sumNumber(rows, 'activeRecords');
+    lines.push(`Sync status: ${active}/${total} active`);
+  }
+  if (persistenceStep && persistenceStep.evidence && persistenceStep.evidence.recordCount !== undefined) {
+    lines.push(`Persistence: ${persistenceStep.evidence.recordCount} record(s)`);
+  }
+}
+
 function pushSummaryRefLines(lines, envelope) {
   const before = lines.length;
-  appendReferenceLayoutLines(lines, envelope, { maxRefChars: 600 });
+  try {
+    pushSyncSummaryLines(lines, envelope);
+    pushE2eTimingSummaryLines(lines, envelope);
+  } catch {
+    // ignore best-effort debug summary extraction
+  }
+  appendReferenceLayoutLines(lines, envelope, { maxRefChars: 600, includeDebugMeta: true });
   if (lines.length === before) {
     lines.push('(No audit or debug references on this report.)');
   }
@@ -130,6 +267,11 @@ module.exports = {
   resolveDebugDisplayMode,
   truncateUtf8String,
   formatDatasourceTestRunDebugBlock,
+  pushE2eTimingSummaryLines,
+  pushCapacityOperationsSummaryLines,
+  parseCapacityScenarioOp,
+  parseCapacityDetailKey,
+  formatCapacityOperationLabel,
   FULL_MAX_BYTES_PER_STRING,
   RAW_MAX_STRING_TTY,
   RAW_MAX_STRING_PIPE,

package/lib/utils/datasource-test-run-display.js

@@ -7,12 +7,23 @@
 const chalk = require('chalk');
 const { sectionTitle, headerKeyValue, colorAggregateGlyph, successGlyph, failureGlyph } = require('./cli-test-layout-chalk');
 const { appendCertificateTTY } = require('./datasource-test-run-certificate-tty');
+const { buildTtyMetaLines: buildTtyMetaLinesCore } = require('./datasource-test-run-tty-meta-lines');
 
 const SEP = '────────────────────────────────';
 
 /** @type {number} */
 const DEFAULT_MAX_REF_CHARS = 200;
 
+// UI-only: round float seconds tokens like "1.1713749s" -> "1.171s".
+function formatSecondsText(text) {
+  const txt = String(text);
+  return txt.replace(/(\d+\.\d+)(?=s\b)/g, m => {
+    const n = Number(m);
+    if (!Number.isFinite(n)) return m;
+    return n.toFixed(3);
+  });
+}
+
 /**
  * @param {'ok'|'warn'|'fail'|'skipped'} status
  * @returns {string}
@@ -144,23 +155,11 @@ function formatCapabilityFocusSection(envelope, focusKey) {
 
 /**
  * @param {Object} envelope
+ * @param {{ includeDebugExecutionSummary?: boolean }} [ttyOptions]
  * @returns {string[]}
  */
-function buildTtyMetaLines(envelope) {
-  const lines = [];
-  lines.push(
-    headerKeyValue('Datasource:', `${envelope.datasourceKey} (${envelope.systemKey})`)
-  );
-  lines.push(headerKeyValue('Run:', String(envelope.runType)));
-  lines.push(formatEnvelopeStatusLine(envelope));
-  const rid = envelope.runId || envelope.testRunId;
-  if (rid) lines.push(`${chalk.gray('Run ID:')} ${chalk.cyan(String(rid))}`);
-  if (envelope.reportCompleteness && envelope.reportCompleteness !== 'full') {
-    lines.push(
-      `${chalk.gray('Report:')} ${chalk.yellow(String(envelope.reportCompleteness))}`
-    );
-  }
-  return lines;
+function buildTtyMetaLines(envelope, ttyOptions = {}) {
+  return buildTtyMetaLinesCore(envelope, formatEnvelopeStatusLine, ttyOptions);
 }
 
 /**
@@ -236,16 +235,6 @@ function appendDebugPayloadRefLines(lines, dbg, maxRefChars) {
  */
 function appendDebugMetaLines(lines, dbg, maxRefChars) {
   let added = false;
-  function formatSecondsText(s) {
-    const txt = String(s);
-    // UI-only: reduce noisy float seconds to 3 decimals, e.g. "1.1713749s" -> "1.171s".
-    // Applies only to number tokens immediately followed by "s".
-    return txt.replace(/(\d+\.\d+)(?=s\b)/g, m => {
-      const n = Number(m);
-      if (!Number.isFinite(n)) return m;
-      return n.toFixed(3);
-    });
-  }
   if (dbg.mode) {
     lines.push(
       `${chalk.blue.bold('debug.mode:')} ${chalk.white(String(dbg.mode))}`
@@ -272,6 +261,7 @@ function appendDebugMetaLines(lines, dbg, maxRefChars) {
  */
 function appendReferenceLayoutLines(lines, envelope, opts = {}) {
   const maxRefChars = opts.maxRefChars ?? DEFAULT_MAX_REF_CHARS;
+  const includeDebugMeta = opts.includeDebugMeta === true;
   const audit = envelope && envelope.audit;
   const dbg = envelope && envelope.debug;
   const parts = [];
@@ -287,7 +277,9 @@ function appendReferenceLayoutLines(lines, envelope, opts = {}) {
 
   if (dbg && typeof dbg === 'object') {
     parts.push(appendStringRefBlock(lines, 'debug.executionIds:', dbg.executionIds, maxRefChars));
-    parts.push(appendDebugMetaLines(lines, dbg, maxRefChars));
+    if (includeDebugMeta) {
+      parts.push(appendDebugMetaLines(lines, dbg, maxRefChars));
+    }
   }
 
   return parts.some(Boolean);
@@ -329,6 +321,8 @@ function appendIntegrationStepLines(lines, envelope) {
   const integ = envelope && envelope.integration;
   const steps = integ && Array.isArray(integ.stepResults) ? integ.stepResults : [];
   if (!steps.length) return;
+  lines.push('');
+  lines.push(chalk.gray(SEP));
   lines.push(sectionTitle('Integration steps:'));
   for (const st of steps) {
     lines.push(formatIntegrationStepLine(st));
@@ -422,22 +416,27 @@ function formatDatasourceTestRunSummary(envelope, options = {}) {
 /**
  * Default TTY block (header + verdict line + short summary + optional completeness).
  * @param {Object} envelope
- * @param {{ focusCapabilityKey?: string }} [options] - When set (e.g. --capability), append single-cap block (plan §2.3).
+ * @param {{
+ *   focusCapabilityKey?: string,
+ *   includeRefs?: boolean,
+ *   includeDebugExecutionSummary?: boolean
+ * }} [options] - When focusCapabilityKey set (e.g. --capability), append single-cap block (plan §2.3).
+ *   includeDebugExecutionSummary: show dataplane `debug.executionSummary` in header (TTY debug appendix uses CLI `--debug`).
  * @returns {string}
  */
 function formatDatasourceTestRunTTY(envelope, options = {}) {
   if (!envelope || typeof envelope !== 'object') return '';
-  const lines = [...buildTtyMetaLines(envelope)];
+  const lines = [
+    ...buildTtyMetaLines(envelope, {
+      includeDebugExecutionSummary: options.includeDebugExecutionSummary === true
+    })
+  ];
   appendNoCapabilitiesReportedLine(lines, envelope, options);
   lines.push('');
   lines.push(sectionTitle('Verdict:'));
   lines.push(chalk.white(pickExecutiveVerdictLine(envelope)));
   appendCertificateTTY(lines, envelope);
-  lines.push('');
-  lines.push(chalk.gray(SEP));
-  if (appendReferenceLayoutLines(lines, envelope, { maxRefChars: 160 })) {
-    lines.push('');
-  }
+  appendRefsSectionIfEnabled(lines, envelope, options);
   appendValidationIssueLines(lines, envelope);
   appendIntegrationStepLines(lines, envelope);
   const focus = normalizedFocusCapabilityKey(options.focusCapabilityKey);
@@ -447,6 +446,20 @@ function formatDatasourceTestRunTTY(envelope, options = {}) {
   return lines.join('\n');
 }
 
+function appendRefsSectionIfEnabled(lines, envelope, options) {
+  if (options.includeRefs !== true) return;
+  const before = lines.length;
+  lines.push('');
+  lines.push(chalk.gray(SEP));
+  const added = appendReferenceLayoutLines(lines, envelope, { maxRefChars: 160, includeDebugMeta: false });
+  if (added) {
+    lines.push('');
+    return;
+  }
+  // remove the blank + separator when no refs exist
+  lines.length = before;
+}
+
 module.exports = {
   formatDatasourceTestRunSummary,
   formatDatasourceTestRunTTY,

package/lib/utils/datasource-test-run-tty-log.js

@@ -42,7 +42,12 @@ function emitCapabilityScopeDiagnostics(envelope, opts = {}) {
  * @param {string} [options.requestedCapabilityKey]
  */
 function printDatasourceTestRunForTTY(envelope, options = {}) {
-  const displayOpts = { focusCapabilityKey: options.requestedCapabilityKey };
+  const mode = resolveDebugDisplayMode(options.debug);
+  const displayOpts = {
+    focusCapabilityKey: options.requestedCapabilityKey,
+    includeRefs: Boolean(mode),
+    includeDebugExecutionSummary: Boolean(mode)
+  };
   if (options.json) {
     logger.log(JSON.stringify(envelope));
     return;
@@ -52,7 +57,6 @@ function printDatasourceTestRunForTTY(envelope, options = {}) {
   } else {
     logger.log(formatDatasourceTestRunTTY(envelope, displayOpts));
   }
-  const mode = resolveDebugDisplayMode(options.debug);
   if (mode) {
     const appendix = formatDatasourceTestRunDebugBlock(envelope, mode, process.stdout.isTTY);
     if (appendix) logger.log(appendix);