@aifabrix/builder 2.44.5 → 2.45.0

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

@@ -2,17 +2,17 @@
   "$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.",
+  "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.",
         "metadata":{
         "key":"external-datasource-schema",
         "name":"External Data Source Configuration Schema",
         "description":"JSON schema for validating ExternalDataSource configuration files",
-    "version":"2.4.6",
+    "version":"2.4.8",
         "type":"schema",
         "category":"integration",
         "author":"AI Fabrix Team",
         "createdAt":"2024-01-01T00:00:00Z",
-        "updatedAt":"2026-04-20T00:00:00Z",
+        "updatedAt":"2026-05-10T00:00:00Z",
         "compatibility":{
            "minVersion":"1.0.0",
            "maxVersion":"3.0.0",
@@ -183,6 +183,27 @@
               "Added optional fetch.httpResponseNormalization for manifest-driven GET response shaping (302 Location follow, JSON redirect envelopes, nested JSON string URL follow-up)."
            ],
            "breaking":false
+        },
+        {
+           "version":"2.4.8",
+           "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.",
+              "Clarified externalSpec and openapi property descriptions to distinguish vendor spec location from generated or persisted AI-facing OpenAPI material managed by dataplane."
+           ],
+           "breaking":false
+        },
+        {
+           "version":"2.4.7",
+           "date":"2026-05-08T00:00:00Z",
+           "changes":[
+              "externalSpec: optional root object with required type (openapi | mcp) plus documentKey, url, relativePath for vendor or tooling provenance (wizard/import).",
+              "fieldMappings.attributes.<name>: added optional writePath (provider-payload target dot-path), direction (read|write|readwrite), and passthrough (boolean) to support bidirectional mapping authoring; compiler auto-derives writePath from invertible '{{raw.<dot.path>}}' expressions.",
+              "fieldMappings.attributes.<name>: short-form sugar accepted - a string equal to a {{...}} expression is normalized to { expression: '<value>' } at compile time.",
+              "Rejected body and rawBody as aliases for writePath (engine-neutral writePath is the only write-target identifier).",
+              "validate_raw_path: replaced provider-aware traversal with one generic JSON-Schema rule (descend via properties.<seg>; accept remaining path under additionalProperties: true; otherwise emit one actionable error)."
+           ],
+           "breaking":false
         }
      ]
   },
