@aifabrix/builder 2.52.0 → 2.52.1

package/lib/schema/integration-definition.schema.json

@@ -0,0 +1,195 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "aifabrix://schema/integration-definition.schema.json",
+  "title": "AI Fabrix Builder Integration Definition (BID)",
+  "description": "Canonical BT → Builder integration definition. Schema name aifabrix.builder.integrationDefinition v1.0.0.",
+  "metadata": {
+    "key": "integration-definition-schema",
+    "name": "Builder Integration Definition",
+    "version": "1.0.0",
+    "schemaName": "aifabrix.builder.integrationDefinition",
+    "type": "schema",
+    "category": "integration",
+    "author": "AI Fabrix Team",
+    "createdAt": "2026-08-04T00:00:00Z",
+    "updatedAt": "2026-08-04T00:00:00Z"
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaName",
+    "schemaVersion",
+    "definitionId",
+    "definitionHash",
+    "meta",
+    "packageIdentity",
+    "system",
+    "datasources",
+    "relationships",
+    "sync",
+    "capabilities",
+    "authority",
+    "acceptance"
+  ],
+  "properties": {
+    "schemaName": {
+      "type": "string",
+      "const": "aifabrix.builder.integrationDefinition"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "BID schema semver; implementers must accept 1.0.0."
+    },
+    "definitionId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "definitionHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 of canonicalized BID body excluding this field."
+    },
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["suiteRunId", "producedAt", "btAssistantKey"],
+      "properties": {
+        "suiteRunId": { "type": "string", "minLength": 1 },
+        "producedAt": { "type": "string", "format": "date-time" },
+        "btAssistantKey": { "type": "string", "minLength": 1 },
+        "answerFingerprint": { "type": "string" },
+        "knowledgePackRefs": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "humanAnswerRefs": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "replaceSystemKey": { "type": "boolean", "default": false }
+      }
+    },
+    "packageIdentity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["systemKey", "packageVersion", "displayName"],
+      "properties": {
+        "systemKey": { "type": "string", "pattern": "^[a-z0-9-]+$", "minLength": 3 },
+        "packageVersion": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+        "displayName": { "type": "string", "minLength": 1 }
+      }
+    },
+    "system": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["key", "systemKind", "connectionRefs"],
+      "properties": {
+        "key": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+        "displayName": { "type": "string" },
+        "description": { "type": "string" },
+        "systemKind": { "type": "string", "minLength": 1 },
+        "type": { "type": "string", "enum": ["openapi", "mcp", "custom"] },
+        "connectionRefs": {
+          "type": "object",
+          "description": "kv:// or credential key refs only — no plaintext secrets.",
+          "additionalProperties": { "type": "string", "minLength": 1 }
+        },
+        "openapiSourceRef": { "type": "string" }
+      }
+    },
+    "datasources": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["key", "displayName", "entityType", "resourceType"],
+        "properties": {
+          "key": { "type": "string", "pattern": "^[a-z0-9-]+$", "minLength": 3 },
+          "displayName": { "type": "string", "minLength": 1 },
+          "entityType": {
+            "type": "string",
+            "enum": [
+              "documentStorage",
+              "vectorStore",
+              "recordStorage",
+              "messageService",
+              "serviceContract",
+              "none"
+            ]
+          },
+          "resourceType": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+          "capabilityKeys": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^[a-z][a-zA-Z0-9]*$" }
+          },
+          "propertyKeys": {
+            "type": "array",
+            "description": "Vendor property names to sync/index (CRM objects → CIP query.properties + fieldMappings).",
+            "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$", "minLength": 1 }
+          },
+          "openapiSourceRef": { "type": "string" }
+        }
+      }
+    },
+    "relationships": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["from", "to", "kind"],
+        "properties": {
+          "from": { "type": "string", "minLength": 1 },
+          "to": { "type": "string", "minLength": 1 },
+          "kind": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "sync": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["mode"],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["incremental"],
+          "description": "Incremental sync is mandatory for CRM profile datasources."
+        },
+        "datasources": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z0-9-]+$" }
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": { "type": "string", "pattern": "^[a-z][a-zA-Z0-9]*$" }
+      },
+      "description": "Map of datasource key → capability keys (must include named write for company DS)."
+    },
+    "authority": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["writeRequiresUserAuthority"],
+      "properties": {
+        "writeRequiresUserAuthority": { "type": "boolean" },
+        "notes": { "type": "string" }
+      }
+    },
+    "acceptance": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["gates"],
+      "properties": {
+        "gates": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/lib/utils/authentication-shape.js

@@ -110,6 +110,9 @@ function buildAuthenticationFromMethod(systemKey, authType) {
   if (method === 'none') {
     return { authType: 'none' };
   }
+  if (method === 'system') {
+    return { authType: 'system' };
+  }
   const flat = buildFlatCredentialTemplate(systemKey, method);
   return {
     authType: 'credential',
@@ -174,6 +177,9 @@ function migrateAuthenticationToNestedSchema(authentication, systemKey) {
   if (authentication.authType === 'none') {
     return { authentication: { authType: 'none' }, changed: false };
   }
+  if (authentication.authType === 'system') {
+    return { authentication: { authType: 'system' }, changed: false };
+  }
   if (authentication.authType === 'apiProvider' && authentication.apiProvider) {
     return { authentication, changed: false };
   }

package/lib/utils/docker-build.js

@@ -253,12 +253,12 @@ async function executeBuild(imageName, dockerfilePath, contextPath, tag, options
   );
   await executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs, noCache);
 
-  // Tag image if additional tag provided
-  if (options && options.tag && options.tag !== 'latest') {
+  // Also apply floating `main` when building a version tag (matches dev-promote dual tags).
+  if (options && options.tag && options.tag !== 'latest' && options.tag !== 'main') {
     const { execFileWithDockerEnv } = require('./docker-exec');
     const { getDockerExecEnv } = require('./remote-docker-env');
     const env = await getDockerExecEnv();
-    await execFileWithDockerEnv('docker', ['tag', `${imageName}:${tag}`, `${imageName}:latest`], { env });
+    await execFileWithDockerEnv('docker', ['tag', `${imageName}:${tag}`, `${imageName}:main`], { env });
   }
 }
 

package/lib/utils/help-builder.js

@@ -111,6 +111,7 @@ const CATEGORIES = [
       { name: 'delete', term: 'delete <systemKey>' },
       { name: 'repair', term: 'repair <systemKey>' },
       { name: 'manifest', term: 'manifest get-section <systemKey> <sectionKey>' },
+      { name: 'integration-definition', term: 'integration-definition apply <file>' },
       { name: 'channel', term: 'channel scaffold <channelTarget>' },
       { name: 'datasource' },
       { name: 'datasource load', term: 'datasource load <datasourceKey>' },

package/lib/utils/promote-dev-docker-image.js

@@ -1,9 +1,10 @@
 /**
  * Promote a developer-scoped local Docker image to the manifest base repository (tag only).
  *
- * @fileoverview Used by `aifabrix build --base --from-dev` and dev-promote workflows
+ * @fileoverview Used by `aifabrix build --base --from-dev` and dev-promote workflows.
+ * Promote always applies two base tags: `main` (floating) and the version tag (TAG / package version).
  * @author AI Fabrix Team
- * @version 1.0.0
+ * @version 1.1.0
  */
 
 'use strict';
@@ -15,6 +16,9 @@ const { execWithDockerEnv } = require('./docker-exec');
 const logger = require('./logger');
 const { formatSuccessLine } = require('./cli-test-layout-chalk');
 
+/** Floating base tag applied on every promote alongside the version tag. */
+const PROMOTE_MAIN_TAG = 'main';
+
 /**
  * @param {string} value
  * @returns {string}
@@ -61,6 +65,33 @@ async function dockerTagImageRef(sourceRef, targetRef) {
   await execWithDockerEnv(`docker tag ${shellQuote(sourceRef)} ${shellQuote(targetRef)}`);
 }
 
+/**
+ * Version tag for promote (not floating aliases).
+ * @param {Object} options
+ * @returns {string}
+ */
+function resolvePromoteVersionTag(options = {}) {
+  const raw = String(options.tag || '').trim();
+  if (!raw || raw === 'latest' || raw === PROMOTE_MAIN_TAG) {
+    return 'latest';
+  }
+  return raw;
+}
+
+/**
+ * Base tags to apply on promote: version first, then `main` when distinct.
+ * @param {Object} options
+ * @returns {string[]}
+ */
+function resolvePromoteBaseTags(options = {}) {
+  const versionTag = resolvePromoteVersionTag(options);
+  const tags = [versionTag];
+  if (versionTag !== PROMOTE_MAIN_TAG) {
+    tags.push(PROMOTE_MAIN_TAG);
+  }
+  return tags;
+}
+
 /**
  * @param {string} appName
  * @param {Object} variables
@@ -69,7 +100,7 @@ async function dockerTagImageRef(sourceRef, targetRef) {
  * @returns {Promise<{ devRef: string, baseRef: string, devTag: string, baseTag: string }>}
  */
 async function resolveDevAndBaseImageRefs(appName, variables, developerId, options) {
-  const baseTag = options.tag || 'latest';
+  const baseTag = resolvePromoteVersionTag(options);
   const devTag = options.fromDevTag || 'latest';
   const { buildImageName: baseName } = await resolveBuildDockerTagNames(appName, variables, developerId, {
     ...options,
@@ -93,31 +124,68 @@ async function resolveDevAndBaseImageRefs(appName, variables, developerId, optio
  * @param {Object} appConfig
  * @param {string|number} developerId
  * @param {Object} options
- * @returns {Promise<{ devRef: string, baseRef: string }|null>}
+ * @returns {Promise<{
+ *   devRef: string,
+ *   baseRef: string,
+ *   baseName: string,
+ *   baseTags: string[]
+ * }|null>}
  */
 async function resolvePromoteSourceAndTargetRefs(appName, appConfig, developerId, options) {
-  const baseTag = options.tag || 'latest';
+  const baseTags = resolvePromoteBaseTags(options);
+  const versionTag = baseTags[0];
   const devTagCandidates = ['latest'];
-  if (baseTag !== 'latest' && !devTagCandidates.includes(baseTag)) {
-    devTagCandidates.push(baseTag);
+  if (versionTag !== 'latest' && !devTagCandidates.includes(versionTag)) {
+    devTagCandidates.push(versionTag);
   }
   for (const fromDevTag of devTagCandidates) {
     const refs = await resolveDevAndBaseImageRefs(appName, appConfig, developerId, {
       ...options,
+      tag: versionTag,
       fromDevTag
     });
     if (await dockerImageRefExists(refs.devRef)) {
-      return { devRef: refs.devRef, baseRef: refs.baseRef };
+      const baseName = refs.baseRef.slice(0, refs.baseRef.lastIndexOf(':'));
+      return {
+        devRef: refs.devRef,
+        baseRef: refs.baseRef,
+        baseName,
+        baseTags
+      };
     }
   }
   return null;
 }
 
+/**
+ * @param {string} baseName
+ * @param {string[]} baseTags
+ * @param {string|null} devId
+ * @returns {Promise<boolean>} true when every target already matches dev image id
+ */
+async function allBaseTagsMatchDev(baseName, baseTags, devId) {
+  if (!devId) {
+    return false;
+  }
+  for (const tag of baseTags) {
+    const ref = `${baseName}:${tag}`;
+    if (!(await dockerImageRefExists(ref))) {
+      return false;
+    }
+    const baseId = await readDockerImageId(ref);
+    if (!baseId || baseId !== devId) {
+      return false;
+    }
+  }
+  return true;
+}
+
 /**
  * Tag developer-scoped image as manifest base when present locally.
+ * Always applies the version tag and `main`.
  * @param {string} appName
  * @param {Object} options - build options (`base`, `tag`, `registry`, `fromDev`)
- * @returns {Promise<string|null>} base image ref when promoted/skipped; null when dev image missing
+ * @returns {Promise<string|null>} primary base image ref (version) when promoted; null when missing
  */
 async function tryPromoteDevImageToBase(appName, options = {}) {
   if (options.base !== true) {
@@ -135,19 +203,27 @@ async function tryPromoteDevImageToBase(appName, options = {}) {
   if (!resolved) {
     return null;
   }
-  const { devRef, baseRef } = resolved;
+  const { devRef, baseRef, baseName, baseTags } = resolved;
 
   const devId = await readDockerImageId(devRef);
-  if (await dockerImageRefExists(baseRef)) {
-    const baseId = await readDockerImageId(baseRef);
-    if (devId && baseId && devId === baseId) {
-      logger.log(formatSuccessLine(`Base image already matches dev build: ${baseRef}`));
-      return baseRef;
-    }
+  if (await allBaseTagsMatchDev(baseName, baseTags, devId)) {
+    logger.log(
+      formatSuccessLine(
+        `Base image already matches dev build: ${baseTags.map((t) => `${baseName}:${t}`).join(', ')}`
+      )
+    );
+    return baseRef;
   }
 
-  await dockerTagImageRef(devRef, baseRef);
-  logger.log(formatSuccessLine(`Promoted dev image to base (tag only): ${baseRef}`));
+  for (const tag of baseTags) {
+    const targetRef = `${baseName}:${tag}`;
+    await dockerTagImageRef(devRef, targetRef);
+  }
+  logger.log(
+    formatSuccessLine(
+      `Promoted dev image to base (tag only): ${baseTags.map((t) => `${baseName}:${t}`).join(', ')}`
+    )
+  );
   return baseRef;
 }
 
@@ -160,10 +236,13 @@ function shouldAttemptDevPromote(options) {
 }
 
 module.exports = {
+  PROMOTE_MAIN_TAG,
   tryPromoteDevImageToBase,
   shouldAttemptDevPromote,
   resolveDevAndBaseImageRefs,
   resolvePromoteSourceAndTargetRefs,
+  resolvePromoteBaseTags,
+  resolvePromoteVersionTag,
   dockerImageRefExists,
   readDockerImageId,
   dockerTagImageRef

package/lib/utils/transient-developer-id.js

@@ -0,0 +1,28 @@
+/**
+ * Transient developer-id override for CLI commands (does not persist config).
+ *
+ * @fileoverview Resolve optional --developer-id / --developer without setDeveloperId
+ */
+
+'use strict';
+
+const { validateAndNormalizeDeveloperId } = require('../core/config-normalize');
+
+/**
+ * Resolve optional CLI developer override (transient — does not persist).
+ * Prefers developerId (--developer-id) over developer (-d/--developer).
+ *
+ * @param {Object} [options] - Commander options
+ * @returns {string|undefined} Normalized digit string, or undefined to use config
+ */
+function resolveTransientDeveloperIdFromOptions(options) {
+  const raw = options && (options.developerId ?? options.developer);
+  if (raw === undefined || raw === null || raw === '') {
+    return undefined;
+  }
+  return validateAndNormalizeDeveloperId(raw);
+}
+
+module.exports = {
+  resolveTransientDeveloperIdFromOptions
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.52.0",
+  "version": "2.52.1",
   "description": "AI Fabrix Builder — CLI and developer scripts (pnpm + af)",
   "main": "lib/index.js",
   "bin": {

package/scripts/pnpm/af.mjs

@@ -4,9 +4,13 @@
  * Usage: pnpm run af <subcommand>  |  npm run af -- <subcommand>
  */
 import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { resolveAifabrixBin } from './lib/resolve-aifabrix-bin.mjs';
 
 const AIFABRIX_BIN = resolveAifabrixBin();
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '../..');
 
 const USAGE = `Usage: pnpm run af <subcommand>
 
@@ -19,7 +23,7 @@ Subcommands:
   ba-build        aifabrix build builder-api
   dev-build       ba-build then ba-run (local Docker image)
   dev-reload      Docker live reload (spinner + URL + .temp/dev-reload.log)
-  dev-promote     build --base --from-dev + run --base (global image; TAG=1.9.5 pnpm run dev-promote)
+  dev-promote     build --base --from-dev + run --base (tags main + version; TAG=2.52.0 or package.json)
 `;
 
 const COMMANDS = {
@@ -36,10 +40,20 @@ async function runDevBuild() {
   await runCommand(COMMANDS['ba-run']);
 }
 
+function readPackageVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(REPO_ROOT, 'package.json'), 'utf8'));
+    const version = String(pkg.version || '').trim();
+    return version || null;
+  } catch {
+    return null;
+  }
+}
+
 function resolvePromoteTag() {
   const fromArg = process.argv[3];
-  const tag = (process.env.TAG || fromArg || '').trim();
-  if (!tag || tag === 'latest') {
+  const tag = (process.env.TAG || fromArg || readPackageVersion() || '').trim();
+  if (!tag || tag === 'latest' || tag === 'main') {
     return null;
   }
   return tag;
@@ -47,13 +61,14 @@ function resolvePromoteTag() {
 
 async function runDevPromote() {
   const tag = resolvePromoteTag();
-  if (tag) {
-    await runCommand([AIFABRIX_BIN, 'build', 'builder-api', '--base', '--from-dev', '--tag', tag]);
-    await runCommand([AIFABRIX_BIN, 'run', 'builder-api', '--base', '--tag', tag]);
-    return;
+  if (!tag) {
+    throw new Error(
+      'dev-promote requires a version tag. Set TAG=x.y.z or ensure package.json has "version".'
+    );
   }
-  await runCommand([AIFABRIX_BIN, 'build', 'builder-api', '--base', '--from-dev']);
-  await runCommand([AIFABRIX_BIN, 'run', 'builder-api', '--base']);
+  // Promote applies both :main and :<version>; run uses the version tag.
+  await runCommand([AIFABRIX_BIN, 'build', 'builder-api', '--base', '--from-dev', '--tag', tag]);
+  await runCommand([AIFABRIX_BIN, 'run', 'builder-api', '--base', '--tag', tag]);
 }
 
 function runCommand(args) {

package/scripts/pnpm/help.mjs

@@ -25,7 +25,7 @@ const publicSections = [
 
 const advancedLines = [
   '--- Advanced (help -- --all) ---',
-  'dev-build / dev-promote / af ba-*',
+  'dev-build / dev-promote (tags main + version) / af ba-*',
   'build:ci           → lint + schema-sync + flags + test:ci (same as GitHub)',
   'sync-json          → publish builder/builder-api → templates/',
   'test:154           → builder-api scoped Jest + arch grep',

package/templates/applications/dataplane/application.yaml

@@ -5,7 +5,7 @@ app:
   description: "AI Fabrix Dataplane is a secure, in-tenant integration and automation layer that supplies governed, normalized, and explainable enterprise data to AI agents. Using CIP as a declarative standard, it enforces RBAC and ABAC, executes integrations, and exposes trusted data via MCP and OpenAPI."
   type: webapp
   language: python # Explicitly specify Python language
-  version: 2.0.20
+  version: 2.0.26
 # Image Configuration
 # Set tag to match your build (example: aifabrix build dataplane -t 1.0.0).
 # Registry is required so the controller can pull the image (avoids docker-not-found on the controller host).
@@ -88,7 +88,8 @@ build:
 # - MISO_*, KEYCLOAK_* → auto-generated during Azure install
 # - AI params / provider secrets → LLM external systems + secret store
 #   (never product OPENAI_* / AZURE_OPENAI_*). ≥2 providers →
-#   ENTERPRISE_LLM_DEFAULT_SELECTOR (portal LLM category).
+#   ENTERPRISE_LLM_DEFAULT_SELECTOR (portal/env deploy default); Environment
+#   Settings ai.llmProvider overrides without redeploy.
 # - ENVIRONMENT → set by deployment target
 
 configuration:

package/templates/applications/dataplane/env.template

@@ -44,7 +44,7 @@ API_KEY_BYPASS_ROLES=full-access
 
 # API Configuration
 API_V1_STR=/api/v1
-VERSION=2.0.20
+VERSION=2.0.26
 # Minimum supported aifabrix-builder CLI semver (advertised on /health and /api/v1/health; empty = no gate)
 # MIN_BUILDER_CLI_VERSION=2.45.0
 MIN_BUILDER_CLI_VERSION=2.45.5
@@ -155,11 +155,10 @@ MISO_PIPELINE_ENV_KEY=
 
 # LLM: chat/embed route through governed enterprise-llm only. Provider credentials
 # live on LLM provider external systems + dataplane secret store (not product .env).
-# When ≥2 LLM providers are published under enterprise-llm, set selectorKey
-# (system key), e.g. openai | azure-openai | ollama. Ignored when only one.
-# Prefer portal Configuration category LLM after deploy; this env is the resolve target.
-# Default LLM provider systemKey when ≥2 LLM providers are published under
-# enterprise-llm (fail-closed if empty). Portal category LLM can override.
+# Deploy-time default provider (systemKey) when Environment Settings ai.llmProvider
+# is empty. Operators can override in Environment Settings without redeploying.
+# When ≥2 LLM providers are published and both settings and this env are empty,
+# resolve fails closed. Ignored when only one provider is published.
 # Lab default: openai (catalog also ships azure-openai).
 ENTERPRISE_LLM_DEFAULT_SELECTOR=openai
 
@@ -180,6 +179,8 @@ ABAC_EXPLAIN_MODE_ENABLED=false
 ABAC_PERFORMANCE_THRESHOLD_MS=1000
 
 # RBAC Audit Configuration
+# When true, audit denials (rbac.permission.check.failure) and decision traces.
+# Successful allow checks are not audited (no forensic value; floods every request).
 RBAC_AUDIT_ENABLED=true
 # RBAC audit detail: summary | detailed | explain
 RBAC_AUDIT_DETAIL_LEVEL=summary