@aifabrix/builder 2.52.0 → 2.53.0

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

@@ -27,6 +27,10 @@ const EVIDENCE_DIR_NAME = 'evidence';
 const EVIDENCE_EXPORT_FILE = 'evidence.json';
 const VALIDATION_FAILED = 'failed';
 const VALIDATION_PASSED = 'passed';
+/** Builder-keyed Category B catalogue — never import as Evidence (517.3 / 517.4.1). */
+const SKIP_EVIDENCE_BASENAMES = new Set(['capability-business-catalog.json']);
+/** PoC draft folders under evidence/ — never import as governed Evidence. */
+const SKIP_EVIDENCE_DIR_NAMES = new Set(['candidates', 'candidate']);
 
 const EVIDENCE_MUTABLE_KEYS = [
   'key',
@@ -79,6 +83,23 @@ function isEvidenceFileName(fileName) {
   return lower.endsWith('.json') || lower.endsWith('.yaml') || lower.endsWith('.yml');
 }
 
+/**
+ * Skip retired / forbidden evidence payloads (517.4.1 scrub).
+ * @param {string} filePath
+ * @param {unknown} parsed
+ * @returns {boolean}
+ */
+function shouldSkipEvidencePayload(filePath, parsed) {
+  const base = path.basename(String(filePath || '')).toLowerCase();
+  if (SKIP_EVIDENCE_BASENAMES.has(base)) {
+    return true;
+  }
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && parsed._retired === true) {
+    return true;
+  }
+  return false;
+}
+
 function collectEvidenceFiles(dirPath) {
   if (!fs.existsSync(dirPath)) {
     return [];
@@ -88,6 +109,10 @@ function collectEvidenceFiles(dirPath) {
   for (const entry of entries) {
     const fullPath = path.join(dirPath, entry.name);
     if (entry.isDirectory()) {
+      const dirName = String(entry.name || '').trim().toLowerCase();
+      if (SKIP_EVIDENCE_DIR_NAMES.has(dirName)) {
+        continue;
+      }
       files.push(...collectEvidenceFiles(fullPath));
       continue;
     }
@@ -152,8 +177,13 @@ function sanitizeEvidenceRow(row, systemKey, options = {}) {
 function loadEvidenceRowsFromFolder(evidencePath, systemKey) {
   const files = collectEvidenceFiles(evidencePath);
   const rows = [];
+  const skippedFiles = [];
   for (const filePath of files) {
     const parsed = parseEvidenceFile(filePath);
+    if (shouldSkipEvidencePayload(filePath, parsed)) {
+      skippedFiles.push(path.relative(evidencePath, filePath));
+      continue;
+    }
     const extractedRows = extractEvidenceRows(parsed);
     for (const row of extractedRows) {
       if (!row || typeof row !== 'object' || Array.isArray(row)) {
@@ -169,7 +199,7 @@ function loadEvidenceRowsFromFolder(evidencePath, systemKey) {
       rows.push(normalized);
     }
   }
-  return { files, rows };
+  return { files, rows, skippedFiles };
 }
 
 function resolveEvidenceDirectory(systemKey, pathOptions = {}) {
@@ -277,21 +307,25 @@ function buildFailureSummary(failures) {
   return `${preview}${more}`;
 }
 
-function buildEvidenceDryRunSummary(evidencePath, files, rows) {
+function buildEvidenceDryRunSummary(evidencePath, files, rows, skippedFiles = []) {
   return {
     skipped: false,
     dryRun: true,
     evidencePath,
     filesDiscovered: files.length,
+    filesSkipped: skippedFiles.length,
+    skippedFiles: [...skippedFiles],
     discovered: rows.length
   };
 }
 
-function buildEvidenceImportSummary(evidencePath, files, rows, loadResult) {
+function buildEvidenceImportSummary(evidencePath, files, rows, loadResult, skippedFiles = []) {
   return {
     skipped: false,
     evidencePath,
     filesDiscovered: files.length,
+    filesSkipped: skippedFiles.length,
+    skippedFiles: [...skippedFiles],
     discovered: rows.length,
     loaded: Number(loadResult.inserted || 0) + Number(loadResult.updated || 0),
     validated: 0,
@@ -347,12 +381,18 @@ async function importRoleAssistantEvidence(params) {
     return { skipped: true, reason: 'not-role-assistant' };
   }
   const evidencePath = resolveEvidenceDirectory(systemKey, pathOptions);
-  const { files, rows } = loadEvidenceRowsFromFolder(evidencePath, systemKey);
+  const { files, rows, skippedFiles } = loadEvidenceRowsFromFolder(evidencePath, systemKey);
   if (rows.length === 0) {
-    return { skipped: true, reason: 'no-evidence-files', evidencePath };
+    return {
+      skipped: true,
+      reason: 'no-evidence-files',
+      evidencePath,
+      filesSkipped: (skippedFiles || []).length,
+      skippedFiles: [...(skippedFiles || [])]
+    };
   }
   if (dryRun) {
-    return buildEvidenceDryRunSummary(evidencePath, files, rows);
+    return buildEvidenceDryRunSummary(evidencePath, files, rows, skippedFiles);
   }
   const { loadResult, refs } = await loadEvidenceAndResolveRefs(
     dataplaneUrl,
@@ -360,7 +400,13 @@ async function importRoleAssistantEvidence(params) {
     systemKey,
     rows
   );
-  const summary = buildEvidenceImportSummary(evidencePath, files, rows, loadResult);
+  const summary = buildEvidenceImportSummary(
+    evidencePath,
+    files,
+    rows,
+    loadResult,
+    skippedFiles
+  );
   const failures = await runEvidenceLifecycleBatch(dataplaneUrl, authConfig, refs, summary);
   appendUnresolvedEvidenceFailures(summary, failures, refs.length, rows.length);
   throwWhenEvidenceLifecycleFailed(summary, failures);
@@ -443,6 +489,8 @@ function logRoleAssistantEvidenceExportSummary(systemKey, result, options = {})
 
 module.exports = {
   isDigitalWorkerModel,
+  shouldSkipEvidencePayload,
+  loadEvidenceRowsFromFolder,
   importRoleAssistantEvidence,
   exportRoleAssistantEvidence,
   logRoleAssistantEvidenceImportSummary,

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

@@ -0,0 +1,58 @@
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatSuccessLine, formatWarningLine, metadata } = require('../utils/cli-test-layout-chalk');
+
+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 = {
+  logKnowledgeImportSummary,
+  logDocumentStorageSettingsPushSummary,
+  logKnowledgeExportSummary
+};

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,
@@ -32,6 +30,11 @@ const {
   knowledgeSearchMetadataFromFrontmatter,
   splitMarkdownFrontmatter
 } = require('./knowledge-markdown-frontmatter');
+const {
+  logKnowledgeImportSummary,
+  logDocumentStorageSettingsPushSummary,
+  logKnowledgeExportSummary
+} = require('./knowledge-sync-logging');
 
 function resolveSystemNode(input) {
   if (!input || typeof input !== 'object') {
@@ -80,53 +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) {
-    return {
-      skipped: false,
-      dryRun: true,
-      documentStorageKey: documentStorageKey || null
-    };
+  const debugBody = mapRoleAssistantDebugToAssistantsSettings(section.debug);
+  if (!documentStorageKey && Object.keys(debugBody).length === 0) {
+    return { result: { skipped: true, reason: 'no-document-storage-key', documentStorageKey: null } };
   }
-  if (documentStorageKey === '') {
-    // No Knowledge binding in role-assistant.yaml — skip Assistants settings write.
-    // Draft / not-yet-catalogued digital workers would 404 on PATCH otherwise.
+  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: true,
-      reason: 'no-document-storage-key',
-      documentStorageKey: null
+      skipped: false,
+      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 ||
@@ -136,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.
@@ -408,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;
 }