@aifabrix/builder 2.57.0 → 2.59.0

package/lib/programmatic/builder-api-startup.js

@@ -0,0 +1,51 @@
+/** @fileoverview Await SDK bootstrap and token proof before accepting requests. */
+'use strict';
+
+const { initializeBuilderMisoRuntime, closeBuilderMisoRuntime } = require('./builder-miso-runtime');
+const { ensureBuilderApiRuntimeConfigDir } = require('./builder-api-runtime-config');
+
+/** @param {Object} server HTTP server @returns {Promise<void>} Listener closed */
+function closeServer(server) {
+  return new Promise(resolve => {
+    server.close(resolve);
+    server.closeAllConnections();
+  });
+}
+
+/**
+ * @param {Object} [options] Startup dependencies
+ * @returns {Promise<{server: Object, close: Function}>} Running application
+ */
+async function startBuilderApi(options = {}) {
+  ensureBuilderApiRuntimeConfigDir();
+  let server;
+  let closing;
+  const close = () => {
+    if (!closing) {
+      closing = Promise.all([server ? closeServer(server) : undefined, closeBuilderMisoRuntime()]);
+    }
+    return closing;
+  };
+  try {
+    const runtime = await initializeBuilderMisoRuntime(options.initSecrets);
+    await runtime.health();
+    const createServer = options.createServer || require('./builder-api-server').createBuilderApiServer;
+    server = createServer(options.port ?? Number(process.env.PORT || 3005));
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.once('listening', () => {
+        server.removeListener('error', reject); resolve();
+      });
+    });
+    return { server, close };
+  } catch (error) {
+    await close().catch(() => {});
+    // Only our allowlisted health errors can cross the process boundary.
+    const failure = new Error('Builder API startup failed: Miso application runtime or authentication unavailable');
+    failure.statusCode = 503;
+    if (error?.statusCode === 503 && error?.errorType?.startsWith('/Errors/miso_')) throw error;
+    throw failure;
+  }
+}
+
+module.exports = { startBuilderApi };

package/lib/programmatic/builder-miso-runtime.js

