@aifabrix/builder 2.52.0 → 2.53.0

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

@@ -53,6 +53,29 @@ const OPENAPI_REQUEST_SCHEMAS = {
     sync: { type: 'boolean' }
   }),
   CreateSystemRequest: frozenObject({ systemKey: schemaRef('SystemKey') }, ['systemKey']),
+  PersistSuppliedOpenApiDocument: frozenObject(
+    {
+      filename: { type: 'string' },
+      name: { type: 'string' },
+      mediaType: { type: 'string' },
+      digest: { type: 'string' },
+      body: {
+        description: 'Authorized OpenAPI document object or JSON string (Runtime-resolved).',
+        oneOf: [{ type: 'object', additionalProperties: true }, { type: 'string' }]
+      }
+    },
+    ['body']
+  ),
+  PersistSuppliedOpenApiRequest: frozenObject(
+    {
+      documents: {
+        type: 'array',
+        minItems: 1,
+        items: schemaRef('PersistSuppliedOpenApiDocument')
+      }
+    },
+    ['documents']
+  ),
   WizardConfigRequest: frozenObject(
     {
       appName: { type: 'string' },
@@ -66,6 +89,23 @@ const OPENAPI_REQUEST_SCHEMAS = {
     },
     ['appName', 'source']
   ),
+  IntegrationDefinitionApplyRequest: frozenObject(
+    {
+      integrationDefinition: {
+        type: 'object',
+        additionalProperties: true,
+        description: 'Builder Integration Definition (aifabrix.builder.integrationDefinition).'
+      },
+      bid: {
+        type: 'object',
+        additionalProperties: true,
+        description: 'Alias for integrationDefinition.'
+      },
+      force: { type: 'boolean' },
+      dryRun: { type: 'boolean' }
+    },
+    ['integrationDefinition']
+  ),
   RepairRequest: frozenObject({
     dryRun: { type: 'boolean' },
     auth: { type: 'string' },

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

@@ -0,0 +1,101 @@
+'use strict';
+
+const { frozenObject, schemaRef } = require('./openapi-schema-helpers');
+
+const OPENAPI_RESULT_SCHEMA_OVERFLOW = {
+  LifecycleRunStep: frozenObject(
+    {
+      pillar: { type: 'string' },
+      success: { type: 'boolean' },
+      error: { type: 'string' }
+    },
+    ['pillar', 'success']
+  ),
+  LifecycleRunReport: frozenObject(
+    {
+      systemKey: schemaRef('SystemKey'),
+      certification: schemaRef('CertificationSummary')
+    },
+    ['systemKey']
+  ),
+  CertifyLifecycleRunResultData: frozenObject(
+    {
+      report: schemaRef('LifecycleRunReport'),
+      stepsRun: { type: 'array', items: schemaRef('LifecycleRunStep') }
+    },
+    ['report']
+  ),
+  CertifyResultData: {
+    oneOf: [
+      schemaRef('CertifyOperationsResultData'),
+      schemaRef('CertifyTrustResultData'),
+      schemaRef('CertifyGovernanceResultData'),
+      schemaRef('CertifyLifecycleRunResultData')
+    ]
+  },
+  LifecycleReportData: frozenObject(
+    {
+      systemKey: schemaRef('SystemKey'),
+      certification: schemaRef('CertificationSummary'),
+      operationalReadinessPercent: { type: 'number' },
+      summary: { type: 'boolean' },
+      details: { type: 'boolean' }
+    },
+    ['systemKey']
+  ),
+  EnterpriseMcpToolOutput: frozenObject({
+    success: { type: 'boolean' },
+    status: { type: 'string' },
+    message: { type: 'string' },
+    branch: { type: 'string' },
+    pullRequestUrl: { type: 'string', format: 'uri' },
+    syncDirection: schemaRef('RepositorySyncDirection'),
+    commitSha: { type: 'string' },
+    workflowRunId: { type: 'string' }
+  }),
+  WorkspaceRemoteUnavailable: frozenObject(
+    {
+      unavailable: { type: 'boolean', enum: [true] },
+      message: { type: 'string' }
+    },
+    ['unavailable', 'message']
+  ),
+  WorkspaceRemoteStatus: {
+    oneOf: [
+      schemaRef('EnterpriseMcpToolOutput'),
+      schemaRef('WorkspaceRemoteUnavailable'),
+      { type: 'null' }
+    ]
+  },
+  EnterpriseMcpInvocationData: frozenObject(
+    {
+      capabilityKey: { type: 'string' },
+      result: schemaRef('EnterpriseMcpToolOutput')
+    },
+    ['capabilityKey', 'result']
+  ),
+  WorkspaceStatusData: frozenObject(
+    {
+      local: schemaRef('SystemManifestData'),
+      remote: schemaRef('WorkspaceRemoteStatus')
+    },
+    ['local', 'remote']
+  ),
+  RepositoryStatusData: frozenObject(
+    {
+      capabilityKey: { type: 'string', enum: ['repository.status'] },
+      result: schemaRef('EnterpriseMcpToolOutput')
+    },
+    ['capabilityKey', 'result']
+  ),
+  HealthData: frozenObject({ status: { type: 'string', enum: ['ok'] } }, ['status']),
+  ReadyData: frozenObject(
+    {
+      status: { type: 'string', enum: ['ready'] },
+      dataplaneUrl: { type: ['string', 'null'], format: 'uri' }
+    },
+    ['status']
+  )
+};
+
+module.exports = { OPENAPI_RESULT_SCHEMA_OVERFLOW };

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

@@ -9,6 +9,7 @@
 'use strict';
 
 const { frozenObject, schemaRef, stringArraySchema } = require('./openapi-schema-helpers');
+const { OPENAPI_RESULT_SCHEMA_OVERFLOW } = require('./openapi-result-schemas-overflow');
 
 /** @type {Record<string, Object>} */
 const OPENAPI_RESULT_SCHEMAS = {
@@ -19,9 +20,9 @@ const OPENAPI_RESULT_SCHEMAS = {
         title: { type: 'string' },
         status: { type: 'integer', minimum: 100, maximum: 599 },
         detail: { type: 'string' },
-        instance: { type: 'string' },
+        instance: { type: 'string', format: 'uri' },
         correlationId: { type: 'string' },
-        errors: { type: 'array', items: schemaRef('ProblemValidationError') }
+        errors: { type: 'array', items: schemaRef('ValidationError') }
       },
       ['type', 'title', 'status', 'detail', 'correlationId', 'instance', 'errors']
     ),
@@ -31,9 +32,15 @@ const OPENAPI_RESULT_SCHEMAS = {
         title: 'Unauthorized',
         status: 401,
         detail: 'Missing or invalid Bearer token.',
-        instance: '/api/v1/builder/workspaces/me/systems',
+        instance: 'https://api.example.com/api/v1/builder/workspaces/me/systems',
         correlationId: '00000000-0000-4000-8000-000000000003',
-        errors: []
+        errors: [
+          {
+            field: 'authorization',
+            message: 'Missing or invalid Bearer token.',
+            value: null
+          }
+        ]
       }
     }
   ),
@@ -41,14 +48,27 @@ const OPENAPI_RESULT_SCHEMAS = {
   ProblemDetails: {
     allOf: [schemaRef('ProblemDetail')]
   },
-  ProblemValidationError: frozenObject(
+  ValidationError: Object.assign(
+    frozenObject(
+      {
+        field: { type: 'string' },
+        message: { type: 'string' },
+        value: { type: ['string', 'null'] }
+      },
+      ['field', 'message', 'value']
+    ),
     {
-      field: { type: 'string' },
-      message: { type: 'string' },
-      value: { type: 'string' }
-    },
-    ['message']
+      example: {
+        field: 'authorization',
+        message: 'Missing or invalid Bearer token.',
+        value: null
+      }
+    }
   ),
+  /** Legacy alias — published REST requires ValidationError (OAPI-249/608). */
+  ProblemValidationError: {
+    allOf: [schemaRef('ValidationError')]
+  },
   LifecycleVerdict: {
     type: 'string',
     enum: ['VERIFIED', 'FAILED', 'NOT_VERIFIED', 'NOT_APPLICABLE']
@@ -109,6 +129,36 @@ const OPENAPI_RESULT_SCHEMAS = {
     },
     ['systemKey', 'meta']
   ),
+  PersistSuppliedOpenApiAcceptedFile: frozenObject(
+    {
+      filename: { type: 'string' },
+      path: { type: 'string' },
+      digest: { type: 'string' }
+    },
+    ['filename', 'path', 'digest']
+  ),
+  PersistSuppliedOpenApiRejectedFile: frozenObject(
+    {
+      filename: { type: 'string' },
+      reason: { type: 'string' },
+      detail: { type: 'string' }
+    },
+    ['filename', 'reason']
+  ),
+  PersistSuppliedOpenApiData: frozenObject(
+    {
+      accepted: {
+        type: 'array',
+        items: schemaRef('PersistSuppliedOpenApiAcceptedFile')
+      },
+      rejected: {
+        type: 'array',
+        items: schemaRef('PersistSuppliedOpenApiRejectedFile')
+      },
+      workspaceRoot: { type: 'string' }
+    },
+    ['accepted', 'rejected', 'workspaceRoot']
+  ),
   SystemManifestData: frozenObject(
     {
       systemKey: schemaRef('SystemKey'),
@@ -131,6 +181,21 @@ const OPENAPI_RESULT_SCHEMAS = {
     },
     ['systemKey', 'status']
   ),
+  IntegrationDefinitionApplyData: frozenObject(
+    {
+      status: {
+        type: 'string',
+        enum: ['created', 'updated', 'idempotent', 'dryRun']
+      },
+      systemKey: schemaRef('SystemKey'),
+      outputDir: { type: 'string' },
+      definitionId: { type: 'string' },
+      definitionHash: { type: 'string' },
+      packageVersion: { type: 'string' },
+      files: stringArraySchema()
+    },
+    ['status', 'systemKey']
+  ),
   RepairResultData: frozenObject(
     {
       updated: { type: 'boolean' },
@@ -397,95 +462,7 @@ const OPENAPI_RESULT_SCHEMAS = {
     },
     ['command', 'systemKey', 'verdict', 'enforcementScenarios', 'datasourceRows']
   ),
-  LifecycleRunStep: frozenObject(
-    {
-      pillar: { type: 'string' },
-      success: { type: 'boolean' },
-      error: { type: 'string' }
-    },
-    ['pillar', 'success']
-  ),
-  LifecycleRunReport: frozenObject(
-    {
-      systemKey: schemaRef('SystemKey'),
-      certification: schemaRef('CertificationSummary')
-    },
-    ['systemKey']
-  ),
-  CertifyLifecycleRunResultData: frozenObject(
-    {
-      report: schemaRef('LifecycleRunReport'),
-      stepsRun: { type: 'array', items: schemaRef('LifecycleRunStep') }
-    },
-    ['report']
-  ),
-  CertifyResultData: {
-    oneOf: [
-      schemaRef('CertifyOperationsResultData'),
-      schemaRef('CertifyTrustResultData'),
-      schemaRef('CertifyGovernanceResultData'),
-      schemaRef('CertifyLifecycleRunResultData')
-    ]
-  },
-  LifecycleReportData: frozenObject(
-    {
-      systemKey: schemaRef('SystemKey'),
-      certification: schemaRef('CertificationSummary'),
-      operationalReadinessPercent: { type: 'number' },
-      summary: { type: 'boolean' },
-      details: { type: 'boolean' }
-    },
-    ['systemKey']
-  ),
-  EnterpriseMcpToolOutput: frozenObject({
-    success: { type: 'boolean' },
-    status: { type: 'string' },
-    message: { type: 'string' },
-    branch: { type: 'string' },
-    pullRequestUrl: { type: 'string', format: 'uri' },
-    syncDirection: schemaRef('RepositorySyncDirection'),
-    commitSha: { type: 'string' },
-    workflowRunId: { type: 'string' }
-  }),
-  WorkspaceRemoteUnavailable: frozenObject(
-    {
-      unavailable: { type: 'boolean', enum: [true] },
-      message: { type: 'string' }
-    },
-    ['unavailable', 'message']
-  ),
-  WorkspaceRemoteStatus: {
-    oneOf: [schemaRef('EnterpriseMcpToolOutput'), schemaRef('WorkspaceRemoteUnavailable'), { type: 'null' }]
-  },
-  EnterpriseMcpInvocationData: frozenObject(
-    {
-      capabilityKey: { type: 'string' },
-      result: schemaRef('EnterpriseMcpToolOutput')
-    },
-    ['capabilityKey', 'result']
-  ),
-  WorkspaceStatusData: frozenObject(
-    {
-      local: schemaRef('SystemManifestData'),
-      remote: schemaRef('WorkspaceRemoteStatus')
-    },
-    ['local', 'remote']
-  ),
-  RepositoryStatusData: frozenObject(
-    {
-      capabilityKey: { type: 'string', enum: ['repository.status'] },
-      result: schemaRef('EnterpriseMcpToolOutput')
-    },
-    ['capabilityKey', 'result']
-  ),
-  HealthData: frozenObject({ status: { type: 'string', enum: ['ok'] } }, ['status']),
-  ReadyData: frozenObject(
-    {
-      status: { type: 'string', enum: ['ready'] },
-      dataplaneUrl: { type: ['string', 'null'], format: 'uri' }
-    },
-    ['status']
-  )
+  ...OPENAPI_RESULT_SCHEMA_OVERFLOW
 };
 
 module.exports = {

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

@@ -28,18 +28,21 @@ const CORE_SCHEMA_DESCRIPTIONS = {
     title: 'Short human-readable error title.',
     status: 'HTTP status code echoed in the body.',
     detail: 'Actionable error detail safe for operators and agents.',
-    instance: 'Request path or instance identifier.',
+    instance: 'Request URL for this occurrence (URI).',
     correlationId: 'Correlation id for log lookup across services.',
-    errors: 'Field-level validation errors when status is 400.'
+    errors: 'Field-level validation errors (non-empty when status is 400/422).'
   },
   ProblemDetails: {
     _schema: 'Alias of ProblemDetail (allOf) for backward-compatible $refs.'
   },
-  ProblemValidationError: {
+  ValidationError: {
     _schema: 'Single field validation error inside ProblemDetail.errors.',
     field: 'JSON pointer or field name that failed validation.',
     message: 'Validation failure message.',
-    value: 'Rejected value when safe to echo (may be omitted for secrets).'
+    value: 'Rejected value when safe to echo (null when omitted for secrets).'
+  },
+  ProblemValidationError: {
+    _schema: 'Legacy alias of ValidationError (allOf) for older $refs.'
   },
   LifecycleVerdict: {
     _schema: 'Lifecycle verification outcome: VERIFIED, FAILED, NOT_VERIFIED, or NOT_APPLICABLE.'
@@ -75,6 +78,24 @@ const CORE_SCHEMA_DESCRIPTIONS = {
     _schema: 'Payload for listSystems: integration keys under the authenticated user.',
     systems: 'Workspace summaries ordered by systemKey.'
   },
+  PersistSuppliedOpenApiData: {
+    _schema: 'Findings for persistSuppliedOpenApi (accepted and rejected files).',
+    accepted: 'Successfully validated and written OpenAPI files.',
+    rejected: 'Documents that failed validation (no success claim).',
+    workspaceRoot: 'Absolute workspace integration root for this user.'
+  },
+  PersistSuppliedOpenApiAcceptedFile: {
+    _schema: 'One accepted OpenAPI file written under the workspace.',
+    filename: 'Basename written under openapi/.',
+    path: 'Workspace-relative path including integration/<systemKey>/openapi/.',
+    digest: 'sha256 digest of the serialized JSON body.'
+  },
+  PersistSuppliedOpenApiRejectedFile: {
+    _schema: 'One rejected OpenAPI document (not written).',
+    filename: 'Requested basename when available.',
+    reason: 'Stable rejection reason code (openapi.invalid, …).',
+    detail: 'Human-readable validation detail.'
+  },
   CreateSystemData: {
     _schema: 'Payload after createSystem: new workspace folder and metadata.',
     systemKey: 'Created integration system key.',

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

@@ -12,7 +12,7 @@
 const HELP_SCHEMA_DESCRIPTIONS = Object.freeze({
   BuilderHelpTopic: {
     _schema:
-      'Help topic enum: overview, sections, section, dependencyGraph, repairRules, workflow, schemaCatalog, subscriptionGuide, cipOverview, goldenExamples, goldenExample, evidencePatterns, evidencePattern.'
+      'Help topic enum including resourceTypeCatalog (taxonomy keys for BID datasources[].resourceType), overview, sections, schemaCatalog, platformRoles, dimensionsGuide, and related bootstrap topics.'
   },
   BuilderHelpData: {
     _schema: 'Deterministic LLM help payload for one topic (read-only product documentation).',

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

@@ -35,6 +35,25 @@ const OPERATIONS_SCHEMA_DESCRIPTIONS = {
     _schema: 'Request body to create an empty integration workspace folder.',
     systemKey: 'Unique integration system key for the new workspace.'
   },
+  PersistSuppliedOpenApiDocument: {
+    _schema: 'One Runtime-authorized OpenAPI document to persist.',
+    filename: 'Target basename under openapi/ (no path segments).',
+    name: 'Optional alias for filename.',
+    mediaType: 'Optional media type (application/json).',
+    digest: 'Optional sha256 digest of the serialized body for integrity check.',
+    body: 'OpenAPI document object or JSON string resolved by Runtime before CIP.'
+  },
+  PersistSuppliedOpenApiRequest: {
+    _schema: 'Request body for persistSuppliedOpenApi.',
+    documents: 'One or more authorized OpenAPI documents to validate and write.'
+  },
+  PersistSuppliedOpenApiResponse: {
+    _schema: '200 response envelope for persistSuppliedOpenApi.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see PersistSuppliedOpenApiData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
   WizardConfigRequest: {
     _schema: 'Headless wizard configuration to generate system and datasource JSON.',
     appName: 'Integration app folder name under the user workspace.',
@@ -46,6 +65,30 @@ const OPERATIONS_SCHEMA_DESCRIPTIONS = {
     preferences: 'Optional expose, RBAC, and sync generation flags.',
     debug: 'When true, enable verbose wizard logging (also available as query param).'
   },
+  IntegrationDefinitionApplyRequest: {
+    _schema: 'Apply a Builder Integration Definition (BID) into the workspace package.',
+    integrationDefinition: 'BID document (aifabrix.builder.integrationDefinition).',
+    bid: 'Alias for integrationDefinition.',
+    force: 'When true, rewrite package even if definitionHash matches stamp.',
+    dryRun: 'When true, return planned files without writing.'
+  },
+  IntegrationDefinitionApplyResponse: {
+    _schema: '200 response envelope for applyIntegrationDefinition.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see IntegrationDefinitionApplyData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  IntegrationDefinitionApplyData: {
+    _schema: 'Typed apply result payload.',
+    status: 'created, updated, unchanged, or dryRun.',
+    systemKey: 'Integration system key that was materialized.',
+    outputDir: 'Absolute workspace integration directory.',
+    definitionId: 'BID definitionId.',
+    definitionHash: 'Canonical definitionHash written to stamp.',
+    packageVersion: 'Package version from packageIdentity.',
+    files: 'Relative package file names written or planned.'
+  },
   RepairRequest: {
     _schema: 'Optional flags for workspace repair aligning manifest files with on-disk JSON.',
     dryRun: 'Preview repair actions without writing files.',

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

@@ -41,14 +41,14 @@ function stringArraySchema() {
  * @returns {Object}
  */
 function buildSuccessEnvelopeSchema(dataSchemaName) {
-  const dataExamples = {
-    HealthData: { status: 'ok' },
-    ReadyData: { status: 'ready', dataplaneUrl: 'http://localhost:3601' },
-    ListSystemsData: { systems: [] },
-    EmptyResultData: {},
-    WorkspaceStatusData: { status: 'ready' },
-    RepositoryStatusData: { status: 'ready' }
-  };
+  const { OPENAPI_ENVELOPE_DATA_EXAMPLES } = require('./openapi-envelope-examples');
+  const dataExample = OPENAPI_ENVELOPE_DATA_EXAMPLES[dataSchemaName];
+  if (dataExample === undefined) {
+    throw new Error(
+      `Missing OpenAPI envelope data example for ${dataSchemaName} (OAPI-136). ` +
+        'Add it to lib/programmatic/openapi-envelope-examples.js'
+    );
+  }
   const schema = frozenObject(
     {
       success: { type: 'boolean', enum: [true] },
@@ -60,7 +60,7 @@ function buildSuccessEnvelopeSchema(dataSchemaName) {
   );
   schema.example = {
     success: true,
-    data: dataExamples[dataSchemaName] || {},
+    data: dataExample,
     correlationId: '00000000-0000-4000-8000-000000000001',
     requestId: '00000000-0000-4000-8000-000000000002'
   };

package/lib/programmatic/openapi-spec.js

@@ -73,7 +73,7 @@ function buildStandardErrorResponses() {
  * @returns {boolean}
  */
 function requiresBearerAuth(handlerId) {
-  return handlerId !== 'health' && handlerId !== 'ready';
+  return handlerId !== 'health' && handlerId !== 'ready' && handlerId !== 'getBuilderHelp';
 }
 
 /**
@@ -149,10 +149,20 @@ function buildOpenApiTags() {
     { 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: 'help',
+      description:
+        'Deterministic LLM help topics (resourceTypeCatalog, schemaCatalog, …). No authentication.'
+    },
     {
       name: 'evidence',
       description:
         'BTA-facing Evidence authoring: metadata, download, upload (validate+certify), and human-gated activate.'
+    },
+    {
+      name: 'channel',
+      description:
+        'Discovery-driven channel packaging (Copilot, ChatGPT, Slack, Teams): build, summary, ZIP, branding.'
     }
   ];
 }

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

@@ -71,6 +71,16 @@ const ORCHESTRATION_TAG_CATALOG = Object.freeze({
     resourceType: 'role-evidence',
     permissionClass: 'evidence',
     displayName: 'Evidence'
+  },
+  channel: {
+    resourceType: 'channel',
+    permissionClass: 'channel',
+    displayName: 'Channel'
+  },
+  help: {
+    resourceType: 'document',
+    permissionClass: 'read',
+    displayName: 'Help'
   }
 });