@aifabrix/builder 2.46.0 → 2.47.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.4.11",
+     "version":"2.8.1",
          "type":"schema",
          "category":"integration",
          "author":"AI Fabrix Team",
          "createdAt":"2024-01-01T00:00:00Z",
-         "updatedAt":"2026-05-21T00:00:00Z",
+         "updatedAt":"2026-06-16T00:00:00Z",
          "compatibility":{
             "minVersion":"1.0.0",
             "maxVersion":"3.0.0",
@@ -31,6 +31,49 @@
          "external-system.schema.json"
       ],
       "changelog":[
+         {
+            "version":"2.8.1",
+            "date":"2026-06-15T00:00:00Z",
+            "changes":[
+               "Added composition.datasources for composed enterprise and Digital Worker datasources (438.6).",
+               "Added optional subscriptionFilter (roleKeys, includeSystemKinds, excludeSystemKinds, resourceTypes, systemKeys, datasourceKeys) on datasource manifests."
+            ],
+            "breaking":false
+         },
+         {
+            "version":"2.7.2",
+            "date":"2026-06-13T00:00:00Z",
+            "changes":[
+               "346 §13.1: exposed.profiles keys must match capabilities or default; decorative orphan keys (minimal, metadata, analytics) forbidden."
+            ],
+            "breaking":false
+         },
+         {
+            "version":"2.7.1",
+            "date":"2026-06-12T00:00:00Z",
+            "changes":[
+               "Removed unused root serviceCategory property (use entityType serviceContract + resourceType for classification)."
+            ],
+            "breaking":false
+         },
+         {
+            "version":"2.7.0",
+            "date":"2026-06-12T00:00:00Z",
+            "changes":[
+               "Added entityType serviceContract for normalized executable service adapters (metadataSchema + fieldMappings + exposed required; no primaryKey/sync/storage).",
+               "Staged migration: entityType none + resourceType llm deprecated in favor of serviceContract (validator phases 1–3)."
+            ],
+            "breaking":false
+         },
+         {
+            "version":"2.6.0",
+            "date":"2026-06-11T00:00:00Z",
+            "changes":[
+               "Added optional executionMetrics with fixed token/cost/duration expression fields for post-CIP observability (437.3).",
+               "Documented llm resourceType usage with call and embed capabilities on entityType none enterprise surfaces."
+            ],
+            "breaking":false
+         },
          {
             "version":"1.0.0",
             "date":"2024-01-01T00:00:00Z",
@@ -184,6 +227,26 @@
             ],
             "breaking":false
          },
+         {
+            "version":"2.5.0",
+            "date":"2026-06-10T00:00:00Z",
+            "changes":[
+               "BREAKING (COM v2): capabilities is object array { key, description?, riskLevel?, approvalRequired? } — string[] removed.",
+               "BREAKING: Removed root context object (semanticTags, synonyms).",
+               "BREAKING: Removed fieldMappings.*.semantic.synonyms and semantic.categories.",
+               "resourceType is a catalog key reference (validated against resource_types).",
+               "Added optional boolean authority on datasource root for write routing."
+            ],
+            "breaking":true
+         },
+         {
+            "version":"2.4.12",
+            "date":"2026-06-05T00:00:00Z",
+            "changes":[
+               "Removed context.naturalLanguageHints (plan 432). Use semanticTags, synonyms, and fieldMappings.*.semantic.description instead."
+            ],
+            "breaking":true
+         },
          {
             "version":"2.4.11",
             "date":"2026-05-21T00:00:00Z",
@@ -265,14 +328,19 @@
       },
       "entityType":{
          "type":"string",
-         "enum":["documentStorage","vectorStore","recordStorage","messageService","none"],
-         "description":"Entity type identifier. Defines storage semantics and behavior: 'documentStorage' (creates document storage service with vector-storage), 'vectorStore' (external vector storage system), 'recordStorage' (creates record-based system with metadata sync and access rights), 'messageService' (message service for notifications - Slack, Teams, Email), 'none' (uses external system data directly or connects other data sources). Required field. Canonical values are camelCase."
+         "enum":["documentStorage","vectorStore","recordStorage","messageService","serviceContract","none"],
+         "description":"Entity type identifier. Defines storage semantics and behavior: 'documentStorage' (creates document storage service with vector-storage), 'vectorStore' (external vector storage system), 'recordStorage' (creates record-based system with metadata sync and access rights), 'messageService' (message service for notifications - Slack, Teams, Email), 'serviceContract' (normalized executable service adapter without persistence — requires metadataSchema, fieldMappings, exposed), 'none' (orchestration/composition only). Required field. Canonical values are camelCase."
       },
       "resourceType":{
          "type":"string",
          "pattern":"^[a-z0-9-]+$",
          "default":"document",
-         "description":"Resource type for the datasource. Represents business entity classification. Common values: customer, contact, person, document, deal, record. Any lowercase alphanumeric string with hyphens is allowed."
+         "description":"Catalog key reference (resource_types.key). Must match an active entry synced from miso-controller."
+      },
+      "authority":{
+         "type":"boolean",
+         "default":false,
+         "description":"When true, this datasource is the preferred write/list authority for its resourceType when multiple writable sources exist. Optional; sole writable datasource may omit (implicit authority)."
       },
       "version":{
          "type":"string",
@@ -284,6 +352,28 @@
          "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."
       },
