@aifabrix/builder 2.60.0 → 2.62.0

package/lib/core/environment-mode-policy.js

@@ -0,0 +1,177 @@
+/**
+ * Which environments a local installation may build in and select (plan 210.0).
+ *
+ * Two rules, kept together because they describe one position: `tst` and `pro` are
+ * **promotion targets**, not working environments.
+ *
+ * **Build is a dev activity.** `tst` and `pro` receive a promoted image — the same image run
+ * as another container under an environment-suffixed name. Building into them would mean the
+ * artifact in production was never the artifact that was tested, which is the property
+ * promotion exists to guarantee. Miso does not police this; a build leaves no trace of where
+ * it happened, so the refusal has to be here.
+ *
+ * **`tst` and `pro` need the front door.** They exist only in `full` platform mode, where
+ * Traefik routes each environment under its own path. `single-traefik` is a front door for
+ * **one** environment, and `single` is direct ports: several environments on one host collide
+ * on ports there. Allowing the selection in either would produce an environment that is
+ * unreachable rather than one that failed to start, so it is refused up front.
+ *
+ * Pure except for `resolveEffectiveBuildEnvironment`, which reads the configured environment.
+ *
+ * @fileoverview Build and platform-mode environment policy for local installations
+ */
+
+'use strict';
+
+const {
+  SETUP_PLATFORM_MODE,
+  normalizeSetupPlatformMode
+} = require('./setup-platform-mode');
+
+/** Environments that receive a promoted artifact and are never built into. */
+const PROMOTION_ONLY_ENVIRONMENTS = Object.freeze(['tst', 'pro']);
+
+/**
+ * @param {unknown} envKey - Environment key
+ * @returns {string} Lowercase trimmed key
+ */
+function normalizeEnvKey(envKey) {
+  return String(envKey ?? '').trim().toLowerCase();
+}
+
+/**
+ * @param {unknown} envKey - Environment key
+ * @returns {boolean} True when the environment only ever receives a promoted artifact
+ */
+function isPromotionOnlyEnvironment(envKey) {
+  return PROMOTION_ONLY_ENVIRONMENTS.includes(normalizeEnvKey(envKey));
+}
+
+/**
+ * Refuse a build that would target a promotion-only environment.
+ *
+ * `--env` has no default, so an omitted flag silently takes the configured environment. The
+ * message distinguishes the two cases: being told "build cannot target pro" after typing no
+ * environment at all is not actionable on its own.
+ *
+ * @param {unknown} envKey - Resolved environment key
+ * @param {Object} [opts] - Context
+ * @param {boolean} [opts.explicit] - Whether the caller passed --env
+ * @throws {Error} When the environment is tst or pro
+ */
+function assertBuildEnvironmentAllowed(envKey, opts = {}) {
+  const key = normalizeEnvKey(envKey);
+  if (!isPromotionOnlyEnvironment(key)) {
+    return;
+  }
+  const cause = opts.explicit
+    ? `--env ${key}`
+    : `the current environment is ${key}`;
+  throw new Error(
+    `Cannot build into ${key} (${cause}). ${key} receives a promoted image, never a locally ` +
+      'built one, so that what runs there is what was tested in dev.\n' +
+      'Build in dev with: aifabrix build <appKey> --env dev\n' +
+      `Then promote into ${key} with: aifabrix env`
+  );
+}
+
+/**
+ * Refuse selecting a promotion-only environment outside the front-door platform mode.
+ *
+ * @param {unknown} envKey - Environment key being selected
+ * @param {unknown} mode - setupPlatformMode value
+ * @throws {Error} When the environment needs full mode and the install is not in it
+ */
+function assertEnvironmentAllowedForPlatformMode(envKey, mode) {
+  const key = normalizeEnvKey(envKey);
+  if (!isPromotionOnlyEnvironment(key)) {
+    return;
+  }
+  const normalized = normalizeSetupPlatformMode(mode);
+  if (normalized === SETUP_PLATFORM_MODE.FULL) {
+    return;
+  }
+  const reason =
+    normalized === SETUP_PLATFORM_MODE.SINGLE_TRAEFIK
+      ? 'single-traefik is a front door for one environment only'
+      : 'single mode publishes direct ports, and several environments on one host collide on ports';
+  throw new Error(
+    `Environment ${key} requires platform mode "full" (HTTPS front door with per-environment ` +
+      `paths). This installation is "${normalized}": ${reason}.\n` +
+      'Switch with: aifabrix setup --platform full'
+  );
+}
+
+/**
+ * Refuse a promotion-only environment against the installation's configured mode.
+ *
+ * @param {unknown} envKey - Environment key being selected
+ * @returns {Promise<void>}
+ * @throws {Error} When the environment needs full mode and the install is not in it
+ */
+async function assertEnvironmentAllowedForCurrentMode(envKey) {
+  if (!isPromotionOnlyEnvironment(envKey)) {
+    return;
+  }
+  const config = require('./config');
+  const mode =
+    typeof config.getSetupPlatformMode === 'function'
+      ? await config.getSetupPlatformMode()
+      : SETUP_PLATFORM_MODE.SINGLE;
+  assertEnvironmentAllowedForPlatformMode(envKey, mode);
+}
+
+/**
+ * The environment a build will actually target.
+ *
+ * Mirrors how the secret path resolves it (`buildScopedKvContext`): an omitted `--env` falls
+ * through to the configured environment, so a guard that only inspected the flag would let
+ * `aifabrix build` run against `pro` on a machine configured for it.
+ *
+ * @param {Object} [options] - Build options carrying `env`
+ * @returns {Promise<{ envKey: string, explicit: boolean }>}
+ */
+async function resolveEffectiveBuildEnvironment(options = {}) {
+  if (options && options.env) {
+    return { envKey: normalizeEnvKey(options.env), explicit: true };
+  }
+  const config = require('./config');
+  if (typeof config.getCurrentEnvironment !== 'function') {
+    return { envKey: 'dev', explicit: false };
+  }
+  let current;
+  try {
+    current = await config.getCurrentEnvironment();
+  } catch {
+    // An unreadable config is a different failure, reported properly by whatever next needs
+    // it — secrets resolution cannot proceed without it either. Turning it into "cannot
+    // build" would stop every build on a machine whose config has an unrelated problem, and
+    // it protects nothing: reaching tst or pro requires either an explicit --env, which
+    // never reads config, or a readable config naming one.
+    return { envKey: 'dev', explicit: false };
+  }
+  return { envKey: normalizeEnvKey(current) || 'dev', explicit: false };
+}
+
+/**
+ * Resolve the build environment and refuse it when it is promotion-only.
+ *
+ * @param {Object} [options] - Build options carrying `env`
+ * @returns {Promise<string>} The allowed environment key
+ * @throws {Error} When the environment is tst or pro
+ */
+async function assertBuildEnvironmentForOptions(options = {}) {
+  const { envKey, explicit } = await resolveEffectiveBuildEnvironment(options);
+  assertBuildEnvironmentAllowed(envKey, { explicit });
+  return envKey;
+}
+
+module.exports = {
+  PROMOTION_ONLY_ENVIRONMENTS,
+  isPromotionOnlyEnvironment,
+  assertBuildEnvironmentAllowed,
+  assertEnvironmentAllowedForPlatformMode,
+  assertEnvironmentAllowedForCurrentMode,
+  resolveEffectiveBuildEnvironment,
+  assertBuildEnvironmentForOptions
+};