@@ -0,0 +1,167 @@
+/**
+ * Builder's process-owned SDK runtime and application-token health check.
+ * @fileoverview SDK owns providers, secrets, renewal and connections.
+ */
+'use strict';
+
+const { validateMisoApplicationToken } = require('../api/miso-health.api');
+let activeRuntime;
+
+/** @param {string} code Safe category @returns {Error} Service-unavailable error */
+function runtimeError(code) {
+  const messages = {
+    miso_authentication_failed: 'Miso application authentication failed',
+    miso_timeout: 'Miso application token check timed out',
+    miso_unreachable: 'Miso Controller is unavailable',
+    miso_runtime_unavailable: 'Miso application runtime is unavailable'
+  };
+  return Object.assign(new Error(messages[code]), {
+    statusCode: 503, code, errorType: `/Errors/${code}`
+  });
+}
+
+/** @param {unknown} error SDK error @returns {string} Safe category */
+function failureCode(error) {
+  const status = error?.statusCode || error?.errorResponse?.status || error?.response?.status;
+  if ([401, 403].includes(status) || error?.code === 'authorization-denied') {
+    return 'miso_authentication_failed';
+  }
+  if (['ECONNABORTED', 'ETIMEDOUT', 'ERR_CANCELED'].includes(error?.code)) {
+    return 'miso_timeout';
+  }
+  return 'miso_unreachable';
+}
+
+/** SDK resource ownership and fail-closed application state. */
+class RuntimeController {
+  /** @param {Object} runtime SDK runtime */
+  constructor(runtime) {
+    this.runtime = runtime;
+    this.unsubscribe = runtime.onInvalidated(reason => {
+      this.unavailable = reason === 'authorization-denied'
+        ? 'miso_authentication_failed' : 'miso_runtime_unavailable';
+      this.abort?.abort();
+    });
+  }
+
+  /** @returns {void} Throws when the SDK snapshot is unavailable */
+  assertAvailable() {
+    if (this.unavailable) throw runtimeError(this.unavailable);
+    try {
+      this.runtime.secrets.get('');
+    } catch {
+      throw runtimeError(this.unavailable || 'miso_runtime_unavailable');
+    }
+  }
+
+  /** @returns {Object} Initialized client */
+  getClient() {
+    this.assertAvailable();
+    return this.runtime.client;
+  }
+
+  /** @returns {Promise<void>} Idempotent cleanup */
+  close() {
+    if (!this.closing) {
+      this.unavailable = this.unavailable || 'miso_runtime_unavailable';
+      this.abort?.abort();
+      this.unsubscribe();
+      this.closing = Promise.resolve().then(() => this.runtime.close()).catch(() => {
+        throw runtimeError('miso_runtime_unavailable');
+      });
+    }
+    return this.closing;
+  }
+
+  /** @returns {Promise<void>} Fresh, coalesced token proof; never caches success */
+  health() {
+    this.assertAvailable();
+    if (!this.pending) {
+      this.abort = new AbortController();
+      this.pending = runProbe(this.runtime.client, this.abort,
+        () => this.assertAvailable(), code => {
+          this.unavailable = code;
+          void this.close().catch(() => {});
+        }, () => {
+          this.pending = undefined;
+        });
+    }
+    return this.pending;
+  }
+}
+
+/** @param {Object} runtime SDK runtime @returns {RuntimeController} Consumer controls */
+function createRuntimeController(runtime) {
+  return new RuntimeController(runtime);
+}
+
+/**
+ * Coalesce until transport settles, including SDK-owned token acquisition after a deadline.
+ * @param {Object} client SDK client
+ * @param {AbortController} abort Cancellation
+ * @param {Function} assertAvailable Runtime guard
+ * @param {Function} invalidate Terminal rejection
+ * @param {Function} settled Release in-flight work
+ * @returns {Promise<void>} Bounded health result
+ */
+function runProbe(client, abort, assertAvailable, invalidate, settled) {
+  let timer;
+  const deadline = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      abort.abort(); reject(runtimeError('miso_timeout'));
+    }, 3000);
+  });
+  const request = validateMisoApplicationToken(client, abort.signal).then(() => {
+    assertAvailable();
+  }).catch(error => {
+    let code = failureCode(error);
+    try {
+      assertAvailable();
+    } catch (unavailable) {
+      code = unavailable.code;
+    }
+    if (code === 'miso_authentication_failed') invalidate(code);
+    throw runtimeError(code);
+  }).finally(() => {
+    clearTimeout(timer); settled();
+  });
+  return Promise.race([request, deadline]);
+}
+
+/** @param {Function} [init] SDK factory for tests @returns {Promise<Object>} Runtime controls */
+async function initializeBuilderMisoRuntime(init) {
+  if (activeRuntime) throw runtimeError('miso_runtime_unavailable');
+  const factory = init || require('@aifabrix/miso-client/bootstrap').initSecrets;
+  try {
+    activeRuntime = createRuntimeController(await factory());
+    return activeRuntime;
+  } catch {
+    throw runtimeError('miso_runtime_unavailable');
+  }
+}
+
+/** @returns {Object} Active guarded runtime */
+function getBuilderMisoRuntime() {
+  if (!activeRuntime) throw runtimeError('miso_runtime_unavailable');
+  return activeRuntime;
+}
+
+/** @returns {Promise<void>} Close and release process-owned runtime */
+async function closeBuilderMisoRuntime() {
+  const current = activeRuntime;
+  activeRuntime = undefined;
+  await current?.close();
+}
+
+/** @param {boolean} [ready] Readiness response @returns {Promise<Object>} Healthy payload */
+async function checkBuilderMisoHealth(ready = false) {
+  await getBuilderMisoRuntime().health();
+  return ready
+    ? { status: 'ready', dataplaneUrl: process.env.DATAPLANE_URL || null }
+    : { status: 'ok' };
+}
+
+module.exports = {
+  initializeBuilderMisoRuntime, getBuilderMisoRuntime, closeBuilderMisoRuntime,
+  checkBuilderMisoHealth, createRuntimeController
+};

package/lib/programmatic/openapi-descriptions.js

