@aifabrix/builder 2.51.0 → 2.52.0

package/lib/programmatic/openapi-spec.js

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

package/lib/programmatic/run-evidence-authoring.js

@@ -0,0 +1,80 @@
+/**
+ * Programmatic Evidence authoring wrappers (plan 162.0 BTA-facing APIs).
+ *
+ * @fileoverview HTTP handlers → lib/api/evidence-authoring.api.js
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const {
+  getEvidenceMetadata: getEvidenceMetadataApi,
+  downloadEvidence: downloadEvidenceApi,
+  uploadEvidenceCandidates: uploadEvidenceCandidatesApi,
+  activateEvidenceCandidates: activateEvidenceCandidatesApi
+} = require('../api/evidence-authoring.api');
+const { mergeProgrammaticOptions } = require('./command-options');
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [options]
+ * @returns {{ dataplaneUrl: string, authConfig: Object, apiOptions: Object }}
+ */
+function resolveEvidenceCallContext(ctx, options = {}) {
+  const merged = mergeProgrammaticOptions(ctx, options);
+  return {
+    dataplaneUrl: merged.dataplaneUrl,
+    authConfig: merged.authConfig,
+    apiOptions: {
+      controllerUrl: merged.controllerUrl || options.controllerUrl || null
+    }
+  };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {string} roleKey
+ * @param {Object} [options]
+ */
+async function getEvidenceMetadata(ctx, roleKey, options = {}) {
+  const call = resolveEvidenceCallContext(ctx, options);
+  return getEvidenceMetadataApi(call.dataplaneUrl, call.authConfig, roleKey, call.apiOptions);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} params
+ * @param {Object} [options]
+ */
+async function downloadEvidence(ctx, params = {}, options = {}) {
+  const call = resolveEvidenceCallContext(ctx, options);
+  return downloadEvidenceApi(call.dataplaneUrl, call.authConfig, params, call.apiOptions);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object|Object[]} payload
+ * @param {Object} [options]
+ */
+async function uploadEvidenceCandidates(ctx, payload = {}, options = {}) {
+  const call = resolveEvidenceCallContext(ctx, options);
+  return uploadEvidenceCandidatesApi(call.dataplaneUrl, call.authConfig, payload, call.apiOptions);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} payload
+ * @param {Object} [options]
+ */
+async function activateEvidenceCandidates(ctx, payload = {}, options = {}) {
+  const call = resolveEvidenceCallContext(ctx, options);
+  return activateEvidenceCandidatesApi(call.dataplaneUrl, call.authConfig, payload, call.apiOptions);
+}
+
+module.exports = {
+  getEvidenceMetadata,
+  downloadEvidence,
+  uploadEvidenceCandidates,
+  activateEvidenceCandidates
+};

package/lib/programmatic/run-protection.js

@@ -0,0 +1,124 @@
+/**
+ * Programmatic protection wrappers for builder-api.
+ *
+ * @fileoverview POST …/protection/upload and …/protection/create
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const {
+  runProtectionUpload: uploadProtectionCli
+} = require('../protection/run-commands');
+const { runProtectionCreate: createProtectionCli } = require('../protection/run-protection-create');
+const { resolveProtectionArgument } = require('../protection/resolve');
+const { runWithWorkspaceContext } = require('./workspace-context');
+const { mergeProgrammaticOptions } = require('./command-options');
+const { touchWorkspaceMeta } = require('./workspace-meta');
+
+/**
+ * Quiet logger for programmatic (non-TTY) protection calls.
+ * @returns {{ log: Function, error: Function, warn: Function }}
+ */
+function programmaticLogger() {
+  return {
+    log() {},
+    error() {},
+    warn() {}
+  };
+}
+
+/**
+ * @param {number} code
+ * @param {string} operation
+ */
+function assertExitOk(code, operation) {
+  if (code === 0 || code === null || code === undefined) {
+    return;
+  }
+  const err = new Error(`${operation} failed (exit ${code})`);
+  err.statusCode = 422;
+  throw err;
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {string} datasourceKey
+ * @param {Object} [options]
+ * @param {boolean} [options.dryRun]
+ * @param {boolean} [options.sync]
+ * @param {boolean} [options.verbose]
+ * @returns {Promise<{ datasourceKey: string, uploaded: boolean, dryRun: boolean }>}
+ */
+async function runProtectionUpload(ctx, datasourceKey, options = {}) {
+  const merged = mergeProgrammaticOptions(ctx, options);
+  const logger = programmaticLogger();
+  return runWithWorkspaceContext(ctx, async() => {
+    const resolved = resolveProtectionArgument(datasourceKey);
+    const code = await uploadProtectionCli(resolved.datasourceKey, resolved.manifest, {
+      ...merged,
+      manifestPath: resolved.manifestPath,
+      dryRun: options.dryRun === true,
+      sync: options.sync === true,
+      verbose: options.verbose === true
+    }, logger);
+    assertExitOk(code, 'Protection upload');
+    if (!options.dryRun) {
+      touchWorkspaceMeta(ctx, { lastOperation: 'protection:upload' });
+    }
+    return {
+      datasourceKey: resolved.datasourceKey,
+      uploaded: options.dryRun !== true,
+      dryRun: options.dryRun === true
+    };
+  });
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {string} datasourceKey
+ * @param {Object} [options]
+ * @returns {Promise<{ datasourceKey: string, created: boolean, dryRun: boolean }>}
+ */
+async function runProtectionCreate(ctx, datasourceKey, options = {}) {
+  const merged = mergeProgrammaticOptions(ctx, options);
+  const logger = programmaticLogger();
+  return runWithWorkspaceContext(ctx, async() => {
+    const code = await createProtectionCli(
+      datasourceKey,
+      {
+        ...merged,
+        type: options.type,
+        dimensionKey: options.dimensionKey,
+        field: options.field,
+        fkName: options.fkName,
+        protectionKey: options.protectionKey,
+        displayName: options.displayName,
+        ruleKey: options.ruleKey,
+        principalExpression: options.principalExpression,
+        valueExpression: options.valueExpression,
+        dryRun: options.dryRun === true,
+        force: options.force === true,
+        verbose: options.verbose === true,
+        disabled: options.disabled === true
+      },
+      logger
+    );
+    assertExitOk(code, 'Protection create');
+    if (!options.dryRun) {
+      touchWorkspaceMeta(ctx, { lastOperation: 'protection:create' });
+    }
+    return {
+      datasourceKey,
+      created: options.dryRun !== true,
+      dryRun: options.dryRun === true
+    };
+  });
+}
+
+module.exports = {
+  runProtectionUpload,
+  runProtectionCreate,
+  programmaticLogger
+};

package/lib/programmatic/run-template-workspace.js

@@ -12,6 +12,7 @@ const { runEnterpriseMcpCapability } = require('./run-enterprise-mcp');
 const { getSystemManifest } = require('./workspace-ops');
 const { invokeEnterpriseMcpCapability } = require('./enterprise-mcp-client');
 const { runWithWorkspaceContext } = require('./workspace-context');
+const { touchWorkspaceMeta } = require('./workspace-meta');
 
 /**
  * @param {import('./workspace-context').WorkspaceContext} ctx
@@ -51,11 +52,37 @@ async function getWorkspaceStatus(ctx) {
 }
 
 /**
+ * Diff local draft vs remote/template baseline.
+ * Local-first when Enterprise MCP workspace DS is not published
+ * (default ENTERPRISE_MCP_SYSTEM_KEY=enterprise-integration-lifecycle has no workspace DS).
+ *
  * @param {import('./workspace-context').WorkspaceContext} ctx
  * @param {Object} body
  */
 async function runWorkspaceDiff(ctx, body = {}) {
-  return runEnterpriseMcpCapability(ctx, 'workspace.diff', body);
+  return runWithWorkspaceContext(ctx, async() => {
+    const local = getSystemManifest(ctx);
+    try {
+      const result = await invokeEnterpriseMcpCapability(ctx, 'workspace.diff', body);
+      touchWorkspaceMeta(ctx, { lastOperation: 'workspace.diff' });
+      return {
+        capabilityKey: 'workspace.diff',
+        source: 'enterprise-mcp',
+        result,
+        local
+      };
+    } catch (err) {
+      touchWorkspaceMeta(ctx, { lastOperation: 'workspace.diff' });
+      return {
+        capabilityKey: 'workspace.diff',
+        source: 'local',
+        local,
+        remote: { unavailable: true, message: err.message },
+        note:
+          'Enterprise MCP workspace.diff unavailable; returning local draft snapshot only'
+      };
+    }
+  });
 }
 
 /**

package/lib/programmatic/workspace-context.js

@@ -123,6 +123,12 @@ function runWithWorkspaceContext(ctx, fn) {
         return alt;
       }
       return ctx.getIntegrationPath();
+    },
+    /** Workspace-scoped protection manifests: integration/.protection next to system folders. */
+    getProtectionRoot: () => {
+      const root = path.join(ctx.getIntegrationRoot(), '.protection');
+      assertPathContained(root, ctx.workspaceRoot);
+      return root;
     }
   };
   return runWithIntegrationPathScope(scope, fn);