@aifabrix/builder 2.51.1 → 2.52.1

package/lib/role-assistant/knowledge-sync.js

@@ -12,8 +12,6 @@ const path = require('path');
 const crypto = require('crypto');
 const fs = require('../internal/fs-real-sync');
 const yaml = require('js-yaml');
-const logger = require('../utils/logger');
-const { formatSuccessLine, formatWarningLine, metadata } = require('../utils/cli-test-layout-chalk');
 const { listDocuments, validateDocuments, bulkDocuments } = require('../api/datasources-extended.api');
 const {
   extractDocumentStorageKeyFromAssistantDetails,
@@ -28,6 +26,15 @@ const {
   resolveDocumentStorageKeyFromRoleAssistantSettings,
   resolveRoleAssistantEnvironmentSettings
 } = require('./settings');
+const {
+  knowledgeSearchMetadataFromFrontmatter,
+  splitMarkdownFrontmatter
+} = require('./knowledge-markdown-frontmatter');
+const {
+  logKnowledgeImportSummary,
+  logDocumentStorageSettingsPushSummary,
+  logKnowledgeExportSummary
+} = require('./knowledge-sync-logging');
 
 function resolveSystemNode(input) {
   if (!input || typeof input !== 'object') {
@@ -76,44 +83,91 @@ async function resolveDocumentStorageKeyFromDataplane(dataplaneUrl, authConfig,
 }
 
 /**
- * Push role-assistant.yaml knowledge.documentStorageKey to dataplane Assistants settings.
+ * Map role-assistant.yaml debug.* → Assistants settings PATCH fields.
+ * includePromptTrace → fullDebugEnabled (LLM prompt capture gate).
+ * enabled → debugEnabled (runtime debug traces).
+ * @param {Object|null|undefined} debugSection
+ * @returns {{ debugEnabled?: boolean, fullDebugEnabled?: boolean }}
+ */
+function mapRoleAssistantDebugToAssistantsSettings(debugSection) {
+  if (!debugSection || typeof debugSection !== 'object') {
+    return {};
+  }
+  const body = {};
+  if (typeof debugSection.enabled === 'boolean') {
+    body.debugEnabled = debugSection.enabled;
+  }
+  if (typeof debugSection.includePromptTrace === 'boolean') {
+    body.fullDebugEnabled = debugSection.includePromptTrace;
+  }
+  return body;
+}
+
+/**
+ * Push role-assistant.yaml knowledge + debug settings to dataplane Assistants.
  * Called on upload/deploy so the operator UI and CLI stay aligned.
  */
-async function pushRoleAssistantDocumentStorageSettings(params) {
+function resolveAssistantSettingsPush(params) {
   const {
     systemKey,
-    dataplaneUrl,
-    authConfig,
     environment = 'dev',
-    pathOptions = {},
-    dryRun = false
+    pathOptions = {}
   } = params;
   const settingsEnv = resolveRoleAssistantSettingsEnvKey(environment);
   const settings = readRoleAssistantSettings(systemKey, { required: false, pathOptions });
   if (!settings) {
-    return { skipped: true, reason: 'missing-role-assistant-settings' };
+    return { result: { skipped: true, reason: 'missing-role-assistant-settings' } };
   }
   const section = resolveRoleAssistantEnvironmentSettings(settings, settingsEnv, {
     required: false
   });
   if (!section) {
-    return { skipped: true, reason: 'missing-env-settings' };
+    return { result: { skipped: true, reason: 'missing-env-settings' } };
   }
   const documentStorageKey =
     resolveDocumentStorageKeyFromRoleAssistantSettings(settings, settingsEnv) || '';
-  if (dryRun) {
+  const debugBody = mapRoleAssistantDebugToAssistantsSettings(section.debug);
+  if (!documentStorageKey && Object.keys(debugBody).length === 0) {
+    return { result: { skipped: true, reason: 'no-document-storage-key', documentStorageKey: null } };
+  }
+  const patchBody = { ...debugBody };
+  if (documentStorageKey) {
+    patchBody.documentStorageKey = documentStorageKey;
+  }
+  return { documentStorageKey, debugBody, patchBody };
+}
+
+async function applyAssistantSettingsPush(dataplaneUrl, systemKey, authConfig, settingsPush) {
+  const { documentStorageKey, debugBody, patchBody } = settingsPush;
+  const hasDocumentStorageKey = documentStorageKey !== '';
+  const hasDebugSettings = Object.keys(debugBody).length > 0;
+  let response = await updateAssistantSettings(
+    dataplaneUrl,
+    systemKey,
+    authConfig,
+    patchBody
+  );
+  if (response && response.success === false && hasDocumentStorageKey && hasDebugSettings) {
+    response = await updateAssistantSettings(
+      dataplaneUrl,
+      systemKey,
+      authConfig,
+      debugBody
+    );
+    if (response && response.success === false) {
+      throw new Error(
+        response.formattedError ||
+          response.error ||
+          'Failed to update Assistants debug settings'
+      );
+    }
     return {
       skipped: false,
-      dryRun: true,
-      documentStorageKey: documentStorageKey || null
+      documentStorageKey: null,
+      documentStoragePushFailed: true,
+      ...debugBody
     };
   }
-  if (!dataplaneUrl || !authConfig) {
-    return { skipped: true, reason: 'missing-dataplane-auth' };
-  }
-  const response = await updateAssistantSettings(dataplaneUrl, systemKey, authConfig, {
-    documentStorageKey
-  });
   if (response && response.success === false) {
     throw new Error(
       response.formattedError ||
@@ -123,10 +177,27 @@ async function pushRoleAssistantDocumentStorageSettings(params) {
   }
   return {
     skipped: false,
-    documentStorageKey: documentStorageKey || null
+    documentStorageKey: documentStorageKey || null,
+    ...debugBody
   };
 }
 
+async function pushRoleAssistantDocumentStorageSettings(params) {
+  const { systemKey, dataplaneUrl, authConfig, dryRun = false } = params;
+  const settingsPush = resolveAssistantSettingsPush(params);
+  if (settingsPush.result) {
+    return settingsPush.result;
+  }
+  const { documentStorageKey, debugBody } = settingsPush;
+  if (dryRun) {
+    return { skipped: false, dryRun: true, documentStorageKey: documentStorageKey || null, ...debugBody };
+  }
+  if (!dataplaneUrl || !authConfig) {
+    return { skipped: true, reason: 'missing-dataplane-auth' };
+  }
+  return applyAssistantSettingsPush(dataplaneUrl, systemKey, authConfig, settingsPush);
+}
+
 /**
  * Resolve Knowledge document storage key.
  * Order: role-assistant.yaml → dataplane Assistants settings → package dataSources.
@@ -182,20 +253,27 @@ function normalizeDocumentExternalId(knowledgeRoot, filePath) {
 }
 
 function buildDocumentRecord(knowledgeRoot, filePath) {
-  const content = fs.readFileSync(filePath, 'utf8');
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = splitMarkdownFrontmatter(raw);
+  const searchMeta = knowledgeSearchMetadataFromFrontmatter(frontmatter);
   const externalId = normalizeDocumentExternalId(knowledgeRoot, filePath);
-  const title = path.basename(externalId);
+  const title =
+    (typeof searchMeta.title === 'string' && searchMeta.title) || path.basename(externalId);
+  const content = typeof body === 'string' ? body : raw;
   const contentHash = crypto.createHash('sha256').update(content, 'utf8').digest('hex');
   const metadata = {
     externalId,
-    title,
     mimeType: 'text/markdown',
     sourcePath: path.relative(knowledgeRoot, filePath).replace(/\\/g, '/'),
-    sourceType: 'role-assistant-markdown'
+    sourceType: 'role-assistant-markdown',
+    ...searchMeta,
+    title
   };
   return {
     key: externalId,
-    name: title,
+    // Prefer sourcePath (*.md) so binary storage uses a known markdown extension
+    // instead of inventing ".guide" from path-like keys or titles.
+    name: metadata.sourcePath || `${externalId}.md`,
     contentHash,
     metadata,
     binaryBase64: Buffer.from(content, 'utf8').toString('base64'),
@@ -388,74 +466,11 @@ async function exportRoleAssistantKnowledge(params) {
   return { skipped: false, datasourceKey, count: rows.length, knowledgePath, settingsPath };
 }
 
-function logKnowledgeImportSummary(systemKey, result, options = {}) {
-  if (result.skipped) {
-    if (options.verbose === true) {
-      logger.log(metadata(`Knowledge sync skipped (${systemKey}): ${result.reason}`));
-    }
-    return;
-  }
-  if (result.dryRun) {
-    logger.log(
-      formatWarningLine(
-        `Role assistant knowledge dry-run: ${result.fileCount} file(s), ${result.recordCount} record(s), datasource ${result.datasourceKey}`
-      )
-    );
-    return;
-  }
-  logger.log(
-    formatSuccessLine(
-      `Role assistant knowledge synced (${result.datasourceKey}): ${result.recordCount} record(s) from ${result.fileCount} file(s).`
-    )
-  );
-}
-
-function logDocumentStorageSettingsPushSummary(systemKey, result, options = {}) {
-  if (result.skipped) {
-    if (options.verbose === true) {
-      logger.log(
-        metadata(`Knowledge document storage settings skipped (${systemKey}): ${result.reason}`)
-      );
-    }
-    return;
-  }
-  if (result.dryRun) {
-    logger.log(
-      formatWarningLine(
-        `Knowledge document storage settings dry-run (${systemKey}): ${
-          result.documentStorageKey || '(clear)'
-        }`
-      )
-    );
-    return;
-  }
-  logger.log(
-    formatSuccessLine(
-      `Knowledge document storage settings updated (${systemKey}): ${
-        result.documentStorageKey || '(cleared)'
-      }`
-    )
-  );
-}
-
-function logKnowledgeExportSummary(systemKey, result, options = {}) {
-  if (result.skipped) {
-    if (options.verbose === true) {
-      logger.log(metadata(`Knowledge export skipped (${systemKey}): ${result.reason}`));
-    }
-    return;
-  }
-  logger.log(
-    formatSuccessLine(
-      `Role assistant knowledge exported (${result.datasourceKey}): ${result.count} document(s) to ${result.knowledgePath}.`
-    )
-  );
-}
-
 module.exports = {
   isDigitalWorkerModel,
   resolveRoleAssistantSettingsEnvKey,
   resolveRoleAssistantDocumentStorageKey,
+  mapRoleAssistantDebugToAssistantsSettings,
   pushRoleAssistantDocumentStorageSettings,
   importRoleAssistantKnowledge,
   exportRoleAssistantKnowledge,

package/lib/role-assistant/test-cases-bid.js

@@ -0,0 +1,155 @@
+/**
+ * Evaluate expected.bid assertions for suite 002 hard GP.
+ * @fileoverview BID emission / apply expectation checks
+ */
+
+'use strict';
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function softWrap(assertion, soft) {
+  if (!assertion || assertion.passed || !soft) {
+    return assertion;
+  }
+  return {
+    ...assertion,
+    passed: true,
+    soft: true,
+    warn: true,
+    message: `${assertion.message} (soft — warning only)`
+  };
+}
+
+function findInteraction(interactions, type) {
+  return asArray(interactions).find((row) => row && row.type === type) || null;
+}
+
+function pushBidAssertion(assertions, soft, id, passed, okMsg, failMsg) {
+  assertions.push(
+    softWrap(
+      {
+        id,
+        passed,
+        message: passed ? okMsg : failMsg
+      },
+      soft
+    )
+  );
+}
+
+function hasEmitOrApply(observed) {
+  return Boolean(observed.emitRow || observed.applyRow || observed.emitted);
+}
+
+function collectBidSchemaAssertions(expectedBid, observed, assertions, soft) {
+  const { emitRow, applyRow, emitted } = observed;
+  if (expectedBid.schemaName) {
+    const actualSchema = (emitted && emitted.schemaName) || expectedBid.schemaName;
+    pushBidAssertion(
+      assertions,
+      soft,
+      'expected.bid.schemaName',
+      hasEmitOrApply(observed) && actualSchema === expectedBid.schemaName,
+      `BID schemaName observed (${expectedBid.schemaName}).`,
+      `BID schemaName "${expectedBid.schemaName}" not observed in suite emit/apply.`
+    );
+  }
+  if (expectedBid.schemaVersion) {
+    const version = emitted && emitted.schemaVersion;
+    const versionOk =
+      version === null || version === undefined || version === expectedBid.schemaVersion;
+    pushBidAssertion(
+      assertions,
+      soft,
+      'expected.bid.schemaVersion',
+      hasEmitOrApply({ emitRow, applyRow, emitted }) && versionOk,
+      `BID schemaVersion "${expectedBid.schemaVersion}" accepted.`,
+      `BID schemaVersion "${expectedBid.schemaVersion}" not observed.`
+    );
+  }
+}
+
+function assertDefinitionHash(expectedBid, observed, assertions, soft) {
+  if (expectedBid.requireDefinitionHash !== true) {
+    return;
+  }
+  const { emitRow, applyRow, emitted } = observed;
+  const hash =
+    (emitted && emitted.definitionHash) ||
+    (emitRow && emitRow.definitionHash) ||
+    (applyRow && applyRow.definitionHash) ||
+    '';
+  pushBidAssertion(
+    assertions,
+    soft,
+    'expected.bid.requireDefinitionHash',
+    typeof hash === 'string' && hash.startsWith('sha256:'),
+    `BID definitionHash present (${String(hash).slice(0, 18)}…).`,
+    'BID definitionHash (sha256:…) not observed on emit/apply.'
+  );
+}
+
+function assertSuiteRunId(expectedBid, observed, assertions, soft) {
+  if (expectedBid.requireSuiteRunId !== true) {
+    return;
+  }
+  const { emitRow, applyRow, emitted } = observed;
+  const suiteRunId =
+    (emitted && emitted.meta && emitted.meta.suiteRunId) ||
+    (emitRow && emitRow.suiteRunId) ||
+    (applyRow && applyRow.suiteRunId) ||
+    '';
+  pushBidAssertion(
+    assertions,
+    soft,
+    'expected.bid.requireSuiteRunId',
+    Boolean(String(suiteRunId).trim()),
+    `BID suiteRunId present (${suiteRunId}).`,
+    'BID meta.suiteRunId not observed on emit/apply.'
+  );
+}
+
+function collectBidProvenanceAssertions(expectedBid, observed, assertions, soft) {
+  assertDefinitionHash(expectedBid, observed, assertions, soft);
+  assertSuiteRunId(expectedBid, observed, assertions, soft);
+}
+
+function collectBidPathAssertions(expectedBid, observed, assertions, soft) {
+  if (expectedBid.forbidGoldPaths === true) {
+    const { emitRow, applyRow, emitted } = observed;
+    const blob = JSON.stringify(emitted || emitRow || applyRow || {});
+    const banned = /test-e2e-hubspot|knownPlatform|gold-package/i.test(blob);
+    pushBidAssertion(
+      assertions,
+      soft,
+      'expected.bid.forbidGoldPaths',
+      !banned,
+      'BID trail has no gold/knownPlatform generation paths.',
+      'BID trail references forbidden gold/knownPlatform generation paths.'
+    );
+  }
+}
+
+function collectBidAssertions(expectedBid, observation, options = {}) {
+  if (!expectedBid || typeof expectedBid !== 'object') {
+    return [];
+  }
+  const interactions = asArray(observation.interactions || observation.workInteractions);
+  const observed = {
+    emitRow: findInteraction(interactions, 'bid-emit'),
+    applyRow: findInteraction(interactions, 'bid-apply'),
+    emitted: observation.emittedBid || null
+  };
+  const assertions = [];
+  const soft = options.soft === true;
+  collectBidSchemaAssertions(expectedBid, observed, assertions, soft);
+  collectBidProvenanceAssertions(expectedBid, observed, assertions, soft);
+  collectBidPathAssertions(expectedBid, observed, assertions, soft);
+  return assertions;
+}
+
+module.exports = {
+  collectBidAssertions
+};

package/lib/role-assistant/test-cases-evaluate.js

@@ -9,6 +9,7 @@ const {
   buildHonestyObservation,
   evaluateHonestyExpectations
 } = require('./test-cases-honesty');
+const { collectBidAssertions } = require('./test-cases-bid');
 
 function getValueAtPath(obj, dottedPath) {
   const parts = String(dottedPath || '').split('.').filter(Boolean);
@@ -109,7 +110,13 @@ function buildCaseObservation(result, lifecycleVerdict, portalUrl) {
     processExecutionId: result?.processExecutionId || null,
     workResult,
     workResultError: result?.workResultError || null,
-    honesty: buildHonestyObservation(workResult)
+    honesty: buildHonestyObservation(workResult),
+    interactions: Array.isArray(result?.interactions)
+      ? result.interactions
+      : Array.isArray(result?.workInteractions)
+        ? result.workInteractions
+        : [],
+    emittedBid: result?.emittedBid || null
   };
 }
 
@@ -146,6 +153,7 @@ function collectCaseAssertions(expected, observation) {
   assertions.push(...evaluateFactExpectations(expected.facts, observation));
   assertions.push(...evaluateProhibitedExpectations(expected.prohibited, observation));
   assertions.push(...evaluateHonestyExpectations(expected.honesty, observation, { soft }));
+  assertions.push(...collectBidAssertions(expected.bid, observation, { soft }));
   return assertions;
 }
 

package/lib/role-assistant/test-cases-honesty.js

@@ -68,7 +68,18 @@ function buildHonestyObservation(workResult) {
   };
 }
 
-function pushHonestyAssertion(assertions, id, passed, message) {
+function pushHonestyAssertion(assertions, id, passed, message, options = {}) {
+  const soft = options.soft === true;
+  if (soft && !passed) {
+    assertions.push({
+      id,
+      passed: true,
+      soft: true,
+      warn: true,
+      message: `${message} (soft — warning only)`
+    });
+    return;
+  }
   assertions.push({ id, passed, message });
 }
 
@@ -87,7 +98,7 @@ function assertWorkResultPresent(assertions, honesty, observation) {
   );
 }
 
-function assertSchemaVersion(assertions, honestySpec, honesty) {
+function assertSchemaVersion(assertions, honestySpec, honesty, soft) {
   if (!honestySpec.schemaVersion) {
     return;
   }
@@ -99,11 +110,12 @@ function assertSchemaVersion(assertions, honestySpec, honesty) {
     passed,
     passed
       ? `schemaVersion matched "${expected}".`
-      : `schemaVersion expected "${expected}" but got ${JSON.stringify(honesty.schemaVersion)}.`
+      : `schemaVersion expected "${expected}" but got ${JSON.stringify(honesty.schemaVersion)}.`,
+    { soft }
   );
 }
 
-function assertCompletion(assertions, honestySpec, honesty) {
+function assertCompletion(assertions, honestySpec, honesty, soft) {
   if (honestySpec.requireCompletion === false) {
     return;
   }
@@ -115,11 +127,12 @@ function assertCompletion(assertions, honestySpec, honesty) {
     stateOk && goalOk,
     stateOk && goalOk
       ? `completion.state/goalStatus honest (${honesty.completionState}/${honesty.goalStatus}).`
-      : `completion missing or invalid: state=${JSON.stringify(honesty.completionState)} goalStatus=${JSON.stringify(honesty.goalStatus)}.`
+      : `completion missing or invalid: state=${JSON.stringify(honesty.completionState)} goalStatus=${JSON.stringify(honesty.goalStatus)}.`,
+    { soft }
   );
 }
 
-function assertContribution(assertions, honestySpec, honesty) {
+function assertContribution(assertions, honestySpec, honesty, soft) {
   if (honestySpec.requireContributionObservation === false) {
     return;
   }
@@ -130,7 +143,8 @@ function assertContribution(assertions, honestySpec, honesty) {
     ok,
     ok
       ? `contributionObservation.status honest (${honesty.contributionStatus}).`
-      : `contributionObservation.status missing or invalid: ${JSON.stringify(honesty.contributionStatus)}.`
+      : `contributionObservation.status missing or invalid: ${JSON.stringify(honesty.contributionStatus)}.`,
+    { soft }
   );
 }
 
@@ -171,9 +185,9 @@ function evaluateHonestyExpectations(honestySpec, observation, options = {}) {
     // Missing Output is always a hard failure when required — soft does not waive it.
     return assertions;
   }
-  assertSchemaVersion(assertions, honestySpec, honesty);
-  assertCompletion(assertions, honestySpec, honesty);
-  assertContribution(assertions, honestySpec, honesty);
+  assertSchemaVersion(assertions, honestySpec, honesty, soft);
+  assertCompletion(assertions, honestySpec, honesty, soft);
+  assertContribution(assertions, honestySpec, honesty, soft);
   assertMinResourceChanges(assertions, honestySpec, honesty, soft);
   return assertions;
 }

package/lib/role-assistant/test-cases.js

@@ -331,6 +331,32 @@ function collectCapabilitiesFromWorkSteps(out, steps) {
   }
 }
 
+/**
+ * Work-result artifactIndex often carries CIP fingerprints like
+ * `capabilityKey=customer.createBasic|operationId=createbasic` when steps[] is empty.
+ * @param {Set<string>} out
+ * @param {unknown} artifacts
+ */
+function collectCapabilitiesFromArtifactIndex(out, artifacts) {
+  if (!Array.isArray(artifacts)) return;
+  for (const row of artifacts) {
+    if (!row || typeof row !== 'object') continue;
+    addCapabilityToken(out, row.capabilityKey);
+    addCapabilityToken(out, row.capability);
+    const fingerprint = typeof row.fingerprint === 'string' ? row.fingerprint : '';
+    const match = fingerprint.match(/(?:^|[|,])capabilityKey=([^|,]+)/);
+    if (match) {
+      addCapabilityToken(out, match[1]);
+    }
+    const artifactRef = typeof row.artifactRef === 'string' ? row.artifactRef : '';
+    // cip-log:fallback:customer.create:create:<id>
+    const refMatch = artifactRef.match(/^cip-log:[^:]+:([^:]+):/);
+    if (refMatch) {
+      addCapabilityToken(out, refMatch[1]);
+    }
+  }
+}
+
 function collectObservedCapabilities(result) {
   const out = new Set();
   const steps = Array.isArray(result?.stepsRun) ? result.stepsRun : [];
@@ -341,6 +367,8 @@ function collectObservedCapabilities(result) {
   }
   collectCapabilitiesFromWorkSteps(out, result?.steps);
   collectCapabilitiesFromWorkSteps(out, result?.workResult?.steps);
+  collectCapabilitiesFromArtifactIndex(out, result?.workResult?.artifactIndex);
+  collectCapabilitiesFromArtifactIndex(out, result?.artifactIndex);
   addCapabilityToken(out, result?.task?.capabilityKey);
   addCapabilityToken(out, result?.task?.capability);
   if (result?.task?.approvalContext && typeof result.task.approvalContext === 'object') {

package/lib/role-assistant/test-runner-bid-apply.js

@@ -0,0 +1,122 @@
+/**
+ * Soft-loop BID apply after workspace.createsystem (suite 002 / plan 512.4).
+ * @fileoverview Apply input.bidPath into builder-api workspace when Runtime COM
+ * cannot yet invoke template.applyintegrationdefinition (RA facade not refreshed).
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+const {
+  loadCaseBidDocument,
+  resolveTargetSystemKey
+} = require('./test-runner-bid-document');
+
+/**
+ * @returns {string}
+ */
+function resolveBuilderApiBaseUrl() {
+  const fromEnv = String(process.env.BUILDER_API_URL || process.env.BUILDER_URL || '').trim();
+  if (fromEnv) {
+    return fromEnv.replace(/\/$/, '');
+  }
+  let developerId = 0;
+  try {
+    const yaml = require('js-yaml');
+    const cfgPath = path.join(
+      process.env.HOME || '',
+      '.aifabrix',
+      'config.yaml'
+    );
+    if (fs.existsSync(cfgPath)) {
+      const cfg = yaml.load(fs.readFileSync(cfgPath, 'utf8')) || {};
+      developerId = Number(cfg['developer-id'] || cfg.developerId || 0) || 0;
+    }
+  } catch (_err) {
+    developerId = 0;
+  }
+  return `http://localhost:${3005 + developerId * 100}`;
+}
+
+/**
+ * @param {Object} authConfig
+ * @returns {string}
+ */
+function extractBearer(authConfig) {
+  if (!authConfig || typeof authConfig !== 'object') {
+    return '';
+  }
+  if (typeof authConfig.token === 'string' && authConfig.token.trim()) {
+    return authConfig.token.trim();
+  }
+  if (typeof authConfig.bearerToken === 'string' && authConfig.bearerToken.trim()) {
+    return authConfig.bearerToken.trim();
+  }
+  const header = authConfig.headers && authConfig.headers.Authorization;
+  const m = /^Bearer\s+(.+)$/i.exec(String(header || ''));
+  return m ? m[1].trim() : '';
+}
+
+/**
+ * @param {Object} testCase
+ * @param {Object} wait
+ * @returns {boolean}
+ */
+function shouldApplyBidAfterWait(testCase, wait) {
+  const bid = loadCaseBidDocument(testCase);
+  if (!bid) {
+    return false;
+  }
+  const capability = String(
+    wait.questionKey || wait.objectRef?.capabilityKey || wait.prompt || ''
+  ).toLowerCase();
+  return (
+    capability.includes('createsystem') ||
+    capability.includes('applyintegrationdefinition')
+  );
+}
+
+/**
+ * @param {Object} authConfig
+ * @param {Object} testCase
+ * @returns {Promise<Object|null>}
+ */
+async function applyCaseBidViaBuilderApi(authConfig, testCase) {
+  const bid = loadCaseBidDocument(testCase);
+  const systemKey = resolveTargetSystemKey(testCase);
+  const token = extractBearer(authConfig);
+  if (!bid || !systemKey || !token) {
+    return null;
+  }
+  const url = `${resolveBuilderApiBaseUrl()}/api/v1/builder/systems/${encodeURIComponent(systemKey)}/integration-definition/apply`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({ integrationDefinition: bid, force: true })
+  });
+  const text = await res.text();
+  let body = null;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch (_err) {
+    body = { raw: text };
+  }
+  if (!res.ok) {
+    const err = new Error(
+      `BID apply failed HTTP ${res.status}: ${typeof body === 'object' ? JSON.stringify(body).slice(0, 300) : text}`
+    );
+    err.status = res.status;
+    throw err;
+  }
+  return body && body.data ? body.data : body;
+}
+
+module.exports = {
+  resolveBuilderApiBaseUrl,
+  shouldApplyBidAfterWait,
+  applyCaseBidViaBuilderApi
+};