@aifabrix/builder 2.51.0 → 2.51.1

package/lib/lifecycle/product-model.js

@@ -7,7 +7,7 @@
 
 'use strict';
 
-/** @typedef {'VERIFIED'|'FAILED'|'NOT_VERIFIED'} LifecycleVerdict */
+/** @typedef {'VERIFIED'|'FAILED'|'NOT_VERIFIED'|'NOT_APPLICABLE'} LifecycleVerdict */
 
 /** @typedef {'BRONZE'|'SILVER'|'GOLD'|'PLATINUM'|'NONE'} CertificationLevel */
 
@@ -16,7 +16,8 @@
 const VERDICT = Object.freeze({
   VERIFIED: 'VERIFIED',
   FAILED: 'FAILED',
-  NOT_VERIFIED: 'NOT_VERIFIED'
+  NOT_VERIFIED: 'NOT_VERIFIED',
+  NOT_APPLICABLE: 'NOT_APPLICABLE'
 });
 
 const CERTIFICATION_LEVEL = Object.freeze({

package/lib/lifecycle/report-display.js

@@ -58,9 +58,13 @@ function displayHeroMetric(label, percent) {
   logger.log('');
 }
 
-function displayVerdictLine(verdict, verifiedLabel, failedLabel) {
+function displayVerdictLine(verdict, verifiedLabel, failedLabel, notApplicableLabel) {
   if (verdict === VERDICT.VERIFIED) {
     logger.log(formatSuccessParagraph(verifiedLabel));
+  } else if (verdict === VERDICT.NOT_APPLICABLE) {
+    logger.log(
+      formatSuccessParagraph(notApplicableLabel || 'NOT APPLICABLE')
+    );
   } else {
     logger.log(formatBlockingError(failedLabel));
   }
@@ -196,7 +200,12 @@ function displayVerifyGovernanceTTY(systemKey, result, opts = {}) {
   logger.log(chalk.white('Enforcement Scenarios'));
   logger.log(chalk.cyan.bold(`${passed}/${total} Passed`));
   logger.log('');
-  displayVerdictLine(result.verdict, 'GOVERNANCE VERIFIED', 'GOVERNANCE FAILED');
+  displayVerdictLine(
+    result.verdict,
+    'GOVERNANCE VERIFIED',
+    'GOVERNANCE FAILED',
+    'GOVERNANCE NOT APPLICABLE'
+  );
   if (opts.details === true) {
     displayGovernanceVerboseDetails(result);
   }
@@ -209,6 +218,9 @@ function formatPillarLine(label, verdict) {
   if (verdict === VERDICT.FAILED) {
     return `${label.padEnd(24)}${failureGlyph()} FAILED`;
   }
+  if (verdict === VERDICT.NOT_APPLICABLE) {
+    return `${label.padEnd(24)}— NOT APPLICABLE`;
+  }
   return `${label.padEnd(24)}— NOT VERIFIED`;
 }
 

package/lib/programmatic/capability-registry.js

@@ -40,6 +40,21 @@ const CAPABILITIES = Object.freeze([
   { method: 'POST', route: '/systems/:systemKey/certify/:pillar', handlerId: 'runCertifyPillar', operationType: 'certify', mutating: true },
   { 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/datasources/:datasourceKey/protection/upload',
+    handlerId: 'runProtectionUpload',
+    operationType: 'apply.protection',
+    mutating: true
+  },
+  {
+    method: 'POST',
+    route: '/systems/:systemKey/datasources/:datasourceKey/protection/create',
+    handlerId: 'runProtectionCreate',
+    operationType: 'apply.protection',
+    mutating: true
+  },
   { method: 'POST', route: '/systems/:systemKey/template/materialize', handlerId: 'materializeTemplate', operationType: 'template', mutating: true },
   { method: 'GET', route: '/systems/:systemKey/workspace/status', handlerId: 'getWorkspaceStatus', operationType: 'workspace.read', mutating: false },
   { method: 'POST', route: '/systems/:systemKey/workspace/diff', handlerId: 'runWorkspaceDiff', operationType: 'workspace.read', mutating: false },
@@ -49,7 +64,11 @@ const CAPABILITIES = Object.freeze([
   { method: 'GET', route: '/systems/:systemKey/repository/status', handlerId: 'getRepositoryStatus', operationType: 'repository.read', mutating: false },
   { method: 'POST', route: '/systems/:systemKey/repository/dispatch-pipeline', handlerId: 'runRepositoryDispatchPipeline', operationType: 'repository', mutating: true },
   { method: 'GET', route: '/health', handlerId: 'health', operationType: 'infra', mutating: false },
-  { method: 'GET', route: '/health/ready', handlerId: 'ready', operationType: 'infra', mutating: false }
+  { method: 'GET', route: '/health/ready', handlerId: 'ready', operationType: 'infra', mutating: false },
+  { method: 'GET', route: '/evidence/:roleKey/metadata', handlerId: 'getEvidenceMetadata', operationType: 'evidence.read', mutating: false },
+  { method: 'GET', route: '/evidence/:roleKey/download', handlerId: 'downloadEvidence', operationType: 'evidence.read', mutating: false },
+  { method: 'POST', route: '/evidence/:roleKey/upload', handlerId: 'uploadEvidenceCandidates', operationType: 'evidence.write', mutating: true },
+  { method: 'POST', route: '/evidence/:roleKey/activate', handlerId: 'activateEvidenceCandidates', operationType: 'evidence.activate', mutating: true }
 ]);
 
 /**

package/lib/programmatic/command-options.js

@@ -22,6 +22,7 @@ function mergeProgrammaticOptions(ctx, options = {}) {
     authConfig: auth.authConfig,
     dataplaneUrl: auth.dataplaneUrl,
     environment: auth.environment,
+    controllerUrl: ctx.controllerUrl || options.controllerUrl,
     silentResolve: true,
     minimal: options.minimal !== false
   };

package/lib/programmatic/index.js

@@ -6,6 +6,8 @@
 
 const workspaceContext = require('./workspace-context');
 const runUpload = require('./run-upload');
+const runDeploy = require('./run-deploy');
+const runProtection = require('./run-protection');
 const runWizard = require('./run-wizard');
 const runRepair = require('./run-repair');
 const runValidate = require('./run-validate');
@@ -29,6 +31,8 @@ const enterpriseMcpClient = require('./enterprise-mcp-client');
 module.exports = {
   ...workspaceContext,
   ...runUpload,
+  ...runDeploy,
+  ...runProtection,
   ...runWizard,
   ...runRepair,
   ...runValidate,

package/lib/programmatic/manifest-patch-section.js

@@ -33,7 +33,7 @@ const { runWithWorkspaceContext } = require('./workspace-context');
 
 /**
  * @param {import('./workspace-context').WorkspaceContext} ctx
- * @param {{ sectionKey: string, datasourceKey?: string, intent: string, patch: Object, mode: string, sectionReadToken: string, dryRun?: boolean }} body
+ * @param {{ sectionKey: string, datasourceKey?: string, intent: string, patch: Object, mode: string, sectionReadToken?: string, dryRun?: boolean }} body
  */
 async function patchManifestSection(ctx, body) {
   return runWithWorkspaceContext(ctx, async() => {
@@ -43,10 +43,11 @@ async function patchManifestSection(ctx, body) {
 
     const loaded = loadTargetDocument(ctx, def.target, body.datasourceKey);
     const beforeValue = extractSectionValue(loaded.doc, def);
-    verifyReadToken(body, beforeValue);
+    assertSectionReadToken(body, beforeValue);
 
     const draft = JSON.parse(JSON.stringify(loaded.doc));
-    injectSectionValue(draft, def, body.patch, body.mode === 'replace' ? 'replace' : 'merge');
+    const patchValue = normalizeSectionPatch(def, body.patch);
+    injectSectionValue(draft, def, patchValue, body.mode === 'replace' ? 'replace' : 'merge');
     validateDraftDocument(def.target, draft);
 
     const afterValue = extractSectionValue(draft, def);
@@ -58,6 +59,47 @@ async function patchManifestSection(ctx, body) {
   });
 }
 
+/**
+ * Scalar single-path sections (resourceType, entityType, syncBridge, …) accept
+ * `{ value: <scalar> }` or `{ <leaf>: <scalar> }` because OpenAPI types `patch` as object.
+ *
+ * @param {import('./manifest-section-registry-data').SectionDefinition} def
+ * @param {Object} patch
+ * @returns {*}
+ */
+function normalizeSectionPatch(def, patch) {
+  if (!def || !Array.isArray(def.paths) || def.paths.length !== 1) {
+    return patch;
+  }
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+    return patch;
+  }
+  const keys = Object.keys(patch);
+  if (keys.length !== 1) {
+    return patch;
+  }
+  const leaf = def.paths[0].includes('.') ? def.paths[0].split('.').pop() : def.paths[0];
+  if (keys[0] === 'value' || keys[0] === leaf) {
+    return patch[keys[0]];
+  }
+  return patch;
+}
+
+/**
+ * When sectionReadToken is omitted, trust the freshly loaded section value
+ * (CLI patch-section parity — plan 496.2). Explicit tokens still verify.
+ *
+ * @param {Object} body
+ * @param {*} beforeValue
+ */
+function assertSectionReadToken(body, beforeValue) {
+  const token = typeof body.sectionReadToken === 'string' ? body.sectionReadToken.trim() : '';
+  if (!token) {
+    return;
+  }
+  verifyReadToken({ ...body, sectionReadToken: token }, beforeValue);
+}
+
 /**
  * @param {Object} body
  * @param {*} beforeValue
@@ -162,11 +204,6 @@ function assertPatchRequest(body) {
     err.statusCode = 400;
     throw err;
   }
-  if (!body.sectionReadToken) {
-    const err = new Error('sectionReadToken is required — GET the section first');
-    err.statusCode = 400;
-    throw err;
-  }
   if (body.mode !== 'merge' && body.mode !== 'replace') {
     const err = new Error('mode must be merge or replace');
     err.statusCode = 400;
@@ -248,5 +285,7 @@ function buildRiskHints(sectionKey, patch, downstream) {
 }
 
 module.exports = {
-  patchManifestSection
+  patchManifestSection,
+  normalizeSectionPatch,
+  assertSectionReadToken
 };

package/lib/programmatic/manifest-section-registry-data.js

@@ -226,11 +226,12 @@ const SECTION_DEFINITIONS = Object.freeze({
   },
   'datasource.dimensions': {
     target: 'datasource',
-    paths: ['fieldMappings.dimensions'],
+    // Canonical root is top-level `dimensions` (fieldMappings.dimensions removed).
+    paths: ['dimensions'],
     mutable: true,
     required: false,
     sourceOfTruth: true,
-    repairHooks: ['fieldMappings']
+    repairHooks: []
   },
   'datasource.abac': {
     target: 'datasource',

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

@@ -0,0 +1,44 @@
+/**
+ * OpenAPI result schemas for deploy and protection apply routes.
+ *
+ * @fileoverview Split from openapi-result-schemas for file-size limits
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { frozenObject, schemaRef } = require('./openapi-schema-helpers');
+
+/** @type {Record<string, Object>} */
+const OPENAPI_APPLY_RESULT_SCHEMAS = {
+  DeployResultData: frozenObject(
+    {
+      deployed: { type: 'boolean' },
+      deploymentId: { type: 'string' },
+      environment: { type: 'string' },
+      systemKey: schemaRef('SystemKey')
+    },
+    ['deployed']
+  ),
+  ProtectionUploadData: frozenObject(
+    {
+      datasourceKey: schemaRef('DatasourceKey'),
+      uploaded: { type: 'boolean' },
+      dryRun: { type: 'boolean' }
+    },
+    ['datasourceKey', 'uploaded', 'dryRun']
+  ),
+  ProtectionCreateData: frozenObject(
+    {
+      datasourceKey: schemaRef('DatasourceKey'),
+      created: { type: 'boolean' },
+      dryRun: { type: 'boolean' }
+    },
+    ['datasourceKey', 'created', 'dryRun']
+  )
+};
+
+module.exports = {
+  OPENAPI_APPLY_RESULT_SCHEMAS
+};

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

@@ -12,10 +12,15 @@ const { enrichOpenApiComponentSchemas } = require('./openapi-description-enriche
 const { buildSuccessEnvelopeSchema } = require('./openapi-schema-helpers');
 const { OPENAPI_REQUEST_SCHEMAS } = require('./openapi-request-schemas');
 const { OPENAPI_RESULT_SCHEMAS } = require('./openapi-result-schemas');
+const { OPENAPI_APPLY_RESULT_SCHEMAS } = require('./openapi-apply-result-schemas');
 const {
   OPENAPI_MANIFEST_REQUEST_SCHEMAS,
   OPENAPI_MANIFEST_RESULT_SCHEMAS
 } = require('./openapi-manifest-schemas');
+const {
+  OPENAPI_EVIDENCE_REQUEST_SCHEMAS,
+  OPENAPI_EVIDENCE_RESULT_SCHEMAS
+} = require('./openapi-evidence-schemas');
 
 const RESPONSE_ENVELOPES = [
   ['ListSystemsResponse', 'ListSystemsData'],
@@ -27,6 +32,9 @@ const RESPONSE_ENVELOPES = [
   ['ValidateResultResponse', 'ValidateResultData'],
   ['PreviewUploadResponse', 'PreviewUploadData'],
   ['UploadResultResponse', 'UploadResultData'],
+  ['DeployResultResponse', 'DeployResultData'],
+  ['ProtectionUploadResponse', 'ProtectionUploadData'],
+  ['ProtectionCreateResponse', 'ProtectionCreateData'],
   ['TestResultResponse', 'TestResultData'],
   ['CertifyResultResponse', 'CertifyResultData'],
   ['LifecycleReportResponse', 'LifecycleReportData'],
@@ -39,7 +47,11 @@ const RESPONSE_ENVELOPES = [
   ['ManifestSectionViewResponse', 'ManifestSectionViewData'],
   ['ManifestPatchResultResponse', 'ManifestPatchResultData'],
   ['ManifestSectionsListResponse', 'ManifestSectionsListData'],
-  ['ManifestRepairResultResponse', 'ManifestRepairResultData']
+  ['ManifestRepairResultResponse', 'ManifestRepairResultData'],
+  ['EvidenceAuthoringMetadataResponse', 'EvidenceAuthoringMetadataData'],
+  ['EvidenceDownloadResponse', 'EvidenceDownloadData'],
+  ['EvidenceUploadResponse', 'EvidenceUploadData'],
+  ['EvidenceActivateResponse', 'EvidenceActivateData']
 ];
 
 /**
@@ -53,8 +65,11 @@ function buildOpenApiComponentSchemas() {
   return enrichOpenApiComponentSchemas({
     ...OPENAPI_REQUEST_SCHEMAS,
     ...OPENAPI_MANIFEST_REQUEST_SCHEMAS,
+    ...OPENAPI_EVIDENCE_REQUEST_SCHEMAS,
     ...OPENAPI_RESULT_SCHEMAS,
+    ...OPENAPI_APPLY_RESULT_SCHEMAS,
     ...OPENAPI_MANIFEST_RESULT_SCHEMAS,
+    ...OPENAPI_EVIDENCE_RESULT_SCHEMAS,
     EmptyResultData: { type: 'object', properties: {}, additionalProperties: false },
     ...envelopes
   });

package/lib/programmatic/openapi-description-enricher.js

@@ -14,6 +14,7 @@ const { CERTIFY_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-c
 const { MANIFEST_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-manifest');
 const { MCP_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-mcp');
 const { HELP_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-help');
+const { EVIDENCE_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-evidence');
 
 /** @type {Record<string, Object>} */
 const MERGED_SCHEMA_DESCRIPTIONS = {
@@ -22,7 +23,8 @@ const MERGED_SCHEMA_DESCRIPTIONS = {
   ...CERTIFY_SCHEMA_DESCRIPTIONS,
   ...MANIFEST_SCHEMA_DESCRIPTIONS,
   ...MCP_SCHEMA_DESCRIPTIONS,
-  ...HELP_SCHEMA_DESCRIPTIONS
+  ...HELP_SCHEMA_DESCRIPTIONS,
+  ...EVIDENCE_SCHEMA_DESCRIPTIONS
 };
 
 /**

package/lib/programmatic/openapi-descriptions.js

@@ -53,25 +53,32 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
   getManifestSection: {
     summary: 'Read one system manifest section',
     description:
-      'Return section value, schema fragment, quality, dependency graph, and sectionReadToken. MUST call before patchSection.',
+      'Return section value, schema fragment, quality, dependency graph, and sectionReadToken. ' +
+      'Recommended before patch when quality or missingInputs are needed; token is optional on PATCH.',
     tags: ['manifest']
   },
   patchManifestSection: {
     summary: 'Patch one system manifest section',
     description:
-      'Apply governed merge/replace to a system section. Requires intent and sectionReadToken from GET. Mutating.',
+      'Apply governed merge/replace to a system section. Requires intent. ' +
+      'sectionReadToken from GET is optional — when omitted, the server re-reads the section before write. ' +
+      'Stale tokens return 409. Mutating.',
     tags: ['manifest']
   },
   getDatasourceManifestSection: {
     summary: 'Read one datasource manifest section',
     description:
-      'Return datasource section value, quality, missingInputs, and sectionReadToken. MUST call before patchSection.',
+      'Return datasource section value, quality, missingInputs, and sectionReadToken. ' +
+      'Recommended before patch when quality or missingInputs are needed; token is optional on PATCH.',
     tags: ['manifest']
   },
   patchDatasourceManifestSection: {
     summary: 'Patch one datasource manifest section',
     description:
-      'Apply governed merge/replace to a datasource section. Requires intent and sectionReadToken. Mutating.',
+      'Apply governed merge/replace to a datasource section. Requires intent. ' +
+      'sectionReadToken is optional (server re-reads when omitted; stale token → 409). ' +
+      'For scalar sections (e.g. datasource.resourceType), send patch as { "value": "<scalar>" } or ' +
+      '{ "<leafName>": "<scalar>" }. Mutating.',
     tags: ['manifest']
   },
   runManifestRepair: {
@@ -115,6 +122,24 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
       'Full dev publish: validate, sync deploy JSON, push credentials, pipeline upload. Requires external-system:publish in dev. Mutating; use Idempotency-Key; may take up to MAX_UPLOAD_TIMEOUT_MS.',
     tags: ['apply']
   },
+  runDeploySystem: {
+    summary: 'Deploy integration via controller (promote)',
+    description:
+      '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']
+  },
+  runProtectionUpload: {
+    summary: 'Upload protection manifest for a datasource',
+    description:
+      'Validate and upload the workspace protection manifest for the datasource (CLI aifabrix protection upload parity). Optional sync after upload. Mutating; use Idempotency-Key.',
+    tags: ['apply']
+  },
+  runProtectionCreate: {
+    summary: 'Scaffold a local protection manifest',
+    description:
+      'Probe dataplane + dimension catalog and write integration/.protection scaffold (CLI aifabrix protection create parity). Mutating; use Idempotency-Key.',
+    tags: ['apply']
+  },
   materializeTemplate: {
     summary: 'Materialize workspace from template',
     description:
@@ -128,7 +153,8 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
   },
   runWorkspaceDiff: {
     summary: 'Diff workspace draft',
-    description: 'Invoke Enterprise MCP workspace.diff for local draft vs remote/template baseline.',
+    description:
+      'Diff local workspace draft vs remote/template baseline via Enterprise MCP workspace.diff when published; otherwise returns a local draft snapshot (source=local) without failing.',
     tags: ['workspace']
   },
   resetWorkspaceFromTemplate: {
@@ -167,6 +193,30 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
     summary: 'Readiness probe',
     description: 'Returns ready with configured dataplaneUrl. Does not verify Dataplane connectivity in V1.',
     tags: ['infra']
+  },
+  getEvidenceMetadata: {
+    summary: 'Evidence authoring metadata',
+    description:
+      'Return live Evidence kinds, aspects, resource types, Role Assistant capabilities, writable fields, and certification/activation constraints for the selected roleKey. Read-only aggregation over Dataplane and Controller catalogs.',
+    tags: ['evidence']
+  },
+  downloadEvidence: {
+    summary: 'Download Role Assistant Evidence',
+    description:
+      'List or search Evidence for the selected roleKey using existing Dataplane Evidence filters. Read-only projection for AI authoring.',
+    tags: ['evidence']
+  },
+  uploadEvidenceCandidates: {
+    summary: 'Upload Evidence candidates',
+    description:
+      'Load one or many Evidence rows as inactive candidates, validate each row, and technically certify valid rows. Never activates. Mutating; use Idempotency-Key.',
+    tags: ['evidence']
+  },
+  activateEvidenceCandidates: {
+    summary: 'Activate certified Evidence',
+    description:
+      'Activate one or many human-approved certified Evidence ids. Organizational gate after technical certification. Mutating; use Idempotency-Key.',
+    tags: ['evidence']
   }
 });
 

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

@@ -0,0 +1,161 @@
+/**
+ * Frozen OpenAPI request/result schemas for Evidence authoring routes (162.0).
+ *
+ * @fileoverview BTA-facing Evidence metadata/download/upload/activate models
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { frozenObject, schemaRef, stringArraySchema } = require('./openapi-schema-helpers');
+
+/** @type {Record<string, Object>} */
+const OPENAPI_EVIDENCE_REQUEST_SCHEMAS = {
+  EvidenceUploadRow: frozenObject(
+    {
+      key: { type: 'string' },
+      resourceType: { type: 'string' },
+      roleKey: { type: 'string' },
+      kindKey: { type: 'string' },
+      kindVersion: { type: 'string' },
+      title: { type: 'string' },
+      description: { type: 'string' },
+      when: { type: 'string' },
+      expectedBehavior: { type: 'string' },
+      aspect: { type: 'string' },
+      order: { type: 'integer' },
+      status: { type: 'string', enum: ['candidate', 'active', 'disabled', 'archived'] }
+    },
+    ['title', 'when', 'expectedBehavior']
+  ),
+  EvidenceUploadRequest: frozenObject(
+    {
+      roleKey: {
+        type: 'string',
+        description: 'Optional override; defaults to the path roleKey.'
+      },
+      rows: { type: 'array', items: schemaRef('EvidenceUploadRow') },
+      comment: { type: 'string' }
+    },
+    ['rows']
+  ),
+  EvidenceActivateRequest: frozenObject(
+    {
+      evidenceIds: stringArraySchema()
+    },
+    ['evidenceIds']
+  )
+};
+
+/** @type {Record<string, Object>} */
+const OPENAPI_EVIDENCE_RESULT_SCHEMAS = {
+  EvidenceKindSummary: frozenObject({
+    key: { type: ['string', 'null'] },
+    version: { type: ['string', 'null'] },
+    displayName: { type: ['string', 'null'] },
+    purpose: { type: ['string', 'null'] }
+  }),
+  EvidenceResourceTypeSummary: frozenObject({
+    key: { type: ['string', 'null'] },
+    displayName: { type: ['string', 'null'] },
+    category: { type: ['string', 'null'] }
+  }),
+  EvidenceAuthoringConstraints: frozenObject({
+    certification: frozenObject({
+      validationStatus: { type: 'string' },
+      candidateStatus: { type: 'string' }
+    }),
+    activation: frozenObject({
+      requiresCertified: { type: 'boolean' },
+      requiresAuthority: { type: 'boolean' }
+    })
+  }),
+  EvidenceAuthoringMetadataData: frozenObject(
+    {
+      roleKey: { type: 'string' },
+      evidenceKinds: { type: 'array', items: schemaRef('EvidenceKindSummary') },
+      aspects: stringArraySchema(),
+      resourceTypes: { type: 'array', items: schemaRef('EvidenceResourceTypeSummary') },
+      assistantCapabilities: stringArraySchema(),
+      writableFields: stringArraySchema(),
+      requiredFields: stringArraySchema(),
+      constraints: schemaRef('EvidenceAuthoringConstraints')
+    },
+    [
+      'roleKey',
+      'evidenceKinds',
+      'aspects',
+      'resourceTypes',
+      'assistantCapabilities',
+      'writableFields',
+      'requiredFields',
+      'constraints'
+    ]
+  ),
+  EvidenceRowProjection: frozenObject({
+    id: { type: 'string' },
+    key: { type: ['string', 'null'] },
+    resourceType: { type: ['string', 'null'] },
+    roleKey: { type: ['string', 'null'] },
+    kindKey: { type: ['string', 'null'] },
+    kindVersion: { type: ['string', 'null'] },
+    title: { type: 'string' },
+    description: { type: ['string', 'null'] },
+    when: { type: 'string' },
+    expectedBehavior: { type: 'string' },
+    aspect: { type: ['string', 'null'] },
+    order: { type: 'integer' },
+    status: { type: 'string' },
+    fingerprint: { type: ['string', 'null'] }
+  }),
+  EvidenceDownloadData: frozenObject(
+    {
+      roleKey: { type: 'string' },
+      count: { type: 'integer', minimum: 0 },
+      data: { type: 'array', items: schemaRef('EvidenceRowProjection') }
+    },
+    ['roleKey', 'count', 'data']
+  ),
+  EvidenceUploadItemOutcome: frozenObject({
+    rowIndex: { type: 'integer' },
+    evidenceId: { type: ['string', 'null'] },
+    evidenceRef: { type: ['string', 'null'] },
+    status: { type: 'string' },
+    message: { type: 'string' },
+    issues: { type: 'array', items: { type: 'string' } }
+  }),
+  EvidenceUploadData: frozenObject(
+    {
+      roleKey: { type: 'string' },
+      inserted: { type: 'integer', minimum: 0 },
+      updated: { type: 'integer', minimum: 0 },
+      accepted: { type: 'array', items: schemaRef('EvidenceUploadItemOutcome') },
+      rejected: { type: 'array', items: schemaRef('EvidenceUploadItemOutcome') },
+      warnings: { type: 'array', items: schemaRef('EvidenceUploadItemOutcome') },
+      certified: { type: 'array', items: schemaRef('EvidenceUploadItemOutcome') },
+      readyToActivate: { type: 'boolean' }
+    },
+    ['roleKey', 'accepted', 'rejected', 'warnings', 'certified', 'readyToActivate']
+  ),
+  EvidenceActivateItemOutcome: frozenObject({
+    evidenceId: { type: 'string' },
+    result: schemaRef('EvidenceRowProjection'),
+    error: { type: 'string' },
+    status: { type: ['integer', 'null'] }
+  }),
+  EvidenceActivateData: frozenObject(
+    {
+      requested: { type: 'integer', minimum: 0 },
+      activated: { type: 'array', items: schemaRef('EvidenceActivateItemOutcome') },
+      failed: { type: 'array', items: schemaRef('EvidenceActivateItemOutcome') },
+      success: { type: 'boolean' }
+    },
+    ['requested', 'activated', 'failed', 'success']
+  )
+};
+
+module.exports = {
+  OPENAPI_EVIDENCE_REQUEST_SCHEMAS,
+  OPENAPI_EVIDENCE_RESULT_SCHEMAS
+};

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

@@ -54,10 +54,14 @@ const OPENAPI_MANIFEST_REQUEST_SCHEMAS = {
       intent: { type: 'string', minLength: 1, description: 'Why this patch is made — audit and repair hints.' },
       patch: { type: 'object', description: 'Section-scoped merge/replace payload.' },
       mode: { type: 'string', enum: ['merge', 'replace'], description: 'Merge into or replace section value.' },
-      sectionReadToken: { type: 'string', description: 'Token from prior GET; stale token returns 409.' },
+      sectionReadToken: {
+        type: 'string',
+        description:
+          'Optional token from prior GET. When omitted, the server re-reads the section immediately before write. Stale token returns 409.'
+      },
       dryRun: { type: 'boolean', description: 'Validate patch without writing files.' }
     },
-    ['intent', 'patch', 'mode', 'sectionReadToken']
+    ['intent', 'patch', 'mode']
   ),
   ManifestRepairRequest: frozenObject(
     {