@aifabrix/builder 2.53.0 → 2.54.1

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

@@ -8,6 +8,8 @@
 
 'use strict';
 
+const { CHATGPT_APPS_CREATE_URL } = require('../channels/chatgpt-runtime-contract');
+
 const SAMPLE_SYSTEM_KEY = 'hubspot-demo';
 const SAMPLE_DATASOURCE_KEY = 'hubspot-demo-companies';
 const SAMPLE_UUID = '00000000-0000-4000-8000-000000000010';
@@ -272,6 +274,121 @@ const OPENAPI_ENVELOPE_DATA_EXAMPLES = {
     activated: [],
     failed: [],
     success: true
+  },
+  ListChannelTargetsData: {
+    channels: [
+      {
+        key: 'chatgpt',
+        displayLabel: 'ChatGPT',
+        description: 'ChatGPT channel',
+        experimental: false,
+        provisioning: { mode: 'guided' },
+        runtimeTarget: { defaultSystemKey: 'runtime-orchestration', configurable: true },
+        installationSummary: { count: 0, statusRollup: 'none' },
+        installations: [],
+        configuration: [
+          {
+            name: 'CHANNEL_APP_DESCRIPTION',
+            propertyKey: 'appDescription',
+            location: 'variable',
+            required: false,
+            portalInput: { field: 'text', label: 'Description' }
+          }
+        ]
+      }
+    ]
+  },
+  ChannelDefinitionDetailData: {
+    key: 'slack',
+    displayName: 'Slack communication channel',
+    description: 'Slack channel',
+    type: 'custom',
+    systemKind: 'communication',
+    configuration: [],
+    channel: {
+      definitionKey: 'slack',
+      provisioning: { mode: 'guided' },
+      runtimeTarget: { defaultSystemKey: 'runtime-orchestration', configurable: true },
+      experimental: false,
+      profiles: []
+    },
+    installations: []
+  },
+  ChannelInstallationDetailData: {
+    definition: {
+      key: 'slack',
+      displayName: 'Slack',
+      provisioning: { mode: 'guided' }
+    },
+    installation: {
+      key: 'slack-finance',
+      displayName: 'Finance',
+      version: '1.0.0',
+      lifecycle: 'published',
+      availability: 'available',
+      authenticationStatus: 'online',
+      connectedSystemKey: 'slack-finance',
+      runtimeTarget: { systemKey: 'runtime-orchestration' }
+    }
+  },
+  ChannelInstallHelpData: {
+    helpMarkdown: '# Onni — ChatGPT\n\nStatus: Ready\n',
+    helpMarkdownContentType: 'text/markdown',
+    phase: 'waitingForUser',
+    userActions: [
+      {
+        id: 'open-vendor',
+        kind: 'openUrl',
+        label: 'Open ChatGPT apps',
+        required: true,
+        href: CHATGPT_APPS_CREATE_URL
+      }
+    ],
+    definitionKey: 'chatgpt',
+    installationKey: 'chatgpt-onni',
+    systemKey: 'chatgpt-onni'
+  },
+  AuthPermissionsData: {
+    permissions: ['integration-client:read', 'integration-client:create']
+  },
+  ListChannelArtifactsData: {
+    artifacts: [
+      {
+        id: 'appPackage',
+        kind: 'zip',
+        fileName: 'appPackage.dev.zip',
+        contentType: 'application/zip',
+        href: '/api/v1/builder/systems/microsoft-copilot/channels/artifacts/appPackage'
+      }
+    ]
+  },
+  ChannelArtifactBytesData: {
+    fileName: 'appPackage.dev.zip',
+    contentType: 'application/zip',
+    byteLength: 128
+  },
+  ChannelPackageData: {
+    channelTarget: 'microsoft-copilot',
+    installReady: false,
+    blocker: 'discoveryUnavailable',
+    artifactHash: 'sha256:demo',
+    links: { readme: 'dist/channels/microsoft-copilot/INSTALL.md', zip: null }
+  },
+  ChannelPackageSummaryData: {
+    channelTarget: 'microsoft-copilot',
+    installReady: false,
+    blocker: 'discoveryUnavailable',
+    links: { readme: 'dist/channels/microsoft-copilot/INSTALL.md', zip: null }
+  },
+  ChannelPackageZipData: {
+    fileName: 'appPackage.dev.zip',
+    contentType: 'application/zip',
+    byteLength: 128,
+    zipBase64: 'UEsDBBQAAAA='
+  },
+  ChannelBrandingData: {
+    systemKey: 'microsoft-copilot',
+    branding: { displayName: 'Acme Copilot', description: 'Preview' }
   }
 };
 

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

