@aifabrix/builder 2.53.0 → 2.54.1

package/lib/schema/external-datasource.schema.json

@@ -7,12 +7,12 @@
          "key":"external-datasource-schema",
          "name":"External Data Source Configuration Schema",
          "description":"JSON schema for validating ExternalDataSource configuration files",
-     "version":"2.9.6",
+     "version":"2.9.9",
          "type":"schema",
          "category":"integration",
          "author":"AI Fabrix Team",
          "createdAt":"2024-01-01T00:00:00Z",
-         "updatedAt":"2026-08-07T00:00:00Z",
+         "updatedAt":"2026-08-27T00:00:00Z",
          "compatibility":{
             "minVersion":"1.0.0",
             "maxVersion":"3.0.0",
@@ -31,6 +31,23 @@
          "external-system.schema.json"
       ],
       "changelog":[
+         {
+            "version":"2.9.9",
+            "date":"2026-08-27T00:00:00Z",
+            "changes":[
+               "Added optional testPayload.listWindow {page, pageSize} so capacity and CIP-simulate list probes stop after a few vendor pages. Does not change CIP paginate.maxPages. CIP $defs unchanged (543 visual N/A).",
+               "Clarified testPayload descriptions: mapping expectedResult vs capacity expectedRows, write input is exposed shape, listWindow vs live paginate.maxPages."
+            ],
+            "breaking":false
+         },
+         {
+            "version":"2.9.8",
+            "date":"2026-08-25T00:00:00Z",
+            "changes":[
+               "Added optional testPayload.scenarios items expectedRows, identityKey, numericTolerance, and matchMode for capacity E2E row gold (list/get and named CIP). Mapping-step expectedResult is unchanged."
+            ],
+            "breaking":false
+         },
          {
             "version":"2.9.5",
             "date":"2026-07-31T00:00:00Z",
@@ -520,7 +537,7 @@
       },
       "webhook":{
          "type":"object",
-         "description":"Vendor webhook change-signal configuration (454.0). Webhook is trigger-only; business data comes from CIP get.",
+         "description":"Vendor webhook configuration. events[] that match a capability key invoke that CIP operation; other names trigger SyncIntent and CIP get.",
          "additionalProperties":false,
          "properties":{
             "enabled":{
@@ -543,7 +560,7 @@
                   "type":"string",
                   "minLength":1
                },
-               "description":"Vendor event names that trigger SyncIntent creation."
+               "description":"Event names that select work. A name that matches capabilities[].key invokes that operation (fieldMappings reshape the body). Other names trigger SyncIntent and CIP get. Do not mix both kinds on one datasource."
             },
             "deleteEvents":{
                "type":"array",
@@ -556,7 +573,7 @@
             "idPath":{
                "type":"string",
                "minLength":1,
-               "description":"JSONPath to extract vendor object id from webhook payload, e.g. $.objectId"
+               "description":"JSONPath to extract vendor object id from webhook payload, e.g. $.objectId. Required for change-signal events; not required when every events[] entry is a capability key."
             },
             "eventTypePath":{
                "type":"string",
@@ -1014,14 +1031,15 @@
       },
       "testPayload":{
          "type":"object",
-         "description":"Execution-aware test payload configuration for unit and integration testing. Only the listed properties are allowed at this level; nested shapes for payloadTemplate/expectedResult/fk fixtures are validated strictly by the application validator where required.",
+         "description":"Author-owned proof contract for this Business Entity. Mapping uses payloadTemplate plus expectedResult (one normalized record). Capacity E2E walks scenarios in array order: omit expectedRows for success-only; set expectedRows plus identityKey to prove CIP output rows (list, get, and named viewpoint answers). listWindow is the list probe and does not change live CIP paginate.maxPages. Root is closed — unknown keys fail validate. Role Assistant search is not the owner of gold amounts.",
          "properties":{
             "mode":{
                "type":"string",
                "enum":[
                   "mock",
                   "live"
-               ]
+               ],
+               "description":"live runs against the connected system (certification). mock is offline mapping/unit only."
             },
             "primaryKey":{
                "type":"object",
@@ -1033,9 +1051,29 @@
                "default":true,
                "description":"When true (default if scenarios include create), after create the executor merges returned identifiers into the effective primary key for later get/update/delete in that run. When false, mutations use the static manifest primaryKey (destructive on shared fixtures). Ignored when no create scenario exists."
             },
+            "listWindow":{
+               "type":"object",
+               "description":"Default list probe for capacity and CIP-simulate. Runtime passes CIP page and pageSize so paginate stops after a few pages. Does not change production CIP paginate.maxPages (live completeness). Scenario input.page/pageSize override this step. Omitted defaults: page 1, pageSize 5. limit is not a CIP window key.",
+               "additionalProperties":false,
+               "properties":{
+                  "page":{
+                     "type":"integer",
+                     "minimum":1,
+                     "default":1,
+                     "description":"1-based list page for the probe (default 1)."
+                  },
+                  "pageSize":{
+                     "type":"integer",
+                     "minimum":1,
+                     "maximum":100,
+                     "default":5,
+                     "description":"Rows per probe page (default 5, max 100)."
+                  }
+               }
+            },
             "scenarios":{
                "type":"array",
-               "description":"Ordered scenario steps for capacity E2E; execution order is array order (optional order field is a diagnostics hint only).",
+               "description":"Ordered capacity E2E steps (array order). Each operation must match a CIP operation key. Writes prove persist on a following get with expectedRows — do not gold create/update/delete rows. Optional order is diagnostics only.",
                "items":{
                   "type":"object",
                   "required":[
@@ -1044,7 +1082,8 @@
                   "properties":{
                      "operation":{
                         "type":"string",
-                        "pattern":"^[a-z][a-zA-Z0-9]*$"
+                        "pattern":"^[a-z][a-zA-Z0-9]*$",
+                        "description":"CIP operation key for this step (list, get, create, update, delete, or a named capability such as a viewpoint answer)."
                      },
                      "enabled":{
                         "type":"boolean",
@@ -1053,14 +1092,58 @@
                      },
                      "input":{
                         "type":"object",
-                        "additionalProperties":true
+                        "additionalProperties":true,
+                        "description":"Write scenarios: exposed (normalized) payload a REST or MCP caller would send — not the vendor envelope. List scenarios: optional page/pageSize override of listWindow. Read get typically uses testPayload.primaryKey, not this object."
                      },
                      "order":{
                         "type":"integer",
                         "description":"Optional stable sort hint for scenario execution / diagnostics."
+                     },
+                     "expectedRows":{
+                        "type":"array",
+                        "description":"Capacity E2E gold for CIP output rows. Omitted means success-only (invoke did not throw). Empty array means expect zero rows (zero is a fact, not unknown). Same contract for record list/get and viewpoint named operations. PostgreSQL remains the calculator — this asserts the result. Requires identityKey when the array has one or more items.",
+                        "items":{
+                           "type":"object",
+                           "additionalProperties":true
+                        }
+                     },
+                     "identityKey":{
+                        "type":"string",
+                        "minLength":1,
+                        "description":"Published output field that uniquely identifies each gold row (this datasource output, often externalId). Required when expectedRows has one or more items. Not a platform-wide vocabulary."
+                     },
+                     "numericTolerance":{
+                        "type":"number",
+                        "minimum":0,
+                        "default":0,
+                        "description":"Absolute tolerance applied only to numeric expected fields (COUNT typically 0). Does not apply to strings."
+                     },
+                     "matchMode":{
+                        "type":"string",
+                        "enum":[
+                           "subsetIdentities",
+                           "exactIdentities"
+                        ],
+                        "default":"subsetIdentities",
+                        "description":"subsetIdentities (default): every gold identity must appear in CIP output (extra live rows allowed — typical for list probes). exactIdentities also fails extra actual identities."
                      }
                   },
-                  "additionalProperties":false
+                  "additionalProperties":false,
+                  "if":{
+                     "required":[
+                        "expectedRows"
+                     ],
+                     "properties":{
+                        "expectedRows":{
+                           "minItems":1
+                        }
+                     }
+                  },
+                  "then":{
+                     "required":[
+                        "identityKey"
+                     ]
+                  }
                }
             },
             "fk":{
@@ -1086,12 +1169,12 @@
             },
             "payloadTemplate":{
                "type":"object",
-               "description":"Sample payload matching the expected API response structure. Used for testing field mappings and metadata schema validation.",
+               "description":"Sample payload that mapping expressions read (typically provider/raw shape for raw.*). Used by the mapping step and expression resolution. Not write scenario input — writes use scenarios[].input in the exposed shape.",
                "additionalProperties":true
             },
             "expectedResult":{
                "type":"object",
-               "description":"Expected normalized result after field mapping transformations (optional, for validation)",
+               "description":"Mapping-step gold for ONE normalized record after fieldMappings (shape/subset). Not aggregates, not multi-row CIP output — that is scenarios[].expectedRows.",
                "additionalProperties":true
             }
          },
@@ -2534,9 +2617,10 @@
                        "openapi",
                        "http",
                        "datasource",
-                       "viewpoint"
+                       "viewpoint",
+                       "record"
                      ],
-                    "description":"If 'openapi', refer to openapi.operations.*. If 'http', use explicit method/path. If 'datasource', execute another datasource operation. If 'viewpoint', execute saved SQL in fetch.query against records storage (storageType view)."
+                    "description":"If 'openapi', refer to openapi.operations.*. If 'http', use explicit method/path. If 'datasource', execute another datasource operation. If 'viewpoint', execute saved SQL in fetch.query against records storage (storageType view). If 'record', read or persist governed rows in local record storage with no vendor HTTP. Persist vs read follows the CIP operation shape (create|update), not the operation key. Fetch token is singular record; output.mode remains plural records."
                   },
                   "openapiRef":{
                      "type":"string",
@@ -2589,7 +2673,7 @@
                     "description":"When true, append fetch items to the pipeline accumulator for a following merge step."
                  },
                   "query":{
-                     "description":"When source is openapi/http/datasource: static query parameter object. When source is viewpoint: non-empty SQL SELECT string. ABAC/runtime may still append supported filters at execution for viewpoint."
+                     "description":"When source is openapi/http/datasource: static query parameter object. When source is viewpoint: non-empty SQL SELECT string. Forbidden when source is record. ABAC/runtime may still append supported filters at execution for viewpoint."
                   },
                   "bodyTemplate":{
                      "description":"Optional static request body or template for POST/PUT/PATCH fetches.",
@@ -2726,6 +2810,25 @@
                            }
                         }
                      }
