@aifabrix/builder 2.60.0 → 2.61.2

package/lib/commands/wizard-core.js

@@ -3,28 +3,24 @@
  * @author AI Fabrix Team
  * @version 2.0.0
  */
-/* eslint-disable max-lines */
 
+const path = require('path');
 const chalk = require('chalk');
 const ora = require('ora');
-const path = require('path');
-const fs = require('fs').promises;
 const logger = require('../utils/logger');
 const { getDeploymentAuth, requireBearerForDataplanePipeline } = require('../utils/token-manager');
 const { resolveControllerUrl } = require('../utils/controller-url');
 const { normalizeWizardConfigs } = require('./wizard-config-normalizer');
-const { formatSuccessLine, formatSuccessParagraph } = require('../utils/cli-layout-chalk');
+const { formatSuccessLine } = require('../utils/cli-layout-chalk');
 const {
   createWizardSession,
   updateWizardSession,
   detectType,
   getPlatformConfig,
   generateConfig,
-  validateWizardConfig,
-  getDeploymentDocs,
-  postDeploymentDocs
+  validateWizardConfig
 } = require('../api/wizard.api');
-const { generateWizardFiles } = require('../generator/wizard');
+const { handleFileSaving, validateAndCheckAppDirectory } = require('./wizard-file-saving');
 const {
   parseOpenApiSource,
   testMcpServerConnection,
@@ -44,38 +40,6 @@ const {
 const { validateDatasourceKeysBeforePlatformConfig } = require('../validation/validate-datasource-keys-api');
 const { handleEntitySelection } = require('./wizard-entity-selection');
 
-/**
- * Validate app name and check if directory exists
- * @async
- * @function validateAndCheckAppDirectory
- * @param {string} appName - Application name
- * @param {boolean} [interactive=true] - Whether to prompt for confirmation
- * @returns {Promise<boolean>} True if should continue, false if cancelled
- */
-async function validateAndCheckAppDirectory(appName, interactive = true) {
-  if (!/^[a-z0-9-_]+$/.test(appName)) {
-    throw new Error('Application name must contain only lowercase letters, numbers, hyphens, and underscores');
-  }
-  const appPath = path.join(process.cwd(), 'integration', appName);
-  try {
-    await fs.access(appPath);
-    if (interactive) {
-      const { overwrite } = await require('inquirer').prompt([{
-        type: 'confirm', name: 'overwrite',
-        message: `Directory ${appPath} already exists. Overwrite?`, default: false
-      }]);
-      if (!overwrite) {
-        logger.log(chalk.yellow('Wizard cancelled.')); return false;
-      }
-    } else {
-      logger.log(chalk.yellow(`Warning: Directory ${appPath} exists. Overwriting...`));
-    }
-  } catch (error) {
-    if (error.code !== 'ENOENT') throw error;
-  }
-  return true;
-}
-
 /**
  * Extract session ID from response data
  * @function extractSessionId
@@ -393,7 +357,7 @@ async function handleConfigurationGeneration(dataplaneUrl, authConfig, options)
     }
     const result = extractConfigurationFromResponse(generateResponse);
     const systemConfig = resolveSystemConfigForWizardMode(result.systemConfig, options);
-    const normalized = normalizeWizardConfigs(systemConfig, result.datasourceConfigs);
+    const normalized = normalizeWizardConfigs(systemConfig, result.datasourceConfigs, options.openapiSpec);
     await maybeWriteWizardDebugLog(generateResponse, prefs, options);
     logger.log(formatSuccessLine('Configuration generated successfully'));
     return {
@@ -446,122 +410,6 @@ async function validateWizardConfiguration(dataplaneUrl, authConfig, systemConfi
   }
 }
 
-/**
- * Fetches deployment docs and writes README.md when application config and deploy JSON are available.
- * @async
- * @param {string} appPath - Application path
- * @param {string} appName - Application name
- * @param {string} dataplaneUrl - Dataplane URL
- * @param {Object} authConfig - Authentication configuration
- * @param {string} systemKey - System key
- */
-async function tryUpdateReadmeFromDeploymentDocs(appPath, appName, dataplaneUrl, authConfig, systemKey) {
-  const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
-  const deployPath = path.join(appPath, `${appName}-deploy.json`);
-  let variablesYaml = null;
-  let deployJson = null;
-  try {
-    const configPath = resolveApplicationConfigPath(appPath);
-    variablesYaml = await fs.readFile(configPath, 'utf8');
-  } catch {
-    // optional
-  }
-  try {
-    const deployContent = await fs.readFile(deployPath, 'utf8');
-    deployJson = JSON.parse(deployContent);
-  } catch {
-    // optional
-  }
-  const hasBody = variablesYaml !== null || deployJson !== null;
-  const body = hasBody ? { variablesYaml: variablesYaml || null, deployJson: deployJson || null } : null;
-  const docsResponse = body
-    ? await postDeploymentDocs(dataplaneUrl, authConfig, systemKey, body)
-    : await getDeploymentDocs(dataplaneUrl, authConfig, systemKey);
-  const content = docsResponse?.data?.content ?? docsResponse?.content;
-  // Only overwrite README when the API returns substantial content; otherwise keep the template README
-  const MIN_README_LENGTH = 400;
-  if (content && typeof content === 'string' && content.trim().length >= MIN_README_LENGTH) {
-    const readmePath = path.join(appPath, 'README.md');
-    await fs.writeFile(readmePath, content, 'utf8');
-    logger.log(chalk.gray('  Updated README.md from deployment-docs API (application config + deploy JSON).'));
-  }
-}
-
-/**
- * Writes rbac.yaml / rbac.json from datasource resourceType + capabilities (same as `af repair --rbac`).
- * @param {Object} generatedFiles - Result of generateWizardFiles (appPath, systemFilePath, datasourceFilePaths)
- * @param {string} format - Project format: yaml | json
- */
-function logWizardFileSaveFooter(appName, generatedFiles) {
-  logger.log(formatSuccessParagraph('Wizard completed successfully!'));
-  logger.log(chalk.green(`\nFiles created in: ${generatedFiles.appPath}`));
-  logger.log(chalk.blue('\nNext steps:'));
-  logger.log(chalk.gray(`  1. Review the generated files in integration/${appName}/`));
-  logger.log(chalk.gray('  2. Update env.template with your authentication details'));
-  logger.log(chalk.gray(`  3. Deploy using: node deploy.js or aifabrix deploy ${appName}`));
-}
-
-function mergeRbacAfterWizardFilesWritten(generatedFiles, format) {
-  const { mergeRbacFromDatasources, extractRbacFromSystem } = require('./repair-rbac');
-  const { loadConfigFile } = require('../utils/config-format');
-  const systemParsedForRbac = loadConfigFile(generatedFiles.systemFilePath);
-  const datasourceFileNames = (generatedFiles.datasourceFilePaths || []).map((p) => path.basename(p));
-  const rbacChanges = [];
-  const rbacUpdated = mergeRbacFromDatasources(
-    generatedFiles.appPath,
-    systemParsedForRbac,
-    datasourceFileNames,
-    extractRbacFromSystem,
-    { format: format === 'json' ? 'json' : 'yaml', dryRun: false, changes: rbacChanges }
-  );
-  if (rbacUpdated && rbacChanges.length) {
-    rbacChanges.forEach((c) => logger.log(chalk.gray(`  RBAC: ${c}`)));
-    logger.log(chalk.green('  RBAC file updated from datasource capabilities (enableRBAC).'));
-  }
-}
-
-/**
- * Handle file saving step
- * @async
- * @function handleFileSaving
- * @param {string} appName - Application name
- * @param {Object} systemConfig - System configuration
- * @param {Object[]} datasourceConfigs - Datasource configurations
- * @param {string} systemKey - System key
- * @param {{ dataplaneUrl: string, authConfig: Object, enableRBAC?: boolean }} ctx - Dataplane auth + optional RBAC generation
- * @returns {Promise<Object>} Generated files information
- */
-async function handleFileSaving(appName, systemConfig, datasourceConfigs, systemKey, ctx) {
-  const { dataplaneUrl, authConfig, enableRBAC = false } = ctx || {};
-  logger.log(chalk.blue('\n\uD83D\uDCCB Step 7: Save Files'));
-  const spinner = ora('Saving files...').start();
-  try {
-    const config = require('../core/config');
-    const format = ctx?.format || (await config.getFormat()) || 'yaml';
-    const generatedFiles = await generateWizardFiles(appName, systemConfig, datasourceConfigs, systemKey, { aiGeneratedReadme: null, format });
-    if (enableRBAC && generatedFiles.appPath && generatedFiles.systemFilePath) {
-      try {
-        mergeRbacAfterWizardFilesWritten(generatedFiles, format);
-      } catch (e) {
-        logger.log(chalk.yellow(`  Could not generate RBAC file: ${e.message}`));
-      }
-    }
-    if (systemKey && dataplaneUrl && authConfig && generatedFiles.appPath) {
-      try {
-        await tryUpdateReadmeFromDeploymentDocs(generatedFiles.appPath, appName, dataplaneUrl, authConfig, systemKey);
-      } catch (e) {
-        logger.log(chalk.gray(`  Could not fetch AI-generated README: ${e.message}`));
-      }
-    }
-    spinner.stop();
-    logWizardFileSaveFooter(appName, generatedFiles);
-    return generatedFiles;
-  } catch (error) {
-    spinner.stop();
-    throw error;
-  }
-}
-
 /**
  * Setup dataplane URL and authentication
  * @async

package/lib/commands/wizard-file-saving.js

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Save wizard artifacts and update their README and RBAC files.
+ * @author AI Fabrix Team
+ */
+
+const chalk = require('chalk');
+const ora = require('ora');
+const path = require('path');
+const fs = require('fs').promises;
+const logger = require('../utils/logger');
+const { formatSuccessParagraph } = require('../utils/cli-layout-chalk');
+const { getDeploymentDocs, postDeploymentDocs } = require('../api/wizard.api');
+const { generateWizardFiles } = require('../generator/wizard');
+
+/**
+ * Fetches deployment docs and writes README.md when application config and deploy JSON are available.
+ * @async
+ * @param {string} appPath - Application path
+ * @param {string} appName - Application name
+ * @param {string} dataplaneUrl - Dataplane URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} systemKey - System key
+ */
+async function tryUpdateReadmeFromDeploymentDocs(appPath, appName, dataplaneUrl, authConfig, systemKey) {
+  const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
+  const deployPath = path.join(appPath, `${appName}-deploy.json`);
+  let variablesYaml = null;
+  let deployJson = null;
+  try {
+    const configPath = resolveApplicationConfigPath(appPath);
+    variablesYaml = await fs.readFile(configPath, 'utf8');
+  } catch {
+    // optional
+  }
+  try {
+    const deployContent = await fs.readFile(deployPath, 'utf8');
+    deployJson = JSON.parse(deployContent);
+  } catch {
+    // optional
+  }
+  const hasBody = variablesYaml !== null || deployJson !== null;
+  const body = hasBody ? { variablesYaml: variablesYaml || null, deployJson: deployJson || null } : null;
+  const docsResponse = body
+    ? await postDeploymentDocs(dataplaneUrl, authConfig, systemKey, body)
+    : await getDeploymentDocs(dataplaneUrl, authConfig, systemKey);
+  const content = docsResponse?.data?.content ?? docsResponse?.content;
+  // Only overwrite README when the API returns substantial content; otherwise keep the template README
+  const MIN_README_LENGTH = 400;
+  if (content && typeof content === 'string' && content.trim().length >= MIN_README_LENGTH) {
+    const readmePath = path.join(appPath, 'README.md');
+    await fs.writeFile(readmePath, content, 'utf8');
+    logger.log(chalk.gray('  Updated README.md from deployment-docs API (application config + deploy JSON).'));
+  }
+}
+
+/**
+ * Writes rbac.yaml / rbac.json from datasource resourceType + capabilities (same as `af repair --rbac`).
+ * @param {Object} generatedFiles - Result of generateWizardFiles (appPath, systemFilePath, datasourceFilePaths)
+ * @param {string} format - Project format: yaml | json
+ */
+function logWizardFileSaveFooter(appName, generatedFiles) {
+  logger.log(formatSuccessParagraph('Wizard completed successfully!'));
+  logger.log(chalk.green(`\nFiles created in: ${generatedFiles.appPath}`));
+  logger.log(chalk.blue('\nNext steps:'));
+  logger.log(chalk.gray(`  1. Review the generated files in integration/${appName}/`));
+  logger.log(chalk.gray('  2. Update env.template with your authentication details'));
+  logger.log(chalk.gray(`  3. Deploy using: node deploy.js or aifabrix deploy ${appName}`));
+}
+
+function mergeRbacAfterWizardFilesWritten(generatedFiles, format) {
+  const { mergeRbacFromDatasources, extractRbacFromSystem } = require('./repair-rbac');
+  const { loadConfigFile } = require('../utils/config-format');
+  const systemParsedForRbac = loadConfigFile(generatedFiles.systemFilePath);
+  const datasourceFileNames = (generatedFiles.datasourceFilePaths || []).map((p) => path.basename(p));
+  const rbacChanges = [];
+  const rbacUpdated = mergeRbacFromDatasources(
+    generatedFiles.appPath,
+    systemParsedForRbac,
+    datasourceFileNames,
+    extractRbacFromSystem,
+    { format: format === 'json' ? 'json' : 'yaml', dryRun: false, changes: rbacChanges }
+  );
+  if (rbacUpdated && rbacChanges.length) {
+    rbacChanges.forEach((c) => logger.log(chalk.gray(`  RBAC: ${c}`)));
+    logger.log(chalk.green('  RBAC file updated from datasource capabilities (enableRBAC).'));
+  }
+}
+
+/**
+ * Handle file saving step
+ * @async
+ * @function handleFileSaving
+ * @param {string} appName - Application name
+ * @param {Object} systemConfig - System configuration
+ * @param {Object[]} datasourceConfigs - Datasource configurations
+ * @param {string} systemKey - System key
+ * @param {{ dataplaneUrl: string, authConfig: Object, enableRBAC?: boolean }} ctx - Dataplane auth + optional RBAC generation
+ * @returns {Promise<Object>} Generated files information
+ */
+async function handleFileSaving(appName, systemConfig, datasourceConfigs, systemKey, ctx) {
+  const { dataplaneUrl, authConfig, enableRBAC = false } = ctx || {};
+  logger.log(chalk.blue('\n\uD83D\uDCCB Step 7: Save Files'));
+  const spinner = ora('Saving files...').start();
+  try {
+    const config = require('../core/config');
+    const format = ctx?.format || (await config.getFormat()) || 'yaml';
+    const generatedFiles = await generateWizardFiles(appName, systemConfig, datasourceConfigs, systemKey, { aiGeneratedReadme: null, format });
+    if (enableRBAC && generatedFiles.appPath && generatedFiles.systemFilePath) {
+      try {
+        mergeRbacAfterWizardFilesWritten(generatedFiles, format);
+      } catch (e) {
+        logger.log(chalk.yellow(`  Could not generate RBAC file: ${e.message}`));
+      }
+    }
+    if (systemKey && dataplaneUrl && authConfig && generatedFiles.appPath) {
+      try {
+        await tryUpdateReadmeFromDeploymentDocs(generatedFiles.appPath, appName, dataplaneUrl, authConfig, systemKey);
+      } catch (e) {
+        logger.log(chalk.gray(`  Could not fetch AI-generated README: ${e.message}`));
+      }
+    }
+    spinner.stop();
+    logWizardFileSaveFooter(appName, generatedFiles);
+    return generatedFiles;
+  } catch (error) {
+    spinner.stop();
+    throw error;
+  }
+}
+
+/**
+ * Validate app name and check if directory exists
+ * @async
+ * @function validateAndCheckAppDirectory
+ * @param {string} appName - Application name
+ * @param {boolean} [interactive=true] - Whether to prompt for confirmation
+ * @returns {Promise<boolean>} True if should continue, false if cancelled
+ */
+async function validateAndCheckAppDirectory(appName, interactive = true) {
+  if (!/^[a-z0-9-_]+$/.test(appName)) {
+    throw new Error('Application name must contain only lowercase letters, numbers, hyphens, and underscores');
+  }
+  const appPath = path.join(process.cwd(), 'integration', appName);
+  try {
+    await fs.access(appPath);
+    if (interactive) {
+      const { overwrite } = await require('inquirer').prompt([{
+        type: 'confirm', name: 'overwrite',
+        message: `Directory ${appPath} already exists. Overwrite?`, default: false
+      }]);
+      if (!overwrite) {
+        logger.log(chalk.yellow('Wizard cancelled.')); return false;
+      }
+    } else {
+      logger.log(chalk.yellow(`Warning: Directory ${appPath} exists. Overwriting...`));
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return true;
+}
+
+module.exports = { handleFileSaving, validateAndCheckAppDirectory };

package/lib/core/env-platform-expand.js

@@ -39,9 +39,13 @@ function expandValue(value, values, key, strict, context = {}) {
     const where = context.resourceGroup
       ? `resource group "${context.resourceGroup}" and environment "${context.environment || ''}"`
       : `environment "${context.environment || ''}" (no resource group, so platform values are unavailable)`;
+    const hint = context.resourceGroup
+      ? ''
+      : ' The environment key comes from --env, or from the current CLI environment' +
+        ' (aifabrix auth set-environment <key>).';
     throw new Error(
       `${key} references {${name}}, which no platform or environment configuration resolves for ` +
-      `${where}. Declare it under environments, or run against a resource group that supplies it.`
+      `${where}. Declare it under environments, or run against a resource group that supplies it.${hint}`
     );
   });
 }

package/lib/core/secrets-env-content.js

@@ -470,7 +470,11 @@ async function generateEnvFile(appName, secretsPath, environment = 'local', forc
   }
 
   // Always resolve so missing-secret / kv:// errors still surface in noWrite mode.
-  const resolved = await generateEnvContent(appName, secretsPath, environment, force, { appPath, envOnly });
+  const resolved = await generateEnvContent(appName, secretsPath, environment, force, {
+    appPath,
+    envOnly,
+    runEnvKey: opts.runEnvKey
+  });
 
   if (noWrite) {
     return null;

package/lib/core/secrets-env-write.js

@@ -157,8 +157,11 @@ async function resolveAndWriteEnvFile(appName, options = {}) {
   const environment = options.environment || 'docker';
   const secretsPath = options.secretsPath || null;
   const force = options.force === true;
+  const genOpts = options.runEnvKey ? { runEnvKey: String(options.runEnvKey) } : undefined;
 
-  let resolved = await secrets.generateEnvContent(appName, secretsPath, environment, force);
+  let resolved = genOpts
+    ? await secrets.generateEnvContent(appName, secretsPath, environment, force, genOpts)
+    : await secrets.generateEnvContent(appName, secretsPath, environment, force);
   resolved = await injectRegistryTokens(resolved, secretsPath, appName);
   resolved = await injectBashPrefixedExportLines(resolved, secretsPath, appName);
 
@@ -185,7 +188,8 @@ async function resolveAndWriteEnvFile(appName, options = {}) {
  * @async
  * @function resolveAndGetEnvMap
  * @param {string} appName - Application name
- * @param {Object} [options] - Options (same as resolveAndWriteEnvFile)
+ * @param {Object} [options] - Options (same as resolveAndWriteEnvFile); `runEnvKey` selects the
+ *   manifest environment for {NAME} resolution
  * @returns {Promise<Object.<string, string>>} Map of variable name to value
  */
 async function resolveAndGetEnvMap(appName, options = {}) {
@@ -193,7 +197,10 @@ async function resolveAndGetEnvMap(appName, options = {}) {
   const environment = options.environment || 'docker';
   const secretsPath = options.secretsPath || null;
   const force = options.force === true;
-  let content = await secrets.generateEnvContent(appName, secretsPath, environment, force);
+  const genOpts = options.runEnvKey ? { runEnvKey: String(options.runEnvKey) } : undefined;
+  let content = genOpts
+    ? await secrets.generateEnvContent(appName, secretsPath, environment, force, genOpts)
+    : await secrets.generateEnvContent(appName, secretsPath, environment, force);
   content = await injectRegistryTokens(content, secretsPath, appName);
   content = await injectBashPrefixedExportLines(content, secretsPath, appName);
   const map = parseEnvContentToMap(content);

package/lib/core/secrets-load.js

@@ -167,9 +167,11 @@ async function mergeFromConfiguredSecretsPath(configSecretsPath, userSecrets, he
 }
 
 async function loadMergedConfigAndUserSecrets() {
-  const userSecrets = loadPrimaryUserSecrets();
-  const helpers = createMergeHelpers(userSecrets);
   const userPath = pathsUtil.getPrimaryUserSecretsLocalPath();
+  const userSecrets = await decryptSecretsObject(loadPrimaryUserSecrets(), {
+    defaultSourceLabel: userPath
+  });
+  const helpers = createMergeHelpers(userSecrets);
   /** @type {Record<string, string>} */
   const keySources = {};
   for (const k of Object.keys(userSecrets || {})) {

package/lib/datasource/binary-documents-validator.js

@@ -0,0 +1,190 @@
+/**
+ * Offline semantic checks for the binary/documents pairing (dataplane schema 2.9.13).
+ *
+ * The schema alone cannot express these: `output.mode: documents` and
+ * `fetch.responseType: binary` are individually valid anywhere, but only mean something
+ * when paired with a documentStorage entity and a binary-capable fetch source. The
+ * dataplane rejects the bad combinations at upload; these checks give the same answer
+ * offline, under the same error codes, so an author is not told "valid" by the CLI and
+ * "invalid" by the server.
+ *
+ * Codes mirror the dataplane validator and must not be renamed here.
+ *
+ * @fileoverview Semantic validation for binary responses and document output
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** Sources whose response body the runtime can read as bytes. */
+const BINARY_FETCH_SOURCES = new Set(['openapi', 'http']);
+
+/** documentStorage.binaryOperationRef default, per type/document-storage.json. */
+const DEFAULT_BINARY_OPERATION = 'get';
+
+const CODES = Object.freeze({
+  entityType: 'cip_documents_output_entity_type',
+  storageDisabled: 'cip_documents_output_storage_disabled',
+  binarySource: 'cip_fetch_binary_source_invalid',
+  withoutBinaryFetch: 'cip_documents_output_without_binary_fetch'
+});
+
+/**
+ * @param {Object} datasource - Datasource definition
+ * @returns {Array<[string, Object]>} CIP operation entries, empty when not a CIP datasource
+ */
+function cipOperations(datasource) {
+  const cip = datasource?.execution?.engine === 'cip' ? datasource.execution.cip : null;
+  const operations = cip && cip.operations;
+  if (!operations || typeof operations !== 'object') {
+    return [];
+  }
+  return Object.entries(operations).filter(([, operation]) => operation && typeof operation === 'object');
+}
+
+/**
+ * @param {Object} operation - CIP operation
+ * @returns {Array<Object>} Its steps
+ */
+function stepsOf(operation) {
+  return Array.isArray(operation.steps) ? operation.steps : [];
+}
+
+/**
+ * A step declares a binary body. The schema also promotes a binary Content-Type when
+ * responseType is omitted, but that is a runtime decision we cannot make offline, so only
+ * the explicit declaration counts here.
+ * @param {Object} step - CIP step
+ * @returns {boolean} True when the step fetches a binary body
+ */
+function isBinaryFetch(step) {
+  return Boolean(step && step.fetch && String(step.fetch.responseType || '').trim().toLowerCase() === 'binary');
+}
+
+/**
+ * @param {Object} step - CIP step
+ * @returns {boolean} True when the step finalizes as documents
+ */
+function isDocumentsOutput(step) {
+  return Boolean(step && step.output && step.output.mode === 'documents');
+}
+
+/**
+ * `binary` is a body contract, so it only applies where the runtime holds the response
+ * bytes. A datasource, viewpoint or record source produces rows, never a file body.
+ * @param {string} operationName - Operation key
+ * @param {Array<Object>} steps - Operation steps
+ * @param {Array<Object>} errors - Collected errors
+ * @returns {void}
+ */
+function checkBinaryFetchSources(operationName, steps, errors) {
+  steps.forEach((step, index) => {
+    if (!isBinaryFetch(step)) {
+      return;
+    }
+    const source = String(step.fetch.source || 'openapi').trim().toLowerCase();
+    if (BINARY_FETCH_SOURCES.has(source)) {
+      return;
+    }
+    errors.push({
+      code: CODES.binarySource,
+      message:
+        `operations.${operationName}.steps[${index}].fetch.responseType is "binary" but ` +
+        `fetch.source is "${source || 'unset'}"; binary bodies come from openapi or http sources only`
+    });
+  });
+}
+
+/**
+ * @param {Object} datasource - Datasource definition
+ * @param {string} operationName - Operation key that emits documents
+ * @param {number} stepIndex - Index of the output step
+ * @param {Array<Object>} errors - Collected errors
+ * @returns {void}
+ */
+function checkDocumentsEntity(datasource, operationName, stepIndex, errors) {
+  const where = `operations.${operationName}.steps[${stepIndex}].output.mode is "documents"`;
+  if (!['documentstorage', 'document-storage'].includes(String(datasource.entityType || '').trim().toLowerCase().replace(/_/g, '-'))) {
+    errors.push({
+      code: CODES.entityType,
+      message: `${where} but entityType is "${datasource.entityType || 'unset'}"; documents output requires entityType documentStorage`
+    });
+    return;
+  }
+  const storage = datasource.documentStorage;
+  if (!storage || storage.enabled === false) {
+    errors.push({
+      code: CODES.storageDisabled,
+      message: `${where} but documentStorage is ${storage ? 'not enabled' : 'missing'}; set documentStorage.enabled true`
+    });
+  }
+}
+
+/**
+ * The operation named by binaryOperationRef must actually retrieve bytes, otherwise the
+ * document pipeline has nothing to store. A missing reference and a reference to a
+ * JSON-only operation are the same defect from the author's point of view.
+ * @param {Object} datasource - Datasource definition
+ * @param {string} operationName - Operation key that emits documents
+ * @param {Array<Object>} warnings - Collected warnings
+ * @returns {void}
+ */
+function checkBinaryOperationRef(datasource, operationName, warnings) {
+  const storage = datasource.documentStorage || {};
+  const ref = String(storage.binaryOperationRef || DEFAULT_BINARY_OPERATION);
+  const operations = new Map(cipOperations(datasource));
+  const referenced = operations.get(ref);
+  if (ref === operationName && referenced && stepsOf(referenced).some(isBinaryFetch)) {
+    return;
+  }
+  const reason = ref !== operationName && referenced
+    ? `binaryOperationRef "${ref}" does not name this operation "${operationName}"`
+    : referenced
+      ? `operation "${ref}" has no step with fetch.responseType "binary"`
+      : `operation "${ref}" does not exist in execution.cip.operations`;
+  warnings.push({
+    code: CODES.withoutBinaryFetch,
+    message:
+      `operations.${operationName} emits documents but ${reason}; ` +
+      'set documentStorage.binaryOperationRef to the operation that fetches the file'
+  });
+}
+
+/**
+ * Semantic checks for the binary/documents pairing.
+ * @param {Object} datasource - Datasource definition
+ * @returns {{ errors: Array<Object>, warnings: Array<Object> }} Findings with dataplane codes
+ */
+function validateBinaryDocumentsContract(datasource) {
+  const errors = [];
+  const warnings = [];
+  if (!datasource || typeof datasource !== 'object') {
+    return { errors, warnings };
+  }
+  for (const [operationName, operation] of cipOperations(datasource)) {
+    if (operation.enabled === false) continue;
+    const steps = stepsOf(operation);
+    checkBinaryFetchSources(operationName, steps, errors);
+    steps.forEach((step, index) => {
+      if (!isDocumentsOutput(step)) {
+        return;
+      }
+      checkDocumentsEntity(datasource, operationName, index, errors);
+      const preceding = steps.slice(0, index + 1).some(candidate =>
+        isBinaryFetch(candidate) && BINARY_FETCH_SOURCES.has(String(candidate.fetch.source || 'openapi').trim().toLowerCase()));
+      if (!preceding) {
+        warnings.push({ code: CODES.withoutBinaryFetch,
+          message: `operations.${operationName} has no step with fetch.responseType "binary" preceding documents output` });
+      } else {
+        checkBinaryOperationRef(datasource, operationName, warnings);
+      }
+    });
+  }
+  return { errors, warnings };
+}
+
+module.exports = {
+  CODES,
+  validateBinaryDocumentsContract
+};