@@ -8,6 +8,8 @@
 
 'use strict';
 
+const { CHANNEL_INSTALL_BINDINGS } = require('./openapi-channel-install-bindings');
+
 const SYSTEM_KEY_PARAM = {
   name: 'systemKey',
   in: 'path',
@@ -400,7 +402,8 @@ const OPERATION_BINDINGS = Object.freeze({
     parameters: [ROLE_KEY_PARAM],
     requestBody: jsonRequestBody('EvidenceActivateRequest'),
     successResponse: 'EvidenceActivateResponse'
-  }
+  },
+  ...CHANNEL_INSTALL_BINDINGS
 });
 
 /**

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

@@ -0,0 +1,316 @@
+/**
+ * OpenAPI schema descriptions for generic channel install models.
+ *
+ * @fileoverview `_schema` = component description; property values = field descriptions
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** @type {Record<string, Object>} */
+const CHANNEL_INSTALL_SCHEMA_DESCRIPTIONS = {
+  ChannelInstallRequest: {
+    _schema: 'Generic channel install body. Optional profile is required only for generic targets.',
+    name: 'Customer-visible channel name (same as CLI --name).',
+    systemKey: 'Optional Connected System instance key. When omitted, derived from the definition key and name.',
+    configuration: 'Generic map of definition propertyKeys (for example commandPrefix). Unknown keys are rejected.',
+    runtimeSystemKey: 'Optional approved runtime or MCP Connected System when runtimeTarget.configurable is true.',
+    force: 'When true, refresh generated files. Does not rotate stored credentials.',
+    probe: 'When true, validate callbacks and assistant catalog after install.',
+    dryRun: 'When true, generate artifacts only; do not upload or store credentials.',
+    allowExperimental: 'When true, allow experimental channel targets.',
+    onboardUsers: 'When true, match Slack profile email to platform users after install.',
+    profile: 'Installation profile for generic targets (for example cursor). Omit for live vendor keys.',
+    token:
+      'Short-lived vendor session token from the help document. Used once for this request; not stored.'
+  },
+  ChannelInstallContinueRequest: {
+    _schema:
+      'Generic continue body. Optional token from the help document. Empty object remains valid and does not restart Microsoft device-code login. retryLogin restarts vendor login and issues a new handshake.',
+    token:
+      'Short-lived vendor session token from the help document. Used once for this request; not stored.',
+    retryLogin: 'When true, restart vendor login and issue a new handshake. Omit this to continue after Microsoft sign-in.'
+  },
+  ChannelProvisioning: {
+    _schema: 'How Builder provisions a Channel Definition.',
+    mode: 'automatic: API completes with no remaining vendor step. guided: API runs install; leftovers use help.md. cli: return generated CLI instructions; do not run the adapter.'
+  },
+  ChannelRuntimeTarget: {
+    _schema: 'Runtime or MCP Connected System for a channel. Not the channel instance key.',
+    defaultSystemKey: 'Default runtime Connected System key (runtime-orchestration for live definitions).',
+    configurable: 'When true, install may choose an approved runtime or MCP Connected System.',
+    systemKey: 'Resolved runtime Connected System key on an installation row.'
+  },
+  ChannelInstallationSummary: {
+    _schema: 'Rollup of Connected System instances for one Channel Definition.',
+    count: 'Number of matching Connected System instances. Zero when none exist.',
+    statusRollup: 'Single lifecycle/availability value, mixed, or none.'
+  },
+  ChannelInstallationRow: {
+    _schema: 'One Channel installation projected from a Dataplane Connected System.',
+    key: 'Connected System instance key.',
+    displayName: 'Instance display name from Dataplane.',
+    version: 'Instance version when Dataplane provides it.',
+    lifecycle: 'Publication lifecycle from Dataplane, or null.',
+    availability: 'Availability from Dataplane, or null.',
+    authenticationStatus: 'Authentication status from Dataplane, or null.',
+    connectedSystemKey: 'Same as key; explicit Connected System identity for consumers.',
+    runtimeTarget: 'Runtime Connected System used by this instance (systemKey).'
+  },
+  ChannelDefinitionChannel: {
+    _schema: 'Channel specialization on a safe definition payload.',
+    definitionKey: 'Stable catalog identity. Equals key on a definition; preserved on instances.',
+    provisioning: 'Provisioning mode for this definition.',
+    runtimeTarget: 'Default runtime or MCP Connected System.',
+    experimental: 'True when install requires allowExperimental.',
+    maxInstances: 'Optional cap on Connected System instances for this definition. Omit for unbounded.',
+    profiles: 'Optional generic install profiles (for example MCP client targets).'
+  },
+  ChannelTargetProfile: {
+    _schema: 'Optional install profile for a generic channel target.',
+    key: 'Profile key passed as profile on POST install.',
+    displayLabel: 'Human-readable profile name for catalog UI.'
+  },
+  ChannelTargetRow: {
+    _schema: 'One live channel target in the install catalog.',
+    key: 'Channel target key used as systemKey on install routes.',
+    displayLabel: 'Human-readable interface name.',
+    description: 'Short catalog blurb for the portal table. Not remaining-step copy.',
+    experimental: 'True when the target requires allowExperimental.',
+    provisioning: 'How Builder provisions this channel (automatic, guided, or cli).',
+    runtimeTarget: 'Runtime or MCP Connected System. Not the channel instance key.',
+    installationSummary: 'Count and status rollup of Connected System instances for this definition.',
+    installations: 'Connected System instances for this definition. Empty array when none exist. Never includes a CS whose key equals the catalog key.',
+    profiles: 'Optional profiles when the target is generic. Omitted for vendor keys.',
+    configuration: 'Safe Connected System configuration[] plus propertyKey. Secret-shaped values omitted. Portal add form uses these entries.',
+    cliInstructions: 'Generated CLI command when provisioning.mode is cli.',
+    iconHref: 'Data URL for the definition icon.svg from the Builder channel template. Omitted when the template has no icon.',
+    maxInstances: 'Optional instance cap from the Channel Definition. Omitted when unbounded.',
+    installationCount: 'Number of Connected System instances currently projected for this definition.',
+    canInstall: 'False when installationCount is already at maxInstances. Omitted meaning is canInstall true when unbounded.',
+    blockedReason: 'Present when canInstall is false. Explains why a new install is refused.'
+  },
+  ListChannelTargetsData: {
+    _schema: 'Catalog of live channel / interface targets.',
+    channels: 'Live targets the caller may install. Unimplemented keys are omitted.'
+  },
+  ListChannelTargetsResponse: {
+    _schema: '200 response envelope for listChannelTargets.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see ListChannelTargetsData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  ChannelDefinitionDetailData: {
+    _schema: 'Safe Channel Definition plus installation projection. Secrets stripped.',
+    key: 'Definition key (catalog identity).',
+    displayName: 'Human-readable definition name.',
+    description: 'Definition description.',
+    type: 'External System type.',
+    systemKind: 'Enterprise system classification.',
+    configuration: 'Safe configuration plus propertyKey. Secret-shaped values omitted.',
+    channel: 'Channel specialization (provisioning, runtimeTarget, profiles).',
+    cliInstructions: 'Generated CLI command when provisioning.mode is cli.',
+    iconHref: 'Data URL for the definition icon.svg from the Builder channel template.',
+    installations: 'Connected System instances for this definition. Empty array when none exist.',
+    maxInstances: 'Optional instance cap from the Channel Definition. Omitted when unbounded.',
+    installationCount: 'Number of Connected System instances currently projected for this definition.',
+    canInstall: 'False when installationCount is already at maxInstances.',
+    blockedReason: 'Present when canInstall is false.'
+  },
+  ChannelDefinitionDetailResponse: {
+    _schema: '200 response envelope for getChannelDefinitionDetail.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see ChannelDefinitionDetailData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  ChannelInstallationDetailData: {
+    _schema: 'One Channel installation projected from a Dataplane Connected System.',
+    definition: 'Catalog identity for this installation.',
+    installation: 'Projected instance fields from Dataplane. Builder does not persist lifecycle.'
+  },
+  ChannelInstallationDetailResponse: {
+    _schema: '200 response envelope for getChannelInstallation.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see ChannelInstallationDetailData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  ChannelUserAction: {
+    _schema: 'One generic wizard action. Secrets are stripped on the default HTTP JSON.',
+    id: 'Stable action id for resume and tests.',
+    kind: 'Generic action kind (openUrl, downloadArtifact, copyValue, submitInput, remainingVendorStep, retryLogin).',
+    label: 'Human label for the action.',
+    required: 'True when the server cannot finish without this action.',
+    resume: 'How to continue after the human acts (poll or submit).',
+    href: 'URL for openUrl or downloadArtifact.',
+    field: 'Continue-body field name for submitInput (for example token).',
+    artifactId: 'Artifact id for downloadArtifact.',
+    command: 'Optional command text. Secret-shaped values are omitted on HTTP.',
+    value: 'Copyable value. Secret-shaped values are omitted on HTTP.',
+    text: 'Remaining vendor step text.'
+  },
+  ChannelInstallVerdict: {
+    _schema: 'One install verdict (runtime, oauth, or vendor session).',
+    ok: 'True when this check passed.',
+    label: 'Short status label for help markdown.'
+  },
+  ChannelInstallVerdicts: {
+    _schema: 'Install readiness verdicts used to derive phase.',
+    runtime: 'Runtime Connected System availability.',
+    oauth: 'OAuth or Integration Client connection.',
+    vendorSession: 'Vendor session or workspace approval.'
+  },
+  ChannelInstallHelpData: {
+    _schema: 'Default HTTP install result: markdown help plus machine wizard fields.',
+    helpMarkdown: 'Markdown remaining-step document for the human. Generated on each GET/POST. No secrets.',
+    helpMarkdownContentType: 'Always text/markdown.',
+    refreshHintSeconds: 'Optional poll interval after the user follows a link in the document.',
+    phase: 'Wizard phase derived from verdicts and required userActions.',
+    userActions: 'Safe next actions for a generic wizard. Secrets stripped. No Slack-named fields.',
+    verdicts: 'Runtime, oauth, and vendor-session checks.',
+    definitionKey: 'Channel Definition catalog key (for example chatgpt).',
+    installationKey: 'Connected System instance key for this install (for example chatgpt-chatgpt2).',
+    systemKey: 'Same as installationKey. Path for GET install help for this instance.'
+  },
+  ChannelInstallHelpResponse: {
+    _schema: '200 response envelope for channel install help markdown.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see ChannelInstallHelpData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  ChannelArtifactRow: {
+    _schema: 'Downloadable install artifact linked from help markdown.',
+    id: 'Artifact id used in GET .../artifacts/{artifactId}.',
+    kind: 'Storage kind for machine clients (zip, json, markdown). Default HTTP does not require this.',
+    fileName: 'Suggested download file name.',
+    contentType: 'MIME type of the artifact bytes.',
+    href: 'Builder API path to download the artifact.'
+  },
+  ListChannelArtifactsData: {
+    _schema: 'Artifacts produced by the current install session.',
+    artifacts: 'Files linked from the help document (for example the Copilot ZIP).'
+  },
+  ListChannelArtifactsResponse: {
+    _schema: '200 response envelope for listChannelArtifacts.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see ListChannelArtifactsData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  ChannelArtifactBytesData: {
+    _schema: 'JSON metadata for an artifact when not streaming raw bytes.',
+    fileName: 'Download file name.',
+    contentType: 'MIME type of the bytes (application/zip for packages).',
+    byteLength: 'Size of the artifact in bytes.'
+  },
+  ChannelArtifactBytesResponse: {
+    _schema: '200 response envelope metadata for getChannelArtifact (bytes also sent as application/zip).',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see ChannelArtifactBytesData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  ChannelPackageRequest: {
+    _schema: 'Optional body for building a vendor channel package. Does not publish a channel.',
+    name: 'Package display name override.',
+    description: 'Package description override.',
+    baseName: 'Base name used when generating artifact files.',
+    environment: 'Target environment label written into the package summary.',
+    dataplaneUrl: 'Dataplane base URL used for discovery while building the package.',
+    dryRun: 'When true, generate artifacts only.',
+    branding: 'Optional branding overrides stored in the workspace.'
+  },
+  ChannelPackageLinks: {
+    _schema: 'README and ZIP paths produced by a package build.',
+    readme: 'Path to the generated install README.',
+    zip: 'Path to the generated app-package ZIP, or null when not produced.'
+  },
+  ChannelPackageData: {
+    _schema: 'Result of building a vendor channel package. installReady is package-import readiness, not channel-installed.',
+    channelTarget: 'Channel target key that was packaged.',
+    installReady: 'True when the generated vendor package is ready to import. Not the same as a published channel.',
+    blocker: 'Discovery or packaging blocker, or null when none.',
+    artifactHash: 'Hash of the generated package artifact.',
+    links: 'README and ZIP links for the built package.'
+  },
+  ChannelPackageResponse: {
+    _schema: '200 response envelope for buildChannelPackage.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see ChannelPackageData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  ChannelPackageSummaryData: {
+    _schema: 'Last built channel package summary. installReady is package-import readiness, not channel-installed.',
+    channelTarget: 'Channel target key that was packaged.',
+    installReady: 'True when the generated vendor package is ready to import. Not the same as a published channel.',
+    blocker: 'Discovery or packaging blocker, or null when none.',
+    links: 'README and ZIP links for the last build.'
+  },
+  ChannelPackageSummaryResponse: {
+    _schema: '200 response envelope for getChannelPackageSummary.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see ChannelPackageSummaryData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  ChannelPackageZipData: {
+    _schema: 'Built app package ZIP returned as JSON metadata plus zipBase64.',
+    fileName: 'Download file name.',
+    contentType: 'MIME type of the ZIP bytes.',
+    byteLength: 'Size of the ZIP in bytes.',
+    zipBase64: 'ZIP bytes encoded as Base64.'
+  },
+  ChannelPackageZipResponse: {
+    _schema: '200 response envelope for getChannelPackageZip.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see ChannelPackageZipData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  ChannelBrandingFields: {
+    _schema: 'Optional workspace branding used when generating a vendor package.',
+    displayName: 'Customer-visible package display name.',
+    description: 'Customer-visible package description.',
+    iconColorPath: 'Workspace path to the color icon file.',
+    iconOutlinePath: 'Workspace path to the outline icon file.'
+  },
+  ChannelBrandingPatchRequest: {
+    _schema: 'Partial branding update stored in the workspace. Does not publish a channel.',
+    displayName: 'Customer-visible package display name.',
+    description: 'Customer-visible package description.',
+    iconColorPath: 'Workspace path to the color icon file.',
+    iconOutlinePath: 'Workspace path to the outline icon file.'
+  },
+  ChannelBrandingData: {
+    _schema: 'Workspace branding for a channel packaging target.',
+    systemKey: 'Channel target key whose branding was read or patched.',
+    branding: 'Stored branding fields for package generation.'
+  },
+  ChannelBrandingResponse: {
+    _schema: '200 response envelope for channel branding read and patch.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see ChannelBrandingData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
+  AuthPermissionsData: {
+    _schema: 'Thin forward of Miso current-user permissions. Not a Builder permission catalog.',
+    permissions: 'Permission slugs from GET /api/v1/auth/permissions (for example integration-client:read).'
+  },
+  AuthPermissionsResponse: {
+    _schema: '200 response envelope for getAuthPermissions.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see AuthPermissionsData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  }
+};
+
+module.exports = {
+  CHANNEL_INSTALL_SCHEMA_DESCRIPTIONS
+};

package/lib/programmatic/openapi-spec.js

@@ -27,14 +27,18 @@ function toOpenApiPath(routePattern) {
  * @param {string} responseSchemaName
  * @returns {Object}
  */
-function successResponseContent(responseSchemaName) {
+function successResponseContent(responseSchemaName, extraContent) {
+  const content = {
+    'application/json': {
+      schema: { $ref: `#/components/schemas/${responseSchemaName}` }
+    }
+  };
+  if (extraContent && typeof extraContent === 'object') {
+    Object.assign(content, extraContent);
+  }
   return {
     description: 'Successful builder-api envelope (success, data, correlationId, requestId).',
-    content: {
-      'application/json': {
-        schema: { $ref: `#/components/schemas/${responseSchemaName}` }
-      }
-    }
+    content
   };
 }
 
@@ -106,7 +110,7 @@ function buildOperationObject(capability) {
     description: meta.description,
     tags: meta.tags,
     responses: {
-      200: successResponseContent(binding.successResponse),
+      200: successResponseContent(binding.successResponse, binding.extraSuccessContent),
       ...buildStandardErrorResponses()
     }
   };
@@ -162,7 +166,7 @@ function buildOpenApiTags() {
     {
       name: 'channel',
       description:
-        'Discovery-driven channel packaging (Copilot, ChatGPT, Slack, Teams): build, summary, ZIP, branding.'
+        'Channel install and packaging: catalog, help markdown, artifacts, Copilot/ChatGPT/Slack/Teams packages and branding.'
     }
   ];
 }

package/lib/programmatic/platform-rbac-catalog.js

@@ -1,60 +1,70 @@
 /**
- * Platform RBAC role catalog — mirrors dataplane builder/dataplane/rbac.yaml roles block.
+ * Platform RBAC role catalog — mirrors dataplane builder/dataplane/rbac.yaml
+ * role values and display names (without an "AI Fabrix" name prefix).
  *
- * @fileoverview SSOT for facade/orchestration integrations using platform roles (plan 154.7)
+ * @fileoverview SSOT for facade/orchestration integrations using platform roles
  * @author AI Fabrix Team
  * @version 1.0.0
  */
 
 'use strict';
 
+const ROLE_PLATFORM_ADMIN = 'aifabrix-platform-admin';
+const ROLE_SECURITY_ADMIN = 'aifabrix-security-admin';
+const ROLE_DEPLOYMENT_ADMIN = 'aifabrix-deployment-admin';
+const ROLE_COMPLIANCE_ADMIN = 'aifabrix-compliance-admin';
+const ROLE_DEVELOPER = 'aifabrix-developer';
+const ROLE_OBSERVER = 'aifabrix-observer';
+const ROLE_AI_TRUST_OPERATOR = 'aifabrix-ai-trust-operator';
+const ROLE_EXTERNAL_SYSTEM_DISCOVERER = 'aifabrix-external-system-discoverer';
+
 /** @type {ReadonlyArray<{ name: string, value: string, description: string, groups: string[] }>} */
 const PLATFORM_ROLES = Object.freeze([
   {
-    name: 'AI Fabrix Platform Admin',
-    value: 'aifabrix-platform-admin',
+    name: 'Platform Admin',
+    value: ROLE_PLATFORM_ADMIN,
     description: 'Full platform infrastructure management and enterprise controller access',
     groups: ['AI-Fabrix-Platform-Admins']
   },
   {
-    name: 'AI Fabrix Security Admin',
-    value: 'aifabrix-security-admin',
+    name: 'Security Admin',
+    value: ROLE_SECURITY_ADMIN,
     description: 'Security and compliance management for enterprise controller',
     groups: ['AI-Fabrix-Security-Admins']
   },
   {
-    name: 'AI Fabrix Deployment Admin',
-    value: 'aifabrix-deployment-admin',
+    name: 'Deployment Admin',
+    value: ROLE_DEPLOYMENT_ADMIN,
     description: 'Application deployment orchestration and environment management',
     groups: ['AI-Fabrix-Deployment-Admins']
   },
   {
-    name: 'AI Fabrix Compliance Admin',
-    value: 'aifabrix-compliance-admin',
+    name: 'Compliance Admin',
+    value: ROLE_COMPLIANCE_ADMIN,
     description: 'ISO 27001 compliance monitoring and audit management',
     groups: ['AI-Fabrix-Compliance-Admins']
   },
   {
-    name: 'AI Fabrix Developer',
-    value: 'aifabrix-developer',
+    name: 'Developer',
+    value: ROLE_DEVELOPER,
     description: 'Developer access to deploy applications via CI pipelines',
     groups: ['AI-Fabrix-Developers']
   },
   {
-    name: 'AI Fabrix Observer',
-    value: 'aifabrix-observer',
+    name: 'Observer',
+    value: ROLE_OBSERVER,
     description: 'Read-only access to monitoring, logs, and compliance reports',
     groups: ['AI-Fabrix-Observers']
   },
   {
-    name: 'AI Fabrix AI Trust Operator',
-    value: 'aifabrix-ai-trust-operator',
+    name: 'AI Trust Operator',
+    value: ROLE_AI_TRUST_OPERATOR,
     description: 'Run AI Trust access evaluation and explain visibility for governed users',
     groups: ['AI-Fabrix-AI-Trust-Operators']
   },
   {
-    name: 'AI Fabrix External System Discoverer',
-    value: 'aifabrix-external-system-discoverer',
+    name: 'External System Discoverer',
+    value: ROLE_EXTERNAL_SYSTEM_DISCOVERER,
     description: 'Discover business context for external systems via REST and MCP',
     groups: ['AI-Fabrix-External-System-Discoverers']
   }
@@ -83,6 +93,14 @@ function isPlatformRoleValue(value) {
 }
 
 module.exports = {
+  ROLE_PLATFORM_ADMIN,
+  ROLE_SECURITY_ADMIN,
+  ROLE_DEPLOYMENT_ADMIN,
+  ROLE_COMPLIANCE_ADMIN,
+  ROLE_DEVELOPER,
+  ROLE_OBSERVER,
+  ROLE_AI_TRUST_OPERATOR,
+  ROLE_EXTERNAL_SYSTEM_DISCOVERER,
   PLATFORM_ROLES,
   PLATFORM_ROLE_VALUES,
   listPlatformRoles,