+      "composition":{
+         "type":"object",
+         "description":"Declares upstream datasources merged into this composed datasource. Generator owns merged metadata, exposedSchema, capabilities, and REST/MCP contract.",
+         "additionalProperties":false,
+         "required":["datasources"],
+         "properties":{
+            "datasources":{
+               "type":"array",
+               "minItems":1,
+               "items":{
+                  "type":"string",
+                  "pattern":"^[a-z0-9-]+$",
+                  "minLength":1
+               },
+               "description":"Child datasource keys resolved at generation and execute time."
+            }
+         }
+      },
+      "subscriptionFilter":{
+         "$ref":"aifabrix://schema/external-system.schema.json#/$defs/subscriptionFilter",
+         "description":"Optional role and systemKind filters for Digital Worker generation inputs on datasource manifests."
+      },
       "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.",
@@ -356,7 +446,7 @@
                         "type":"string",
                         "description":"Short-form sugar: an expression string is normalized by the compiler to { expression: '<value>' }.",
                         "maxLength":512,
-                        "pattern":"^\\s*\\{\\{(raw\\.[a-zA-Z0-9_.]+|fk\\.[a-z][a-zA-Z0-9]*\\.metadata\\.[a-z][a-zA-Z0-9]*|fk\\.[a-z][a-zA-Z0-9]*\\.dimension\\.[a-zA-Z0-9_]+(\\.label)?|dimension\\.[a-zA-Z0-9_]+(\\.label)?)\\}\\}(\\s*\\|\\s*[a-zA-Z0-9_]+(\\([^)]*\\))?)*\\s*$"
+                        "pattern":"^\\s*\\{\\{(raw\\.[a-zA-Z0-9_\\[\\].]+|fk\\.[a-z][a-zA-Z0-9]*\\.metadata\\.[a-z][a-zA-Z0-9]*|fk\\.[a-z][a-zA-Z0-9]*\\.dimension\\.[a-zA-Z0-9_]+(\\.label)?|dimension\\.[a-zA-Z0-9_]+(\\.label)?)\\}\\}(\\s*\\|\\s*[a-zA-Z0-9_]+(\\([^)]*\\))?)*\\s*$"
                      },
                      {
                         "type":"object",
@@ -365,7 +455,7 @@
                               "type":"string",
                               "description":"Pipe-based DSL expression. Allowed roots: raw.<path>, fk.<fk>.metadata.<field>, fk.<fk>.dimension.<dimension>[.label], dimension.<dimension>[.label]. FK traversal in DSL is one-hop only.",
                               "maxLength":512,
-                              "pattern":"^\\s*\\{\\{(raw\\.[a-zA-Z0-9_.]+|fk\\.[a-z][a-zA-Z0-9]*\\.metadata\\.[a-z][a-zA-Z0-9]*|fk\\.[a-z][a-zA-Z0-9]*\\.dimension\\.[a-zA-Z0-9_]+(\\.label)?|dimension\\.[a-zA-Z0-9_]+(\\.label)?)\\}\\}(\\s*\\|\\s*[a-zA-Z0-9_]+(\\([^)]*\\))?)*\\s*$"
+                              "pattern":"^\\s*\\{\\{(raw\\.[a-zA-Z0-9_\\[\\].]+|fk\\.[a-z][a-zA-Z0-9]*\\.metadata\\.[a-z][a-zA-Z0-9]*|fk\\.[a-z][a-zA-Z0-9]*\\.dimension\\.[a-zA-Z0-9_]+(\\.label)?|dimension\\.[a-zA-Z0-9_]+(\\.label)?)\\}\\}(\\s*\\|\\s*[a-zA-Z0-9_]+(\\([^)]*\\))?)*\\s*$"
                            },
                            "description":{
                               "type":"string",
@@ -402,20 +492,6 @@
                                  "example":{
                                     "description":"Example value for this field.",
                                     "type":["string","number","boolean","object","array","null"]
-                                 },
-                                 "categories":{
-                                    "type":"array",
-                                    "description":"Logical categories/tags (e.g. ['sales', 'revenue']).",
-                                    "items":{
-                                       "type":"string"
-                                    }
-                                 },
-                                 "synonyms":{
-                                    "type":"array",
-                                    "description":"Optional list of synonyms used in natural language (e.g. 'opportunity', 'sales-case').",
-                                    "items":{
-                                       "type":"string"
-                                    }
                                  }
                               },
                               "additionalProperties":false
