@aifabrix/builder 2.44.6 → 2.45.5

package/lib/protection/validate-local.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Local AJV validation for protection manifests (shape only).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+
+const SCHEMA_PATH = path.join(__dirname, '..', 'schema', 'protection.schema.json');
+
+let compiledValidator = null;
+
+/**
+ * Strip AI Fabrix schema file metadata (not part of JSON Schema validation).
+ * @param {Object} raw
+ * @returns {Object}
+ */
+function protectionSchemaForAjv(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return raw;
+  }
+  const { metadata: _meta, ...schema } = raw;
+  if (schema.$schema && String(schema.$schema).includes('2020-12')) {
+    delete schema.$schema;
+  }
+  return schema;
+}
+
+function getValidator() {
+  if (compiledValidator) {
+    return compiledValidator;
+  }
+  const schema = protectionSchemaForAjv(require(SCHEMA_PATH));
+  const ajv = new Ajv({ allErrors: true, strict: false, strictSchema: false });
+  addFormats(ajv);
+  compiledValidator = ajv.compile(schema);
+  return compiledValidator;
+}
+
+/**
+ * @param {Object} manifest
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateProtectionManifestLocal(manifest) {
+  const validate = getValidator();
+  const valid = validate(manifest);
+  if (valid) {
+    return { valid: true, errors: [] };
+  }
+  const errors = (validate.errors || []).map((err) => {
+    const at = err.instancePath || err.schemaPath || '';
+    return at ? `${at}: ${err.message}` : String(err.message || 'Schema validation failed');
+  });
+  return { valid: false, errors };
+}
+
+module.exports = {
+  validateProtectionManifestLocal,
+  getValidator,
+  protectionSchemaForAjv
+};

package/lib/resolvers/dimension-file.js

@@ -8,8 +8,8 @@
 
 'use strict';
 
-const fs = require('fs');
 const path = require('path');
+const { existsSync, readFileSync } = require('../internal/fs-real-sync');
 
 /**
  * @typedef {Object} DimensionCreateInput
@@ -17,10 +17,28 @@ const path = require('path');
  * @property {string} displayName
  * @property {string} [description]
  * @property {'string'|'number'|'boolean'} dataType
+ * @property {'static'|'dynamic'|'both'} [valueType]
  * @property {boolean} [isRequired]
  * @property {Array<{ value: string, displayName?: string, description?: string }>} [values]
  */
 