+                  },
+                  {
+                     "if":{
+                        "properties":{
+                           "source":{
+                              "const":"record"
+                           }
+                        },
+                        "required":[
+                           "source"
+                        ]
+                     },
+                     "then":{
+                        "not":{
+                           "required":[
+                              "query"
+                           ]
+                        }
+                     }
                   }
                ],
                "additionalProperties":false

package/lib/schema/external-system.schema.json

@@ -7,12 +7,12 @@
       "key": "external-system-schema",
       "name": "External System Configuration Schema",
       "description": "JSON schema for validating ExternalSystem configuration files",
-      "version": "1.14.0",
+      "version": "1.16.0",
       "type": "schema",
       "category": "integration",
       "author": "AI Fabrix Team",
       "createdAt": "2024-01-01T00:00:00Z",
-      "updatedAt": "2026-08-07T00:00:00Z",
+      "updatedAt": "2026-08-23T00:00:00Z",
       "compatibility": {
          "minVersion": "1.4.0",
          "maxVersion": "2.0.0",
@@ -27,6 +27,22 @@
       ],
       "dependencies": [],
       "changelog": [
+         {
+            "version": "1.16.0",
+            "date": "2026-08-23T00:00:00Z",
+            "changes": [
+               "Added optional channel.maxInstances (integer, minimum 1) for Channel Definition cardinality. Omit for unbounded. Builder refuses new installs at the cap; existing instance keys are not deleted."
+            ],
+            "breaking": false
+         },
+         {
+            "version": "1.15.0",
+            "date": "2026-08-22T00:00:00Z",
+            "changes": [
+               "Added optional top-level channel specialization for Channel Definition documents and materialized communication Connected Systems (definitionKey, provisioning.mode automatic|guided|cli, runtimeTarget, profiles, packaging)."
+            ],
+            "breaking": false
+         },
          {
             "version": "1.14.0",
             "date": "2026-08-07T00:00:00Z",
@@ -1716,6 +1732,147 @@
             }
          },
          "additionalProperties": false