@@ -775,34 +851,6 @@
          },
          "additionalProperties":false
       },
-      "context":{
-         "type":"object",
-         "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":"Structured tags for classification and OpenAPI tag emission (e.g. ['crm', 'sales', 'deals']).",
-               "items":{
-                  "type":"string"
-               }
-            },
-            "synonyms":{
-               "type":"array",
-               "description":"Terms users might use in natural language to refer to this datasource or its primary entity.",
-               "items":{
-                  "type":"string"
-               }
-            },
-            "naturalLanguageHints":{
-               "type":"array",
-               "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"
-               }
-            }
-         },
-         "additionalProperties":false
-      },
       "documentStorage":{
          "$ref":"aifabrix://schema/type/document-storage.json",
          "description":"Document storage configuration (optional). Schema is canonical under type/document-storage.json."
@@ -897,13 +945,11 @@
          "additionalProperties":false
       },
     "capabilities":{
-       "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.",
+       "description":"COM v2 capability metadata array. Each object binds an operation key to optional business description and Workforce placeholders (riskLevel, approvalRequired). Trust is computed by Enterprise Compiler — no aiTrustLevel on manifest.",
        "type":"array",
        "items":{
-          "type":"string",
-          "pattern":"^[a-z][a-zA-Z0-9_]*$"
-       },
-       "uniqueItems":true
+          "$ref":"#/$defs/capabilityMetadata"
+       }
     },
       "execution":{
          "type":"object",
@@ -930,6 +976,9 @@
          },
          "additionalProperties":false
       },
+      "executionMetrics":{
+         "$ref":"#/$defs/executionMetricsDefinition"
+      },
       "config":{
          "type":"object",
          "description":"Additional configuration for this datasource.",
@@ -1026,8 +1075,83 @@
                   }
                ]
             }
+         }
+      },
+      {
+         "if":{
+            "properties":{
+               "entityType":{
+                  "const":"serviceContract"
+               }
+            },
+            "required":[
+               "entityType"
+            ]
          },
-         "else":{
+         "then":{
+            "required":[
+               "metadataSchema",
+               "fieldMappings",
+               "exposed"
+            ],
+            "not":{
+               "anyOf":[
+                  {
+                     "required":[
+                        "primaryKey"
+                     ]
+                  },
+                  {
+                     "required":[
+                        "labelKey"
+                     ]
+                  },
+                  {
+                     "required":[
+                        "sync"
+                     ]
+                  },
+                  {
+                     "required":[
+                        "quality"
+                     ]
+                  },
+                  {
+                     "required":[
+                        "validation"
+                     ]
+                  },
+                  {
+                     "required":[
+                        "documentStorage"
+                     ]
+                  },
+                  {
+                     "required":[
+                        "recordStorage"
+                     ]
+                  }
+               ]
+            }
+         }
+      },
+      {
+         "if":{
+            "properties":{
+               "entityType":{
+                  "enum":[
+                     "recordStorage",
+                     "documentStorage",
+                     "vectorStore",
+                     "messageService"
+                  ]
+               }
+            },
+            "required":[
+               "entityType"
+            ]
+         },
+         "then":{
             "required":[
                "metadataSchema",
                "primaryKey",
@@ -1102,6 +1226,64 @@
       }
    ],
    "$defs":{
+      "executionMetricsDefinition":{
+         "type":"object",
+         "description":"Fixed metric expression map evaluated after CIP execution. Each value is a template path (for example {{response.usage.prompt_tokens}}) or dotted path against response and execution context. usageMappings is not supported.",
+         "additionalProperties":false,
+         "properties":{
+            "inputTokens":{
+               "type":"string",
+               "minLength":1,
+               "description":"Expression resolving input/prompt token count."
+            },
+            "outputTokens":{
+               "type":"string",
+               "minLength":1,
+               "description":"Expression resolving completion token count."
+            },
+            "totalTokens":{
+               "type":"string",
+               "minLength":1,
+               "description":"Expression resolving total token count."
+            },
+            "durationMs":{
+               "type":"string",
+               "minLength":1,
+               "description":"Expression resolving operation duration in milliseconds."
+            },
+            "costUsd":{
+               "type":"string",
+               "minLength":1,
+               "description":"Expression resolving estimated cost in USD when provider returns billing metadata."
+            }
+         }
+      },
+      "capabilityMetadata":{
+         "type":"object",
+         "description":"COM v2 capability object — meaning is key + optional description only.",
+         "additionalProperties":false,
+         "required":["key"],
+         "properties":{
+            "key":{
+               "type":"string",
+               "pattern":"^[a-z][a-zA-Z0-9_]*$",
+               "description":"Operation key binding to openapi.operations and/or execution.cip.operations."
+            },
+            "description":{
+               "type":"string",
+               "description":"Business meaning of this capability for agents and AI Trust scoring."
+            },
+            "riskLevel":{
+               "type":"string",
+               "enum":["low","medium","high","critical"],
+               "description":"Workforce risk placeholder — not manifest trust score."
+            },
+            "approvalRequired":{
+               "type":"boolean",
+               "description":"Workforce approval placeholder — not manifest trust score."
+            }
+         }
+      },
       "httpResponseNormalization":{
          "type":"object",
          "description":"Optional GET response shaping for miso-client adapter dicts and native 302 Location follows. Omitted = disabled.",
@@ -1245,6 +1427,31 @@
             "pattern":{
                "type":"string"
             },
+            "enum":{
+               "type":"array",
+               "minItems":1,
+               "maxItems":64,
+               "items":{
+                  "oneOf":[
+                     {
+                        "type":"string"
+                     },
+                     {
+                        "type":"integer"
+                     },
+                     {
+                        "type":"number"
+                     },
+                     {
+                        "type":"boolean"
+                     },
+                     {
+                        "type":"null"
+                     }
+                  ]
+               },
+               "description":"Closed set of allowed scalar values (438.20). Only on string|integer|number|boolean leaves without properties/items."
+            },
             "minimum":{
                "type":"number"
             },
@@ -1389,6 +1596,57 @@
                      ]
                   }
                }
+            },
+            {
+               "if":{
+                  "required":[
+                     "enum"
+                  ],
+                  "properties":{
+                     "enum":{
+                        "type":"array",
+                        "minItems":1
+                     }
+                  }
+               },
+               "then":{
+                  "properties":{
+                     "type":{
+                        "type":"string",
+                        "enum":[
+                           "string",
+                           "number",
+                           "integer",
+                           "boolean"
+                        ]
+                     }
+                  },
+                  "required":[
+                     "type"
+                  ],
+                  "not":{
+                     "anyOf":[
+                        {
+                           "required":[
+                              "properties"
+                           ]
+                        },
+                        {
+                           "required":[
+                              "items"
+                           ]
+                        }
+                     ]
+                  }
+               }
+            },
+            {
+               "not":{
+                  "required":[
+                     "enum",
+                     "pattern"
+                  ]
+               }
             }
          ],
          "additionalProperties":false
