@aifabrix/builder 2.51.1 → 2.52.0

package/lib/commands/test-governance-external.js

@@ -23,12 +23,9 @@ const { syncLocalIfRequested } = require('./test-e2e-external');
  */
 async function runTestGovernanceForExternalSystem(externalSystem, options = {}) {
   const pathsUtil = require('../utils/paths');
+  const { assertCertifyExternalWorkspace } = require('../utils/certify-external-workspace');
   const appType = await pathsUtil.detectAppType(externalSystem).catch(() => null);
-  if (!appType || appType.baseDir !== 'integration') {
-    throw new Error(
-      'verify-governance applies to external integration folders only (integration/<systemKey>/).'
-    );
-  }
+  assertCertifyExternalWorkspace(appType && appType.baseDir, 'verify-governance');
 
   const systemKey = externalSystem;
   const packPath = resolveGovernancePackPath(systemKey, {

package/lib/commands/up-miso.js

@@ -41,40 +41,73 @@ function parseImageOptions(imageOpts) {
   return map;
 }
 
-/**
- * Build run options and run keycloak, then miso-controller
- * @async
- * @param {Object} options - Commander options (image, registry, registryMode)
- */
-async function runMisoApps(options) {
-  const imageMap = parseImageOptions(options.image);
+function buildPlatformCommonRunOpts(options) {
   const useBaseImage = options.base !== false;
-  const common = {
+  return {
     registry: options.registry,
     registryMode: options.registryMode,
     skipEnvOutputPath: true,
     skipInfraCheck: true,
     base: useBaseImage,
-    skipManifestMetadataLine: true
+    skipManifestMetadataLine: true,
+    ...(options.platformInstall === true ? { silentPoll: true } : {})
   };
-  const platformPollOpts =
-    options.platformInstall === true
-      ? { silentPoll: true }
-      : {};
-  const keycloakRunOpts = { ...common, ...platformPollOpts };
+}
+
+function applyDeferredPublicUrlWarning(runOpts, options) {
+  if (typeof options.onDeferredPublicUrlWarning !== 'function') {
+    return runOpts;
+  }
+  return {
+    ...runOpts,
+    deferPublicUrlWarning: true,
+    onDeferredPublicUrlWarning: options.onDeferredPublicUrlWarning
+  };
+}
+
+function buildKeycloakRunOpts(options, imageMap) {
+  const runOpts = applyDeferredPublicUrlWarning(buildPlatformCommonRunOpts(options), options);
   if (imageMap.keycloak) {
-    keycloakRunOpts.image = imageMap.keycloak;
+    runOpts.image = imageMap.keycloak;
   }
-  const misoRunOpts = { ...common, ...platformPollOpts };
+  return runOpts;
+}
+
+function buildMisoControllerRunOpts(options, imageMap) {
+  const runOpts = applyDeferredPublicUrlWarning(buildPlatformCommonRunOpts(options), options);
   if (imageMap['miso-controller']) {
-    misoRunOpts.image = imageMap['miso-controller'];
+    runOpts.image = imageMap['miso-controller'];
   }
+  if (typeof options.onMisoPollText === 'function') {
+    runOpts.onPollText = options.onMisoPollText;
+    delete runOpts.silentPoll;
+  }
+  return runOpts;
+}
+
+/**
+ * Build run options and run keycloak, then miso-controller
+ * @async
+ * @param {Object} options - Commander options (image, registry, registryMode)
+ */
+async function runMisoApps(options) {
+  const imageMap = parseImageOptions(options.image);
+  const keycloakRunOpts = buildKeycloakRunOpts(options, imageMap);
+  const misoRunOpts = buildMisoControllerRunOpts(options, imageMap);
   const { emitSystemBuilderAppManifestLineIfTTY } = require('../utils/manifest-source-emit');
-  logger.log(chalk.blue('Starting keycloak...'));
-  emitSystemBuilderAppManifestLineIfTTY(logger, 'keycloak');
+  const platformInstall = options.platformInstall === true;
+  if (!platformInstall) {
+    logger.log(chalk.blue('Starting keycloak...'));
+    emitSystemBuilderAppManifestLineIfTTY(logger, 'keycloak');
+  }
   await app.runApp('keycloak', keycloakRunOpts);
-  logger.log(chalk.blue('Starting miso-controller...'));
-  emitSystemBuilderAppManifestLineIfTTY(logger, 'miso-controller');
+  if (typeof options.onAfterKeycloak === 'function') {
+    options.onAfterKeycloak();
+  }
+  if (!platformInstall) {
+    logger.log(chalk.blue('Starting miso-controller...'));
+    emitSystemBuilderAppManifestLineIfTTY(logger, 'miso-controller');
+  }
   await app.runApp('miso-controller', misoRunOpts);
 }
 
@@ -91,7 +124,9 @@ async function runMisoApps(options) {
  * @throws {Error} If infra not up or any step fails
  */
 async function handleUpMiso(options = {}) {
-  logger.log(chalk.blue('Starting up-miso (keycloak + miso-controller from images)...\n'));
+  if (options.platformInstall !== true) {
+    logger.log(chalk.blue('Starting up-miso (keycloak + miso-controller from images)...\n'));
+  }
   await assertDevInfraUp();
   await ensureAppFromTemplate('keycloak');
   await ensureAppFromTemplate('miso-controller');
@@ -103,8 +138,10 @@ async function handleUpMiso(options = {}) {
   patchEnvOutputPathForDeployOnly('miso-controller');
   refreshUrlsLocalRegistryForCurrentProject();
   await runMisoApps(options);
-  logger.log(formatSuccessParagraph('up-miso complete. Keycloak and miso-controller are running.') +
-    chalk.gray('\n  Run onboarding and register Keycloak from the miso-controller repo if needed. Use \'aifabrix up-dataplane\' for dataplane.'));
+  if (options.platformInstall !== true) {
+    logger.log(formatSuccessParagraph('up-miso complete. Keycloak and miso-controller are running.') +
+      chalk.gray('\n  Run onboarding and register Keycloak from the miso-controller repo if needed. Use \'aifabrix up-dataplane\' for dataplane.'));
+  }
 }
 
 module.exports = { handleUpMiso, parseImageOptions };

package/lib/commands/upload-data-sync-finalize.js

@@ -8,9 +8,18 @@
 
 const { runPostPublishDataSync } = require('./run-post-publish-data-sync');
 const { runUploadSidecarFollowups } = require('./upload-sidecar-followups');
-const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const { formatSuccessLine, formatWarningLine, metadata } = require('../utils/cli-test-layout-chalk');
 const logger = require('../utils/logger');
-const { isQuietMinimalSync } = require('../utils/upload-sync-options');
+
+/**
+ * Internal verify/test --sync / deploy-preflight paths suppress upload banners.
+ * Default CLI `aifabrix upload` uses minimal=true but must still announce "unchanged".
+ * @param {Object} [options]
+ * @returns {boolean}
+ */
+function suppressUnchangedUploadBanner(options = {}) {
+  return options.syncMode === true || options.suppressSummary === true;
+}
 
 /**
  * @async
@@ -37,8 +46,16 @@ async function finalizeUploadPublishResult(ctx, payload, options) {
  */
 async function finishUnchangedUploadPublication(params) {
   const { systemKey, options, payload, dataplaneUrl, authConfig, environment } = params;
-  if (!isQuietMinimalSync(options)) {
+  if (!suppressUnchangedUploadBanner(options)) {
+    logger.log('');
     logger.log(formatSuccessLine('Config unchanged on dataplane — upload skipped.'));
+    logger.log(metadata(`System: ${systemKey}`));
+    if (options.probe === true) {
+      logger.log(
+        formatWarningLine('Probe skipped (nothing published). Use --force to republish, then --probe.')
+      );
+    }
+    logger.log('');
   }
   const sidecar = await runUploadSidecarFollowups({
     systemKey,

package/lib/commands/verify-governance-external.js

@@ -53,12 +53,9 @@ function buildDbPackResult(resolvedKey, datasourceRows) {
  */
 async function runVerifyGovernanceForExternalSystem(systemKey, options = {}) {
   const pathsUtil = require('../utils/paths');
+  const { assertCertifyExternalWorkspace } = require('../utils/certify-external-workspace');
   const appType = await pathsUtil.detectAppType(systemKey).catch(() => null);
-  if (!appType || appType.baseDir !== 'integration') {
-    throw new Error(
-      'verify-governance applies to external integration folders only (integration/<systemKey>/).'
-    );
-  }
+  assertCertifyExternalWorkspace(appType && appType.baseDir, 'verify-governance');
 
   if (options.pack) {
     const runPayload = await runTestGovernanceForExternalSystem(systemKey, options);

package/lib/commands/verify-operations-external.js

@@ -162,12 +162,9 @@ async function buildOperationsResult({
  */
 async function assertIntegrationExternalSystem(systemKey) {
   const pathsUtil = require('../utils/paths');
+  const { assertCertifyExternalWorkspace } = require('../utils/certify-external-workspace');
   const appType = await pathsUtil.detectAppType(systemKey).catch(() => null);
-  if (!appType || appType.baseDir !== 'integration') {
-    throw new Error(
-      'verify-operations applies to external integration folders only (integration/<systemKey>/).'
-    );
-  }
+  assertCertifyExternalWorkspace(appType && appType.baseDir, 'verify-operations');
 }
 
 /**

package/lib/commands/verify-operations-step-plan.js

@@ -66,6 +66,17 @@ function buildE2eStep(systemKey, options) {
       ok: () => true
     };
   }
+  if (shouldSkipE2eForRoleAssistant(systemKey, options)) {
+    return {
+      key: 'e2e',
+      run: async() => ({
+        success: true,
+        skipped: true,
+        reason: 'role-assistant-auth-none'
+      }),
+      ok: () => true
+    };
+  }
   return {
     key: 'e2e',
     run: (progress) =>
@@ -88,6 +99,26 @@ function buildE2eStep(systemKey, options) {
   };
 }
 
+/**
+ * Role Assistant packages use authType none + nested builder-api CIP.
+ * Live capacity E2E expects a system baseUrl credential and is not the RA certify path.
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {boolean}
+ */
+function shouldSkipE2eForRoleAssistant(systemKey, options) {
+  if (options.forceE2e === true) {
+    return false;
+  }
+  try {
+    const { resolveAppWorkspace } = require('../utils/app-path-resolve');
+    const { baseDir } = resolveAppWorkspace(systemKey, {});
+    return baseDir === 'role-assistant';
+  } catch {
+    return false;
+  }
+}
+
 /**
  * @param {string} systemKey
  * @param {Object} options

package/lib/commands/verify-trust-command-action.js

@@ -17,12 +17,9 @@ const { buildJsonEnvelope } = require('../lifecycle/json-envelope');
 async function runVerifyTrustCommandAction(appName, options, cmd) {
   const opts = normalizeTestTrustCliOptions(options, cmd);
   const pathsUtil = require('../utils/paths');
+  const { assertCertifyExternalWorkspace } = require('../utils/certify-external-workspace');
   const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-  if (!appType || appType.baseDir !== 'integration') {
-    throw new Error(
-      'verify-trust applies to external integration folders only (integration/<systemKey>/).'
-    );
-  }
+  assertCertifyExternalWorkspace(appType && appType.baseDir, 'verify-trust');
 
   const result = await runVerifyTrustForExternalSystem(appName, {
     env: opts.env,

package/lib/datasource/datasource-identifier.js

@@ -7,7 +7,7 @@
 'use strict';
 
 const path = require('path');
-const { getIntegrationPath } = require('../utils/paths');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadConfigFile } = require('../utils/config-format');
 
@@ -65,12 +65,13 @@ function pickIntegrationAppForDatasourceIdentifier(identifier, appNames) {
 }
 
 /**
- * List manifest datasource files for an integration app.
+ * List manifest datasource files for an external authoring app
+ * (integration/, role-assistant/, or enterprise-knowledge/).
  * @param {string} appKey
  * @returns {{ appPath: string, schemaBasePath: string, datasourceFiles: string[] }|null}
  */
 function listDatasourceFilesForApp(appKey) {
-  const appPath = getIntegrationPath(appKey);
+  const appPath = resolveExternalSystemPath(appKey);
   let config;
   try {
     const configPath = resolveApplicationConfigPath(appPath);

package/lib/datasource/integration-context.js

@@ -6,7 +6,7 @@
 
 const path = require('path');
 const fs = require('fs').promises;
-const { getIntegrationPath } = require('../utils/paths');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadConfigFile } = require('../utils/config-format');
 const {
@@ -15,11 +15,11 @@ const {
 } = require('./datasource-identifier');
 
 /**
- * @param {string} appKey - Integration app key
+ * @param {string} appKey - Integration / role-assistant / EK app key
  * @returns {Promise<string>} systemKey
  */
 async function getSystemKeyFromAppKey(appKey) {
-  const appPath = getIntegrationPath(appKey);
+  const appPath = resolveExternalSystemPath(appKey);
   const configPath = resolveApplicationConfigPath(appPath);
   const config = loadConfigFile(configPath);
   if (!config.externalIntegration || !config.externalIntegration.systems || config.externalIntegration.systems.length === 0) {

package/lib/datasource/resolve-app.js

@@ -2,15 +2,20 @@
  * Resolve app key for datasource commands from explicit --app, cwd, scan, or key parse.
  * @fileoverview App resolution for datasource test-e2e, test-integration, log-e2e, log-integration
  * @author AI Fabrix Team
- * @version 2.0.0
+ * @version 2.1.0
  */
 
+'use strict';
+
 const fs = require('fs');
 const {
-  getIntegrationPath,
   listIntegrationAppNames,
+  listEnterpriseKnowledgeAnchors,
+  getRoleAssistantRoot,
+  getCwdRoleAssistantRoot,
   resolveIntegrationAppKeyFromCwd
 } = require('../utils/paths');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const {
   appHasDatasourceIdentifier,
   pickIntegrationAppForDatasourceIdentifier
@@ -21,6 +26,80 @@ function appHasDatasourceKey(appKey, datasourceKey) {
   return appHasDatasourceIdentifier(appKey, datasourceKey);
 }
 
+/**
+ * @param {string} appKey
+ * @returns {boolean}
+ */
+function externalAppPathExists(appKey) {
+  try {
+    const appPath = resolveExternalSystemPath(appKey);
+    return Boolean(appPath && fs.existsSync(appPath));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {Set<string>} diskNames
+ */
+function addRoleAssistantAppDirs(root, diskNames) {
+  if (!root || !fs.existsSync(root)) {
+    return;
+  }
+  let entries;
+  try {
+    entries = fs.readdirSync(root);
+  } catch {
+    return;
+  }
+  const pathJoin = require('path').join;
+  for (const name of entries) {
+    if (!name || name.startsWith('.')) {
+      continue;
+    }
+    try {
+      if (fs.statSync(pathJoin(root, name)).isDirectory()) {
+        diskNames.add(name);
+      }
+    } catch {
+      // skip
+    }
+  }
+}
+
+/**
+ * List app folders under role-assistant/ (cwd + materialization).
+ * @returns {string[]}
+ */
+function listRoleAssistantAppNames() {
+  const diskNames = new Set();
+  const roots = new Set();
+  const cwdRoot = getCwdRoleAssistantRoot();
+  if (cwdRoot) {
+    roots.add(cwdRoot);
+  }
+  roots.add(getRoleAssistantRoot());
+  for (const root of roots) {
+    addRoleAssistantAppDirs(root, diskNames);
+  }
+  return [...diskNames].sort();
+}
+
+/**
+ * External authoring apps: integration + role-assistant + enterprise-knowledge.
+ * @returns {string[]}
+ */
+function listExternalAuthoringAppNames() {
+  return [
+    ...new Set([
+      ...listIntegrationAppNames(),
+      ...listRoleAssistantAppNames(),
+      ...listEnterpriseKnowledgeAnchors()
+    ])
+  ].sort();
+}
+
 /**
  * @param {string} key
  * @param {string} [explicitApp]
@@ -31,7 +110,7 @@ function resolveFromExplicitApp(key, explicitApp) {
     return null;
   }
   const appKey = explicitApp.trim();
-  if (fs.existsSync(getIntegrationPath(appKey))) {
+  if (externalAppPathExists(appKey)) {
     return { appKey };
   }
   return null;
@@ -71,15 +150,16 @@ function resolveFromPrefixOrSegments(key, appNames) {
     return null;
   }
   const candidate = segments.slice(0, -1).join('-');
-  const candidatePath = getIntegrationPath(candidate);
-  if (fs.existsSync(candidatePath) && appHasDatasourceIdentifier(candidate, key)) {
+  if (externalAppPathExists(candidate) && appHasDatasourceIdentifier(candidate, key)) {
     return { appKey: candidate };
   }
   return null;
 }
 
 const RESOLVE_APP_HINT =
-  'Could not determine app context. Use --app <app>, a datasource key, a datasource JSON filename (e.g. myapp-datasource-contacts), or run from integration/<systemKey>/ directory.';
+  'Could not determine app context. Use --app <app>, a datasource key, a datasource JSON filename ' +
+  '(e.g. myapp-datasource-contacts), or run from integration/<systemKey>/, ' +
+  'role-assistant/<systemKey>/, or enterprise-knowledge/<systemKey>/.';
 
 /**
  * Resolve app key for a datasource: explicit --app, cwd, scan by key, or parse key convention.
@@ -108,7 +188,7 @@ async function resolveAppKeyForDatasource(datasourceKey, explicitApp) {
     return { appKey: fromCwd };
   }
 
-  const appNames = listIntegrationAppNames();
+  const appNames = listExternalAuthoringAppNames();
   const scanned = resolveFromAppScan(key, appNames);
   if (scanned) {
     return scanned;
@@ -124,5 +204,7 @@ async function resolveAppKeyForDatasource(datasourceKey, explicitApp) {
 
 module.exports = {
   resolveAppKeyForDatasource,
-  appHasDatasourceKey
+  appHasDatasourceKey,
+  listExternalAuthoringAppNames,
+  listRoleAssistantAppNames
 };

package/lib/datasource/test-e2e.js

@@ -9,7 +9,6 @@ const path = require('path');
 const fs = require('fs').promises;
 const chalk = require('chalk');
 const logger = require('../utils/logger');
-const { getIntegrationPath } = require('../utils/paths');
 const { resolveAppKeyForDatasource } = require('./resolve-app');
 const { formatProgress, formatSuccessLine, infoLine } = require('../utils/cli-test-layout-chalk');
 const { runUnifiedDatasourceValidation } = require('./unified-validation-run');
@@ -94,7 +93,8 @@ async function resolvePrimaryKeyValue(value) {
 }
 
 function e2eIntegrationLogDir(appKey) {
-  return path.dirname(getIntegrationPath(appKey));
+  const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
+  return path.dirname(resolveExternalSystemPath(appKey));
 }
 
 /**

package/lib/datasource/unified-validation-run-body.js

@@ -12,6 +12,16 @@ const {
 const testHelpers = require('../utils/external-system-test-helpers');
 const { withStageOnValidationRunBody } = require('../utils/validation-run-stage');
 
+/**
+ * @param {Object} datasource
+ * @returns {boolean}
+ */
+function isVoidCipInput(datasource) {
+  const execution = datasource && typeof datasource === 'object' ? datasource.execution : null;
+  const cip = execution && typeof execution === 'object' ? execution.cip : null;
+  return String((cip && cip.inputType) || '').trim().toLowerCase() === 'void';
+}
+
 /**
  * @param {Object} params
  * @param {string} params.systemKey
@@ -31,7 +41,11 @@ async function buildUnifiedValidationBody(params) {
     const customPayload = await testHelpers.loadCustomPayload(payloadPath);
     payloadTemplate = testHelpers.determinePayloadTemplate(datasource, datasourceKey, customPayload);
     if (runType === 'integration' && !payloadTemplate) {
-      throw new Error(`No test payload found for datasource '${datasourceKey}'`);
+      if (isVoidCipInput(datasource)) {
+        payloadTemplate = {};
+      } else {
+        throw new Error(`No test payload found for datasource '${datasourceKey}'`);
+      }
     }
   }
 

package/lib/datasource/unified-validation-run-resolve.js

@@ -4,7 +4,7 @@
  * @version 2.0.0
  */
 
-const { getIntegrationPath } = require('../utils/paths');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadConfigFile } = require('../utils/config-format');
 const {
@@ -48,7 +48,7 @@ function findDatasourceFileByIdentifier(appPath, schemaBasePath, datasourceFiles
  * @returns {{ datasource: Object, datasourcePath: string, datasourceKey: string }}
  */
 function loadDatasourceForApp(appKey, datasourceKey, findDatasourceFileByKey) {
-  const appPath = getIntegrationPath(appKey);
+  const appPath = resolveExternalSystemPath(appKey);
   const config = loadConfigFile(resolveApplicationConfigPath(appPath));
   const schemaBasePath = config.externalIntegration?.schemaBasePath || './';
   const datasourceFiles = config.externalIntegration?.dataSources || [];

package/lib/external-system/deploy-helpers.js

@@ -142,7 +142,7 @@ function extractSystemKey(systemFilePath) {
  * @param {Object} manifest - Controller manifest
  * @returns {Promise<Object|null>} Upload result, or null when not a digital worker
  */
-async function uploadDigitalWorkerIfNeeded(appName, options, compact, manifest) {
+async function uploadDigitalWorkerIfNeeded(appName, options, _compact, manifest) {
   const systemKind =
     manifest && manifest.system && typeof manifest.system.systemKind === 'string'
       ? manifest.system.systemKind.trim()
@@ -150,9 +150,9 @@ async function uploadDigitalWorkerIfNeeded(appName, options, compact, manifest)
   if (systemKind !== 'digitalWorker') {
     return null;
   }
-  if (!compact) {
-    const { formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
-    const logger = require('../utils/logger');
+  const { formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
+  const logger = require('../utils/logger');
+  if (options.json !== true) {
     logger.log(
       formatSuccessParagraph(
         'Role Assistant deployment uses upload pipeline (controller deploy is skipped).'
@@ -162,7 +162,11 @@ async function uploadDigitalWorkerIfNeeded(appName, options, compact, manifest)
   const { uploadExternalSystem } = require('../commands/upload');
   return uploadExternalSystem(appName, {
     ...options,
-    uploadStatus: 'published'
+    uploadStatus: 'published',
+    // Match standalone `af upload` progress for the final publish.
+    silentResolve: false,
+    suppressPipelineSpinner: false,
+    syncMode: false
   });
 }
 

package/lib/external-system/deploy.js

@@ -432,7 +432,8 @@ async function runExternalSystemDeployFlow(appName, options) {
   await validateExternalSystemForDeploy(appName, options, compact);
   const gateOutcomes = await runDeployGateOrchestrator(appName, {
     ...options,
-    quietDeployUi: compact
+    // Compact deploy still shows step progress; only JSON mode stays fully quiet.
+    quietDeployUi: options.json === true
   });
   await syncDeployJsonFromSources(appName);
   const manifest = await generateControllerManifest(appName, options);

package/lib/external-system/test-system-level.js

@@ -12,7 +12,7 @@ const path = require('path');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { writeTestLog } = require('../utils/test-log-writer');
-const { getIntegrationPath } = require('../utils/paths');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const { runUnifiedDatasourceValidation } = require('../datasource/unified-validation-run');
 
 async function runOneDatasourceKey(appName, datasourceKey, opts) {
@@ -61,16 +61,34 @@ async function runOneDatasourceKey(appName, datasourceKey, opts) {
       };
     }
     const env = uni.envelope;
-    const ok = env && typeof env.status === 'string' ? env.status !== 'fail' : false;
+    const ok = isDatasourceRunSuccessful(env);
     return { key: datasourceKey, success: ok, skipped: false, datasourceTestRun: env };
   } catch (err) {
     return { key: datasourceKey, success: false, skipped: false, error: err.message };
   }
 }
 
+/**
+ * Prefer explicit envelope status; soft-pass when validation+certificate succeeded
+ * (documentStorage packs may report overall fail only for missing live evidence).
+ * @param {Object|null|undefined} env
+ * @returns {boolean}
+ */
+function isDatasourceRunSuccessful(env) {
+  if (!env || typeof env.status !== 'string') {
+    return false;
+  }
+  if (env.status !== 'fail') {
+    return true;
+  }
+  const validationOk = env.validation && env.validation.status === 'ok';
+  const certPassed = env.certificate && env.certificate.status === 'passed';
+  return Boolean(validationOk && certPassed);
+}
+
 async function maybeWriteSystemRunLog(appName, systemKey, datasourceKeys, runType, debug, payload) {
   if (!debug) return;
-  const appPath = getIntegrationPath(appName);
+  const appPath = resolveExternalSystemPath(appName);
   const integrationDir = path.dirname(appPath);
   const logPath = await writeTestLog(
     appName,

package/lib/external-system/test.js

@@ -533,8 +533,8 @@ async function testExternalSystemIntegration(appName, options = {}) {
         if (options.debug) {
           try {
             const { writeTestLog } = require('../utils/test-log-writer');
-            const { getIntegrationPath } = require('../utils/paths');
-            const appPath = getIntegrationPath(appName);
+            const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
+            const appPath = resolveExternalSystemPath(appName);
             await writeTestLog(appName, { request: { systemKey }, error: err.message }, 'test-integration', path.dirname(appPath));
           } catch (_) { /* ignore */ }
         }
@@ -561,8 +561,8 @@ async function testExternalSystemIntegration(appName, options = {}) {
       if (options.debug && results.datasourceResults.length > 0) {
         try {
           const { writeTestLog } = require('../utils/test-log-writer');
-          const { getIntegrationPath } = require('../utils/paths');
-          const appPath = getIntegrationPath(appName);
+          const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
+          const appPath = resolveExternalSystemPath(appName);
           await writeTestLog(appName, {
             request: { systemKey, datasource: options.datasource, includeDebug: true },
             response: results