@aifabrix/builder 2.59.0 → 2.61.2

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

@@ -0,0 +1,97 @@
+/**
+ * `{NAME}` expansion in env content (plan 200.0).
+ *
+ * Values resolved from the manifest `platforms` / `environments` sections are substituted into
+ * `env.template` values. Runs after `kv://` and before `url://`, so a resolved value may itself
+ * carry a declarative URL.
+ *
+ * Only the value side of `KEY=value` is touched, and only `{UPPER_SNAKE}` tokens that are not
+ * preceded by `$`. That leaves Builder's existing `${VAR}` expansion and `{lowercase}` text in
+ * comments alone — both appear in shipped templates.
+ *
+ * @fileoverview Platform/environment name expansion for env.template
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { resolveConfiguration } = require('../utils/platform-resolution');
+
+/** `{NAME}` not preceded by `$`; uppercase only, matching the configuration name pattern. */
+const NAME_TOKEN = /(?<!\$)\{([A-Z_][A-Z0-9_]*)\}/g;
+
+/**
+ * @param {Object} [manifest] - Application manifest
+ * @returns {boolean} True when the manifest declares either section
+ */
+function declaresPlatformSections(manifest) {
+  if (!manifest || typeof manifest !== 'object') return false;
+  return Array.isArray(manifest.platforms) || Array.isArray(manifest.environments);
+}
+
+function expandValue(value, values, key, strict, context = {}) {
+  return value.replace(NAME_TOKEN, (match, name) => {
+    if (Object.prototype.hasOwnProperty.call(values, name)) return values[name];
+    if (!strict) return match;
+    // Without a resource group no platform matched, so only environments and built-ins resolved.
+    // Saying so turns "why is this missing" into "declare it here".
+    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.${hint}`
+    );
+  });
+}
+
+/**
+ * Expands `{NAME}` on the value side of every assignment line.
+ * @param {string} content - Env content
+ * @param {Object} values - Resolved names
+ * @param {Object} [opts] - `strict` (default true) errors on an unresolved name; false leaves the
+ *   token in place for a later resolver (the deploy manifest, resolved by Miso per installation)
+ * @returns {string}
+ * @throws {Error} When strict and a referenced name is not resolved
+ */
+function expandNamesInEnvContent(content, values, opts = {}) {
+  const strict = opts.strict !== false;
+  const context = { environment: opts.environment, resourceGroup: opts.resourceGroup };
+  const lines = String(content || '').split('\n');
+  const out = lines.map(line => {
+    const trimmed = line.trimStart();
+    if (!trimmed || trimmed.startsWith('#')) return line;
+    const separator = line.indexOf('=');
+    if (separator < 0) return line;
+    const key = line.slice(0, separator);
+    const value = line.slice(separator + 1);
+    return `${key}=${expandValue(value, values, key.trim(), strict, context)}`;
+  });
+  return out.join('\n');
+}
+
+/**
+ * Resolves the manifest sections and expands `{NAME}` when either section is declared.
+ * A manifest without them is returned untouched, so existing applications are unaffected.
+ * @param {string} content - Env content after kv:// resolution
+ * @param {Object} params - `manifest`, `environment` (deployment env key), `resourceGroup`, `strict`
+ * @returns {string}
+ */
+function expandPlatformNamesIfPresent(content, params = {}) {
+  const { manifest, environment, resourceGroup, strict } = params;
+  if (!declaresPlatformSections(manifest)) return content;
+  const { values } = resolveConfiguration(manifest, { environment, resourceGroup });
+  return expandNamesInEnvContent(content, values, { strict, environment, resourceGroup });
+}
+
+module.exports = {
+  NAME_TOKEN,
+  declaresPlatformSections,
+  expandNamesInEnvContent,
+  expandPlatformNamesIfPresent
+};

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

@@ -44,6 +44,7 @@ const { computeEffectiveEnvironmentScopedResources, redisDbIndexForScopedRunEnv
 const { applyRedisDbIndexToEnvContent } = require('../utils/redis-env-scope');
 const { expandDeclarativeUrlsIfPresent } = require('./secrets-env-declarative-expand');
 const {
+  mergeAdditionalPublishedPorts,
   mergeDockerManifestPublishedPort,
   rewriteDockerManifestPublicPortEnvLine
 } = require('../utils/docker-manifest-public-port');
@@ -154,6 +155,12 @@ async function getDockerRedisDbEndpoints() {
   return { redisHost, redisPort, dbHost, dbPort };
 }
 
+/** Host ports clients connect to: the manifest's own, plus any additionalPorts. */
+async function mergePublishedPorts(envVars, appDoc) {
+  await mergeDockerManifestPublishedPort(envVars, appDoc);
+  await mergeAdditionalPublishedPorts(envVars, appDoc);
+}
+
 /** Docker env transformations: ports, infra endpoints, PORT. */
 async function applyDockerTransformations(resolved, variablesPath) {
   resolved = await resolveServicePortsInEnvContent(resolved, 'docker');
@@ -164,7 +171,7 @@ async function applyDockerTransformations(resolved, variablesPath) {
   const containerPort = getContainerPortFromPath(variablesPath) ?? getContainerPortFromDockerEnv(dockerEnv) ?? 3000;
   const envVars = await buildEnvVarMap('docker', null, null, { appPort: containerPort });
   const appDoc = loadVariablesFromPath(variablesPath);
-  await mergeDockerManifestPublishedPort(envVars, appDoc);
+  await mergePublishedPorts(envVars, appDoc);
   envVars.REDIS_HOST = redisHost;
   envVars.REDIS_PORT = String(redisPort);
   envVars.DB_HOST = dbHost;
@@ -187,6 +194,32 @@ async function applyEnvironmentTransformations(resolved, environment, variablesP
   return resolved;
 }
 
+/**
+ * Expands manifest `{NAME}` values when the application declares platforms/environments.
+ * Local Builder runs pass no resource group, so they resolve as the local platform.
+ * @param {string} content - Env content after kv:// resolution
+ * @param {string|null} variablesPath - Application manifest path (null in env-only mode)
+ * @param {string} runEnvKey - Deployment environment key
+ * @param {Object} [options] - `resourceGroup` when a deployment target is known
+ * @returns {string}
+ */
+function expandPlatformNamesForApp(content, variablesPath, runEnvKey, options = {}) {
+  if (!variablesPath) return content;
+  const { expandPlatformNamesIfPresent } = require('./env-platform-expand');
+  const { loadConfigFile } = require('../utils/config-format');
+  let manifest = null;
+  try {
+    manifest = loadConfigFile(variablesPath);
+  } catch {
+    return content;
+  }
+  return expandPlatformNamesIfPresent(content, {
+    manifest,
+    environment: runEnvKey,
+    resourceGroup: options.resourceGroup
+  });
+}
+
 /**
  * Generate .env content from template and secrets (no disk write).
  * When options.envOnly is true, variablesPath is null (no application config).
@@ -210,15 +243,16 @@ async function generateEnvContent(appName, secretsPath, environment = 'local', f
   }
   const secrets = await loadSecrets(secretsPath, appName);
   const { runEnvKey, effective } = await buildScopedKvContext(appPath, options);
-  const scopedKv = { envKey: runEnvKey, effective };
   let resolved = await resolveKvReferences(template, secrets, environment, secretsPaths, appName, {
     envKey: runEnvKey,
     effective,
     envTemplatePath: templatePath
   });
   if (!secretsPath) {
-    await materializeResolvedKvSecretsToUserLocal(template, secrets, scopedKv, options);
+    await materializeResolvedKvSecretsToUserLocal(template, secrets, { envKey: runEnvKey, effective }, options);
   }
+  // Platform/environment {NAME} before url://, so a resolved value may carry a declarative URL.
+  resolved = expandPlatformNamesForApp(resolved, variablesPath, runEnvKey, options);
   resolved = await expandDeclarativeUrlsIfPresent(
     resolved,
     appName,
@@ -436,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
+};