+const VALUE_TYPES = new Set(['static', 'dynamic', 'both']);
+
+/**
+ * @param {*} raw
+ * @returns {'static'|'dynamic'|'both'}
+ */
+function normalizeValueType(raw) {
+  if (raw === undefined || raw === null || raw === '') {
+    return 'static';
+  }
+  const vt = String(raw).trim();
+  if (!VALUE_TYPES.has(vt)) {
+    throw new Error('valueType must be one of: static, dynamic, both');
+  }
+  return /** @type {'static'|'dynamic'|'both'} */ (vt);
+}
+
 /**
  * @param {string} filePath
  * @returns {DimensionCreateInput}
@@ -30,10 +48,10 @@ function readDimensionCreateFile(filePath) {
   if (!p) {
     throw new Error('--file is required');
   }
-  if (!fs.existsSync(p)) {
+  if (!existsSync(p)) {
     throw new Error(`File not found: ${p}`);
   }
-  const raw = fs.readFileSync(p, 'utf8');
+  const raw = readFileSync(p, 'utf8');
   let parsed;
   try {
     parsed = JSON.parse(raw);
@@ -43,10 +61,17 @@ function readDimensionCreateFile(filePath) {
   if (!parsed || typeof parsed !== 'object') {
     throw new Error(`Dimension file must be a JSON object: ${p}`);
   }
+  if (parsed.valueType !== undefined) {
+    parsed.valueType = normalizeValueType(parsed.valueType);
+  } else {
+    parsed.valueType = 'static';
+  }
   return parsed;
 }
 
 module.exports = {
-  readDimensionCreateFile
+  readDimensionCreateFile,
+  normalizeValueType,
+  VALUE_TYPES
 };
 

package/lib/schema/application-schema.json

@@ -534,6 +534,10 @@
           "pattern": "^[a-zA-Z.$\\{\\}_-]+$",
           "default": true
         },
+        "internalDockerUseOriginOnly": {
+          "type": "boolean",
+          "description": "When true, declarative url://*-internal full URLs in Docker profile use http://service:containerPort only (omit frontDoorRouting.pattern). Use when the ingress path (e.g. /miso) is not part of in-container routes. Omit or false to keep pattern on internal URLs (e.g. Keycloak /auth)."
+        },
         "certStore": {
           "type": "string",
           "description": "Certificate store name for wildcard certificates. Optional - only needed when using a pre-configured certificate store in Traefik.",

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

@@ -2,12 +2,12 @@
   "$schema":"https://json-schema.org/draft/2020-12/schema",
   "$id":"aifabrix://schema/external-datasource.schema.json",
   "title":"External Data Source",
-  "description":"Configuration for AI Fabrix ExternalDataSource entities. Includes metadata schema, data dimensions, transformation mappings, OpenAPI/MCP exposure, execution logic, and sync behavior. Root externalSpec is the datasource-level authoritative reference for where to obtain the vendor or tooling API specification used for import and validation; external-system.schema.json openapi/mcp are system-level connectivity hints only.",
+  "description":"Configuration for AI Fabrix ExternalDataSource entities. Includes metadata schema, data dimensions, transformation mappings, OpenAPI/MCP exposure, execution logic, and sync behavior. Root externalSpec is the datasource-level authoritative reference for where to obtain the vendor or tooling API specification used for import and validation; external-system.schema.json openapi/mcp are system-level connectivity hints only. Agent-facing business metadata (epic 404): most hints are existing properties below; optional businessOrder orders datasources within a system; trust/confidence from agentValidation (404.5) is persisted separately—not in this config document.",
         "metadata":{
         "key":"external-datasource-schema",
         "name":"External Data Source Configuration Schema",
         "description":"JSON schema for validating ExternalDataSource configuration files",
-    "version":"2.4.8",
+    "version":"2.4.10",
         "type":"schema",
         "category":"integration",
         "author":"AI Fabrix Team",
@@ -185,7 +185,24 @@
            "breaking":false
         },
         {
-           "version":"2.4.8",
+           "version":"2.4.10",
+           "date":"2026-05-18T00:00:00Z",
+           "changes":[
+              "Added optional agentExposure.runtimeMeta (boolean, default false) to opt in to meta.business, meta.cip.steps, and meta.agentValidation safe subset on REST runtime responses (plan 404.2)."
+           ],
+           "breaking":false
+        },
+        {
+           "version":"2.4.9",
+           "date":"2026-05-18T00:00:00Z",
+           "changes":[
+              "Added optional root businessOrder (integer >= 1) for cross-datasource ordering within one external system (agent/integrator workflows; does not change CIP execution order).",
+              "Improved descriptions on context, exposed.filterable, fieldMappings.attributes.*.semantic, capabilities, and execution.cip.operations shape/safe documenting what integrators and agents receive on manifest vs published OpenAPI vs runtime meta vs agentValidation evidence (plan 404.0)."
+           ],
+           "breaking":false
+        },
+        {
+           "version":"2.4.9",
            "date":"2026-05-10T00:00:00Z",
            "changes":[
               "Documented roles: root externalSpec is the datasource-level authoritative vendor/API specification provenance (fetch, import, validation); config.openapi is the runtime connector (operations, documentKey) and is the behavioral source of truth; external-system openapi/mcp remain connectivity/bootstrap only.",
@@ -254,6 +271,23 @@
         "pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+$",
         "default":"1.0.0"
      },
+     "businessOrder":{
+        "type":"integer",
+        "minimum":1,
+        "description":"Optional sort order of this datasource within its external system (1 = first) for agent and integrator workflows when multiple record-storage datasources exist. Does not control CIP step execution order. Published to OpenAPI governance / optional runtime meta.business.businessOrder when epic 404.2 is enabled. foreignKeys alone do not define this order."
+     },
+     "agentExposure":{
+        "type":"object",
+        "description":"Opt-in surfaces for AI agent metadata on published OpenAPI and runtime REST envelopes (plans 404.2–404.3). Does not change CIP execution.",
+        "additionalProperties":false,
+        "properties":{
+           "runtimeMeta":{
+              "type":"boolean",
+              "default":false,
+              "description":"When true, REST runtime responses include meta.business (filterable echo, derived dangerousOperations, exposed semantic fields), meta.cip.steps from execution logs, and meta.agentValidation safe subset from persisted 404.5 validation."
+           }
+        }
+     },
      "metadataSchema":{
         "$ref":"#/$defs/metadataSchemaNode"
      },
@@ -347,15 +381,15 @@
                           },
                           "semantic":{
                              "type":"object",
-                             "description":"Semantic metadata for AI agents and schema generation.",
+                             "description":"Per-field business semantics for agents (manifest + OpenAPI component descriptions). Not copied to runtime REST meta by default; use published OpenAPI or manifest fetch for discovery. Validated by deterministic rules (346/370) and optional agentValidation (404.5) which may flag missing descriptions in findings—not auto-written to config.",
                              "properties":{
                                 "title":{
                                    "type":"string",
-                                   "description":"Human-friendly label for this field."
+                                   "description":"Human-friendly label for this normalized attribute (UI and OpenAPI property titles)."
                                 },
                                 "description":{
                                    "type":"string",
-                                   "description":"Business-level description of the field and how it is used."
+                                   "description":"Business meaning of the field and how agents should use it in filters or answers. Primary authoring surface for field-level agent hints (use this, not a separate 'meaning' property)."
                                 },
                                 "example":{
                                    "description":"Example value for this field.",
@@ -452,7 +486,7 @@
            },
            "filterable":{
               "type":"array",
-              "description":"Fields that may be used as deterministic filters in exposed APIs. Must reference materialized fields (`index=true` or `filter=true`).",
+              "description":"Canonical list of normalized attribute names agents and integrators may use as deterministic API filters. Must reference materialized fields (metadataSchema index=true or filter=true). Validated by exposed_exposure_lists_validate.py. Emitted on published OpenAPI when epic 404.3 is enabled; optional runtime echo as meta.business.recommendedFilters. agentValidation (404.5) may suggest additions in observedBusinessModel only—they are not a second config field.",
               "items":{
                  "type":"string",
                  "pattern":"^[a-z][a-zA-Z0-9]*$"
@@ -735,11 +769,11 @@
      },
      "context":{
         "type":"object",
-        "description":"Natural-language and semantic hints for AI agents.",
+        "description":"Datasource-level discovery hints for agents. Copied to COM semantic_tags and OpenAPI tags when COM build runs; not included in runtime REST meta by default. Prefer structured semanticTags and fieldMappings.*.semantic.description over naturalLanguageHints (legacy prose; do not expand in new integrations).",
         "properties":{
            "semanticTags":{
               "type":"array",
-              "description":"High-level tags describing this datasource (e.g. ['crm', 'customer-data', 'deal']).",
+              "description":"Structured tags for classification and OpenAPI tag emission (e.g. ['crm', 'sales', 'deals']).",
               "items":{
                  "type":"string"
               }
@@ -753,7 +787,7 @@
            },
            "naturalLanguageHints":{
               "type":"array",
-              "description":"Free-form hints for LLMs on how to interpret or use this datasource.",
+              "description":"Legacy free-form strings (wizard may still emit). Not structured agent contract metadata; avoid for new authoring (plan 404.1). Not exposed on public OpenAPI or runtime meta.",
               "items":{
                  "type":"string"
               }
@@ -855,7 +889,7 @@
         "additionalProperties":false
      },
    "capabilities":{
-      "description":"Supported operations list.",
+      "description":"Declared operation keys (e.g. list, get, create, update, delete, or custom names matching execution.cip.operations and openapi.operations). Dataplane derives per-operation agent semantics at publish time: core delete and custom ops with CIP shape delete map to x-ai-intent delete and high riskLevel on published OpenAPI—not a separate dangerousOperations list in config.",
       "type":"array",
       "items":{
          "type":"string",
@@ -1868,7 +1902,7 @@
            },
            "safe":{
               "type":"boolean",
-              "description":"Optional safety hint for operation execution."
+              "description":"Optional override when automatic shape/fetch inference misclassifies mutating risk. When wired (plan 404.3), influences COM destructive flags and x-ai-safeToRetry on published OpenAPI. Prefer shape for create/update/delete classification."
            },
            "lineage":{
               "$ref":"#/$defs/cipLineage"
@@ -1883,7 +1917,7 @@
                  "update",
                  "delete"
               ],
-              "description":"Optional semantic classification for this operation when automatic inference from fetch steps (method/path) is insufficient."
+              "description":"Manifest classification for custom operations when fetch step inference is insufficient. Resolved by resolve_cip_write_shape (precedence over fetch inference) and drives x-ai-intent, x-ai-sideEffects, and x-ai-contract.riskLevel on published OpenAPI. shape delete marks the operation as dangerous for agent policy (with core capability delete)."
            },
            "steps":{
               "type":"array",

package/lib/schema/flag-map-validation-run.json

@@ -14,8 +14,8 @@
     { "cliFlag": "--no-run-scenarios", "requestField": "e2eOptions.runScenarios", "runType": "e2e" },
     { "cliFlag": "--no-cleanup", "requestField": "e2eOptions.cleanup", "runType": "e2e" },
     { "cliFlag": "--primary-key-value", "requestField": "e2eOptions.primaryKeyValue", "runType": "e2e" },
-    { "cliFlag": "--capability <key>", "requestField": "e2eOptions.capabilityKeys", "runType": "e2e", "note": "Single key forwarded as capabilityKeys array in request body when set" },
-    { "cliFlag": "--strict-capability-scope", "requestField": null, "runType": "e2e", "note": "Client-only: exit ≥1 when capabilities[] has >1 row while --capability is set (plan §2.3)" },
+    { "cliFlag": "[capabilityKey] (positional)", "requestField": "e2eOptions.capabilityKeys", "runType": "e2e", "note": "Single key forwarded as capabilityKeys array in request body when set" },
+    { "cliFlag": "--strict-capability-scope", "requestField": null, "runType": "e2e", "note": "Client-only: exit ≥1 when capabilities[] has >1 row while [capabilityKey] is set (plan §2.3)" },
     { "cliFlag": "--require-cert", "requestField": null, "note": "Client-only exit code 2 gate" },
     { "cliFlag": "--warnings-as-errors", "requestField": null, "note": "Client-only exit code 1 on warn" },
     { "cliFlag": "--json", "requestField": null, "note": "Stdout prints raw DatasourceTestRun" },

package/lib/schema/infra.parameter.yaml

@@ -342,6 +342,16 @@ parameters:
     azure:
       notes: Empty until set; user-supplied Azure OpenAI API key (not auto-generated).
 
+  # Legacy unprefixed name (scaffold / old env.template); prefer *KeyVault suffix or {appKey}-secrets-apiKeyVault (keyvault.md).
+  - key: api-key
+    scope: app
+    generator:
+      type: randomBytes32
+    ensureOn: [resolveApp]
+    azure:
+      notes: >-
+        Legacy kv://api-key; new apps should use kv://api-keyKeyVault or {appKey}-secrets-apiKeyVault.
+
   # Legacy unprefixed name; prefer kv://{appKey}-secrets-apiKeyVault in env.template (keyvault.md secrets.apiKeyVault).
   - key: miso-controller-secrets-apiKeyVault
     scope: app