@aifabrix/builder 2.54.1 → 2.55.0

package/lib/integration-definition/apply.js

@@ -9,6 +9,15 @@ const path = require('path');
 const fsReal = require('../internal/fs-real-sync');
 const { getIntegrationPath } = require('../utils/paths');
 const { validateIntegrationDefinition } = require('./validate');
+const {
+  canonicalDatasourceKeyMap,
+  datasourceFileName
+} = require('./apply-datasource-keys');
+const { applyBidRelationships } = require('./apply-relationships');
+const { applyStaticAndEnterprise } = require('./apply-static-enterprise');
+const { applyViewpointDefaults } = require('./apply-viewpoint-defaults');
+const { stampCredentialTestEndpoint } = require('./apply-test-endpoint');
+const { buildSystemFile } = require('./apply-system-file');
 
 const STAMP_FILE = '.aifabrix-integration-definition.json';
 
@@ -96,6 +105,21 @@ function buildDatasourceSchema(labelField) {
   };
 }
 
+function mergeBidSchemaProperties(body, ds) {
+  const extra = ds.metadataSchema && ds.metadataSchema.properties;
+  if (!extra || typeof extra !== 'object') {
+    return;
+  }
+  if (!body.metadataSchema || typeof body.metadataSchema !== 'object') {
+    body.metadataSchema = { type: 'object', properties: {} };
+  }
+  const schema = /** @type {Record<string, unknown>} */ (body.metadataSchema);
+  if (!schema.properties || typeof schema.properties !== 'object') {
+    schema.properties = {};
+  }
+  Object.assign(schema.properties, extra);
+}
+
 function enrichDatasourceFile(body, ds, enrichOptions) {
   const { enrichDatasourceFromOpenApi } = require('./enrich-openapi-operations');
   const openapiSourceRef =
@@ -133,6 +157,8 @@ function buildDatasourceFile(ds, systemKey, capabilities, sync, enrichOptions =
     entityType: ds.entityType || 'recordStorage',
     resourceType: ds.resourceType,
     version: '1.0.0',
+    ...(ds.storageType ? { storageType: ds.storageType } : {}),
+    ...(ds.dimensions && typeof ds.dimensions === 'object' ? { dimensions: ds.dimensions } : {}),
     capabilities: buildDatasourceCapabilities(caps, key),
     // Schema sync is mode/schedule/batchSize only; BID sync.mode=incremental is operational intent.
     sync: { mode: 'pull', schedule: /** @type {any} */ (sync).schedule || '0 */6 * * *', batchSize: 100 },
@@ -143,6 +169,7 @@ function buildDatasourceFile(ds, systemKey, capabilities, sync, enrichOptions =
     // Mirror capabilities → openapi.operations + execution.cip.operations stubs (154.7).
   repairSyncOperationsFromCapabilities(body, []);
   seedPropertyKeysOnDatasource(body, ds.propertyKeys);
+  mergeBidSchemaProperties(body, ds);
   enrichDatasourceFile(body, ds, enrichOptions);
   return body;
 }
@@ -192,42 +219,6 @@ function collectAssociationObjectTypes(datasources, systemOpenapiSourceRef, enri
   return [...types];
 }
 
-/**
- * @param {Record<string, unknown>} bid
- * @returns {Record<string, unknown>}
- */
-function buildSystemFile(bid) {
-  const system = /** @type {Record<string, unknown>} */ (bid.system);
-  const identity = /** @type {Record<string, unknown>} */ (bid.packageIdentity);
-  const refs = /** @type {Record<string, string>} */ (system.connectionRefs || {});
-  const tokenRef = refs.token || refs.apiKey || Object.values(refs)[0] || `kv://${identity.systemKey}/token`;
-  return {
-    key: system.key,
-    displayName: system.displayName || identity.displayName,
-    description: system.description || identity.displayName,
-    type: system.type || 'openapi',
-    enabled: true,
-    systemKind: system.systemKind || 'crm',
-    authentication: {
-      authType: 'credential',
-      credential: {
-        credentialKey: `${identity.systemKey}-cred`,
-        method: 'bearerToken',
-        variables: {
-          baseUrl: refs.baseUrl || 'https://example.invalid',
-          headerName: 'Authorization',
-          prefix: 'Bearer'
-        },
-        security: {
-          token: tokenRef
-        },
-        writeOnce: true
-      }
-    },
-    dataSources: (/** @type {any[]} */ (bid.datasources) || []).map((d) => d.key)
-  };
-}
-
 /**
  * @param {Record<string, unknown>} bid
  * @param {string[]} datasourceFiles
@@ -290,45 +281,73 @@ function buildEnvTemplate(bid) {
  *   nextStamp: Record<string, unknown>
  * }}
  */
+function remappedCapabilities(capabilities, keyMap) {
+  const out = {};
+  for (const [key, value] of Object.entries(capabilities || {})) {
+    out[keyMap.get(key) || key] = value;
+  }
+  return out;
+}
+
+function buildApplyStamp(bid, systemKey, identity) {
+  return {
+    schemaName: bid.schemaName,
+    schemaVersion: bid.schemaVersion,
+    definitionId: bid.definitionId,
+    definitionHash: bid.definitionHash,
+    suiteRunId: /** @type {any} */ (bid.meta).suiteRunId,
+    systemKey,
+    packageVersion: identity.packageVersion,
+    appliedAt: new Date().toISOString()
+  };
+}
+
 function buildPackageArtifacts(bid, systemKey, enrichOptions = {}) {
   const identity = /** @type {Record<string, unknown>} */ (bid.packageIdentity);
   const datasources = /** @type {Record<string, unknown>[]} */ (bid.datasources || []);
-  const capabilities = /** @type {Record<string, string[]>} */ (bid.capabilities || {});
+  const capabilities = remappedCapabilities(
+    /** @type {Record<string, string[]>} */ (bid.capabilities || {}),
+    canonicalDatasourceKeyMap(datasources, systemKey)
+  );
   const sync = /** @type {Record<string, unknown>} */ (bid.sync || {});
-  const system = /** @type {Record<string, unknown>} */ (bid.system || {});
+  const systemBlock = /** @type {Record<string, unknown>} */ (bid.system || {});
   const systemOpenapiSourceRef =
-    typeof system.openapiSourceRef === 'string' ? system.openapiSourceRef : '';
+    typeof systemBlock.openapiSourceRef === 'string' ? systemBlock.openapiSourceRef : '';
   const associationTargets = collectAssociationObjectTypes(
     datasources,
     systemOpenapiSourceRef,
     enrichOptions
   );
+  const keyMap = canonicalDatasourceKeyMap(datasources, systemKey);
   const systemFile = `${systemKey}-system.json`;
-  const datasourceFiles = datasources.map((ds) => `${systemKey}-datasource-${ds.key}.json`);
-  return {
-    systemFile,
-    datasourceFiles,
-    application: buildApplicationFile(bid, datasourceFiles, systemFile),
-    system: buildSystemFile(bid),
-    dsFiles: datasources.map((ds) => ({
-      name: `${systemKey}-datasource-${ds.key}.json`,
-      body: buildDatasourceFile(ds, systemKey, capabilities, sync, {
+  const dsFiles = datasources.map((ds) => {
+    const canonicalKey = keyMap.get(String(ds.key)) || String(ds.key);
+    return {
+      name: datasourceFileName(systemKey, canonicalKey),
+      body: buildDatasourceFile({ ...ds, key: canonicalKey }, systemKey, capabilities, sync, {
         ...enrichOptions,
         systemOpenapiSourceRef,
         associationTargets
       })
-    })),
+    };
+  });
+  applyBidRelationships(dsFiles, /** @type {any[]} */ (bid.relationships) || [], keyMap);
+  applyStaticAndEnterprise(dsFiles, bid);
+  applyViewpointDefaults(dsFiles, /** @type {any[]} */ (bid.relationships) || [], keyMap);
+  const system = buildSystemFile(bid);
+  stampCredentialTestEndpoint(system, dsFiles);
+  return {
+    systemFile,
+    datasourceFiles: dsFiles.map((file) => file.name),
+    application: buildApplicationFile(
+      bid,
+      dsFiles.map((file) => file.name),
+      systemFile
+    ),
+    system,
+    dsFiles,
     envTemplate: buildEnvTemplate(bid),
-    nextStamp: {
-      schemaName: bid.schemaName,
-      schemaVersion: bid.schemaVersion,
-      definitionId: bid.definitionId,
-      definitionHash: bid.definitionHash,
-      suiteRunId: /** @type {any} */ (bid.meta).suiteRunId,
-      systemKey,
-      packageVersion: identity.packageVersion,
-      appliedAt: new Date().toISOString()
-    }
+    nextStamp: buildApplyStamp(bid, systemKey, identity)
   };
 }
 

package/lib/integration-definition/enrich-openapi-operations.js

@@ -10,6 +10,7 @@ const fsReal = require('../internal/fs-real-sync');
 const {
   maybeEnrichCrmStyleFieldMappings
 } = require('./enrich-crm-field-mappings');
+const { pickBestMatchingOp, entityTokensFromDatasource } = require('./enrich-openapi-pick');
 
 const PATH_PARAM_RE = /\{(\w+)\}/g;
 
@@ -171,7 +172,8 @@ function normalizeOp(method, opPath, op) {
     method: String(method || '').toUpperCase(),
     path: String(opPath),
     operationId: typeof op.operationId === 'string' ? op.operationId : '',
-    pathParamCount: params.length
+    pathParamCount: params.length,
+    tags: Array.isArray(op.tags) ? op.tags.map((row) => String(row || '')) : []
   };
 }
 
@@ -212,12 +214,29 @@ function isBatchOrSearch(text) {
  * @param {Array<{ method: string, path: string, operationId: string, pathParamCount: number }>} ops
  * @returns {{ method: string, path: string, operationId: string } | null}
  */
-function pickFirstMatchingOp(candidates, predicate, idPattern) {
-  const hits = candidates.filter(predicate);
-  return hits.find((op) => idPattern.test(op.operationId)) || hits[0] || null;
+function requiredQueryDefaults(doc, method, opPath) {
+  const out = {};
+  for (const param of operationParameters(doc, method, opPath)) {
+    if (!param || param.in !== 'query' || param.required !== true) {
+      continue;
+    }
+    const name = String(param.name || '').trim();
+    if (!name) {
+      continue;
+    }
+    const schema = param.schema && typeof param.schema === 'object' ? param.schema : {};
+    if (schema.default !== undefined) {
+      out[name] = schema.default;
+    } else if (typeof schema.minimum === 'number') {
+      out[name] = schema.minimum;
+    } else {
+      out[name] = `{{${name}}}`;
+    }
+  }
+  return out;
 }
 
-function pickOperationForCapability(capabilityKey, ops) {
+function pickOperationForCapability(capabilityKey, ops, entityTokens) {
   const key = String(capabilityKey || '').toLowerCase();
   const candidates = ops.filter((op) => !isBatchOrSearch(`${op.path} ${op.operationId}`));
   const rules = {
@@ -256,7 +275,7 @@ function pickOperationForCapability(capabilityKey, ops) {
   if (!rule) {
     return null;
   }
-  return pickFirstMatchingOp(candidates, rule.predicate, rule.idPattern);
+  return pickBestMatchingOp(candidates, rule.predicate, rule.idPattern, entityTokens);
 }
 
 /**
@@ -293,7 +312,11 @@ function bindOpenApiOperation(body, binding, capabilityKey) {
 
 function createCipQuery(capabilityKey, bindOptions) {
   const cap = String(capabilityKey || '').toLowerCase();
-  const query = {};
+  const query = {
+    ...(bindOptions.requiredQuery && typeof bindOptions.requiredQuery === 'object'
+      ? bindOptions.requiredQuery
+      : {})
+  };
   const targets = Array.isArray(bindOptions.associationTargets)
     ? bindOptions.associationTargets.map((row) => String(row || '').trim()).filter(Boolean)
     : [];
@@ -394,10 +417,11 @@ function enrichDatasourceFromOpenApi(body, openapiSourceRef, options = {}) {
   )
     .map((row) => String(row || '').trim())
     .filter((row) => row && row !== selfType);
+  const entityTokens = entityTokensFromDatasource(body);
   const bound = [];
   let samplePath = '';
   for (const capabilityKey of caps) {
-    const picked = pickOperationForCapability(capabilityKey, indexed);
+    const picked = pickOperationForCapability(capabilityKey, indexed, entityTokens);
     if (!picked) {
       continue;
     }
@@ -408,7 +432,8 @@ function enrichDatasourceFromOpenApi(body, openapiSourceRef, options = {}) {
         picked.path
       ),
       associationTargets,
-      cursorPagination: operationCursorPagination(doc, picked.method, picked.path)
+      cursorPagination: operationCursorPagination(doc, picked.method, picked.path),
+      requiredQuery: requiredQueryDefaults(doc, picked.method, picked.path)
     });
     bound.push(capabilityKey);
     if (!samplePath) {
@@ -429,5 +454,6 @@ module.exports = {
   enrichDatasourceFromOpenApi,
   objectTypeFromOpenApiPath,
   operationDeclaresAssociationsQuery,
-  operationCursorPagination
+  operationCursorPagination,
+  requiredQueryDefaults
 };

package/lib/integration-definition/enrich-openapi-pick.js

@@ -0,0 +1,87 @@
+/**
+ * Score OpenAPI operations by datasource entity tokens.
+ *
+ * @fileoverview Prefer path/tag overlap over first GET in a multi-entity spec
+ */
+
+'use strict';
+
+/**
+ * @param {Record<string, unknown>} body
+ * @returns {string[]}
+ */
+function entityTokensFromDatasource(body) {
+  const tokens = new Set();
+  for (const raw of [body.key, body.resourceType, body.displayName]) {
+    const value = String(raw || '').trim().toLowerCase();
+    if (!value) {
+      continue;
+    }
+    tokens.add(value);
+    for (const part of value.split(/[-_]/g)) {
+      if (part.length > 1) {
+        tokens.add(part);
+      }
+    }
+  }
+  return [...tokens];
+}
+
+/**
+ * @param {{ path?: string, operationId?: string, tags?: string[] }} op
+ * @param {string[]} tokens
+ * @returns {number}
+ */
+function scoreOpForEntity(op, tokens) {
+  if (!Array.isArray(tokens) || tokens.length === 0) {
+    return 0;
+  }
+  const path = String(op.path || '').toLowerCase();
+  const id = String(op.operationId || '').toLowerCase();
+  const tags = Array.isArray(op.tags)
+    ? op.tags.map((row) => String(row || '').toLowerCase()).join(' ')
+    : '';
+  const hay = `${path} ${id} ${tags}`;
+  const segments = path.split('/').filter(Boolean);
+  let score = 0;
+  for (const token of tokens) {
+    if (segments.includes(token)) {
+      score += 20;
+    } else if (hay.includes(token)) {
+      score += 10;
+    }
+  }
+  return score;
+}
+
+/**
+ * @param {Array<{ method: string, path: string, operationId: string }>} candidates
+ * @param {(op: object) => boolean} predicate
+ * @param {RegExp} idPattern
+ * @param {string[]} [entityTokens]
+ * @returns {object | null}
+ */
+function pickBestMatchingOp(candidates, predicate, idPattern, entityTokens) {
+  const hits = candidates.filter(predicate);
+  if (hits.length === 0) {
+    return null;
+  }
+  const tokens = Array.isArray(entityTokens) ? entityTokens : [];
+  if (tokens.length > 0) {
+    const scored = hits.map((op) => ({
+      op,
+      score: scoreOpForEntity(op, tokens) + (idPattern.test(op.operationId) ? 5 : 0)
+    }));
+    scored.sort((left, right) => right.score - left.score);
+    if (scored[0].score > 0) {
+      return scored[0].op;
+    }
+  }
+  return hits.find((op) => idPattern.test(op.operationId)) || hits[0] || null;
+}
+
+module.exports = {
+  entityTokensFromDatasource,
+  scoreOpForEntity,
+  pickBestMatchingOp
+};

package/lib/lifecycle/role-assistant-governance.js

@@ -11,7 +11,9 @@ const { VERDICT } = require('./product-model');
 
 const GOVERNANCE_SCENARIOS_MISSING = 'GOVERNANCE_SCENARIOS_MISSING';
 const GOVERNANCE_NOT_VERIFIED = 'GOVERNANCE_NOT_VERIFIED';
+const OPERATIONS_NOT_VERIFIED = 'OPERATIONS_NOT_VERIFIED';
 const ROLE_ASSISTANT_GOVERNANCE_WARNING = 'ROLE_ASSISTANT_GOVERNANCE_PACKS';
+const ROLE_ASSISTANT_OPERATIONS_WARNING = 'ROLE_ASSISTANT_CS_OPERATIONS';
 
 const VERDICT_RANK = Object.freeze({
   [VERDICT.FAILED]: 4,
@@ -70,37 +72,50 @@ function rollupGovernanceFromDatasources(datasources) {
   return worst;
 }
 
-function stripGovernanceNotVerified(recommendations) {
+function stripCsNotVerified(recommendations) {
   if (!Array.isArray(recommendations)) {
     return [];
   }
-  return recommendations.filter((rec) => rec && rec.code !== GOVERNANCE_NOT_VERIFIED);
+  return recommendations.filter(
+    (rec) =>
+      rec && rec.code !== GOVERNANCE_NOT_VERIFIED && rec.code !== OPERATIONS_NOT_VERIFIED
+  );
 }
 
-function appendRoleAssistantGovernanceWarning(warnings) {
+function appendRoleAssistantCsWarning(warnings, code, message) {
   const next = Array.isArray(warnings) ? [...warnings] : [];
-  const exists = next.some((row) => row && row.code === ROLE_ASSISTANT_GOVERNANCE_WARNING);
+  const exists = next.some((row) => row && row.code === code);
   if (!exists) {
-    next.push({
-      code: ROLE_ASSISTANT_GOVERNANCE_WARNING,
-      message:
-        'Role Assistant datasources do not use Connected System governance packs. ' +
-        'Isolation is Work Hub cases and role-assistant.yaml.'
-    });
+    next.push({ code, message });
   }
   return next;
 }
 
-/**
- * Treat CS-only missing packs as not applicable on a Role Assistant report.
- * @param {Object} report
- * @returns {Object}
- */
-function remapRoleAssistantGovernanceReport(report) {
-  if (!report || typeof report !== 'object') {
-    return report;
+function notApplicableCsPillar(block, errorCode) {
+  const base = block && typeof block === 'object' ? { ...block } : {};
+  base.verdict = VERDICT.NOT_APPLICABLE;
+  if (errorCode) {
+    base.errorCode = errorCode;
   }
-  const next = { ...report };
+  return base;
+}
+
+function remapCsPillars(next) {
+  let remapped = false;
+  const opsVerdict = String((next.operations && next.operations.verdict) || '');
+  if (opsVerdict === VERDICT.FAILED || opsVerdict === VERDICT.NOT_VERIFIED) {
+    next.operations = notApplicableCsPillar(next.operations, OPERATIONS_NOT_VERIFIED);
+    remapped = true;
+  }
+  const govVerdict = String((next.governance && next.governance.verdict) || '');
+  if (govVerdict === VERDICT.FAILED || govVerdict === VERDICT.NOT_VERIFIED) {
+    next.governance = notApplicableCsPillar(next.governance, GOVERNANCE_NOT_VERIFIED);
+    remapped = true;
+  }
+  return remapped;
+}
+
+function remapMissingPackRows(report, next) {
   let remapped = false;
   if (Array.isArray(report.datasources)) {
     next.datasources = report.datasources.map((row) => {
@@ -120,11 +135,30 @@ function remapRoleAssistantGovernanceReport(report) {
     next.governance = notApplicableMissingPack(next.governance);
     remapped = true;
   }
+  return remapped;
+}
+
+function remapRoleAssistantGovernanceReport(report) {
+  if (!report || typeof report !== 'object') {
+    return report;
+  }
+  const next = { ...report };
+  const remapped = remapMissingPackRows(report, next) || remapCsPillars(next);
   if (!remapped) {
     return report;
   }
-  next.recommendations = stripGovernanceNotVerified(report.recommendations);
-  next.warnings = appendRoleAssistantGovernanceWarning(report.warnings);
+  next.recommendations = stripCsNotVerified(report.recommendations);
+  next.warnings = appendRoleAssistantCsWarning(
+    report.warnings,
+    ROLE_ASSISTANT_GOVERNANCE_WARNING,
+    'Role Assistant datasources do not use Connected System governance packs. ' +
+      'Isolation is Work Hub cases and role-assistant.yaml.'
+  );
+  next.warnings = appendRoleAssistantCsWarning(
+    next.warnings,
+    ROLE_ASSISTANT_OPERATIONS_WARNING,
+    'Role Assistant prove does not require Connected System operations verification.'
+  );
   return next;
 }
 
@@ -140,6 +174,7 @@ function lifecyclePillarSatisfied(verdict) {
 module.exports = {
   GOVERNANCE_SCENARIOS_MISSING,
   ROLE_ASSISTANT_GOVERNANCE_WARNING,
+  ROLE_ASSISTANT_OPERATIONS_WARNING,
   governanceIsMissingPack,
   remapRoleAssistantGovernanceReport,
   lifecyclePillarSatisfied

package/lib/programmatic/capability-registry.js

@@ -49,6 +49,7 @@ const CAPABILITIES = Object.freeze([
   { method: 'GET', route: '/systems/:systemKey/lifecycle', handlerId: 'getLifecycleReport', operationType: 'certify.read', mutating: false },
   { method: 'POST', route: '/systems/:systemKey/upload', handlerId: 'runUpload', operationType: 'apply.dev', mutating: true },
   { method: 'POST', route: '/systems/:systemKey/deploy', handlerId: 'runDeploySystem', operationType: 'apply.prod', mutating: true },
+  { method: 'POST', route: '/systems/:systemKey/download', handlerId: 'runDownload', operationType: 'workspace.write', mutating: true },
   {
     method: 'POST',
     route: '/systems/:systemKey/datasources/:datasourceKey/protection/upload',

package/lib/programmatic/index.js

@@ -7,6 +7,7 @@
 const workspaceContext = require('./workspace-context');
 const runUpload = require('./run-upload');
 const runDeploy = require('./run-deploy');
+const runDownload = require('./run-download');
 const runProtection = require('./run-protection');
 const runWizard = require('./run-wizard');
 const runRepair = require('./run-repair');
@@ -32,6 +33,7 @@ module.exports = {
   ...workspaceContext,
   ...runUpload,
   ...runDeploy,
+  ...runDownload,
   ...runProtection,
   ...runWizard,
   ...runRepair,

package/lib/programmatic/openapi-apply-result-schemas.js

@@ -21,6 +21,14 @@ const OPENAPI_APPLY_RESULT_SCHEMAS = {
     },
     ['deployed']
   ),
+  DownloadResultData: frozenObject(
+    {
+      downloaded: { type: 'boolean' },
+      dryRun: { type: 'boolean' },
+      systemKey: schemaRef('SystemKey')
+    },
+    ['downloaded', 'dryRun', 'systemKey']
+  ),
   ProtectionUploadData: frozenObject(
     {
       datasourceKey: schemaRef('DatasourceKey'),

package/lib/programmatic/openapi-channel-install-schemas.js

@@ -90,6 +90,7 @@ const OPENAPI_CHANNEL_INSTALL_RESULT_SCHEMAS = {
     provisioning: schemaRef('ChannelProvisioning'),
     runtimeTarget: schemaRef('ChannelRuntimeTarget'),
     experimental: { type: 'boolean' },
+    status: { type: 'string', enum: ['visible', 'hide', 'coming-soon'] },
     maxInstances: { type: 'integer', minimum: 1 },
     profiles: { type: 'array', items: schemaRef('ChannelTargetProfile') }
   }),
@@ -108,7 +109,8 @@ const OPENAPI_CHANNEL_INSTALL_RESULT_SCHEMAS = {
       maxInstances: { type: 'integer', minimum: 1 },
       installationCount: { type: 'integer', minimum: 0 },
       canInstall: { type: 'boolean' },
-      blockedReason: { type: 'string' }
+      blockedReason: { type: 'string' },
+      status: { type: 'string', enum: ['visible', 'hide', 'coming-soon'] }
     },
     ['key', 'displayName', 'channel', 'installations']
   ),
@@ -140,6 +142,7 @@ const OPENAPI_CHANNEL_INSTALL_RESULT_SCHEMAS = {
       displayLabel: { type: 'string' },
       description: { type: 'string' },
       experimental: { type: 'boolean' },
+      status: { type: 'string', enum: ['visible', 'hide', 'coming-soon'] },
       provisioning: schemaRef('ChannelProvisioning'),
       runtimeTarget: schemaRef('ChannelRuntimeTarget'),
       installationSummary: schemaRef('ChannelInstallationSummary'),

package/lib/programmatic/openapi-component-schemas.js

@@ -40,6 +40,7 @@ const RESPONSE_ENVELOPES = [
   ['PreviewUploadResponse', 'PreviewUploadData'],
   ['UploadResultResponse', 'UploadResultData'],
   ['DeployResultResponse', 'DeployResultData'],
+  ['DownloadResultResponse', 'DownloadResultData'],
   ['ProtectionUploadResponse', 'ProtectionUploadData'],
   ['ProtectionCreateResponse', 'ProtectionCreateData'],
   ['TestResultResponse', 'TestResultData'],

package/lib/programmatic/openapi-descriptions.js

@@ -140,6 +140,12 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
       'Controller deploy for external systems (CLI aifabrix deploy parity). Optional body.gate matches CLI --gate (operations,trust,governance,full). Certificate seal is a platform side-effect of published Deploy — not a separate certificates issue call. Mutating; use Idempotency-Key.',
     tags: ['apply']
   },
+  runDownload: {
+    summary: 'Download system package into the workspace',
+    description:
+      'Fetch the published system from Dataplane into the workspace (CLI aifabrix download parity). Role Assistant packages also pull Evidence, Knowledge, and tests. Mutating; use Idempotency-Key.',
+    tags: ['workspace']
+  },
   runProtectionUpload: {
     summary: 'Upload protection manifest for a datasource',
     description:
@@ -269,13 +275,13 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
   listChannelTargets: {
     summary: 'List live channel definitions',
     description:
-      'List live Channel Definitions. Each row has key, displayLabel, description, experimental, provisioning, runtimeTarget, installationSummary, installationCount, and canInstall. Optional maxInstances and blockedReason when capped. Catalog is information-only; publishing uses POST install. Read-only.',
+      'List live Channel Definitions. Each row has key, displayLabel, description, experimental, status, provisioning, runtimeTarget, installationSummary, installationCount, and canInstall. Optional maxInstances and blockedReason when capped or coming-soon. hide definitions are omitted. Catalog is information-only; publishing uses POST install. Read-only.',
     tags: ['infra']
   },
   getChannelDefinitionDetail: {
     summary: 'Get a Channel Definition',
     description:
-      'Return a safe Channel Definition (identity, configuration, provisioning, runtimeTarget, profiles, optional maxInstances) plus installations projected from Dataplane Connected Systems. Includes canInstall. Unknown definition keys return 404. Known definitions with no instances return installations []. Read-only.',
+      'Return a safe Channel Definition (identity, configuration, provisioning, runtimeTarget, profiles, optional maxInstances, status) plus installations projected from Dataplane Connected Systems. Includes canInstall. Unknown or hide definition keys return 404. Known definitions with no instances return installations []. Read-only.',
     tags: ['infra']
   },
   getChannelInstallation: {
@@ -287,7 +293,7 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
   runChannelInstall: {
     summary: 'Install a channel',
     description:
-      'Scaffold, upload, and configure a channel from a Channel Definition. Path systemKey is the definition key. Body name is required; optional systemKey is the Connected System instance key; configuration is a generic propertyKey map. Returns help markdown plus phase, safe userActions, definitionKey, installationKey, and systemKey (the instance). Mutating.',
+      'Scaffold, upload, and configure a channel from a Channel Definition. Path systemKey is the definition key. Body name is required; optional systemKey is the Connected System instance key; configuration is a generic propertyKey map. hide and coming-soon definitions return 403; --force does not override. Returns help markdown plus phase, safe userActions, definitionKey, installationKey, and systemKey (the instance). Mutating.',
     tags: ['infra']
   },
   getChannelInstall: {

package/lib/programmatic/openapi-envelope-examples.js

@@ -141,6 +141,11 @@ const OPENAPI_ENVELOPE_DATA_EXAMPLES = {
     environment: 'dev',
     systemKey: SAMPLE_SYSTEM_KEY
   },
+  DownloadResultData: {
+    downloaded: true,
+    dryRun: false,
+    systemKey: SAMPLE_SYSTEM_KEY
+  },
   ProtectionUploadData: {
     datasourceKey: SAMPLE_DATASOURCE_KEY,
     uploaded: true,
@@ -282,6 +287,7 @@ const OPENAPI_ENVELOPE_DATA_EXAMPLES = {
         displayLabel: 'ChatGPT',
         description: 'ChatGPT channel',
         experimental: false,
+        status: 'visible',
         provisioning: { mode: 'guided' },
         runtimeTarget: { defaultSystemKey: 'runtime-orchestration', configurable: true },
         installationSummary: { count: 0, statusRollup: 'none' },
@@ -310,6 +316,7 @@ const OPENAPI_ENVELOPE_DATA_EXAMPLES = {
       provisioning: { mode: 'guided' },
       runtimeTarget: { defaultSystemKey: 'runtime-orchestration', configurable: true },
       experimental: false,
+      status: 'visible',
       profiles: []
     },
     installations: []

package/lib/programmatic/openapi-operation-bindings.js

@@ -233,6 +233,11 @@ const OPERATION_BINDINGS = Object.freeze({
     requestBody: jsonRequestBody('DeployRequest'),
     successResponse: 'DeployResultResponse'
   },
+  runDownload: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('DownloadRequest'),
+    successResponse: 'DownloadResultResponse'
+  },
   runProtectionUpload: {
     parameters: [SYSTEM_KEY_PARAM, DATASOURCE_KEY_PARAM],
     requestBody: jsonRequestBody('ProtectionUploadRequest'),

package/lib/programmatic/openapi-request-schemas.js

@@ -147,6 +147,11 @@ const OPENAPI_REQUEST_SCHEMAS = {
     sync: { type: 'boolean' },
     verbose: { type: 'boolean' }
   }),
+  DownloadRequest: frozenObject({
+    force: { type: 'boolean' },
+    dryRun: { type: 'boolean' },
+    format: { type: 'string', enum: ['json', 'yaml'] }
+  }),
   ProtectionUploadRequest: frozenObject({
     dryRun: { type: 'boolean' },
     sync: { type: 'boolean' },