+      },
+      "channel": {
+         "type": "object",
+         "description": "Optional Channel Definition specialization. Present on Channel Definition documents and materialized communication Connected Systems. Omit on non-channel External Systems.",
+         "additionalProperties": false,
+         "required": [
+            "definitionKey",
+            "provisioning"
+         ],
+         "properties": {
+            "definitionKey": {
+               "type": "string",
+               "description": "Stable catalog identity. Equals key on a definition document; preserved on a materialized instance whose key may differ.",
+               "pattern": "^[a-z0-9-]+$",
+               "minLength": 3,
+               "maxLength": 40
+            },
+            "provisioning": {
+               "type": "object",
+               "additionalProperties": false,
+               "required": [
+                  "mode"
+               ],
+               "properties": {
+                  "mode": {
+                     "type": "string",
+                     "enum": [
+                        "automatic",
+                        "guided",
+                        "cli"
+                     ],
+                     "description": "automatic: API completes with no remaining vendor step. guided: API runs install; vendor leftovers use help.md. cli: hosted API must not run the adapter; return generated CLI instructions."
+                  }
+               }
+            },
+            "runtimeTarget": {
+               "type": "object",
+               "additionalProperties": false,
+               "required": [
+                  "defaultSystemKey"
+               ],
+               "properties": {
+                  "defaultSystemKey": {
+                     "type": "string",
+                     "pattern": "^[a-z0-9-]+$",
+                     "description": "Default runtime or MCP Connected System key. Not the channel instance key."
+                  },
+                  "configurable": {
+                     "type": "boolean",
+                     "description": "When true, install may choose an approved runtime or MCP Connected System."
+                  }
+               }
+            },
+            "experimental": {
+               "type": "boolean",
+               "default": false
+            },
+            "maxInstances": {
+               "type": "integer",
+               "minimum": 1,
+               "description": "Maximum Connected System instances for this Channel Definition. Omit for unbounded. Builder refuses new installs at the cap; existing instance keys are not deleted."
+            },
+            "profiles": {
+               "type": "array",
+               "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                     "key",
+                     "displayLabel"
+                  ],
+                  "properties": {
+                     "key": {
+                        "type": "string",
+                        "minLength": 1
+                     },
+                     "displayLabel": {
+                        "type": "string",
+                        "minLength": 1
+                     }
+                  }
+               }
+            },
+            "artifacts": {
+               "type": "array",
+               "description": "Generic artifact ids produced at install (no vendor URLs).",
+               "items": {
+                  "type": "string",
+                  "minLength": 1
+               }
+            },
+            "packaging": {
+               "type": "object",
+               "description": "Builder implementation packaging metadata. Not a consumer contract.",
+               "additionalProperties": false,
+               "properties": {
+                  "templateDir": {
+                     "type": "string"
+                  },
+                  "channelType": {
+                     "type": "string"
+                  },
+                  "artifactFileName": {
+                     "type": "string"
+                  },
+                  "artifactFormat": {
+                     "type": "string"
+                  },
+                  "credentialKey": {
+                     "type": "string"
+                  },
+                  "capabilities": {
+                     "type": "array",
+                     "items": {
+                        "type": "string"
+                     }
+                  },
+                  "displayLabel": {
+                     "type": "string"
+                  },
+                  "category": {
+                     "type": "string"
+                  },
+                  "wizardOrder": {
+                     "type": "integer"
+                  },
+                  "remainingManualStep": {
+                     "type": "string"
+                  },
+                  "docsAnchor": {
+                     "type": "string"
+                  },
+                  "approvalRequired": {
+                     "type": "boolean"
+                  },
+                  "vendorAuthRequired": {
+                     "type": "boolean"
+                  }
+               }
+            }
+         }
       }
    },
    "additionalProperties": false