@@ -1954,6 +2212,9 @@
             {
                "$ref":"#/$defs/cipStepMap"
             },
+            {
+               "$ref":"#/$defs/cipStepMerge"
+            },
             {
                "$ref":"#/$defs/cipStepFilter"
             },
@@ -2068,6 +2329,16 @@
                     "type":"object",
                     "description":"Optional operation parameters forwarded to datasource execution when source='datasource'.",
                     "additionalProperties":true
+                 },
+                 "skipUnauthorized":{
+                    "type":"boolean",
+                    "default":false,
+                    "description":"When true, skip nested datasource fetch on RBAC denial and continue aggregate orchestration."
+                 },
+                 "accumulate":{
+                    "type":"boolean",
+                    "default":false,
+                    "description":"When true, append fetch items to the pipeline accumulator for a following merge step."
                  },
                   "query":{
                      "type":"object",
@@ -2148,9 +2419,12 @@
                        }
                     },
                     "then":{
-                       "required":[
-                          "datasource"
-                       ]
+                       "properties":{
+                          "datasource":{
+                             "type":"string",
+                             "description":"Target child datasource key. Omitted when parent manifest composition.datasources has two or more entries; runtime resolves via selector input."
+                          }
+                       }
                     }
                   }
                ],
@@ -2235,6 +2509,46 @@
          },
          "additionalProperties":false
       },
+      "cipStepMerge":{
+         "type":"object",
+         "required":[
+            "merge"
+         ],
+         "properties":{
+            "merge":{
+               "type":"object",
+               "description":"Merge accumulated fetch outputs (data transformation only).",
+               "required":[
+                  "strategy"
+               ],
+               "properties":{
+                  "strategy":{
+                     "type":"string",
+                     "enum":[
+                        "object",
+                        "array",
+                        "union",
+                        "byKey"
+                     ],
+                     "description":"Merge strategy for accumulated datasource fetch results."
+                  },
+                  "keyField":{
+                     "type":"string",
+                     "description":"Record key field used by byKey strategy (defaults to id)."
+                  }
+               },
+               "additionalProperties":false
+            },
+            "stepId":{
+               "type":"string",
+               "description":"Optional stable step identifier."
+            },
+            "onError":{
+               "$ref":"#/$defs/cipOnErrorConfig"
+            }
+         },
+         "additionalProperties":false
+      },
       "cipStepMap":{
          "type":"object",
          "required":[