@nocobase/flow-engine 2.1.0-beta.14 → 2.1.0-beta.16

package/lib/models/flowModel.d.ts

@@ -13,6 +13,7 @@ import { FlowContext, FlowModelContext, FlowRuntimeContext } from '../flowContex
 import { FlowEngine } from '../flowEngine';
 import type { ActionDefinition, ArrayElementType, CreateModelOptions, CreateSubModelOptions, DefaultStructure, FlowDefinitionOptions, FlowModelMeta, FlowModelOptions, ModelConstructor, ParamObject, ParentFlowModel, PersistOptions, ResolveUseResult, StepParams } from '../types';
 import { IModelComponentProps, ReadonlyModelProps } from '../types';
+import type { MenuProps } from 'antd';
 import { ModelActionRegistry } from '../action-registry/ModelActionRegistry';
 import { ModelEventRegistry } from '../event-registry/ModelEventRegistry';
 import { GlobalFlowRegistry } from '../flow-registry/GlobalFlowRegistry';
@@ -21,7 +22,6 @@ import { FlowSettingsOpenOptions } from '../flowSettings';
 import type { ScheduleOptions } from '../scheduler/ModelOperationScheduler';
 import type { DispatchEventOptions, EventDefinition } from '../types';
 import { ForkFlowModel } from './forkFlowModel';