@@ -213,14 +213,14 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
     tags: ['repository']
   },
   health: {
-    summary: 'Liveness probe',
+    summary: 'Application-token health probe',
     description:
-      'Returns ok when the builder-api process is running. Portal availability probe. Empty channel catalog is not a down signal. No authentication.',
+      'Returns ok only after Miso accepts the application client token. Returns 503 when authentication, runtime validity or connectivity fails. No caller authentication; user credentials cannot substitute for the application token.',
     tags: ['infra']
   },
   ready: {
     summary: 'Readiness probe',
-    description: 'Returns ready with configured dataplaneUrl. Does not verify Dataplane connectivity in V1.',
+    description: 'Verifies the application client token with Miso and returns ready with configured dataplaneUrl. Returns 503 for an unusable token or unavailable Miso runtime. Does not verify Dataplane connectivity.',
     tags: ['infra']
   },
   getBuilderHelp: {

package/lib/programmatic/openapi-schema-descriptions-core.js

@@ -113,11 +113,11 @@ const CORE_SCHEMA_DESCRIPTIONS = {
     deleted: 'Always true when the workspace folder was removed.'
   },
   HealthData: {
-    _schema: 'Liveness probe payload when the builder-api process is running.',
-    status: 'Always ok for successful liveness checks.'
+    _schema: 'Health payload after Miso accepts the application client token.',
+    status: 'Always ok after successful application-token validation.'
   },
   ReadyData: {
-    _schema: 'Readiness probe payload; does not verify Dataplane connectivity in V1.',
+    _schema: 'Readiness after Miso application-token validation; does not verify Dataplane connectivity.',
     status: 'Always ready when the service accepts traffic.',
     dataplaneUrl: 'Configured dev Dataplane base URL, or null when unset.'
   },

package/lib/programmatic/openapi-spec.js

@@ -68,7 +68,8 @@ function buildStandardErrorResponses() {
     408: problemResponseContent('Request exceeded capability timeout.'),
     409: problemResponseContent('Workspace lock held by another in-flight operation.'),
     413: problemResponseContent('Request body exceeds MAX_BODY_BYTES.'),
-    500: problemResponseContent('Unexpected server error.')
+    500: problemResponseContent('Unexpected server error.'),
+    503: problemResponseContent('Miso application authentication failed, token check timed out, or runtime/Controller unavailable. Safe failure category appears in type.')
   };
 }
 

package/lib/programmatic/route-handler-map.js

@@ -8,6 +8,7 @@
 
 'use strict';
 
+const { checkBuilderMisoHealth } = require('./builder-miso-runtime');
 const { buildContext } = require('./route-handlers-context');
 const { listSystems, createSystem, getSystemManifest, deleteSystem } = require('./workspace-ops');
 const { persistSuppliedOpenApi } = require('./persist-supplied-openapi');