package/lib/core/local-env-overrides.js

@@ -0,0 +1,149 @@
+/**
+ * Builder-owned env values for locally installed platform applications.
+ *
+ * `templates/applications/{miso-controller,builder-api,keycloak}/env.template` are
+ * byte-identical mirrors of the Miso master, and `dataplane` mirrors the dataplane
+ * repository. An edit to a mirror survives until the next `chore(templates): sync`
+ * commit and then disappears without a diff anyone reads, so a value Builder decides
+ * cannot live there. It is applied here instead, after the template is resolved.
+ *
+ * @fileoverview Local-install env overrides owned by Builder, not by a mirrored template
+ */
+
+'use strict';
+
+/** Applications the CLI registers itself through `.../applications/bootstrap`. */
+const CLI_BOOTSTRAPPED_APP_KEYS = Object.freeze(['dataplane']);
+
+/**
+ * Controller onboarding owns the miso-only platform applications. Dataplane remains a
+ * CLI-owned workload and must never be inserted into this list.
+ */
+const DEFAULT_LOCAL_ONBOARDING_APPS = Object.freeze(['builder-api']);
+
+/** Config key an installation may set to choose its own onboarding list. */
+const ONBOARDING_APPS_CONFIG_KEY = 'onboardingApps';
+
+/**
+ * Keys Builder's mirror carried that the Miso master does not.
+ *
+ * They were edits to a mirrored file, which is the thing this module exists to prevent: the
+ * mirror has since fallen 57 lines behind its master, and re-syncing it would have dropped
+ * them silently. They are declared here instead, so the next sync cannot lose them.
+ *
+ * - `INFRASTRUCTURE_NAME` is the only one carrying a value, used by controller and onboarding
+ *   flows. Losing it would change behaviour, not merely remove a blank line.
+ * - The other three shipped empty. They are kept so a local install's env has exactly the keys
+ *   it had before this sync: an absent key and an empty one are usually the same thing, and
+ *   "usually" is not a basis for changing every installation at once.
+ *
+ * `ACR_LOGIN_SERVER` is deliberately empty. Miso removed it with the note that its proper home
+ * is Builder's run tooling, which knows the per-developer answer — so an installation that
+ * needs it should have it injected there rather than shipped one test installation's registry
+ * to everybody, which is what happened the last time it carried a value.
+ */
+const MISO_CONTROLLER_LOCAL_ONLY_ENV = Object.freeze({
+  INFRASTRUCTURE_NAME: '${DEV_USERNAME}.${DEV_ROOT_DOMAIN}',
+  KEYCLOAK_PUBLIC_KEY: '',
+  OTEL_SERVICE_VERSION: '',
+  ACR_LOGIN_SERVER: ''
+});
+
+function normalizeAppKeyList(value) {
+  const raw = Array.isArray(value) ? value : String(value ?? '').split(',');
+  const seen = new Set();
+  for (const entry of raw) {
+    const key = String(entry ?? '').trim().toLowerCase();
+    if (key) {
+      seen.add(key);
+    }
+  }
+  return [...seen];
+}
+
+/**
+ * Applications controller onboarding may register on this installation.
+ *
+ * Builder API is always retained because Controller onboarding owns that miso-only
+ * application. This also migrates older explicit-empty setup values safely.
+ *
+ * @param {Object} [cfg] - Parsed `~/.aifabrix/config.yaml`
+ * @returns {string[]} Application keys, never including one the CLI bootstraps
+ */
+function resolveLocalOnboardingApps(cfg) {
+  const configured = cfg ? cfg[ONBOARDING_APPS_CONFIG_KEY] : undefined;
+  const list = configured === undefined || configured === null
+    ? [...DEFAULT_LOCAL_ONBOARDING_APPS]
+    : normalizeAppKeyList(configured);
+  const allowed = list.filter((key) => !CLI_BOOTSTRAPPED_APP_KEYS.includes(key));
+  return ['builder-api', ...allowed.filter((key) => key !== 'builder-api')];
+}
+
+/**
+ * Env values Builder owns for a locally installed application.
+ *
+ * @param {string} appName - Application key
+ * @param {Object} [cfg] - Parsed `~/.aifabrix/config.yaml`
+ * @returns {Object.<string, string>} Map to merge into resolved env content; empty when none apply
+ */
+function localEnvOverridesForApp(appName, cfg) {
+  const key = String(appName ?? '').trim().toLowerCase();
+  if (key === 'miso-controller') {
+    return {
+      ONBOARDING_APPS: resolveLocalOnboardingApps(cfg).join(','),
+      ...MISO_CONTROLLER_LOCAL_ONLY_ENV
+    };
+  }
+  if (key === 'builder-api' || key === 'integration-server') {
+    return { MISO_ENVIRONMENT: 'miso' };
+  }
+  return {};
+}
+
+/**
+ * Merge Builder-owned values into resolved env content for a locally installed application.
+ *
+ * Applied after the template is resolved, so the installation's choice is the authority for
+ * these keys. The merge function is passed in rather than imported, because the only caller
+ * owns it and importing it here would close a require cycle.
+ *
+ * @param {string} content - Resolved env content
+ * @param {string} appName - Application key
+ * @param {(content: string, map: Object) => string} mergeEnvMapIntoContent - Merge helper
+ * @returns {Promise<string>} Content with overrides merged, unchanged when none apply
+ */
+async function applyLocalEnvOverrides(content, appName, mergeEnvMapIntoContent) {
+  let cfg = null;
+  try {
+    cfg = await require('./config').getConfig();
+  } catch {
+    // No readable config (fresh machine, or resolve outside an installation): use defaults.
+  }
+  const overrides = localEnvOverridesForApp(appName, cfg);
+  if (!overrides || Object.keys(overrides).length === 0) {
+    return content;
+  }
+  return mergeEnvMapIntoContent(content, overrides);
+}
+
+/**
+ * The onboarding list for an installation that does or does not carry the integration
+ * server. Written to config so the choice survives, rather than being asked on every run.
+ *
+ * @param {boolean} integrationServer - Whether the installation carries it
+ * @returns {string[]} Value for the `onboardingApps` config key
+ */
+function onboardingAppsForIntegrationServer(integrationServer) {
+  return integrationServer ? ['builder-api', 'integration-server'] : ['builder-api'];
+}
+
+module.exports = {
+  CLI_BOOTSTRAPPED_APP_KEYS,
+  DEFAULT_LOCAL_ONBOARDING_APPS,
+  ONBOARDING_APPS_CONFIG_KEY,
+  MISO_CONTROLLER_LOCAL_ONLY_ENV,
+  resolveLocalOnboardingApps,
+  localEnvOverridesForApp,
+  applyLocalEnvOverrides,
+  onboardingAppsForIntegrationServer
+};