@@ -283,69 +304,131 @@
         "properties":{
            "attributes":{
               "type":"object",
-              "description":"Key = normalized attribute name. Value = transformation configuration.",
+              "description":"Key = normalized attribute name. Value = transformation configuration. Short-form: a string equal to a {{...}} expression is normalized to { expression: '...' } by the compiler.",
               "propertyNames":{
                  "pattern":"^[a-z][a-zA-Z0-9]*$"
               },
               "additionalProperties":{
-                 "type":"object",
-                 "properties":{
-                    "expression":{
+                 "oneOf":[
+                    {
                        "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.",
+                       "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*$"
                     },
-                    "description":{
-                       "type":"string",
-                       "description":"Technical description of the normalized field."
-                    },
-                    "semantic":{
+                    {
                        "type":"object",
-                       "description":"Semantic metadata for AI agents and schema generation.",
                        "properties":{
-                          "title":{
+                          "expression":{
                              "type":"string",
-                             "description":"Human-friendly label for this field."
+                             "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*$"
                           },
                           "description":{
                              "type":"string",
-                             "description":"Business-level description of the field and how it is used."
+                             "description":"Technical description of the normalized field."
                           },
-                          "example":{
-                             "description":"Example value for this field.",
-                             "type":["string","number","boolean","object","array","null"]
+                          "writePath":{
+                             "type":"string",
+                             "description":"Optional. Provider-payload target path for write operations. Dot-separated identifiers (e.g. 'properties.name'). When omitted and the expression is a single, function-free '{{raw.<dot.path>}}', the compiler derives writePath from raw.<dot.path>. When the expression is non-invertible (function chain, fk., dimension., literal, multiple references), writePath is null unless explicitly set.",
+                             "pattern":"^[a-zA-Z_][a-zA-Z0-9_]*(\\.[a-zA-Z_][a-zA-Z0-9_]*)*$",
+                             "maxLength":256
                           },
-                          "categories":{
-                             "type":"array",
-                             "description":"Logical categories/tags (e.g. ['sales', 'revenue']).",
-                             "items":{
-                                "type":"string"
-                             }
+                          "direction":{
+                             "type":"string",
+                             "description":"Optional. Mapping direction. 'readwrite' (default for invertible mappings, including those with explicit writePath), 'read' (default for non-invertible expressions or fields listed in exposed.readonly), 'write' (write-only).",
+                             "enum":["read","write","readwrite"]
                           },
-                          "synonyms":{
-                             "type":"array",
-                             "description":"Optional list of synonyms used in natural language (e.g. 'opportunity', 'sales-case').",
-                             "items":{
-                                "type":"string"
-                             }
+                          "passthrough":{
+                             "type":"boolean",
+                             "description":"Optional. When true, declares an explicit dynamic-keys passthrough into the provider payload. The mapper writes the exposed value verbatim at writePath. Requires writePath. There is no implicit deep-merge of unknown keys; passthrough is the only mechanism for forwarding arbitrary provider-bag keys.",
+                             "default":false
+                          },
+                          "semantic":{
+                             "type":"object",
+                             "description":"Semantic metadata for AI agents and schema generation.",
+                             "properties":{
+                                "title":{
+                                   "type":"string",
+                                   "description":"Human-friendly label for this field."
+                                },
+                                "description":{
+                                   "type":"string",
+                                   "description":"Business-level description of the field and how it is used."
+                                },
+                                "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
+                          },
+                          "lineage":{
+                             "$ref":"#/$defs/fieldMappingLineage"
                           }
                        },
+                       "required":[
+                          "expression"
+                       ],
+                       "not":{
+                          "anyOf":[
+                             {"required":["body"]},
+                             {"required":["rawBody"]}
+                          ]
+                       },
                        "additionalProperties":false
-                    },
-                    "lineage":{
-                       "$ref":"#/$defs/fieldMappingLineage"
                     }
-                 },
-                 "required":[
-                    "expression"
-                 ],
-                 "additionalProperties":false
+                 ]
               }
            }
         },
         "additionalProperties":false
      },
+     "externalSpec":{
+        "type":"object",
+        "description":"Optional datasource-level provenance for the authoritative vendor or tooling API specification: where to fetch or resolve the external OpenAPI document or MCP surface (type, url, relativePath, optional documentKey). Used for import paths and lightweight validation against declared operations—not system-level connectivity (see external-system openapi/mcp). The generated or materialized AI-facing OpenAPI derived from config.openapi.operations is a separate dataplane-managed artifact keyed by openapi.documentKey.",
+        "properties":{
+           "type":{
+              "type":"string",
+              "enum":[
+                 "openapi",
+                 "mcp"
+              ],
+              "description":"Whether this provenance describes an OpenAPI document (openapi) or an MCP server/tooling surface (mcp)."
+           },
+           "documentKey":{
+              "type":"string",
+              "description":"Optional key when external source aligns with openapi.documentKey."
+           },
+           "url":{
+              "type":"string",
+              "description":"Optional absolute URL of the external OpenAPI document or MCP descriptor, depending on type."
+           },
+           "relativePath":{
+              "type":"string",
+              "description":"Optional path relative to the integration bundle root for an external OpenAPI JSON file or MCP artifact, depending on type."
+           }
+        },
+        "required":[
+           "type"
+        ],
+        "additionalProperties":false
+     },
      "exposed":{
         "type":"object",
         "description":"Defines public API exposure contract. v2.4.0 freeze requires exposed.schema as canonical response shape.",
@@ -500,7 +583,7 @@
      },
      "openapi":{
         "type":"object",
-        "description":"OpenAPI-driven connector configuration. Only includes endpoints selected during wizard onboarding. To add more endpoints, run the wizard again.",
+        "description":"OpenAPI-driven connector configuration: authoritative runtime operation bindings and AI-facing documentKey. Operations are selected during wizard onboarding; dataplane may generate or refresh the persisted OpenAPI artifact for that documentKey from these operations when needed. Where the vendor OpenAPI file is obtained from is described by root externalSpec, not this block.",
         "properties":{
            "enabled":{
               "type":"boolean",
@@ -551,8 +634,13 @@
               "type":"boolean",
               "default":false,
               "description":"When true and no explicit operation security scopes are configured, the runtime resolves required RBAC permission as '<resourceType>:<operation>' for each operation (resourceType from the datasource config, default document), matching builder repair RBAC permission names. Explicit operation-level scopes (openapi.operations.*.security/permissions) take precedence and disable autoRbac for that operation."
+           },
+           "operationRef":{
+              "type":"string",
+              "description":"Optional OpenAPI JSON Pointer to the primary operation (e.g. list) used by wizard-generated configs for document resolution."
            }
-        }
+        },
+        "additionalProperties":false
      },
      "validation":{
         "type":"object",
@@ -694,12 +782,17 @@
            },
            "primaryKey":{
               "type":"object",
-              "description":"Optional key/value payload for primary-key focused operation tests.",
+              "description":"Concrete primary-key field values for list/get/mutations, keyed by the same names as the datasource manifest primaryKey array. Authors may supply a subset of PK fields. Optional primaryKey.search (string legacy filter or JSON filter object) resolves a row via list when implemented for the engine.",
               "additionalProperties":true
            },
+           "useCopyForMutations":{
+              "type":"boolean",
+              "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."
+           },
            "scenarios":{
               "type":"array",
-              "description":"Optional operation-specific test scenarios.",
+              "description":"Ordered scenario steps for capacity E2E; execution order is array order (optional order field is a diagnostics hint only).",
               "items":{
                  "type":"object",
                  "required":[
@@ -710,6 +803,11 @@
                        "type":"string",
                        "pattern":"^[a-z][a-zA-Z0-9]*$"
                     },
+                    "enabled":{
+                       "type":"boolean",
+                       "default":true,
+                       "description":"When false, the executor skips this scenario and records an explicit skip (scenario_disabled) in evidence."
+                    },
                     "input":{
                        "type":"object",
                        "additionalProperties":true
@@ -756,15 +854,15 @@
         },
         "additionalProperties":false
      },
-     "capabilities":{
-        "type":"array",
-        "description":"Supported operations list.",
-        "items":{
-           "type":"string",
-           "pattern":"^[a-z][a-zA-Z0-9]*$"
-        },
-        "uniqueItems":true
-     },
+   "capabilities":{
+      "description":"Supported operations list.",
+      "type":"array",
+      "items":{
+         "type":"string",
+         "pattern":"^[a-z][a-zA-Z0-9_]*$"
+      },
+      "uniqueItems":true
+   },
      "execution":{
         "type":"object",
         "description":"Execution engine configuration for this datasource (CIP, Python, or datasource-chaining). CIP is the native declarative mode.",
@@ -1524,6 +1622,29 @@
                  }
               ]
            },
+           "restRuntime":{
+              "type":"object",
+              "description":"Canonical REST path shape for manifest-defined (non-core) operations. Core CRUD keys ignore this block.",
+              "additionalProperties":false,
+              "properties":{
+                 "pathKind":{
+                    "type":"string",
+                    "enum":[
+                       "collection",
+                       "collectionSubresource",
+                       "item",
+                       "itemSubresource"
+                    ]
+                 },
+                 "subpathSegments":{
+                    "type":"array",
+                    "items":{
+                       "type":"string"
+                    },
+                    "description":"Trailing path segments after the resource segment or record identifier (e.g. basic → /{resource}/basic)."
+                 }
+              }
+           },
            "security":{
               "description":"OpenAPI security requirements. Supports object/list/string forms consumed by RBAC coverage validation.",
               "oneOf":[
@@ -1755,6 +1876,15 @@
            "identity":{
               "$ref":"#/$defs/identitySpec"
            },
+           "shape":{
+              "type":"string",
+              "enum":[
+                 "create",
+                 "update",
+                 "delete"
+              ],
+              "description":"Optional semantic classification for this operation when automatic inference from fetch steps (method/path) is insufficient."
+           },
            "steps":{
               "type":"array",
               "minItems":1,

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

@@ -2,17 +2,17 @@
   "$schema":"http://json-schema.org/draft-07/schema#",
   "$id":"aifabrix://schema/external-system.schema.json",
   "title":"AI Fabrix External System Configuration Schema",
-  "description":"Schema for configuring an external system connected to the AI Fabrix Dataplane. This defines authentication, OpenAPI/MCP bindings, field mappings defaults, metadata handling and portal inputs.",
+  "description":"Schema for configuring an external system connected to the AI Fabrix Dataplane. This defines authentication, system-level OpenAPI/MCP connectivity hints (not the datasource-grade vendor contract; see external-datasource.schema.json root externalSpec), field mappings defaults, metadata handling and portal inputs.",
      "metadata":{
      "key":"external-system-schema",
      "name":"External System Configuration Schema",
      "description":"JSON schema for validating ExternalSystem configuration files",
-     "version":"1.6.2",
+    "version":"1.6.3",
      "type":"schema",
      "category":"integration",
      "author":"AI Fabrix Team",
      "createdAt":"2024-01-01T00:00:00Z",
-     "updatedAt":"2026-04-23T00:00:00Z",
+     "updatedAt":"2026-05-10T00:00:00Z",
      "compatibility":{
         "minVersion":"1.4.0",
         "maxVersion":"2.0.0",
@@ -29,6 +29,15 @@
         
      ],
      "changelog":[
+        {
+           "version":"1.6.3",
+           "date":"2026-05-10T00:00:00Z",
+           "changes":[
+              "Documented split: system openapi/mcp objects are connectivity and bootstrap hints (specUrl, serverUrl, documentKey); datasource-level vendor/API provenance belongs in external-datasource externalSpec.",
+              "Declared optional openapi.autoDiscoverEntities (wizard/tooling); tightened openapi and mcp to additionalProperties: false."
+           ],
+           "breaking":false
+        },
         {
            "version":"1.6.2",
            "date":"2026-04-23T00:00:00Z",
@@ -154,7 +163,7 @@
            "mcp",
            "custom"
         ],
-        "description":"Integration type: OpenAPI-driven, MCP-driven, or custom Python connector."
+        "description":"Integration type: openapi and mcp indicate how the system is wired at a high level; per-datasource vendor specifications and import provenance are authored on each ExternalDataSource (external-datasource.schema.json externalSpec), not duplicated as the full contract here."
      },
      "enabled":{
         "type":"boolean",
@@ -235,23 +244,27 @@
      },
      "openapi":{
         "type":"object",
-        "description":"OpenAPI integration configuration",
+        "description":"System-level connectivity and bootstrap hints for OpenAPI-backed systems (e.g. default specUrl for discovery, documentKey alignment with shared registry entries). Not the authoritative per-datasource vendor OpenAPI contract; that is declared on the datasource via externalSpec and validated against imported material.",
         "properties":{
            "documentKey":{
               "type":"string",
-              "description":"Key of the OpenAPI document in the registry"
+              "description":"Optional registry-oriented key associated with this system's default OpenAPI document (wizard/bootstrap)."
            },
            "specUrl":{
               "type":"string",
-              "description":"URL to the OpenAPI specification",
+              "description":"Optional absolute URL to a representative OpenAPI specification for onboarding or tooling (not a substitute for datasource externalSpec).",
               "pattern":"^(http|https)://.*$"
+           },
+           "autoDiscoverEntities":{
+              "type":"boolean",
+              "description":"Optional wizard or tooling hint to discover entities from the system default spec. Not part of the per-datasource vendor contract (see external-datasource externalSpec)."
            }
         },
-        "additionalProperties":true
+        "additionalProperties":false
      },
      "mcp":{
         "type":"object",
-        "description":"Model Context Protocol integration configuration",
+        "description":"System-level MCP connectivity hints (server URL, tool prefix). Not the datasource-level MCP security or operation contract; those live on ExternalDataSource configuration.",
         "properties":{
            "serverUrl":{
               "type":"string",
@@ -264,7 +277,7 @@
               "pattern":"^[a-zA-Z0-9_-]+$"
            }
         },
-        "additionalProperties":true
+        "additionalProperties":false
      },
      "dataSources":{
         "type":"array",

package/lib/schema/infra.parameter.yaml

@@ -11,6 +11,10 @@ defaults:
   userPassword: user123
 # Always ensured on up-infra even when no workspace env.template references these kv:// keys (bootstrap defaults).
 standardUpInfraEnsureKeys:
+  # Docker Postgres admin + Redis — required for admin-secrets / infra compose; not guaranteed in every app env.template
+  - postgres-passwordKeyVault
+  - redis-url
+  - redis-passwordKeyVault
   - databases-miso-controller-0-urlKeyVault
   - databases-miso-controller-0-passwordKeyVault
   - databases-miso-controller-1-urlKeyVault
@@ -113,6 +117,17 @@ parameters:
       vaultSecretName: keycloak-client-secretKeyVault
       notes: Per-app OAuth client secret from Keycloak registration; generated on first ensure.
 
+  # Keycloak events: webhook signature secret used by miso-controller (KEYCLOAK_EVENTS_SECRET).
+  # This must exist on first boot because up-platform runs containers from templates (no prior resolve).
+  - key: keycloak-events-secretKeyVault
+    scope: shared-service
+    generator:
+      type: randomBytes32
+    ensureOn: [upInfra, resolveApp]
+    azure:
+      notes: >-
+        Shared secret for Keycloak event signature verification. Generated on first ensure for local bootstrap.
+
   - key: keycloak-default-passwordKeyVault
     scope: shared-service
     generator:
@@ -236,6 +251,16 @@ parameters:
       notes: >-
         Per-app OAuth client id from controller registration; literal default matches local Keycloak client naming.
 
+  - key: miso-controller-client-secretKeyVault
+    scope: app
+    generator:
+      type: randomBytes32
+    ensureOn: [upInfra, resolveApp]
+    azure:
+      notes: >-
+        Per-app OAuth client secret used by miso-controller for service-to-service auth (MISO_CLIENTSECRET).
+        Generated on first ensure for local bootstrap.
+
   # Dataplane ↔ controller OAuth (builder/dataplane env.template MISO_CLIENTID / MISO_CLIENTSECRET).
   - key: dataplane-client-idKeyVault
     scope: app
@@ -332,7 +357,7 @@ parameters:
     scope: app
     generator:
       type: randomBytes32
-    ensureOn: [resolveApp]
+    ensureOn: [upInfra, resolveApp]
     azure:
       notes: >-
         Prefer {appKey}-secrets-apiKeyVault locally; dataplane shares miso-controller's entry for pipeline Bearer bypass.

package/lib/schema/wizard-config.schema.json

@@ -214,7 +214,7 @@
         },
         "debug": {
           "type": "boolean",
-          "description": "When true, capture detailed generation steps and save to debug.log (dataplane returns debugLog)",
+          "description": "When true, capture detailed generation steps and save to integration/<app>/logs/debug.log (dataplane returns debugLog)",
           "default": false
         }
       }

package/lib/utils/aifabrix-config-dir-walk.js

@@ -0,0 +1,40 @@
+/**
+ * Walk ancestors of `startDir` for `<dir>/.aifabrix/config.yaml`.
+ *
+ * @fileoverview Config directory discovery from cwd
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+
+/**
+ * @param {string} startDir
+ * @param {(p: string) => boolean} existsSyncFn
+ * @returns {string|null} Absolute path to `.aifabrix` directory containing `config.yaml`
+ */
+function findAifabrixConfigDirFromAncestors(startDir, existsSyncFn) {
+  if (!startDir || typeof startDir !== 'string') {
+    return null;
+  }
+  let dir = path.resolve(startDir);
+  const maxSteps = 64;
+  for (let i = 0; i < maxSteps; i += 1) {
+    const candidate = path.join(dir, '.aifabrix', 'config.yaml');
+    if (existsSyncFn(candidate)) {
+      return path.join(dir, '.aifabrix');
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  return null;
+}
+
+module.exports = {
+  findAifabrixConfigDirFromAncestors
+};

package/lib/utils/aifabrix-runtime-config-dir.js

@@ -3,8 +3,8 @@
  * Shared by `paths.getConfigDirForPaths` and `config.getConfigDir` (no circular imports).
  *
  * When `AIFABRIX_HOME` is set to the POSIX home (builder-server pattern) but the real
- * config file is under `~/.aifabrix/config.yaml`, use that nested directory so
- * `secrets.local.yaml` and auth config stay beside `config.yaml`.
+ * config file is under `~/.aifabrix/config.yaml`, use that nested directory.
+ * With no env override, walks up from cwd for `<ancestor>/.aifabrix/config.yaml`, else `~/.aifabrix`.
  *
  * Relative `AIFABRIX_HOME` / `AIFABRIX_CONFIG` values are anchored to the user home
  * directory (not `process.cwd()`), so a mistaken `aifabrix-training` does not become
@@ -21,6 +21,7 @@
 const { existsSync } = require('../internal/fs-real-sync');
 const path = require('path');
 const os = require('os');
+const { findAifabrixConfigDirFromAncestors } = require('./aifabrix-config-dir-walk');
 
 /**
  * @returns {string}
@@ -102,6 +103,23 @@ function resolveAifabrixConfigEnvPath(raw) {
   return resolveAifabrixHomeLikePath(raw);
 }
 
+/**
+ * When neither `AIFABRIX_CONFIG` nor `AIFABRIX_HOME` is set, look for `<ancestor>/.aifabrix/config.yaml`
+ * walking up from `process.cwd()`. Skipped under Jest so suites do not pick up the workspace config.
+ *
+ * @returns {string|null} Directory containing `config.yaml`, or null
+ */
+function findAifabrixConfigDirWalkingUpFromCwd() {
+  if (process.env.NODE_ENV === 'test' || process.env.JEST_WORKER_ID !== undefined) {
+    return null;
+  }
+  try {
+    return findAifabrixConfigDirFromAncestors(process.cwd(), existsSync);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * @returns {string} Absolute directory containing `config.yaml`
  */
@@ -122,11 +140,16 @@ function getAifabrixRuntimeConfigDir() {
     }
     return homeDir;
   }
+  const fromCwd = findAifabrixConfigDirWalkingUpFromCwd();
+  if (fromCwd) {
+    return fromCwd;
+  }
   return path.join(safeHomedir(), '.aifabrix');
 }
 
 module.exports = {
   getAifabrixRuntimeConfigDir,
   resolveAifabrixHomeLikePath,
-  resolveAifabrixConfigEnvPath
+  resolveAifabrixConfigEnvPath,
+  findAifabrixConfigDirWalkingUpFromCwd
 };

package/lib/utils/app-config-resolver.js

@@ -12,7 +12,28 @@
 'use strict';
 
 const path = require('path');
-const fs = require('fs');
+const defaultFs = require('fs');
+const { nodeFs } = require('../internal/node-fs');
+
+const realFs = nodeFs();
+
+/**
+ * Prefer real disk when `fs` is not mocked (avoids `jest.mock('fs')` bleed in other suites).
+ * Use `require('fs')` when Jest replaced it so tests with virtual file stores still work.
+ *
+ * @returns {Pick<import('fs'), 'existsSync'|'renameSync'>}
+ */
+function getResolverFs() {
+  if (
+    typeof jest !== 'undefined' &&
+    defaultFs.existsSync &&
+    typeof jest.isMockFunction === 'function' &&
+    jest.isMockFunction(defaultFs.existsSync)
+  ) {
+    return defaultFs;
+  }
+  return realFs;
+}
 
 /**
  * Resolves path to application config file (application.yaml, application.json, or legacy variables.yaml).
@@ -23,6 +44,7 @@ const fs = require('fs');
  * @throws {Error} If no config file found
  */
 function resolveApplicationConfigPath(appPath) {
+  const fs = getResolverFs();
   if (!appPath || typeof appPath !== 'string') {
     throw new Error('App path is required and must be a string');
   }
@@ -59,6 +81,7 @@ const RBAC_NAMES = ['rbac.yaml', 'rbac.yml', 'rbac.json'];
  * @returns {string|null} Absolute path to RBAC file, or null if none exist
  */
 function resolveRbacPath(appPath) {
+  const fs = getResolverFs();
   if (!appPath || typeof appPath !== 'string') {
     throw new Error('App path is required and must be a string');
   }