package/lib/schema/mcp-client-profile.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MCP client installation profile",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["key", "displayName", "transport", "config", "oauth", "reload", "uninstall"],
+  "properties": {
+    "key": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "displayName": {
+      "type": "string",
+      "minLength": 1
+    },
+    "transport": {
+      "type": "string",
+      "enum": ["streamable-http"]
+    },
+    "config": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scope", "relativePath", "serversKey", "serverKey"],
+      "properties": {
+        "scope": {
+          "type": "string",
+          "enum": ["user", "project"]
+        },
+        "relativePath": {
+          "type": "string",
+          "minLength": 1
+        },
+        "serversKey": {
+          "type": "string",
+          "enum": ["mcpServers", "servers"]
+        },
+        "serverKey": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "oauth": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "integrationClientKey",
+        "keycloakClientId",
+        "registrationMode",
+        "redirectUris"
+      ],
+      "properties": {
+        "integrationClientKey": {
+          "type": "string",
+          "minLength": 1
+        },
+        "keycloakClientId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "registrationMode": {
+          "type": "string",
+          "enum": ["predefinedClient", "cimd"]
+        },
+        "redirectUris": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "cimdDocumentHosts": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "reload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["remainingStep"],
+      "properties": {
+        "remainingStep": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "uninstall": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["removeServerKeyOnly"],
+      "properties": {
+        "removeServerKeyOnly": {
+          "type": "boolean"
+        }
+      }
+    }
+  }
+}

package/lib/utils/app-path-resolve.js