-import type { MenuProps } from 'antd';
 type BaseMenuItem = NonNullable<MenuProps['items']>[number];
 type MenuLeafItem = Exclude<BaseMenuItem, {
     children: MenuProps['items'];
@@ -239,6 +239,7 @@ export declare class FlowModel<Structure extends DefaultStructure = DefaultStruc
      * 使用 lodash debounce 避免频繁调用
      */
     private _rerunLastAutoRun;
+    private resetAutoRunState;
     /**
      * 通用事件分发钩子：开始
      * 子类可覆盖；beforeRender 事件可通过抛出 FlowExitException 提前终止。

package/lib/models/flowModel.js

@@ -56,25 +56,33 @@ var import_reactive = require("@formily/reactive");
 var import_lodash = __toESM(require("lodash"));
 var import_react = __toESM(require("react"));
 var import_secure = require("uid/secure");
-var import_StepRequiredSettingsDialog = require("../components/settings/wrappers/contextual/StepRequiredSettingsDialog");
-var import_StepSettingsDialog = require("../components/settings/wrappers/contextual/StepSettingsDialog");
 var import_emitter = require("../emitter");
 var import_InstanceFlowRegistry = require("../flow-registry/InstanceFlowRegistry");
 var import_flowContext = require("../flowContext");
 var import_utils = require("../utils");
-var import_lib = require("antd/lib");
+var import_antd = require("antd");
+var import__ = require("..");
 var import_ModelActionRegistry = require("../action-registry/ModelActionRegistry");
 var import_utils2 = require("../components/subModel/utils");
 var import_ModelEventRegistry = require("../event-registry/ModelEventRegistry");
 var import_GlobalFlowRegistry = require("../flow-registry/GlobalFlowRegistry");
 var import_forkFlowModel = require("./forkFlowModel");
-var import__ = require("..");
 var _flowContext;
 const classActionRegistries = /* @__PURE__ */ new WeakMap();
 const classEventRegistries = /* @__PURE__ */ new WeakMap();
 const modelMetas = /* @__PURE__ */ new WeakMap();
 const modelGlobalRegistries = /* @__PURE__ */ new WeakMap();
 const classMenuExtensions = /* @__PURE__ */ new WeakMap();
+async function loadOpenStepSettingsDialog() {
+  const mod = await import("../components/settings/wrappers/contextual/StepSettingsDialog");
+  return mod.openStepSettingsDialog;
+}
+__name(loadOpenStepSettingsDialog, "loadOpenStepSettingsDialog");
+async function loadOpenRequiredParamsStepFormDialog() {
+  const mod = await import("../components/settings/wrappers/contextual/StepRequiredSettingsDialog");
+  return mod.openRequiredParamsStepFormDialog;
+}
+__name(loadOpenRequiredParamsStepFormDialog, "loadOpenRequiredParamsStepFormDialog");
 var ModelRenderMode = /* @__PURE__ */ ((ModelRenderMode2) => {
   ModelRenderMode2["ReactElement"] = "reactElement";
   ModelRenderMode2["RenderFunction"] = "renderFunction";
@@ -183,10 +191,13 @@ const _FlowModel = class _FlowModel {
       if (changed.type === "set" && import_lodash.default.isEqual(changed.value, changed.oldValue)) {
         return;
       }
+      const hasLastAutoRun = !!this._lastAutoRunParams;
       if (this.flowEngine) {
         this.invalidateFlowCache("beforeRender");
       }
-      this._rerunLastAutoRun();
+      if (hasLastAutoRun) {
+        this._rerunLastAutoRun();
+      }
       this.forks.forEach((fork) => {
         fork.rerender();
       });
@@ -674,6 +685,11 @@ const _FlowModel = class _FlowModel {
     }, "isMatch");
     return Array.from(allFlows.values()).filter(isMatch);
   }
+  resetAutoRunState() {
+    var _a, _b;
+    (_b = (_a = this._rerunLastAutoRun) == null ? void 0 : _a.cancel) == null ? void 0 : _b.call(_a);
+    this._lastAutoRunParams = null;
+  }
   /**
    * 通用事件分发钩子：开始
    * 子类可覆盖；beforeRender 事件可通过抛出 FlowExitException 提前终止。
@@ -763,6 +779,7 @@ const _FlowModel = class _FlowModel {
             }));
             return () => {
               var _a3, _b3;
+              renderTarget.resetAutoRunState();
               if (typeof renderTarget.onUnmount === "function") {
                 renderTarget.onUnmount();
               }
@@ -1058,7 +1075,7 @@ const _FlowModel = class _FlowModel {
    * @param {string} stepKey 步骤的唯一标识符
    * @returns {void}
    */
-  openStepSettingsDialog(flowKey, stepKey) {
+  async openStepSettingsDialog(flowKey, stepKey) {
     var _a;
     const flow = this.getFlow(flowKey);
     const step = (_a = flow == null ? void 0 : flow.steps) == null ? void 0 : _a[stepKey];
@@ -1069,7 +1086,8 @@ const _FlowModel = class _FlowModel {
     const ctx = new import_flowContext.FlowRuntimeContext(this, flowKey, "settings");
     (0, import_utils.setupRuntimeContextSteps)(ctx, flow.steps, this, flowKey);
     ctx.defineProperty("currentStep", { value: step });
-    return (0, import_StepSettingsDialog.openStepSettingsDialog)({
+    const openStepSettingsDialog = await loadOpenStepSettingsDialog();
+    return openStepSettingsDialog({
       model: this,
       flowKey,
       stepKey,
@@ -1084,7 +1102,8 @@ const _FlowModel = class _FlowModel {
    * @returns {Promise<any>} 返回表单提交的值
    */
   async configureRequiredSteps(dialogWidth, dialogTitle) {
-    return (0, import_StepRequiredSettingsDialog.openRequiredParamsStepFormDialog)({
+    const openRequiredParamsStepFormDialog = await loadOpenRequiredParamsStepFormDialog();
+    return openRequiredParamsStepFormDialog({
       model: this,
       dialogWidth,
       dialogTitle
@@ -1303,7 +1322,7 @@ const _ErrorFlowModel = class _ErrorFlowModel extends FlowModel {
     this.errorMessage = msg;
   }
   render() {
-    return /* @__PURE__ */ import_react.default.createElement(import_lib.Typography.Text, { type: "danger" }, this.errorMessage);
+    return /* @__PURE__ */ import_react.default.createElement(import_antd.Typography.Text, { type: "danger" }, this.errorMessage);
   }
 };
 __name(_ErrorFlowModel, "ErrorFlowModel");

package/lib/types.d.ts

@@ -303,6 +303,52 @@ export interface CreateModelOptions {
     delegateToParent?: boolean;
     [key: string]: any;
 }
+/**
+ * FlowModel loader result.
+ * Supports returning the model constructor directly, a default export, or a module object containing the named export.
+ */
+export type FlowModelLoaderResult = ModelConstructor | {
+    default?: ModelConstructor;
+    [key: string]: unknown;
+} | Record<string, unknown>;
+/**
+ * FlowModel loader function.
+ */
+export type FlowModelLoader = () => Promise<FlowModelLoaderResult>;
+/**
+ * FlowModel loader entry (normalized internal form).
+ */
+export interface FlowModelLoaderEntry {
+    loader: FlowModelLoader;
+    extends?: string[];
+}
+/**
+ * FlowModel loader input (user-facing form for registerModelLoaders).
+ * The `extends` field accepts flexible formats that will be normalized to `string[]` at registration time.
+ */
+export interface FlowModelLoaderInput {
+    loader: FlowModelLoader;
+    extends?: string | ModelConstructor | (string | ModelConstructor)[];
+}
+/**
+ * FlowModel loader entry map (normalized internal form).
+ */
+export type FlowModelLoaderMap = Record<string, FlowModelLoaderEntry>;
+/**
+ * FlowModel loader input map (user-facing form for registerModelLoaders).
+ */
+export type FlowModelLoaderInputMap = Record<string, FlowModelLoaderInput>;
+/**
+ * Batch ensure result.
+ */
+export interface EnsureBatchResult {
+    requested: string[];
+    loaded: string[];
+    failed: Array<{
+        name: string;
+        error?: unknown;
+    }>;
+}
 export interface IFlowModelRepository<T extends FlowModel = FlowModel> {
     findOne(query: Record<string, any>): Promise<Record<string, any> | null>;
     save(model: T, options?: {

package/lib/utils/runjsTemplateCompat.js

@@ -527,8 +527,8 @@ function extractUsedCtxLibKeys(code) {
 }
 __name(extractUsedCtxLibKeys, "extractUsedCtxLibKeys");
 function injectEnsureLibsPreamble(code) {
-  if (!CTX_LIBS_MARKER_RE.test(code)) return code;
   if (ENSURE_LIBS_MARKER_RE.test(code)) return code;
+  if (!CTX_LIBS_MARKER_RE.test(code)) return code;
   const keys = extractUsedCtxLibKeys(code);
   if (!keys.length) return code;
   return `/* __runjs_ensure_libs */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/flow-engine",
-  "version": "2.1.0-beta.14",
+  "version": "2.1.0-beta.16",
   "private": false,
   "description": "A standalone flow engine for NocoBase, managing workflows, models, and actions.",
   "main": "lib/index.js",
@@ -8,8 +8,8 @@
   "dependencies": {
     "@formily/antd-v5": "1.x",
     "@formily/reactive": "2.x",
-    "@nocobase/sdk": "2.1.0-beta.14",
-    "@nocobase/shared": "2.1.0-beta.14",
+    "@nocobase/sdk": "2.1.0-beta.16",
+    "@nocobase/shared": "2.1.0-beta.16",
     "ahooks": "^3.7.2",
     "axios": "^1.7.0",
     "dayjs": "^1.11.9",
@@ -37,5 +37,5 @@
   ],
   "author": "NocoBase Team",
   "license": "Apache-2.0",
-  "gitHead": "cd55c9a14596d834c30c83a82c38f1f719f7aac4"
+  "gitHead": "b9a191705a440a336c85d82fd877fdf152bec70f"
 }

package/src/__tests__/flow-engine.test.ts

@@ -189,4 +189,170 @@ describe('FlowEngine', () => {
       expect(mounted?.uid).toBe('c3');
     });
   });
+
+  describe('getSubclassesOfAsync', () => {
+    it('should return async-loaded subclasses matching extends declaration', async () => {
+      class AsyncSubModelD extends BaseModel {}
+      class AsyncSubModelE extends BaseModel {}
+
+      engine.registerModelLoaders({
+        AsyncSubModelD: {
+          extends: 'BaseModel',
+          loader: async () => ({ AsyncSubModelD }),
+        },
+        AsyncSubModelE: {
+          extends: 'BaseModel',
+          loader: async () => ({ AsyncSubModelE }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel);
+
+      // Sync-registered subclasses
+      expect(result.has('SubModelA')).toBe(true);
+      expect(result.has('SubModelB')).toBe(true);
+      expect(result.has('SubModelC')).toBe(true);
+      // Async-loaded subclasses
+      expect(result.has('AsyncSubModelD')).toBe(true);
+      expect(result.has('AsyncSubModelE')).toBe(true);
+      // Base class excluded
+      expect(result.has('BaseModel')).toBe(false);
+    });
+
+    it('should merge sync-registered and async-loaded subclasses', async () => {
+      class AsyncSubModel extends BaseModel {}
+
+      engine.registerModelLoaders({
+        AsyncSubModel: {
+          extends: 'BaseModel',
+          loader: async () => ({ AsyncSubModel }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync('BaseModel');
+
+      // Sync: SubModelA, SubModelB, SubModelC
+      expect(result.has('SubModelA')).toBe(true);
+      expect(result.has('SubModelB')).toBe(true);
+      expect(result.has('SubModelC')).toBe(true);
+      // Async
+      expect(result.has('AsyncSubModel')).toBe(true);
+      expect(result.size).toBe(4);
+    });
+
+    it('should support extends as string array (multiple parents)', async () => {
+      class AnotherBase extends FlowModel {}
+      class MultiParentModel extends BaseModel {}
+
+      engine.registerModels({ AnotherBase });
+      engine.registerModelLoaders({
+        MultiParentModel: {
+          extends: ['BaseModel', 'AnotherBase'],
+          loader: async () => ({ MultiParentModel }),
+        },
+      });
+
+      const resultBase = await engine.getSubclassesOfAsync(BaseModel);
+      expect(resultBase.has('MultiParentModel')).toBe(true);
+
+      // Also found by AnotherBase (even though actual inheritance is from BaseModel, not AnotherBase)
+      // The extends declaration triggers loading, but isInheritedFrom validation will exclude it from AnotherBase results
+      const resultAnother = await engine.getSubclassesOfAsync(AnotherBase);
+      expect(resultAnother.has('MultiParentModel')).toBe(false);
+    });
+
+    it('should support extends as ModelConstructor', async () => {
+      class AsyncCtorSubModel extends BaseModel {}
+
+      engine.registerModelLoaders({
+        AsyncCtorSubModel: {
+          extends: BaseModel,
+          loader: async () => ({ AsyncCtorSubModel }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel);
+      expect(result.has('AsyncCtorSubModel')).toBe(true);
+    });
+
+    it('should validate actual inheritance and warn on mismatch', async () => {
+      class UnrelatedModel extends FlowModel {}
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      engine.registerModelLoaders({
+        UnrelatedModel: {
+          extends: 'BaseModel',
+          loader: async () => ({ UnrelatedModel }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel);
+      expect(result.has('UnrelatedModel')).toBe(false);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("declares extends 'BaseModel' but does not actually inherit from it"),
+      );
+
+      warnSpy.mockRestore();
+    });
+
+    it('should resolve base class from loaders if not in _modelClasses', async () => {
+      const freshEngine = new FlowEngine();
+
+      class LazyBase extends FlowModel {}
+      class LazySub extends LazyBase {}
+
+      freshEngine.registerModelLoaders({
+        LazyBase: {
+          loader: async () => ({ LazyBase }),
+        },
+        LazySub: {
+          extends: 'LazyBase',
+          loader: async () => ({ LazySub }),
+        },
+      });
+
+      const result = await freshEngine.getSubclassesOfAsync('LazyBase');
+      expect(result.has('LazySub')).toBe(true);
+      expect(result.size).toBe(1);
+    });
+
+    it('should return empty Map when base class cannot be found', async () => {
+      const result = await engine.getSubclassesOfAsync('NonExistentModel');
+      expect(result.size).toBe(0);
+    });
+
+    it('should support filter parameter on both sync and async sources', async () => {
+      class FilteredAsyncModel extends BaseModel {}
+
+      engine.registerModelLoaders({
+        FilteredAsyncModel: {
+          extends: 'BaseModel',
+          loader: async () => ({ FilteredAsyncModel }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel, (_ModelClass, name) => name.startsWith('SubModelA'));
+
+      // Only SubModelA passes the filter (SubModelB, SubModelC, FilteredAsyncModel excluded)
+      expect(result.has('SubModelA')).toBe(true);
+      expect(result.has('SubModelB')).toBe(false);
+      expect(result.has('SubModelC')).toBe(false);
+      expect(result.has('FilteredAsyncModel')).toBe(false);
+    });
+
+    it('should not include loaders without extends declaration', async () => {
+      class NoExtendsModel extends BaseModel {}
+
+      engine.registerModelLoaders({
+        NoExtendsModel: {
+          loader: async () => ({ NoExtendsModel }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel);
+      // Only sync-registered subclasses; NoExtendsModel has no extends, so not discovered
+      expect(result.has('NoExtendsModel')).toBe(false);
+      expect(result.has('SubModelA')).toBe(true);
+    });
+  });
 });

package/src/__tests__/flowEngine.modelLoaders.test.ts

@@ -0,0 +1,245 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { FlowEngine } from '../flowEngine';
+import { ErrorFlowModel, FlowModel } from '../models';
+import type { IFlowModelRepository } from '../types';
+
+class MockFlowModelRepository implements IFlowModelRepository {
+  findOneResult: any = null;
+  save = vi.fn(async (model: FlowModel) => ({ success: true, uid: model.uid }));
+
+  async findOne() {
+    return this.findOneResult ? JSON.parse(JSON.stringify(this.findOneResult)) : null;
+  }
+
+  async destroy() {
+    return true;
+  }
+
+  async move() {}
+
+  async duplicate() {
+    return null;
+  }
+}
+
+describe('FlowEngine model loaders', () => {
+  let engine: FlowEngine;
+  let repo: MockFlowModelRepository;
+
+  beforeEach(() => {
+    engine = new FlowEngine();
+    repo = new MockFlowModelRepository();
+    engine.setModelRepository(repo);
+  });
+
+  it('resolves explicit and meta-default model trees before synchronous creation', async () => {
+    class ParentModel extends FlowModel {}
+    class ChildModel extends FlowModel {}
+    class DefaultChildModel extends FlowModel {}
+
+    ParentModel.define({
+      createModelOptions: {
+        subModels: {
+          defaultChild: {
+            use: 'DefaultChildModel',
+          },
+        },
+      },
+    });
+
+    const parentLoader = vi.fn(async () => ({ ParentModel }));
+    const childLoader = vi.fn(async () => ({ ChildModel }));
+    const defaultChildLoader = vi.fn(async () => ({ DefaultChildModel }));
+
+    engine.registerModelLoaders({
+      ParentModel: { loader: parentLoader },
+      ChildModel: { loader: childLoader },
+      DefaultChildModel: { loader: defaultChildLoader },
+    });
+
+    const model = await engine.loadOrCreateModel({
+      uid: 'parent-model',
+      use: 'ParentModel',
+      subModels: {
+        child: {
+          use: 'ChildModel',
+        },
+      },
+    });
+
+    expect(model).toBeInstanceOf(ParentModel);
+    expect(model?.subModels.child).toBeInstanceOf(ChildModel);
+    expect(model?.subModels.defaultChild).toBeInstanceOf(DefaultChildModel);
+    expect(parentLoader).toHaveBeenCalledTimes(1);
+    expect(childLoader).toHaveBeenCalledTimes(1);
+    expect(defaultChildLoader).toHaveBeenCalledTimes(1);
+  });
+
+  it('resolves repository-loaded model trees before loadModel creates instances', async () => {
+    class RepoRootModel extends FlowModel {}
+    class RepoChildModel extends FlowModel {}
+
+    const rootLoader = vi.fn(async () => ({ RepoRootModel }));
+    const childLoader = vi.fn(async () => ({ RepoChildModel }));
+
+    engine.registerModelLoaders({
+      RepoRootModel: { loader: rootLoader },
+      RepoChildModel: { loader: childLoader },
+    });
+
+    repo.findOneResult = {
+      uid: 'repo-root',
+      use: 'RepoRootModel',
+      subModels: {
+        child: {
+          use: 'RepoChildModel',
+        },
+      },
+    };
+
+    const model = await engine.loadModel({ uid: 'repo-root' });
+
+    expect(model).toBeInstanceOf(RepoRootModel);
+    expect(model?.subModels.child).toBeInstanceOf(RepoChildModel);
+    expect(rootLoader).toHaveBeenCalledTimes(1);
+    expect(childLoader).toHaveBeenCalledTimes(1);
+  });
+
+  it('supports async model creation and async getters', async () => {
+    class AsyncRootModel extends FlowModel {}
+    class AsyncChildModel extends FlowModel {}
+
+    const rootLoader = vi.fn(async () => ({ AsyncRootModel }));
+    const childLoader = vi.fn(async () => ({ AsyncChildModel }));
+
+    engine.registerModelLoaders({
+      AsyncRootModel: { loader: rootLoader },
+      AsyncChildModel: { loader: childLoader },
+    });
+
+    const rootClass = await engine.getModelClassAsync('AsyncRootModel');
+    const classes = await engine.getModelClassesAsync();
+    const model = await engine.createModelAsync({
+      uid: 'async-root',
+      use: 'AsyncRootModel',
+      subModels: {
+        child: {
+          use: 'AsyncChildModel',
+        },
+      },
+    });
+
+    expect(rootClass).toBe(AsyncRootModel);
+    expect(classes.get('AsyncRootModel')).toBe(AsyncRootModel);
+    expect(classes.get('AsyncChildModel')).toBe(AsyncChildModel);
+    expect(model).toBeInstanceOf(AsyncRootModel);
+    expect(model.subModels.child).toBeInstanceOf(AsyncChildModel);
+    expect(rootLoader).toHaveBeenCalledTimes(1);
+    expect(childLoader).toHaveBeenCalledTimes(1);
+  });
+
+  it('createModelAsync degrades unresolved loader failures to ErrorFlowModel', async () => {
+    const invalidLoader = vi.fn(async () => ({ notAModel: {} }));
+
+    engine.registerModelLoaders({
+      BrokenRootModel: { loader: invalidLoader as any },
+    });
+
+    const model = await engine.createModelAsync({
+      uid: 'broken-root',
+      use: 'BrokenRootModel',
+    });
+
+    expect(model).toBeInstanceOf(ErrorFlowModel);
+    expect(invalidLoader).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps loader resolution idempotent across resolveModelTree and flow settings preload', async () => {
+    class RuntimeResolvedModel extends FlowModel {}
+    class DesignResolvedModel extends FlowModel {}
+
+    const runtimeLoader = vi.fn(async () => ({ RuntimeResolvedModel }));
+    const designLoader = vi.fn(async () => ({ DesignResolvedModel }));
+
+    engine.registerModelLoaders({
+      RuntimeResolvedModel: { loader: runtimeLoader },
+      DesignResolvedModel: { loader: designLoader },
+    });
+
+    await engine.resolveModelTree({
+      use: 'RuntimeResolvedModel',
+    });
+
+    const firstPreload = await engine.preloadModelLoaders();
+    const secondPreload = await engine.preloadModelLoaders();
+
+    expect(runtimeLoader).toHaveBeenCalledTimes(1);
+    expect(designLoader).toHaveBeenCalledTimes(1);
+    expect(firstPreload.loaded).toContain('DesignResolvedModel');
+    expect(firstPreload.loaded).not.toContain('RuntimeResolvedModel');
+    expect(secondPreload.loaded).toHaveLength(0);
+    expect(secondPreload.failed).toHaveLength(0);
+  });
+
+  it('picks up newly registered loaders after preload has already completed', async () => {
+    class FirstModel extends FlowModel {}
+    class SecondModel extends FlowModel {}
+
+    const firstLoader = vi.fn(async () => ({ FirstModel }));
+    const secondLoader = vi.fn(async () => ({ SecondModel }));
+
+    engine.registerModelLoaders({
+      FirstModel: { loader: firstLoader },
+    });
+
+    await engine.preloadModelLoaders();
+    expect(firstLoader).toHaveBeenCalledTimes(1);
+    expect(engine.getModelClass('FirstModel')).toBe(FirstModel);
+
+    engine.registerModelLoaders({
+      SecondModel: { loader: secondLoader },
+    });
+
+    const result = await engine.preloadModelLoaders();
+
+    expect(secondLoader).toHaveBeenCalledTimes(1);
+    expect(result.loaded).toContain('SecondModel');
+    expect(engine.getModelClass('SecondModel')).toBe(SecondModel);
+  });
+
+  it('degrades unresolved loader failures to ErrorFlowModel instead of crashing runtime creation', async () => {
+    class ParentModel extends FlowModel {}
+
+    const parentLoader = vi.fn(async () => ({ ParentModel }));
+    const invalidChildLoader = vi.fn(async () => ({ notAModel: {} }));
+
+    engine.registerModelLoaders({
+      ParentModel: { loader: parentLoader },
+      BrokenChildModel: { loader: invalidChildLoader as any },
+    });
+
+    const model = await engine.loadOrCreateModel({
+      uid: 'parent-with-broken-child',
+      use: 'ParentModel',
+      subModels: {
+        child: {
+          use: 'BrokenChildModel',
+        },
+      },
+    });
+
+    expect(model).toBeInstanceOf(ParentModel);
+    expect(model?.subModels.child).toBeInstanceOf(ErrorFlowModel);
+    expect(parentLoader).toHaveBeenCalledTimes(1);
+    expect(invalidChildLoader).toHaveBeenCalledTimes(1);
+  });
+});