package/lib/core/secrets-ensure.js

@@ -29,6 +29,7 @@ const {
   saveSecretsFile
 } = require('../utils/secrets-generator');
 const { encryptSecret } = require('../utils/secrets-encryption');
+const { generateRsaSecretValues } = require('../parameters/rsa-secret-values');
 const { loadEnvTemplate } = require('../utils/secrets-helpers');
 const {
   buildInfraPlaceholderContext,
@@ -287,12 +288,13 @@ async function ensureSecretsForKeys(keys, options = {}) {
   if (toAdd.length === 0) return [];
 
   const encryptionKey = await config.getSecretsEncryptionKey();
+  const rsaValues = emptyForCredentials ? {} : generateRsaSecretValues(toAdd, { ...existing, ...suggested }, encryptionKey);
   const added = [];
 
   return addSecretsToFile({
     filePath: target.filePath,
-    toAdd,
-    suggested,
+    toAdd: [...new Set([...toAdd, ...Object.keys(rsaValues)])],
+    suggested: { ...rsaValues, ...suggested },
     emptyForCredentials,
     encryptionKey,
     added,

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

@@ -12,6 +12,7 @@ const fs = require('fs');
 const path = require('path');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const config = require('./config');
+const { applyLocalEnvOverrides } = require('./local-env-overrides');
 const {
   interpolateEnvVars,
   collectMissingSecrets,
@@ -40,8 +41,9 @@ const secretsEnsure = require('./secrets-ensure');
 const { resolveSecretsPath, getActualSecretsPath } = require('../utils/secrets-path');
 const pathsUtil = require('../utils/paths');
 const { readAppEnvironmentScopedFlagForAppPath } = require('../utils/app-scoped-config');
-const { computeEffectiveEnvironmentScopedResources, redisDbIndexForScopedRunEnv } = require('../utils/environment-scoped-resources');
-const { applyRedisDbIndexToEnvContent } = require('../utils/redis-env-scope');
+const { computeEffectiveEnvironmentScopedResources } = require('../utils/environment-scoped-resources');
+const { isStrictScopedEnvironment } = require('../utils/secrets-kv-scope');
+const { applyScopedRedisDbIndex } = require('../utils/redis-env-scope');
 const { expandDeclarativeUrlsIfPresent } = require('./secrets-env-declarative-expand');
 const {
   mergeAdditionalPublishedPorts,
@@ -106,7 +108,8 @@ async function resolveKvReferences(
         secretsFilePaths,
         appName,
         envTemplatePath,
-        envTemplate
+        envTemplate,
+        scopedKv
       })
     );
   }
@@ -237,12 +240,14 @@ async function generateEnvContent(appName, secretsPath, environment = 'local', f
   const variablesPath = (options && options.envOnly) ? null : resolveApplicationConfigPath(appPath);
   const template = loadEnvTemplate(templatePath);
   const secretsPaths = await getActualSecretsPath(secretsPath, appName);
-  if (force) {
+  const { runEnvKey, effective } = await buildScopedKvContext(appPath, options);
+  // --force backfills a missing secret by generating one. A strict environment must not be
+  // handed a value the Controller has never seen, so it errors on the missing key instead.
+  if (force && !isStrictScopedEnvironment(runEnvKey)) {
     const preferredPath = secretsPath ? resolveSecretsPath(secretsPath) : secretsPaths.userPath;
     await secretsEnsure.ensureSecretsFromEnvTemplate(templatePath, { preferredFilePath: preferredPath });
   }
   const secrets = await loadSecrets(secretsPath, appName);
-  const { runEnvKey, effective } = await buildScopedKvContext(appPath, options);
   let resolved = await resolveKvReferences(template, secrets, environment, secretsPaths, appName, {
     envKey: runEnvKey,
     effective,
@@ -262,10 +267,8 @@ async function generateEnvContent(appName, secretsPath, environment = 'local', f
     Boolean(options.envOnly)
   );
   resolved = await applyEnvironmentTransformations(resolved, environment, variablesPath);
-  if (effective) {
-    const idx = redisDbIndexForScopedRunEnv(runEnvKey);
-    resolved = applyRedisDbIndexToEnvContent(resolved, idx);
-  }
+  resolved = applyScopedRedisDbIndex(resolved, runEnvKey, effective);
+  resolved = await applyLocalEnvOverrides(resolved, appName, mergeEnvMapIntoContent);
 
   return resolved;
 }
@@ -470,7 +473,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);
@@ -201,7 +208,7 @@ async function resolveAndGetEnvMap(appName, options = {}) {
     const adminSecrets = require('./admin-secrets');
     const { applyAdminSecretsPlatformOverlay } = require('./admin-secrets-env-overlay');
     const adminObj = await adminSecrets.readAndDecryptAdminSecrets();
-    applyAdminSecretsPlatformOverlay(map, adminObj);
+    applyAdminSecretsPlatformOverlay(map, adminObj, appName);
   } catch {
     // admin-secrets.env optional until up-infra/setup
   }

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
+};

package/lib/datasource/capability/capability-manifest.js

@@ -9,6 +9,7 @@
 'use strict';
 
 const FORBIDDEN_ROOT_KEYS = new Set([
+  '_comManifestRoleCatalog',
   'context',
   'origin',
   'generatedBy',