@aifabrix/builder 2.45.0 → 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/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/protection.schema.json

@@ -0,0 +1,374 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "aifabrix://schema/protection.schema.json",
+  "title": "AI Fabrix Protection Manifest Schema",
+  "description": "Schema for Protection manifests deployed to the AI Fabrix Dataplane. A protection binds to exactly one deployed external datasource (spec.datasourceKey) and declares how synced records project principal-to-dimension-value grants during datasource sync. Distinct from datasource validation-rule 'when' in contracts/schemas/rule.schema.json: rules[].when here gates assignment and runtime using the local identity snapshot (User, Group, UserGroup) and subject dimension state only.",
+  "metadata": {
+    "key": "protection-schema",
+    "name": "Protection Manifest Schema",
+    "description": "JSON schema for validating Protection manifest documents (apiVersion/kind/metadata/spec envelope)",
+    "version": "1.0.0",
+    "type": "schema",
+    "category": "integration",
+    "author": "AI Fabrix Team",
+    "createdAt": "2026-05-18T00:00:00Z",
+    "updatedAt": "2026-05-18T00:00:00Z",
+    "compatibility": {
+      "minVersion": "1.0.0",
+      "maxVersion": "1.0.0",
+      "deprecated": false
+    },
+    "tags": [
+      "schema",
+      "protection",
+      "dataplane",
+      "integration",
+      "validation",
+      "abac",
+      "dimensions",
+      "projection"
+    ],
+    "dependencies": [
+      "external-datasource.schema.json"
+    ],
+    "changelog": [
+      {
+        "version": "1.0.0",
+        "date": "2026-05-18T00:00:00Z",
+        "changes": [
+          "Initial production schema for Protection manifests (401.1 dataplane baseline).",
+          "Envelope: apiVersion dataplane.aifabrix.ai/v1, kind Protection, metadata.key/displayName, spec.enabled/datasourceKey/mode/rules.",
+          "spec.datasourceKey scopes runtime projection to one deployed datasource; do not use legacy field name 'datasource'.",
+          "spec.mode: replaceForSource — per protection, per source record, replace prior projection outputs for that record.",
+          "rules[].principal: user (field) or group (field|expression); exactly one of field or expression per principal block.",
+          "rules[].grants: required dimensionKey and valueExpression; optional valueType only when Dimension.valueType is both (catalog resolved at validate/projection).",
+          "rules[].when: optional groups.requireAny (Group.key) and/or dimensions.requireAll (subject preconditions); additionalProperties false on when/groups/dimensions.",
+          "Expression roots (v1): metadata.*, fk.<name>.metadata.*, fk.<name>.dimension.* (one-hop FK only).",
+          "principalRef storage uses normalized User.id / Group.id after projection (401.3); not validated structurally in this schema."
+        ],
+        "breaking": false
+      }
+    ]
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["apiVersion", "kind", "metadata", "spec"],
+  "properties": {
+    "apiVersion": {
+      "type": "string",
+      "const": "dataplane.aifabrix.ai/v1",
+      "description": "API version of the Protection manifest envelope. Must be dataplane.aifabrix.ai/v1 for v1 tooling and upload APIs."
+    },
+    "kind": {
+      "type": "string",
+      "const": "Protection",
+      "description": "Resource kind discriminator. Must be Protection."
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Identity and display metadata for this protection. metadata.key is globally unique in v1 and is the protection key used in APIs, lineage tables, and builder CLI.",
+      "required": ["key", "displayName"],
+      "properties": {
+        "key": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "description": "Unique protection key (globally unique in v1). Lowercase alphanumeric and hyphens; used as protectionKey in storage and APIs.",
+          "examples": ["hubspot-country-sales", "hr-persons-protection"]
+        },
+        "displayName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "description": "Human-readable name shown in builder and operator UIs.",
+          "examples": ["HubSpot Country Sales Access", "HR Persons Protection"]
+        }
+      }
+    },
+    "spec": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Protection specification. spec.enabled is the canonical enable flag; the dataplane denormalizes it to ProtectionManifest.enabled for indexed queries.",
+      "required": ["enabled", "datasourceKey", "mode", "rules"],
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Canonical enable flag. When false, the protection is stored but not selected for projection during datasource sync (indexed enabled column mirrors this value on upload)."
+        },
+        "datasourceKey": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "description": "Deployed external datasource key this protection applies to. Runtime projection runs only during sync of this datasource. Must match ExternalDataSource.key. Do not use the field name 'datasource'.",
+          "examples": ["hubspot-companies", "hubspot-deals", "hr-persons"]
+        },
+        "mode": {
+          "type": "string",
+          "enum": ["replaceForSource"],
+          "description": "Projection replacement mode (v1). replaceForSource: for each source record on datasourceKey, replace all dynamic values and grants previously emitted by this protection for that sourceRecordId (per protection, not global)."
+        },
+        "rules": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Projection rules. rules[].key is unique within this protection only; storage identity is (protectionKey, projectionRuleKey).",
+          "items": {
+            "$ref": "#/$defs/protectionRule"
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "protectionRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "One projection rule: resolve principals from synced records, optionally gate on subject when, emit dimension value grants.",
+      "required": ["key", "principal", "grants"],
+      "properties": {
+        "key": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "description": "Rule key unique within this protection (projectionRuleKey in lineage).",
+          "examples": ["sales-country-users", "hr-manager-department", "europe-region-group"]
+        },
+        "when": {
+          "$ref": "#/$defs/ruleWhen",
+          "description": "Optional subject preconditions evaluated against local identity snapshot and subject dimensions. Omitted = rule always eligible (subject to principal resolution only). Not the same as datasource validation-rule when."
+        },
+        "principal": {
+          "$ref": "#/$defs/principal",
+          "description": "How to resolve the principal (user or group) from each synced record on datasourceKey."
+        },
+        "grants": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Dimension value grants to attach to the resolved principal for each qualifying record.",
+          "items": {
+            "$ref": "#/$defs/grant"
+          }
+        }
+      }
+    },
+    "ruleWhen": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "description": "Optional rule-level gate. If both groups and dimensions are present, all blocks must pass (AND). Evaluated at projection (401.3) and re-checked at runtime (401.4).",
+      "properties": {
+        "groups": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Group membership gate. For user principals: grants are not persisted unless the user is in at least one requireAny group (UserGroup). Group-target rules typically ignore when.groups unless product overrides.",
+          "required": ["requireAny"],
+          "properties": {
+            "requireAny": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "description": "Group.key values from the local identity snapshot; subject must be a member of at least one.",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128
+              },
+              "examples": [["Manager"], ["Sales", "SalesManager"]]
+            }
+          }
+        },
+        "dimensions": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Subject dimension precondition: the subject must already hold all listed dimension values before grants from this rule are applied.",
+          "required": ["requireAll"],
+          "properties": {
+            "requireAll": {
+              "type": "array",
+              "minItems": 1,
+              "description": "All entries must be satisfied (AND). Gates subject state, not record fields.",
+              "items": {
+                "$ref": "#/$defs/whenDimensionRequireAll"
+              }
+            }
+          }
+        }
+      }
+    },
+    "whenDimensionRequireAll": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["dimensionKey", "values"],
+      "properties": {
+        "dimensionKey": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "Dimension catalog key (Dimension.key).",
+          "examples": ["department", "sensitivity", "country"]
+        },
+        "values": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "Required dimension value strings for the subject at evaluation time.",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512
+          },
+          "examples": [["restricted"], ["FI", "SE"]]
+        }
+      }
+    },
+    "principal": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Principal resolution from the syncing datasource record. Exactly one of field or expression must be set. Resolved principalRef at projection must be User.id or Group.id (never display name or raw email as canonical ref).",
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["user", "group"],
+          "description": "Principal kind. user: resolve via field on the record to a User row. group: resolve via field or expression to a Group row (Group.key or Group.id)."
+        },
+        "field": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "description": "Record field path (scalar or array path such as metadata.teamMembers[].email). Required for type=user. Allowed for type=group when resolving from record data.",
+          "examples": ["metadata.managerEmail", "metadata.teamMembers[].email"]
+        },
+        "expression": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "description": "Template expression resolving to a group identifier (typically Group.key). Common for type=group. Allowed roots: metadata.*, fk.<name>.metadata.*, fk.<name>.dimension.* (one-hop FK only).",
+          "examples": [
+            "Sales {{fk.country.metadata.iso3}} Users",
+            "Sales Nordics Users"
+          ]
+        }
+      },
+      "oneOf": [
+        {
+          "required": ["field"],
+          "not": {
+            "required": ["expression"]
+          }
+        },
+        {
+          "required": ["expression"],
+          "not": {
+            "required": ["field"]
+          }
+        }
+      ]
+    },
+    "grant": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Grant of one dimension value to the resolved principal. effective valueType is resolved from Dimension.valueType in the synced catalog when Dimension.valueType is static or dynamic; grant.valueType is required only when catalog valueType is both.",
+      "required": ["dimensionKey", "valueExpression"],
+      "properties": {
+        "dimensionKey": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "Dimension catalog key (Dimension.key). Must exist in the synced dimension catalog.",
+          "examples": ["country", "region", "department", "project"]
+        },
+        "valueExpression": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "description": "Expression evaluated per record/FK context to produce the dimension value string. static dimensions: value must exist in DimensionValue catalog. dynamic dimensions: value may be upserted into dynamic_dimension_values at projection.",
+          "examples": [
+            "{{fk.country.metadata.iso2}}",
+            "europe",
+            "{{metadata.departmentCode}}",
+            "{{metadata.projectCode}}"
+          ]
+        },
+        "labelExpression": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "description": "Optional human-readable label for dynamic dimension values (projection stores label when valueType resolves to dynamic)."
+        },
+        "valueType": {
+          "type": "string",
+          "enum": ["static", "dynamic"],
+          "description": "Disambiguates static vs dynamic assignment when Dimension.valueType in the catalog is both. Omit when catalog valueType is static or dynamic."
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "apiVersion": "dataplane.aifabrix.ai/v1",
+      "kind": "Protection",
+      "metadata": {
+        "key": "hubspot-country-sales",
+        "displayName": "HubSpot Country Sales Access"
+      },
+      "spec": {
+        "enabled": true,
+        "datasourceKey": "hubspot-companies",
+        "mode": "replaceForSource",
+        "rules": [
+          {
+            "key": "sales-country-users",
+            "principal": {
+              "type": "group",
+              "expression": "Sales {{fk.country.metadata.iso3}} Users"
+            },
+            "grants": [
+              {
+                "dimensionKey": "country",
+                "valueExpression": "{{fk.country.metadata.iso2}}",
+                "labelExpression": "{{fk.country.metadata.name}}"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "apiVersion": "dataplane.aifabrix.ai/v1",
+      "kind": "Protection",
+      "metadata": {
+        "key": "hr-persons-protection",
+        "displayName": "HR Persons Protection"
+      },
+      "spec": {
+        "enabled": true,
+        "datasourceKey": "hr-persons",
+        "mode": "replaceForSource",
+        "rules": [
+          {
+            "key": "hr-manager-department",
+            "when": {
+              "groups": {
+                "requireAny": ["Manager"]
+              }
+            },
+            "principal": {
+              "type": "user",
+              "field": "metadata.managerEmail"
+            },
+            "grants": [
+              {
+                "dimensionKey": "department",
+                "valueExpression": "{{metadata.departmentCode}}"
+              }
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}