@@ -230,8 +231,8 @@ const HANDLER_MAP = {
   getRepositoryStatus: (params, auth) => getRepositoryStatus(buildContext(auth, params.systemKey)),
   runRepositoryDispatchPipeline: (params, auth, body) =>
     runRepositoryDispatchPipeline(buildContext(auth, params.systemKey), body),
-  health: () => ({ status: 'ok' }),
-  ready: () => ({ status: 'ready', dataplaneUrl: process.env.DATAPLANE_URL || null }),
+  health: () => checkBuilderMisoHealth(),
+  ready: () => checkBuilderMisoHealth(true),
   getBuilderHelp: (_params, _auth, _body, query) => handleGetBuilderHelp(query || {}),
   getEvidenceMetadata: (params, auth) =>
     getEvidenceMetadata(buildContext(auth, '_evidence'), params.roleKey),

package/lib/schema/environment-deploy-request.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/environment-deploy-request.schema.json",
+  "$id": "aifabrix://schema/environment-deploy-request.schema.json",
   "title": "Environment Deploy Request",
   "description": "Request body for POST /api/v1/environments/{envKey}/deploy",
   "type": "object",

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

@@ -7,12 +7,12 @@
          "key":"external-datasource-schema",
          "name":"External Data Source Configuration Schema",
          "description":"JSON schema for validating ExternalDataSource configuration files",
-     "version":"2.9.11",
+     "version":"2.9.12",
          "type":"schema",
          "category":"integration",
          "author":"AI Fabrix Team",
          "createdAt":"2024-01-01T00:00:00Z",
-         "updatedAt":"2026-08-30T00:00:00Z",
+         "updatedAt":"2026-09-17T00:00:00Z",
          "compatibility":{
             "minVersion":"1.0.0",
             "maxVersion":"3.0.0",
@@ -31,6 +31,15 @@
          "external-system.schema.json"
       ],
       "changelog":[
+         {
+            "version":"2.9.12",
+            "date":"2026-09-17T00:00:00Z",
+            "changes":[
+               "Added cipOperation.shape enum value 'upsert' (manifest-declared only; composes the datasource's standard create + update via fetch.source datasource; existence-resolved branch with fail-closed per-action permissions). COM writeShape and published x-ai-intent gain the same value. 543 O-SHAPE updated.",
+               "Added optional sync.enabled (default true) to disable scheduled, manual, webhook, and syncBridge synchronization without disabling datasource reads. Added @monthly as the authoring default for new full-set schedules; existing schedule-less manifests remain valid and are not migrated. CIP $defs unchanged (543 visual N/A)."
+            ],
+            "breaking":false
+         },
          {
             "version":"2.9.11",
             "date":"2026-08-30T00:00:00Z",
@@ -862,6 +871,11 @@
          "type":"object",
          "description":"Record synchronization rules.",
          "properties":{
+            "enabled":{
+               "type":"boolean",
+               "description":"Whether synchronization is enabled for this datasource. False blocks scheduled, manual, webhook, and syncBridge synchronization while preserving normal datasource access.",
+               "default":true
+            },
             "mode":{
                "type":"string",
                "enum":[
@@ -874,6 +888,7 @@
             "schedule":{
                "type":"string",
                "description":"Cron for full-set (sync all) jobs. Supports 5-field cron syntax or @hourly/@daily/@weekly/@monthly.",
+               "default":"@monthly",
                "pattern":"^(@hourly|@daily|@weekly|@monthly|([0-9*/,-]+\\s+){4}[0-9*/,-]+)$"
             },
             "batchSize":{
@@ -2547,9 +2562,10 @@
                "enum":[
                   "create",
                   "update",
-                  "delete"
+                  "delete",
+                  "upsert"
                ],
-               "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)."
+               "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). shape upsert is never inferred: the operation must compose exactly this datasource's standard create and update operations as two fetch.source 'datasource' steps; at execution the generic CIP branch resolves record existence from validation.repeatingValues reject fields and runs exactly one half, enforcing that half's permissions fail-closed (no cross-action fallback)."
             },
             "steps":{
                "type":"array",
@@ -3467,4 +3483,3 @@
    },
    "additionalProperties":false
  }
- 

package/lib/schema/infra-parameter.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://aifabrix.dev/schemas/infra-parameter.schema.json",
+  "$id": "aifabrix://schema/infra-parameter.schema.json",
   "title": "Infra parameter catalog",
   "type": "object",
   "required": ["version", "parameters"],

package/lib/schema/infra.parameter.yaml

@@ -98,7 +98,8 @@ parameters:
     category: Redis
     sensitive: true
     valueSource: providerOutput
-    requiredOnSystemOnboarding: true
+    # Not needed at first-time install: Redis is provisioned later (env deploy / TA), not at marketplace bootstrap.
+    requiredOnSystemOnboarding: false
     scope: system
     generator:
       type: literal

package/lib/schema/infrastructure-schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/infrastructure-schema.json",
+  "$id": "aifabrix://schema/infrastructure-schema.json",
   "title": "AI Fabrix Installation Infrastructure Manifest",
   "description": "Committed, non-secret environment-infra.json for an installation workspace under infrastructure/<resource-group>/. Secrets appear only as valueFromEnv references.",
   "metadata": {
@@ -12,7 +12,7 @@
     "category": "infrastructure",
     "author": "AI Fabrix Team",
     "createdAt": "2024-01-01T00:00:00Z",
-    "updatedAt": "2026-09-16T00:00:00Z",
+    "updatedAt": "2026-09-17T00:00:00Z",
     "compatibility": {
       "minVersion": "2.0.0",
       "maxVersion": "2.0.0",
@@ -34,7 +34,7 @@
           "Replaced the environment-configuration shape with the installation workspace manifest (environment-infra.json).",
           "Removed smtp without replacement.",
           "Covers every Marketplace template parameter and output with source/description metadata; secure parameters are valueFromEnv references.",
-          "Added vendor, workspace subscription/tenant, acrName, default-off allowMyIp, licenseEdition, onboardingMode, tenant activation, deployment and application variable catalog sections."
+          "Added vendor, workspace subscription/tenant, acrName, acrAuth (auto|mi|credentials, deprecated admin alias, resolved effective mode), deployRoleAssignments restore metadata, default-off allowMyIp, licenseEdition, onboardingMode, tenant activation, deployment and application variable catalog sections."
         ]
       },
       {
@@ -366,6 +366,44 @@
         }
       }
     },
+    "acrAuth": {
+      "type": "object",
+      "required": [
+        "value",
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "enum": [
+            "auto",
+            "mi",
+            "credentials",
+            "admin"
+          ],
+          "description": "Requested image-pull auth; admin is a deprecated alias for credentials."
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "effective": {
+          "enum": [
+            "mi",
+            "credentials"
+          ],
+          "description": "Pull auth resolved by the last infra run (non-secret)."
+        }
+      }
+    },
     "allowMyIp": {
       "type": "object",
       "required": [
@@ -469,6 +507,7 @@
         "entraIdClientSecret",
         "entraIdTenantId",
         "licenseEdition",
+        "capacityProfile",
         "onboardingMode",
         "misoImageTag",
         "keycloakImageTag"
@@ -926,6 +965,65 @@
             },
             "required": {
               "type": "boolean"
+            },
+            "restoreValue": {
+              "type": [
+                "string",
+                "boolean",
+                "number",
+                "object",
+                "array"
+              ],
+              "description": "Value to restore when credential mode no longer applies."
+            },
+            "restoreSource": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "deployRegistryRoleAssignment": {
+          "type": "object",
+          "required": [
+            "value",
+            "source",
+            "description"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "value": {
+              "type": [
+                "string",
+                "boolean",
+                "number",
+                "object",
+                "array"
+              ]
+            },
+            "source": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": {
+              "type": "boolean"
+            },
+            "restoreValue": {
+              "type": [
+                "string",
+                "boolean",
+                "number",
+                "object",
+                "array"
+              ],
+              "description": "Value to restore when credential mode no longer applies."
+            },
+            "restoreSource": {
+              "type": "string",
+              "minLength": 1
             }
           }
         },
@@ -1190,6 +1288,98 @@
               "type": "boolean"
             }
           }
+        },
+        "moriLicensePublicKey": {
+          "type": "object",
+          "required": [
+            "value",
+            "source",
+            "description"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "value": {
+              "type": [
+                "string",
+                "boolean",
+                "number",
+                "object",
+                "array"
+              ]
+            },
+            "source": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": {
+              "type": "boolean"
+            }
+          }
+        },
+        "moriLicenseIssuer": {
+          "type": "object",
+          "required": [
+            "value",
+            "source",
+            "description"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "value": {
+              "type": [
+                "string",
+                "boolean",
+                "number",
+                "object",
+                "array"
+              ]
+            },
+            "source": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": {
+              "type": "boolean"
+            }
+          }
+        },
+        "capacityProfile": {
+          "type": "object",
+          "required": [
+            "value",
+            "source",
+            "description"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "value": {
+              "enum": [
+                "s",
+                "m",
+                "l",
+                "xl"
+              ]
+            },
+            "source": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": {
+              "type": "boolean"
+            }
+          }
         }
       }
     },
@@ -1274,6 +1464,12 @@
         },
         "portalUrl": {
           "$ref": "#/definitions/output"
+        },
+        "azureOpenAiCreated": {
+          "$ref": "#/definitions/output"
+        },
+        "azureOpenAiSkipReason": {
+          "$ref": "#/definitions/output"
         }
       }
     },
@@ -1611,6 +1807,7 @@
       "then": {
         "required": [
           "acrName",
+          "acrAuth",
           "allowMyIp",
           "preset",
           "parameters",

package/lib/schema/installation-environment.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/installation-environment.schema.json",
+  "$id": "aifabrix://schema/installation-environment.schema.json",
   "title": "AI Fabrix Installation Environment File",
   "description": "Committed, non-secret infrastructure/<resource-group>/environment-dev|tst|pro.json. Inherited shared values name environment-infra.json as their source; request is the exact non-secret Miso deploy projection.",
   "metadata": {

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

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/wizard-config.schema.json",
+  "$id": "aifabrix://schema/wizard-config.schema.json",
   "title": "AI Fabrix Wizard Configuration Schema",
   "description": "Schema for validating wizard.yaml configuration files for headless external system creation",
   "type": "object",