@aifabrix/builder 2.50.0 → 2.51.1

package/lib/programmatic/openapi-schema-descriptions-evidence.js

@@ -0,0 +1,156 @@
+/**
+ * OpenAPI schema descriptions — Evidence authoring (162.0).
+ *
+ * @fileoverview Request/result models for BTA Evidence APIs
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** @type {Record<string, Object>} */
+const EVIDENCE_SCHEMA_DESCRIPTIONS = {
+  EvidenceUploadRow: {
+    _schema: 'One Evidence candidate row proposed for upload.',
+    key: 'Stable Evidence key when known.',
+    resourceType: 'Catalog resource type key this Evidence applies to.',
+    roleKey: 'Role Assistant key; must match the selected Role Assistant.',
+    kindKey: 'Evidence kind key from live metadata.',
+    kindVersion: 'Evidence kind version from live metadata.',
+    title: 'Short Evidence title.',
+    description: 'Optional longer description.',
+    when: 'Condition describing when this Evidence applies.',
+    expectedBehavior: 'Required expected behavior text.',
+    aspect: 'Optional Evidence aspect label.',
+    order: 'Optional display or priority order.',
+    status: 'Lifecycle status; upload persists as candidate.'
+  },
+  EvidenceUploadRequest: {
+    _schema: 'Upload one or many Evidence candidates for technical certification.',
+    roleKey: 'Selected Role Assistant key for authoring scope.',
+    rows: 'Evidence candidate rows to load, validate, and certify.',
+    comment: 'Optional certification comment applied to valid rows.'
+  },
+  EvidenceActivateRequest: {
+    _schema: 'Activate human-approved certified Evidence candidates.',
+    evidenceIds: 'Evidence ids or keys approved for activation.'
+  },
+  EvidenceKindSummary: {
+    _schema: 'Evidence kind available for authoring.',
+    key: 'Evidence kind key.',
+    version: 'Evidence kind version.',
+    displayName: 'Human-readable kind name.',
+    purpose: 'Kind purpose summary when present.'
+  },
+  EvidenceResourceTypeSummary: {
+    _schema: 'Resource type available for Evidence scoping.',
+    key: 'Resource type catalog key.',
+    displayName: 'Human-readable resource type name.',
+    category: 'Resource type category when present.'
+  },
+  EvidenceAuthoringConstraints: {
+    _schema: 'Certification and activation constraints for authoring.',
+    certification: 'Technical certification prerequisites.',
+    activation: 'Human-gate activation prerequisites.'
+  },
+  EvidenceAuthoringMetadataData: {
+    _schema: 'Authoritative Evidence authoring structure for a Role Assistant.',
+    roleKey: 'Selected Role Assistant key.',
+    evidenceKinds: 'Live Evidence kinds and versions.',
+    aspects: 'Distinct aspects already used by this Role Assistant.',
+    resourceTypes: 'Catalog resource types available for scoping.',
+    assistantCapabilities: 'Capability keys from the Role Assistant.',
+    writableFields: 'Fields the authoring API accepts on upload rows.',
+    requiredFields: 'Fields required on every upload row.',
+    constraints: 'Certification and activation constraints.'
+  },
+  EvidenceRowProjection: {
+    _schema: 'Evidence row projection returned by download/upload/activate.',
+    id: 'Dataplane Evidence id.',
+    key: 'Stable Evidence key when present.',
+    resourceType: 'Resource type key.',
+    roleKey: 'Role Assistant key.',
+    kindKey: 'Evidence kind key.',
+    kindVersion: 'Evidence kind version.',
+    title: 'Evidence title.',
+    description: 'Optional description.',
+    when: 'When condition text.',
+    expectedBehavior: 'Expected behavior text.',
+    aspect: 'Aspect label when present.',
+    order: 'Order value.',
+    status: 'Lifecycle status.',
+    fingerprint: 'Content fingerprint when present.'
+  },
+  EvidenceDownloadData: {
+    _schema: 'Existing Evidence for the selected Role Assistant.',
+    roleKey: 'Selected Role Assistant key.',
+    count: 'Number of Evidence rows returned.',
+    data: 'Evidence rows matching the download filters.'
+  },
+  EvidenceUploadItemOutcome: {
+    _schema: 'Per-row upload, validation, or certification outcome.',
+    rowIndex: 'Zero-based index in the upload rows array.',
+    evidenceId: 'Resolved Evidence id when available.',
+    evidenceRef: 'Evidence reference used for lifecycle calls.',
+    status: 'Outcome status label.',
+    message: 'Human-readable outcome message.',
+    issues: 'Validation or certification issues for the row.'
+  },
+  EvidenceUploadData: {
+    _schema: 'Upload result after load, validate, and certify (never activate).',
+    roleKey: 'Selected Role Assistant key.',
+    inserted: 'Rows inserted by bulk load.',
+    updated: 'Rows updated by bulk load.',
+    accepted: 'Rows accepted after technical certification.',
+    rejected: 'Rows rejected by validation or certification.',
+    warnings: 'Non-fatal row warnings.',
+    certified: 'Rows that completed technical certification.',
+    readyToActivate: 'True when at least one certified inactive row is ready.'
+  },
+  EvidenceActivateItemOutcome: {
+    _schema: 'Per-id activation outcome.',
+    evidenceId: 'Requested Evidence id or key.',
+    result: 'Activated Evidence projection when successful.',
+    error: 'Error message when activation failed.',
+    status: 'HTTP or API status code when activation failed.'
+  },
+  EvidenceActivateData: {
+    _schema: 'Activation result for one or many Evidence ids.',
+    requested: 'Number of unique Evidence ids requested.',
+    activated: 'Successfully activated Evidence outcomes.',
+    failed: 'Failed activation outcomes.',
+    success: 'True when every requested id activated.'
+  },
+  EvidenceAuthoringMetadataResponse: {
+    _schema: '200 response envelope for getEvidenceMetadata.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see EvidenceAuthoringMetadataData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  EvidenceDownloadResponse: {
+    _schema: '200 response envelope for downloadEvidence.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see EvidenceDownloadData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  EvidenceUploadResponse: {
+    _schema: '200 response envelope for uploadEvidenceCandidates.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see EvidenceUploadData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  EvidenceActivateResponse: {
+    _schema: '200 response envelope for activateEvidenceCandidates.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see EvidenceActivateData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  }
+};
+
+module.exports = {
+  EVIDENCE_SCHEMA_DESCRIPTIONS
+};

package/lib/programmatic/openapi-schema-descriptions-manifest.js

@@ -37,11 +37,12 @@ const MANIFEST_SCHEMA_DESCRIPTIONS = {
     assumptions: 'Assumptions recorded during quality scoring.'
   },
   ManifestPatchSectionRequest: {
-    _schema: 'Governed patch body; requires prior GET sectionReadToken.',
+    _schema: 'Governed patch body; intent required. sectionReadToken optional (auto re-read when omitted).',
     intent: 'Why this patch is made — audit and repair hints.',
     patch: 'Section-scoped merge or replace payload.',
     mode: 'Merge into existing section value or replace entirely.',
-    sectionReadToken: 'Token from prior GET; stale token returns 409.',
+    sectionReadToken:
+      'Optional token from prior GET. When omitted, server re-reads before write. Stale token returns 409.',
     dryRun: 'Validate patch without writing files.'
   },
   ManifestRepairRequest: {
@@ -68,7 +69,7 @@ const MANIFEST_SCHEMA_DESCRIPTIONS = {
     },
     repairHooks: 'Suggested repair hook names after patch.',
     recommendedNextActions: 'Agent-facing next steps (validate, repair, ask user).',
-    sectionReadToken: 'Opaque token required for PATCH; obtained from this GET.',
+    sectionReadToken: 'Opaque token for optimistic concurrency on PATCH; optional when PATCH auto-refreshes.',
     quality: 'Deterministic quality score and blocking issues.'
   },
   ManifestPatchResultData: {

package/lib/programmatic/openapi-schema-descriptions-operations.js

@@ -73,6 +73,36 @@ const OPERATIONS_SCHEMA_DESCRIPTIONS = {
     force: 'When true, upload even when validation reports non-blocking issues.',
     probe: 'When true, perform connectivity probe before upload.'
   },
+  DeployRequest: {
+    _schema: 'Optional flags for controller Deploy (CLI aifabrix deploy parity).',
+    gate: 'Optional pre-promote gates (comma-separated: operations, trust, governance, full).',
+    subjectEmail: 'Subject email for governance gate when gate includes governance or full.',
+    probe: 'When true, run dataplane probe checks after deploy.',
+    sync: 'When true, force full datasource data sync after deploy.',
+    verbose: 'When true, expand deploy summary output.'
+  },
+  ProtectionUploadRequest: {
+    _schema: 'Optional flags for protection upload (CLI protection upload parity).',
+    dryRun: 'When true, validate only; do not upload or sync.',
+    sync: 'When true, force full datasource data sync after upload.',
+    verbose: 'When true, emit verbose protection logs.'
+  },
+  ProtectionCreateRequest: {
+    _schema: 'Optional flags for protection create (CLI protection create parity).',
+    type: 'Preset type (for example country-sales).',
+    dimensionKey: 'Dimension catalog key when not inferred from type.',
+    field: 'Metadata field used by preset value templates.',
+    fkName: 'FK binding name in expressions.',
+    protectionKey: 'metadata.key override.',
+    displayName: 'metadata.displayName override.',
+    ruleKey: 'Rule key inside spec.rules[0].',
+    principalExpression: 'Group principal expression override.',
+    valueExpression: 'Grant valueExpression override.',
+    dryRun: 'When true, print scaffold without writing the file.',
+    force: 'When true, overwrite an existing local protection manifest.',
+    verbose: 'When true, emit verbose probe logs.',
+    disabled: 'When true, set spec.enabled to false.'
+  },
   TestRequest: {
     _schema: 'Optional test ladder options; runType may also be passed as query param.',
     runType: 'Test stage: unit, integration (default), or e2e.',
@@ -267,6 +297,46 @@ const OPERATIONS_SCHEMA_DESCRIPTIONS = {
     correlationId: 'UUID correlating logs for this request.',
     requestId: 'Optional per-request UUID when emitted by the server.'
   },
+  DeployResultData: {
+    _schema: 'Controller deploy outcome summary.',
+    deployed: 'True when controller deploy completed without gate failure.',
+    deploymentId: 'Controller deployment id when returned.',
+    environment: 'Target environment key.',
+    systemKey: 'Deployed integration system key.'
+  },
+  DeployResultResponse: {
+    _schema: '200 response envelope for runDeploySystem.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see DeployResultData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  ProtectionUploadData: {
+    _schema: 'Protection upload outcome.',
+    datasourceKey: 'Datasource key whose protection manifest was uploaded.',
+    uploaded: 'True when the manifest was published (false on dryRun).',
+    dryRun: 'True when validate-only dry run was requested.'
+  },
+  ProtectionUploadResponse: {
+    _schema: '200 response envelope for runProtectionUpload.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see ProtectionUploadData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  ProtectionCreateData: {
+    _schema: 'Protection create outcome.',
+    datasourceKey: 'Datasource key for the scaffolded protection manifest.',
+    created: 'True when the local manifest was written (false on dryRun).',
+    dryRun: 'True when scaffold was not written to disk.'
+  },
+  ProtectionCreateResponse: {
+    _schema: '200 response envelope for runProtectionCreate.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see ProtectionCreateData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
   TestResultResponse: {
     _schema: '200 response envelope for runTest.',
     success: 'Always true for successful builder-api JSON responses.',

package/lib/programmatic/openapi-schema-helpers.js

@@ -41,7 +41,15 @@ function stringArraySchema() {
  * @returns {Object}
  */
 function buildSuccessEnvelopeSchema(dataSchemaName) {
-  return frozenObject(
+  const dataExamples = {
+    HealthData: { status: 'ok' },
+    ReadyData: { status: 'ready', dataplaneUrl: 'http://localhost:3601' },
+    ListSystemsData: { systems: [] },
+    EmptyResultData: {},
+    WorkspaceStatusData: { status: 'ready' },
+    RepositoryStatusData: { status: 'ready' }
+  };
+  const schema = frozenObject(
     {
       success: { type: 'boolean', enum: [true] },
       data: schemaRef(dataSchemaName),
@@ -50,6 +58,13 @@ function buildSuccessEnvelopeSchema(dataSchemaName) {
     },
     ['success', 'data', 'correlationId']
   );
+  schema.example = {
+    success: true,
+    data: dataExamples[dataSchemaName] || {},
+    correlationId: '00000000-0000-4000-8000-000000000001',
+    requestId: '00000000-0000-4000-8000-000000000002'
+  };
+  return schema;
 }
 
 /**

package/lib/programmatic/openapi-spec.js

@@ -47,7 +47,7 @@ function problemResponseContent(description) {
     description,
     content: {
       'application/problem+json': {
-        schema: { $ref: '#/components/schemas/ProblemDetails' }
+        schema: { $ref: '#/components/schemas/ProblemDetail' }
       }
     }
   };
@@ -83,6 +83,7 @@ function requiresBearerAuth(handlerId) {
 function applyOperationDurationHints(capability, operation) {
   const durationByHandler = {
     runUpload: Number(process.env.MAX_UPLOAD_TIMEOUT_MS || 300000),
+    runDeploySystem: Number(process.env.MAX_DEPLOY_TIMEOUT_MS || 300000),
     runTest: Number(process.env.MAX_TEST_E2E_TIMEOUT_MS || 120000),
     runCertifyPillar: Number(process.env.MAX_CERTIFY_TIMEOUT_MS || 120000)
   };
@@ -133,6 +134,49 @@ function buildOperationObject(capability) {
   return operation;
 }
 
+/**
+ * @returns {Object[]}
+ */
+function buildOpenApiTags() {
+  return [
+    { name: 'workspace', description: 'Per-user integration workspaces (list, create, manifest, status, diff).' },
+    { name: 'build', description: 'Wizard generation and manifest repair.' },
+    { name: 'manifest', description: 'Governed section get/patch/repair for LLM and MCP workflows.' },
+    { name: 'validate', description: 'Local AJV validation and preview-upload (no Dataplane mutation).' },
+    { name: 'test', description: 'Unit, integration, and e2e test ladder.' },
+    { name: 'certify', description: 'Verify operations/trust/governance and lifecycle certification.' },
+    { name: 'apply', description: 'Dev Dataplane upload (requires external-system:publish).' },
+    { name: 'template', description: 'Enterprise MCP template.materializeWorkspace and workspace reset.' },
+    { name: 'repository', description: 'Enterprise MCP repository.sync, createReview, status, dispatchPipeline.' },
+    { name: 'infra', description: 'Liveness and readiness probes (no authentication).' },
+    {
+      name: 'evidence',
+      description:
+        'BTA-facing Evidence authoring: metadata, download, upload (validate+certify), and human-gated activate.'
+    }
+  ];
+}
+
+/**
+ * @returns {Object}
+ */
+function buildOpenApiInfo() {
+  return {
+    title: 'AI Fabrix Builder API',
+    version: '1.0.0',
+    description:
+      'Workspace orchestration for external-system dev publish. Repository and template operations delegate to Enterprise MCP (154.1). Successful JSON responses use `{ success, data, correlationId, requestId? }` with `application/json`. Errors use RFC 7807 Problem Details (`application/problem+json`) aligned with miso-controller and dataplane.',
+    'x-aifabrix': {
+      redocUrl: '/api/docs',
+      contractTier: 'public',
+      mcpGenerationReady: true,
+      rbacPreset: 'platform',
+      datasourceSplitMode: 'per-tag',
+      orchestrationDatasourceTags: listOrchestrationDatasourceTags()
+    }
+  };
+}
+
 /**
  * @param {Object} [options]
  * @param {string} [options.publicBaseUrl]
@@ -148,39 +192,14 @@ function buildOpenApiSpec(options = {}) {
     if (!paths[pathKey]) {
       paths[pathKey] = {};
     }
-    const method = capability.method.toLowerCase();
-    paths[pathKey][method] = buildOperationObject(capability);
+    paths[pathKey][capability.method.toLowerCase()] = buildOperationObject(capability);
   }
 
   return {
     openapi: '3.0.3',
-    info: {
-      title: 'AI Fabrix Builder API',
-      version: '1.0.0',
-      description:
-        'Workspace orchestration for external-system dev publish. Repository and template operations delegate to Enterprise MCP (154.1). Successful JSON responses use `{ success, data, correlationId, requestId? }` with `application/json`. Errors use RFC 7807 Problem Details (`application/problem+json`) aligned with miso-controller and dataplane.',
-      'x-aifabrix': {
-        redocUrl: '/api/docs',
-        contractTier: 'public',
-        mcpGenerationReady: true,
-        rbacPreset: 'platform',
-        datasourceSplitMode: 'per-tag',
-        orchestrationDatasourceTags: listOrchestrationDatasourceTags()
-      }
-    },
+    info: buildOpenApiInfo(),
     servers: [{ url: serverUrl, description: 'Builder API public base URL' }],
-    tags: [
-      { name: 'workspace', description: 'Per-user integration workspaces (list, create, manifest, status, diff).' },
-      { name: 'build', description: 'Wizard generation and manifest repair.' },
-      { name: 'manifest', description: 'Governed section get/patch/repair for LLM and MCP workflows.' },
-      { name: 'validate', description: 'Local AJV validation and preview-upload (no Dataplane mutation).' },
-      { name: 'test', description: 'Unit, integration, and e2e test ladder.' },
-      { name: 'certify', description: 'Verify operations/trust/governance and lifecycle certification.' },
-      { name: 'apply', description: 'Dev Dataplane upload (requires external-system:publish).' },
-      { name: 'template', description: 'Enterprise MCP template.materializeWorkspace and workspace reset.' },
-      { name: 'repository', description: 'Enterprise MCP repository.sync, createReview, status, dispatchPipeline.' },
-      { name: 'infra', description: 'Liveness and readiness probes (no authentication).' }
-    ],
+    tags: buildOpenApiTags(),
     components: {
       securitySchemes: {
         bearerAuth: {

package/lib/programmatic/orchestration-openapi-meta.js

@@ -66,6 +66,11 @@ const ORCHESTRATION_TAG_CATALOG = Object.freeze({
     resourceType: 'channel',
     permissionClass: 'infra',
     displayName: 'Infrastructure'
+  },
+  evidence: {
+    resourceType: 'role-evidence',
+    permissionClass: 'evidence',
+    displayName: 'Evidence'
   }
 });
 

package/lib/programmatic/request-timeout.js

@@ -16,6 +16,9 @@ function getTimeoutMsForHandler(handlerId) {
   if (handlerId === 'runUpload') {
     return Number(process.env.MAX_UPLOAD_TIMEOUT_MS || 300000);
   }
+  if (handlerId === 'runDeploySystem') {
+    return Number(process.env.MAX_DEPLOY_TIMEOUT_MS || 300000);
+  }
   if (handlerId === 'runTest') {
     return Number(process.env.MAX_TEST_E2E_TIMEOUT_MS || 120000);
   }

package/lib/programmatic/route-handler-map.js

@@ -14,6 +14,8 @@ const { runWizard } = require('./run-wizard');
 const { runRepair } = require('./run-repair');
 const { runValidate } = require('./run-validate');
 const { runPreviewUpload, runUpload } = require('./run-upload');
+const { runDeploySystem } = require('./run-deploy');
+const { runProtectionUpload, runProtectionCreate } = require('./run-protection');
 const { runTest } = require('./run-test');
 const { runCertifyPillar } = require('./run-certify');
 const { getLifecycleReport } = require('./run-lifecycle');
@@ -32,6 +34,12 @@ const {
 const { getManifestSection, listManifestSections } = require('./manifest-get-section');
 const { patchManifestSection } = require('./manifest-patch-section');
 const { runManifestRepair } = require('./manifest-repair');
+const {
+  getEvidenceMetadata,
+  downloadEvidence,
+  uploadEvidenceCandidates,
+  activateEvidenceCandidates
+} = require('./run-evidence-authoring');
 
 /** @type {Record<string, Function>} */
 const HANDLER_MAP = {
@@ -108,6 +116,36 @@ const HANDLER_MAP = {
       probe: body.probe === true,
       minimal: true
     }),
+  runDeploySystem: (params, auth, body) =>
+    runDeploySystem(buildContext(auth, params.systemKey), {
+      gate: body.gate,
+      subjectEmail: body.subjectEmail,
+      probe: body.probe === true,
+      sync: body.sync === true,
+      verbose: body.verbose === true
+    }),
+  runProtectionUpload: (params, auth, body) =>
+    runProtectionUpload(buildContext(auth, params.systemKey), params.datasourceKey, {
+      dryRun: body.dryRun === true,
+      sync: body.sync === true,
+      verbose: body.verbose === true
+    }),
+  runProtectionCreate: (params, auth, body) =>
+    runProtectionCreate(buildContext(auth, params.systemKey), params.datasourceKey, {
+      type: body.type,
+      dimensionKey: body.dimensionKey,
+      field: body.field,
+      fkName: body.fkName,
+      protectionKey: body.protectionKey,
+      displayName: body.displayName,
+      ruleKey: body.ruleKey,
+      principalExpression: body.principalExpression,
+      valueExpression: body.valueExpression,
+      dryRun: body.dryRun === true,
+      force: body.force === true,
+      verbose: body.verbose === true,
+      disabled: body.disabled === true
+    }),
   runTest: (params, auth, body, query) =>
     runTest(buildContext(auth, params.systemKey), {
       runType: body.runType || query.runType || 'integration',
@@ -117,7 +155,10 @@ const HANDLER_MAP = {
     runCertifyPillar(buildContext(auth, params.systemKey), params.pillar, {
       noPublish: body.noPublish === true,
       pack: body.pack,
-      body: body.lifecycleBody
+      body: body.lifecycleBody,
+      subjectEmails: _certifySubjectEmails(body),
+      subjectUserIds: _stringList(body.subjectUserIds),
+      certificationProfile: body.certificationProfile
     }),
   getLifecycleReport: (params, auth, _body, query) =>
     getLifecycleReport(buildContext(auth, params.systemKey), {
@@ -137,7 +178,53 @@ const HANDLER_MAP = {
   runRepositoryDispatchPipeline: (params, auth, body) =>
     runRepositoryDispatchPipeline(buildContext(auth, params.systemKey), body),
   health: () => ({ status: 'ok' }),
-  ready: () => ({ status: 'ready', dataplaneUrl: process.env.DATAPLANE_URL || null })
+  ready: () => ({ status: 'ready', dataplaneUrl: process.env.DATAPLANE_URL || null }),
+  getEvidenceMetadata: (params, auth) =>
+    getEvidenceMetadata(buildContext(auth, '_evidence'), params.roleKey),
+  downloadEvidence: (params, auth, _body, query) =>
+    downloadEvidence(buildContext(auth, '_evidence'), {
+      roleKey: params.roleKey,
+      resourceType: query.resourceType,
+      status: query.status,
+      kindKey: query.kindKey,
+      aspect: query.aspect,
+      search: query.search,
+      genericOnly: query.genericOnly === 'true',
+      limit: query.limit,
+      offset: query.offset
+    }),
+  uploadEvidenceCandidates: (params, auth, body) =>
+    uploadEvidenceCandidates(buildContext(auth, '_evidence'), {
+      ...(body && typeof body === 'object' ? body : {}),
+      roleKey: (body && body.roleKey) || params.roleKey
+    }),
+  activateEvidenceCandidates: (_params, auth, body) =>
+    activateEvidenceCandidates(buildContext(auth, '_evidence'), body)
 };
 
+/**
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+function _stringList(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map(item => String(item || '').trim()).filter(Boolean);
+}
+
+/**
+ * Normalize subject emails from CertifyRequest (singular or list).
+ * @param {Object} body
+ * @returns {string[]}
+ */
+function _certifySubjectEmails(body) {
+  const fromList = _stringList(body && body.subjectEmails);
+  const single = body && body.subjectEmail ? String(body.subjectEmail).trim() : '';
+  if (single && !fromList.includes(single)) {
+    return [single, ...fromList];
+  }
+  return fromList;
+}
+
 module.exports = { HANDLER_MAP };

package/lib/programmatic/run-certify.js

@@ -11,6 +11,7 @@
 const { runVerifyOperationsForExternalSystem } = require('../commands/verify-operations-external');
 const { runVerifyTrustForExternalSystem } = require('../commands/verify-trust-external');
 const { runVerifyGovernanceForExternalSystem } = require('../commands/verify-governance-external');
+const { runVerifyGovernanceCombined } = require('../commands/verify-governance-combined-external');
 const { runSystemLifecycle } = require('../api/lifecycle.api');
 const { runWithWorkspaceContext } = require('./workspace-context');
 const { mergeProgrammaticOptions } = require('./command-options');
@@ -45,7 +46,7 @@ async function runCertifyPillar(ctx, pillar, options = {}) {
     } else if (pillar === 'trust') {
       result = await runVerifyTrustForExternalSystem(ctx.systemKey, merged);
     } else if (pillar === 'governance') {
-      result = await runVerifyGovernanceForExternalSystem(ctx.systemKey, merged);
+      result = await runGovernanceCertify(ctx.systemKey, merged);
     } else {
       result = await runSystemLifecycle(merged.dataplaneUrl, merged.authConfig, ctx.systemKey, options.body || {});
     }
@@ -54,4 +55,16 @@ async function runCertifyPillar(ctx, pillar, options = {}) {
   });
 }
 
-module.exports = { runCertifyPillar, PILLARS };
+/**
+ * Governance certify: generate packs (subjects required) then verify, unless pack override.
+ * @param {string} systemKey
+ * @param {Object} options
+ */
+async function runGovernanceCertify(systemKey, options) {
+  if (options.pack) {
+    return runVerifyGovernanceForExternalSystem(systemKey, options);
+  }
+  return runVerifyGovernanceCombined(systemKey, options);
+}
+
+module.exports = { runCertifyPillar, runGovernanceCertify, PILLARS };

package/lib/programmatic/run-deploy.js

@@ -0,0 +1,74 @@
+/**
+ * Programmatic deploy wrapper — CLI deploy parity for builder-api.
+ *
+ * @fileoverview runDeploySystem for POST /systems/:systemKey/deploy
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { deployExternalSystem } = require('../external-system/deploy');
+const { runWithWorkspaceContext } = require('./workspace-context');
+const { mergeProgrammaticOptions } = require('./command-options');
+const { touchWorkspaceMeta } = require('./workspace-meta');
+
+/**
+ * @param {unknown} gate
+ * @returns {string|undefined}
+ */
+function normalizeGate(gate) {
+  if (gate === null || gate === undefined || gate === '') {
+    return undefined;
+  }
+  if (typeof gate === 'string') {
+    return gate.trim() || undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Map gateFailure / deploy errors to Problem Details status codes.
+ * @param {Error & { gateFailure?: boolean, statusCode?: number }} err
+ */
+function attachDeployStatus(err) {
+  if (err && err.gateFailure === true && !err.statusCode) {
+    err.statusCode = 422;
+  }
+  return err;
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [options]
+ * @param {string} [options.gate] - Same as CLI --gate (operations,trust,governance,full)
+ * @param {string} [options.subjectEmail]
+ * @param {boolean} [options.probe]
+ * @param {boolean} [options.sync]
+ * @param {boolean} [options.verbose]
+ * @returns {Promise<Object>}
+ */
+async function runDeploySystem(ctx, options = {}) {
+  const merged = mergeProgrammaticOptions(ctx, {
+    ...options,
+    gate: normalizeGate(options.gate),
+    subjectEmail: options.subjectEmail,
+    probe: options.probe === true,
+    sync: options.sync === true,
+    verbose: options.verbose === true
+  });
+  return runWithWorkspaceContext(ctx, async() => {
+    try {
+      const result = await deployExternalSystem(ctx.systemKey, merged);
+      touchWorkspaceMeta(ctx, { lastOperation: 'deploy' });
+      return result && typeof result === 'object' ? result : { deployed: true };
+    } catch (err) {
+      throw attachDeployStatus(err);
+    }
+  });
+}
+
+module.exports = {
+  runDeploySystem,
+  normalizeGate
+};