@@ -160,6 +160,7 @@ function resolveFromExistingPathsBackwardCompatible(
  * Resolves authoring tree for an external system or Enterprise Knowledge anchor.
  * @param {string} appName - App or anchor key
  * @param {Object} [options]
+ * @param {string} [options.appPath] - Explicit package directory (channel instance upload)
  * @param {string} [options.workspace] - integration | enterprise-knowledge | role-assistant
  * @param {string} [options.systemKind] - Explicit systemKind override
  * @returns {{ appPath: string, baseDir: 'integration' | 'enterprise-knowledge' | 'role-assistant' }}
@@ -168,6 +169,9 @@ function resolveAppWorkspace(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
+  if (typeof options.appPath === 'string' && options.appPath.trim()) {
+    return workspacePair(path.resolve(options.appPath.trim()), WORKSPACE_INTEGRATION);
+  }
   const { getIntegrationPath } = require('./paths');
   const workspaceOverride = normalizeWorkspaceOverride(options.workspace);
   const explicitKind = typeof options.systemKind === 'string' ? options.systemKind.trim() : '';

package/lib/utils/authentication-env-template.js

@@ -13,7 +13,7 @@ const {
   securityKeyToVar,
   systemKeyToKvPrefix
 } = require('./credential-secrets-env');
-const { getKvPathSegmentForSecurityKey } = require('./credential-secrets-env-kv');
+const { getKvPathSegmentForSecurityKey, isValidKvPath } = require('./credential-secrets-env-kv');
 
 /**
  * @param {string} slotKey
@@ -53,6 +53,45 @@ function buildSlotKvPath(systemKey, slotKey, securityKey) {
   return `kv://${systemKey}/${segment}`;
 }
 
+/**
+ * Prefer the credential's kv:// path; invent a slot path only when missing.
+ * @param {unknown} securityVal
+ * @param {string} systemKey
+ * @param {string} slotKey
+ * @param {string} securityKey
+ * @returns {string|null}
+ */
+function kvPathFromSecurityValue(securityVal, systemKey, slotKey, securityKey) {
+  if (typeof securityVal === 'string' && isValidKvPath(securityVal)) {
+    return securityVal.trim();
+  }
+  return buildSlotKvPath(systemKey, slotKey, securityKey);
+}
+
+/**
+ * Env name from an existing kv:// path so nested slot paths stay nested
+ * and shared secrets (same path, two usages) share one KV_* line.
+ * @param {string} prefix
+ * @param {string} kvPath
+ * @param {string} slotKey
+ * @param {string} securityKey
+ * @returns {string}
+ */
+function envNameFromKvPath(prefix, kvPath, slotKey, securityKey) {
+  const parts = String(kvPath || '')
+    .replace(/^kv:\/\//, '')
+    .split('/')
+    .filter(Boolean);
+  if (parts.length >= 3) {
+    const folder = parts[1].replace(/-/g, '_').toUpperCase();
+    return `KV_${prefix}_${folder}_${securityKeyToVar(parts[parts.length - 1])}`;
+  }
+  if (parts.length === 2) {
+    return `KV_${prefix}_${securityKeyToVar(parts[1])}`;
+  }
+  return buildSlotEnvName(prefix, slotKey, securityKey);
+}
+
 /**
  * @param {Array} effective
  * @param {Set<string>} seenNames
@@ -79,13 +118,12 @@ function addSecurityKeysFromAuthBlock(
     if (typeof securityVal === 'string' && isPlatformCatalogKvRef(securityVal)) {
       continue;
     }
-    const envName = buildSlotEnvName(prefix, slotKey, key);
-    if (seenNames.has(envName)) {
+    const pathVal = kvPathFromSecurityValue(securityVal, systemKey, slotKey, key);
+    if (!pathVal) {
       continue;
     }
-    const pathVal =
-      kvEnvKeyToPath(envName, systemKey) || buildSlotKvPath(systemKey, slotKey, key);
-    if (!pathVal) {
+    const envName = envNameFromKvPath(prefix, pathVal, slotKey, key);
+    if (seenNames.has(envName)) {
       continue;
     }
     effective.push({

package/lib/utils/credential-secrets-env.js

@@ -262,8 +262,13 @@ async function pushCredentialSecrets(dataplaneUrl, authConfig, options = {}) {
   buildItemsFromPayload(payload, secrets, itemsByKey);
   reconcileBearerTokenSecretPaths(itemsByKey, appName, authConfig);
 
+  const excluded = new Set(
+    Array.isArray(options.excludeKeys)
+      ? options.excludeKeys.map((key) => String(key).trim()).filter(Boolean)
+      : []
+  );
   const items = Array.from(itemsByKey.entries())
-    .filter(([k]) => isValidKvPath(k))
+    .filter(([k]) => isValidKvPath(k) && !excluded.has(k))
     .map(([key, value]) => ({ key, value }));
 
   if (items.length === 0) return { pushed: 0, skipped: true };