@nocobase/flow-engine 2.1.0-alpha.12 → 2.1.0-alpha.13

package/src/FlowSchemaRegistry.ts

@@ -1,1799 +0,0 @@
-/**
- * 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 _ from 'lodash';
-import type {
-  ActionDefinition,
-  FlowActionSchemaContribution,
-  FlowFieldBindingContextContribution,
-  FlowFieldBindingContribution,
-  FlowFieldModelCompatibility,
-  FlowSchemaBundleDocument,
-  FlowSchemaBundleNode,
-  FlowSchemaBundleSlotCatalog,
-  FlowSchemaContextEdge,
-  FlowSchemaDocs,
-  FlowDynamicHint,
-  FlowSchemaInventoryContribution,
-  FlowJsonSchema,
-  FlowModelSchemaPatch,
-  FlowModelSchemaContribution,
-  FlowModelMeta,
-  FlowSchemaCoverage,
-  FlowSchemaDetail,
-  FlowSchemaDocument,
-  FlowModelSchemaExposure,
-  FlowSchemaPublicDocument,
-  FlowSubModelSlotSchema,
-  ModelConstructor,
-  StepDefinition,
-} from './types';
-import {
-  buildFieldModelCompatibility,
-  matchesFieldBinding,
-  normalizeFieldBindingContextContribution,
-  normalizeFieldBindingContribution,
-  type RegisteredFieldBinding,
-  type RegisteredFieldBindingContext,
-} from './flow-schema-registry/fieldBinding';
-import {
-  applyModelSchemaPatch,
-  matchesDescendantSchemaPatch,
-  normalizeSubModelSlots,
-  resolveChildSchemaPatch,
-} from './flow-schema-registry/modelPatches';
-import { inferParamsSchemaFromUiSchema, type StepSchemaResolution } from './flow-schema-registry/schemaInference';
-import {
-  JSON_SCHEMA_DRAFT_07,
-  buildSkeletonFromSchema,
-  collectAllowedUses,
-  createFlowHint,
-  deepFreezePlainGraph,
-  hashString,
-  mergeSchemas,
-  normalizeSchemaDocs,
-  normalizeSchemaHints,
-  normalizeStringArray,
-  stableStringify,
-  toSchemaTitle,
-} from './flow-schema-registry/utils';
-
-export type RegisteredActionSchema = {
-  name: string;
-  title?: string;
-  definition?: ActionDefinition;
-  schema?: FlowJsonSchema;
-  docs: FlowSchemaDocs;
-  coverage: FlowSchemaCoverage;
-  dynamicHints: FlowDynamicHint[];
-};
-
-export type RegisteredModelSchema = {
-  use: string;
-  modelClass?: ModelConstructor;
-  stepParamsSchema?: FlowJsonSchema;
-  flowRegistrySchema?: FlowJsonSchema;
-  subModelSlots?: Record<string, FlowSubModelSlotSchema>;
-  flowRegistrySchemaPatch?: FlowJsonSchema;
-  title?: string;
-  examples: any[];
-  docs: FlowSchemaDocs;
-  skeleton?: any;
-  dynamicHints: FlowDynamicHint[];
-  coverage: FlowSchemaCoverage;
-  exposure: FlowModelSchemaExposure;
-  abstract: boolean;
-  allowDirectUse: boolean;
-  suggestedUses: string[];
-};
-
-type ModelPatchContribution = {
-  patch: FlowModelSchemaPatch;
-  source: FlowSchemaCoverage['source'];
-  strict?: boolean;
-};
-
-export class FlowSchemaRegistry {
-  private readonly modelSchemas = new Map<string, RegisteredModelSchema>();
-  private readonly actionSchemas = new Map<string, RegisteredActionSchema>();
-  private readonly fieldBindingContexts = new Map<string, RegisteredFieldBindingContext>();
-  private readonly fieldBindings = new Map<string, RegisteredFieldBinding[]>();
-  private readonly resolvedModelCache = new Map<string, RegisteredModelSchema>();
-  private readonly modelSnapshotSchemaCache = new Map<string, FlowJsonSchema>();
-  private readonly compactModelSnapshotSchemaCache = new Map<string, FlowJsonSchema>();
-  private readonly modelSchemaHashCache = new Map<string, string>();
-  private readonly compactModelSchemaHashCache = new Map<string, string>();
-  private readonly modelDocumentCache = new Map<string, FlowSchemaDocument>();
-  private readonly modelLocalDynamicHintsCache = new Map<string, FlowDynamicHint[]>();
-  private readonly publicModelDocumentCache = new Map<string, FlowSchemaPublicDocument>();
-  private readonly publicTreeRoots = new Set<string>();
-  private readonly slotUseExpansions = new Map<string, string[]>();
-
-  private invalidateDerivedCaches() {
-    this.resolvedModelCache.clear();
-    this.modelSnapshotSchemaCache.clear();
-    this.compactModelSnapshotSchemaCache.clear();
-    this.modelSchemaHashCache.clear();
-    this.compactModelSchemaHashCache.clear();
-    this.modelDocumentCache.clear();
-    this.modelLocalDynamicHintsCache.clear();
-    this.publicModelDocumentCache.clear();
-  }
-
-  registerAction(action: ActionDefinition | ({ name: string } & Partial<ActionDefinition>)) {
-    const name = String(action?.name || '').trim();
-    if (!name) return;
-
-    const previous = this.actionSchemas.get(name);
-    const inferred = inferParamsSchemaFromUiSchema(name, action.uiSchema as any, `actions.${name}`);
-    const mergedSchema = mergeSchemas(action.paramsSchema || inferred.schema, action.paramsSchemaPatch);
-    const explicit = !!action.paramsSchema || !!action.paramsSchemaPatch;
-    const coverageStatus: FlowSchemaCoverage['status'] = explicit
-      ? inferred.schema
-        ? 'mixed'
-        : 'manual'
-      : inferred.coverage;
-    const docs = normalizeSchemaDocs({
-      ...previous?.docs,
-      ...action.schemaDocs,
-      examples: action.schemaDocs?.examples || previous?.docs?.examples,
-      dynamicHints: [...(previous?.docs?.dynamicHints || []), ...(action.schemaDocs?.dynamicHints || [])],
-    });
-
-    this.actionSchemas.set(name, {
-      name,
-      title: action.title,
-      definition: action as ActionDefinition,
-      schema: mergedSchema,
-      coverage: {
-        status: mergedSchema ? coverageStatus : 'unresolved',
-        source: previous?.coverage.source || 'official',
-        strict: previous?.coverage.strict,
-      },
-      docs,
-      dynamicHints: normalizeSchemaHints([
-        ...(previous?.dynamicHints || []),
-        ...(inferred.hints || []),
-        ...(docs.dynamicHints || []),
-      ]),
-    });
-    this.invalidateDerivedCaches();
-  }
-
-  registerActions(actions: Record<string, ActionDefinition>) {
-    for (const action of Object.values(actions || {})) {
-      this.registerAction(action);
-    }
-  }
-
-  registerActionContribution(contribution: FlowActionSchemaContribution) {
-    const name = String(contribution?.name || '').trim();
-    if (!name) return;
-
-    const previous = this.actionSchemas.get(name);
-    const docs = normalizeSchemaDocs({
-      ...previous?.docs,
-      ...contribution.docs,
-      examples: contribution.docs?.examples || previous?.docs?.examples,
-      dynamicHints: [...(previous?.docs?.dynamicHints || []), ...(contribution.docs?.dynamicHints || [])],
-      commonPatterns: contribution.docs?.commonPatterns || previous?.docs?.commonPatterns,
-      antiPatterns: contribution.docs?.antiPatterns || previous?.docs?.antiPatterns,
-      minimalExample:
-        contribution.docs?.minimalExample !== undefined
-          ? contribution.docs.minimalExample
-          : previous?.docs?.minimalExample,
-    });
-    this.actionSchemas.set(name, {
-      name,
-      title: contribution.title || previous?.title,
-      definition: previous?.definition,
-      schema: contribution.paramsSchema ? _.cloneDeep(contribution.paramsSchema) : previous?.schema,
-      docs,
-      coverage: {
-        status: contribution.paramsSchema ? 'manual' : previous?.coverage.status || 'unresolved',
-        source: contribution.source || previous?.coverage.source || 'official',
-        strict: contribution.strict ?? previous?.coverage.strict,
-      },
-      dynamicHints: normalizeSchemaHints([...(previous?.dynamicHints || []), ...(docs.dynamicHints || [])]),
-    });
-    this.invalidateDerivedCaches();
-  }
-
-  registerActionContributions(
-    contributions: FlowActionSchemaContribution[] | Record<string, FlowActionSchemaContribution>,
-  ) {
-    const values = Array.isArray(contributions) ? contributions : Object.values(contributions || {});
-    for (const contribution of values) {
-      this.registerActionContribution(contribution);
-    }
-  }
-
-  registerFieldBindingContext(contribution: FlowFieldBindingContextContribution, fallbackName?: string) {
-    const normalized = normalizeFieldBindingContextContribution(contribution, fallbackName);
-    if (!normalized) {
-      return;
-    }
-
-    const previous = this.fieldBindingContexts.get(normalized.name);
-    this.fieldBindingContexts.set(normalized.name, {
-      name: normalized.name,
-      inherits: _.uniq([...(previous?.inherits || []), ...normalized.inherits]),
-    });
-    this.invalidateDerivedCaches();
-  }
-
-  registerFieldBindingContexts(
-    contributions:
-      | FlowFieldBindingContextContribution[]
-      | Record<string, FlowFieldBindingContextContribution>
-      | undefined,
-  ) {
-    if (!contributions) {
-      return;
-    }
-
-    if (Array.isArray(contributions)) {
-      for (const contribution of contributions) {
-        this.registerFieldBindingContext(contribution);
-      }
-      return;
-    }
-
-    for (const [name, contribution] of Object.entries(contributions)) {
-      if (!contribution) {
-        continue;
-      }
-      this.registerFieldBindingContext(contribution, name);
-    }
-  }
-
-  registerFieldBinding(contribution: FlowFieldBindingContribution, source: FlowSchemaCoverage['source'] = 'official') {
-    const normalized = normalizeFieldBindingContribution(contribution, source);
-    if (!normalized) {
-      return;
-    }
-
-    const bindings = this.fieldBindings.get(normalized.context) || [];
-    bindings.push(normalized);
-    this.fieldBindings.set(normalized.context, bindings);
-    this.invalidateDerivedCaches();
-  }
-
-  registerFieldBindings(
-    contributions:
-      | FlowFieldBindingContribution[]
-      | Record<string, FlowFieldBindingContribution | FlowFieldBindingContribution[]>
-      | undefined,
-    source: FlowSchemaCoverage['source'] = 'official',
-  ) {
-    if (!contributions) {
-      return;
-    }
-
-    if (Array.isArray(contributions)) {
-      for (const contribution of contributions) {
-        this.registerFieldBinding(contribution, source);
-      }
-      return;
-    }
-
-    for (const [context, contribution] of Object.entries(contributions)) {
-      if (!contribution) {
-        continue;
-      }
-
-      const items = Array.isArray(contribution) ? contribution : [contribution];
-      for (const item of items) {
-        this.registerFieldBinding(
-          {
-            ...item,
-            context: item.context || context,
-          },
-          source,
-        );
-      }
-    }
-  }
-
-  registerModel(use: string, options: Partial<RegisteredModelSchema>) {
-    const name = String(use || '').trim();
-    if (!name) return;
-    const previous = this.modelSchemas.get(name);
-    this.modelSchemas.set(name, {
-      use: name,
-      title: options.title || previous?.title,
-      modelClass: options.modelClass || previous?.modelClass,
-      stepParamsSchema: options.stepParamsSchema || previous?.stepParamsSchema,
-      flowRegistrySchema: options.flowRegistrySchema || previous?.flowRegistrySchema,
-      subModelSlots: normalizeSubModelSlots(options.subModelSlots || previous?.subModelSlots),
-      flowRegistrySchemaPatch: options.flowRegistrySchemaPatch || previous?.flowRegistrySchemaPatch,
-      examples: options.examples || previous?.examples || [],
-      docs: normalizeSchemaDocs({
-        ...previous?.docs,
-        ...options.docs,
-        examples: options.docs?.examples || previous?.docs?.examples,
-        dynamicHints: [...(previous?.docs?.dynamicHints || []), ...(options.docs?.dynamicHints || [])],
-        commonPatterns: options.docs?.commonPatterns || previous?.docs?.commonPatterns,
-        antiPatterns: options.docs?.antiPatterns || previous?.docs?.antiPatterns,
-        minimalExample:
-          options.docs?.minimalExample !== undefined ? options.docs.minimalExample : previous?.docs?.minimalExample,
-      }),
-      skeleton: options.skeleton !== undefined ? _.cloneDeep(options.skeleton) : previous?.skeleton,
-      dynamicHints: normalizeSchemaHints([...(previous?.dynamicHints || []), ...(options.dynamicHints || [])]),
-      coverage: options.coverage || previous?.coverage || { status: 'unresolved', source: 'third-party' },
-      exposure: options.exposure ?? previous?.exposure ?? 'public',
-      abstract: options.abstract ?? previous?.abstract ?? false,
-      allowDirectUse: options.allowDirectUse ?? previous?.allowDirectUse ?? true,
-      suggestedUses: normalizeStringArray(options.suggestedUses || previous?.suggestedUses),
-    });
-    this.invalidateDerivedCaches();
-  }
-
-  registerModelContribution(contribution: FlowModelSchemaContribution) {
-    const use = String(contribution?.use || '').trim();
-    if (!use) return;
-
-    const previous = this.modelSchemas.get(use);
-    const hasSchemaContribution =
-      !!contribution.stepParamsSchema ||
-      !!contribution.flowRegistrySchema ||
-      !!contribution.flowRegistrySchemaPatch ||
-      !!contribution.subModelSlots;
-    const docs = normalizeSchemaDocs({
-      ...previous?.docs,
-      ...contribution.docs,
-      examples: contribution.examples || contribution.docs?.examples || previous?.docs?.examples,
-      dynamicHints: [...(previous?.docs?.dynamicHints || []), ...(contribution.docs?.dynamicHints || [])],
-      commonPatterns: contribution.docs?.commonPatterns || previous?.docs?.commonPatterns,
-      antiPatterns: contribution.docs?.antiPatterns || previous?.docs?.antiPatterns,
-      minimalExample:
-        contribution.docs?.minimalExample !== undefined
-          ? contribution.docs.minimalExample
-          : previous?.docs?.minimalExample,
-    });
-    this.registerModel(use, {
-      title: contribution.title,
-      stepParamsSchema: contribution.stepParamsSchema ? _.cloneDeep(contribution.stepParamsSchema) : undefined,
-      flowRegistrySchema: contribution.flowRegistrySchema ? _.cloneDeep(contribution.flowRegistrySchema) : undefined,
-      subModelSlots: contribution.subModelSlots ? normalizeSubModelSlots(contribution.subModelSlots) : undefined,
-      flowRegistrySchemaPatch: contribution.flowRegistrySchemaPatch
-        ? _.cloneDeep(contribution.flowRegistrySchemaPatch)
-        : undefined,
-      examples: contribution.examples || docs.examples || [],
-      docs,
-      skeleton: contribution.skeleton,
-      dynamicHints: [...(contribution.dynamicHints || []), ...(docs.dynamicHints || [])],
-      coverage: hasSchemaContribution
-        ? {
-            status: previous?.coverage.status === 'auto' ? 'mixed' : 'manual',
-            source: contribution.source || previous?.coverage.source || 'official',
-            strict: contribution.strict ?? previous?.coverage.strict,
-          }
-        : previous?.coverage || {
-            status: 'unresolved',
-            source: contribution.source || 'official',
-            strict: contribution.strict,
-          },
-      exposure: contribution.exposure,
-      abstract: contribution.abstract,
-      allowDirectUse: contribution.allowDirectUse,
-      suggestedUses: contribution.suggestedUses,
-    });
-  }
-
-  registerModelContributions(
-    contributions: FlowModelSchemaContribution[] | Record<string, FlowModelSchemaContribution>,
-  ) {
-    const values = Array.isArray(contributions) ? contributions : Object.values(contributions || {});
-    for (const contribution of values) {
-      this.registerModelContribution(contribution);
-    }
-  }
-
-  registerModelClass(use: string, modelClass: ModelConstructor) {
-    const meta = ((modelClass as any).meta || {}) as FlowModelMeta;
-    const schemaMeta = meta.schema || {};
-    const inferredSlots = this.inferSubModelSlotsFromModelClass(use, modelClass);
-    const inferredHints = this.collectModelDynamicHints(use, modelClass, meta);
-    const hasManual =
-      !!schemaMeta.stepParamsSchema ||
-      !!schemaMeta.flowRegistrySchema ||
-      !!schemaMeta.subModelSlots ||
-      !!schemaMeta.flowRegistrySchemaPatch;
-    const hasAuto = !!Object.keys(inferredSlots).length;
-
-    this.registerModel(use, {
-      modelClass,
-      title: toSchemaTitle(meta.label, use),
-      stepParamsSchema: schemaMeta.stepParamsSchema,
-      flowRegistrySchema: schemaMeta.flowRegistrySchema,
-      subModelSlots: Object.keys(schemaMeta.subModelSlots || {}).length ? schemaMeta.subModelSlots : inferredSlots,
-      flowRegistrySchemaPatch: schemaMeta.flowRegistrySchemaPatch,
-      examples: schemaMeta.examples || schemaMeta.docs?.examples || [],
-      docs: schemaMeta.docs,
-      skeleton: schemaMeta.skeleton,
-      dynamicHints: [...(schemaMeta.dynamicHints || []), ...(schemaMeta.docs?.dynamicHints || []), ...inferredHints],
-      coverage: {
-        status: hasManual && hasAuto ? 'mixed' : hasManual ? 'manual' : hasAuto ? 'auto' : 'unresolved',
-        source: schemaMeta.source || 'official',
-        strict: schemaMeta.strict,
-      },
-      exposure: schemaMeta.exposure,
-      abstract: schemaMeta.abstract,
-      allowDirectUse: schemaMeta.allowDirectUse,
-      suggestedUses: schemaMeta.suggestedUses,
-    });
-  }
-
-  registerModels(models: Record<string, ModelConstructor | undefined>) {
-    for (const [use, modelClass] of Object.entries(models || {})) {
-      if (modelClass) {
-        this.registerModelClass(use, modelClass);
-      }
-    }
-  }
-
-  registerInventory(inventory: FlowSchemaInventoryContribution | undefined, _source: FlowSchemaCoverage['source']) {
-    if (!inventory) {
-      return;
-    }
-
-    for (const use of normalizeStringArray(inventory.publicTreeRoots)) {
-      this.publicTreeRoots.add(use);
-    }
-
-    for (const item of inventory.slotUseExpansions || []) {
-      const parentUse = String(item?.parentUse || '').trim();
-      const slotKey = String(item?.slotKey || '').trim();
-      const uses = normalizeStringArray(item?.uses);
-      if (!parentUse || !slotKey || uses.length === 0) {
-        continue;
-      }
-
-      const key = this.createSlotUseExpansionKey(parentUse, slotKey);
-      this.slotUseExpansions.set(key, _.uniq([...(this.slotUseExpansions.get(key) || []), ...uses]));
-    }
-    this.invalidateDerivedCaches();
-  }
-
-  resolveFieldBindingCandidates(
-    context: string,
-    options: {
-      interface?: string;
-      fieldType?: string;
-      association?: boolean;
-      targetCollectionTemplate?: string;
-    } = {},
-  ) {
-    const contextChain = this.resolveFieldBindingContextChain(context);
-    const entries = contextChain.flatMap((contextName, contextIndex) =>
-      (this.fieldBindings.get(contextName) || []).map((binding, bindingIndex) => ({
-        binding,
-        contextIndex,
-        bindingIndex,
-      })),
-    );
-
-    const candidates = entries
-      .filter(({ binding }) => matchesFieldBinding(binding, options))
-      .filter(({ binding }) => this.hasQueryableModel(binding.use))
-      .sort((a, b) => {
-        if (a.binding.isDefault !== b.binding.isDefault) {
-          return a.binding.isDefault ? -1 : 1;
-        }
-
-        const aOrder = typeof a.binding.order === 'number' ? a.binding.order : Number.MAX_SAFE_INTEGER;
-        const bOrder = typeof b.binding.order === 'number' ? b.binding.order : Number.MAX_SAFE_INTEGER;
-        if (aOrder !== bOrder) {
-          return aOrder - bOrder;
-        }
-
-        if (a.contextIndex !== b.contextIndex) {
-          return a.contextIndex - b.contextIndex;
-        }
-
-        return a.bindingIndex - b.bindingIndex;
-      })
-      .map(({ binding }) => ({
-        use: binding.use,
-        defaultProps: binding.defaultProps === undefined ? undefined : _.cloneDeep(binding.defaultProps),
-        compatibility: buildFieldModelCompatibility(binding),
-      }));
-
-    return _.uniqBy(candidates, (candidate) => `${candidate.use}:${stableStringify(candidate.compatibility)}`);
-  }
-
-  getAction(name: string): RegisteredActionSchema | undefined {
-    return this.actionSchemas.get(name);
-  }
-
-  listActionNames(): string[] {
-    return Array.from(this.actionSchemas.keys()).sort();
-  }
-
-  getModel(use: string): RegisteredModelSchema | undefined {
-    return this.modelSchemas.get(use);
-  }
-
-  private resolveFieldBindingContextChain(context: string, visited = new Set<string>()): string[] {
-    const name = String(context || '').trim();
-    if (!name || visited.has(name)) {
-      return [];
-    }
-
-    visited.add(name);
-
-    const chain = [name];
-    const inherits = this.fieldBindingContexts.get(name)?.inherits || [];
-    for (const inheritedContext of inherits) {
-      for (const item of this.resolveFieldBindingContextChain(inheritedContext, visited)) {
-        if (!chain.includes(item)) {
-          chain.push(item);
-        }
-      }
-    }
-
-    return chain;
-  }
-
-  private resolveModelSchemaRef(use: string, contextChain: FlowSchemaContextEdge[] = []): RegisteredModelSchema {
-    const name = String(use || '').trim();
-    const cacheKey = `${name}::${stableStringify(contextChain)}`;
-    const cached = this.resolvedModelCache.get(cacheKey);
-    if (cached) {
-      return cached;
-    }
-
-    const registered = this.modelSchemas.get(name);
-    const resolved: RegisteredModelSchema = {
-      use: name,
-      title: registered?.title || name,
-      modelClass: registered?.modelClass,
-      stepParamsSchema: registered?.stepParamsSchema
-        ? _.cloneDeep(registered.stepParamsSchema)
-        : this.buildInferredStepParamsSchema(name),
-      flowRegistrySchema: registered?.flowRegistrySchema
-        ? _.cloneDeep(registered.flowRegistrySchema)
-        : this.buildInferredFlowRegistrySchema(name),
-      subModelSlots: normalizeSubModelSlots(registered?.subModelSlots),
-      flowRegistrySchemaPatch: registered?.flowRegistrySchemaPatch
-        ? _.cloneDeep(registered.flowRegistrySchemaPatch)
-        : undefined,
-      examples: _.cloneDeep(registered?.examples || []),
-      docs: normalizeSchemaDocs(registered?.docs),
-      skeleton: registered?.skeleton === undefined ? undefined : _.cloneDeep(registered.skeleton),
-      dynamicHints: normalizeSchemaHints(registered?.dynamicHints),
-      coverage: registered?.coverage || { status: 'unresolved', source: 'third-party' },
-      exposure: registered?.exposure || 'public',
-      abstract: registered?.abstract ?? false,
-      allowDirectUse: registered?.allowDirectUse ?? true,
-      suggestedUses: normalizeStringArray(registered?.suggestedUses),
-    };
-
-    for (const contribution of this.collectContextPatches(name, contextChain)) {
-      applyModelSchemaPatch(resolved, contribution.patch, contribution.source, contribution.strict);
-    }
-
-    const frozen = deepFreezePlainGraph(resolved);
-    this.resolvedModelCache.set(cacheKey, frozen);
-    return frozen;
-  }
-
-  resolveModelSchema(use: string, contextChain: FlowSchemaContextEdge[] = []): RegisteredModelSchema {
-    return _.cloneDeep(this.resolveModelSchemaRef(use, contextChain));
-  }
-
-  private isPublicModel(model?: Pick<RegisteredModelSchema, 'exposure'>): boolean {
-    return (model?.exposure || 'public') === 'public';
-  }
-
-  private isQueryableModel(model?: Pick<RegisteredModelSchema, 'abstract'>): boolean {
-    return !!model && model.abstract !== true;
-  }
-
-  getSuggestedUses(use: string): string[] {
-    const model = this.modelSchemas.get(String(use || '').trim());
-    if (model?.suggestedUses?.length) {
-      return normalizeStringArray(model.suggestedUses);
-    }
-    return this.listModelUses({ directUseOnly: true })
-      .filter((item) => item !== use)
-      .slice(0, 20);
-  }
-
-  hasQueryableModel(use: string): boolean {
-    const model = this.modelSchemas.get(String(use || '').trim());
-    return this.isQueryableModel(model);
-  }
-
-  isDirectUseAllowed(use: string): boolean {
-    const model = this.modelSchemas.get(String(use || '').trim());
-    return model ? this.isQueryableModel(model) && model.allowDirectUse !== false : true;
-  }
-
-  listPublicTreeRoots(): string[] {
-    return Array.from(this.publicTreeRoots).sort();
-  }
-
-  listModelUses(options: { publicOnly?: boolean; directUseOnly?: boolean; queryableOnly?: boolean } = {}): string[] {
-    const { publicOnly = false, directUseOnly = false, queryableOnly = false } = options;
-    return Array.from(this.modelSchemas.values())
-      .filter((model) => !publicOnly || (this.isPublicModel(model) && this.isQueryableModel(model)))
-      .filter((model) => !queryableOnly || this.isQueryableModel(model))
-      .filter((model) => !directUseOnly || (this.isQueryableModel(model) && model.allowDirectUse !== false))
-      .map((model) => model.use)
-      .sort();
-  }
-
-  getSchemaBundle(uses?: string[]): FlowSchemaBundleDocument {
-    return {
-      items: (Array.isArray(uses) && uses.length > 0 ? uses.filter((use) => this.hasQueryableModel(use)) : []).map(
-        (use) => this.buildBundleNode(use, [], new Set<string>()),
-      ),
-    };
-  }
-
-  getModelDocument(use: string, contextChain: FlowSchemaContextEdge[] = []): FlowSchemaDocument {
-    return _.cloneDeep(this.getModelDocumentRef(use, contextChain));
-  }
-
-  getModelDocumentRef(use: string, contextChain: FlowSchemaContextEdge[] = []): Readonly<FlowSchemaDocument> {
-    const cacheKey = this.createContextVisitKey(use, contextChain);
-    const cached = this.modelDocumentCache.get(cacheKey);
-    if (cached) {
-      return cached;
-    }
-    const document = this.buildModelDocument(use, contextChain, new Set<string>());
-    const frozen = deepFreezePlainGraph(document);
-    this.modelDocumentCache.set(cacheKey, frozen);
-    return frozen;
-  }
-
-  getPublicModelDocument(
-    use: string,
-    options: { detail?: FlowSchemaDetail; contextChain?: FlowSchemaContextEdge[] } = {},
-  ): FlowSchemaPublicDocument {
-    return _.cloneDeep(this.getPublicModelDocumentRef(use, options));
-  }
-
-  getPublicModelDocumentRef(
-    use: string,
-    options: { detail?: FlowSchemaDetail; contextChain?: FlowSchemaContextEdge[] } = {},
-  ): Readonly<FlowSchemaPublicDocument> {
-    const detail = options.detail === 'full' ? 'full' : 'compact';
-    const contextChain = options.contextChain || [];
-    const cacheKey = `${detail}::${this.createContextVisitKey(use, contextChain)}`;
-    const cached = this.publicModelDocumentCache.get(cacheKey);
-    if (cached) {
-      return cached;
-    }
-
-    const document =
-      detail === 'full'
-        ? this.buildFullPublicModelDocument(use, contextChain)
-        : this.buildCompactPublicModelDocument(use, contextChain);
-    const frozen = deepFreezePlainGraph(document);
-    this.publicModelDocumentCache.set(cacheKey, frozen);
-    return frozen;
-  }
-
-  private buildFullPublicModelDocument(use: string, contextChain: FlowSchemaContextEdge[]): FlowSchemaPublicDocument {
-    const document = this.getModelDocumentRef(use, contextChain);
-    return {
-      use: document.use,
-      title: document.title,
-      jsonSchema: document.jsonSchema,
-      dynamicHints: document.dynamicHints,
-      minimalExample: document.minimalExample,
-      commonPatterns: document.commonPatterns,
-      antiPatterns: document.antiPatterns,
-      hash: document.hash,
-      source: document.source,
-    };
-  }
-
-  private buildCompactPublicModelDocument(
-    use: string,
-    contextChain: FlowSchemaContextEdge[],
-  ): FlowSchemaPublicDocument {
-    const resolved = this.resolveModelSchemaRef(use, contextChain);
-    const jsonSchema = this.buildCompactModelSnapshotSchemaRef(use, contextChain);
-    const minimalExample = _.cloneDeep(
-      resolved?.docs?.minimalExample ??
-        resolved?.examples?.[0] ??
-        resolved?.skeleton ??
-        buildSkeletonFromSchema(jsonSchema),
-    );
-
-    return {
-      use,
-      title: resolved?.title || use,
-      jsonSchema,
-      dynamicHints: [...this.getModelLocalDynamicHintsRef(use, contextChain)],
-      minimalExample,
-      commonPatterns: _.cloneDeep(resolved?.docs?.commonPatterns || []),
-      antiPatterns: _.cloneDeep(resolved?.docs?.antiPatterns || []),
-      hash: this.getCompactModelSchemaHash(use, contextChain),
-      source: (resolved?.coverage || { source: 'third-party' as const }).source,
-    };
-  }
-
-  private getModelLocalDynamicHintsRef(
-    use: string,
-    contextChain: FlowSchemaContextEdge[] = [],
-  ): Readonly<FlowDynamicHint[]> {
-    const cacheKey = this.createContextVisitKey(use, contextChain);
-    const cached = this.modelLocalDynamicHintsCache.get(cacheKey);
-    if (cached) {
-      return cached;
-    }
-
-    const hints = this.buildModelLocalDynamicHints(use, contextChain);
-    const frozen = deepFreezePlainGraph(hints);
-    this.modelLocalDynamicHintsCache.set(cacheKey, frozen);
-    return frozen;
-  }
-
-  private buildModelLocalDynamicHints(use: string, contextChain: FlowSchemaContextEdge[]): FlowDynamicHint[] {
-    const resolved = this.resolveModelSchemaRef(use, contextChain);
-    const baseCoverage = resolved.coverage || { status: 'unresolved', source: 'third-party' as const };
-    const flowDiagnostics = this.collectFlowSchemaDiagnostics(use);
-    const slotHints = Object.entries(resolved?.subModelSlots || {}).map(([slotKey, slot]) => {
-      const allowedUses = this.resolveSlotAllowedUses(use, slotKey, slot);
-      return createFlowHint(
-        {
-          kind: slot.dynamic || slot.fieldBindingContext ? 'dynamic-children' : 'manual-schema-required',
-          path: `${use}.subModels.${slotKey}`,
-          message:
-            slot.description ||
-            `${use}.subModels.${slotKey} accepts ${slot.type}${
-              allowedUses.length ? `: ${allowedUses.join(', ')}` : ''
-            }.`,
-        },
-        {
-          slotRules: {
-            slotKey,
-            type: slot.type,
-            allowedUses,
-          },
-        },
-      );
-    });
-    const coverage = this.buildDocumentCoverage(baseCoverage, flowDiagnostics.statuses);
-
-    return normalizeSchemaHints([
-      ...(resolved?.dynamicHints || []),
-      ...slotHints,
-      ...flowDiagnostics.hints,
-      ...(coverage.status === 'unresolved'
-        ? [
-            createFlowHint(
-              {
-                kind: 'unresolved-model' as const,
-                path: use,
-                message: `${use} has no registered server-safe schema contribution yet.`,
-              },
-              {
-                unresolvedReason: 'missing-model-contribution',
-                recommendedFallback: { use },
-              },
-            ),
-          ]
-        : []),
-    ]);
-  }
-
-  getModelSchemaHash(use: string, contextChain: FlowSchemaContextEdge[] = []): string {
-    const cacheKey = this.createContextVisitKey(use, contextChain);
-    const cached = this.modelSchemaHashCache.get(cacheKey);
-    if (cached) {
-      return cached;
-    }
-    const hash = hashString(stableStringify(this.buildModelSnapshotSchemaRef(use, contextChain)));
-    this.modelSchemaHashCache.set(cacheKey, hash);
-    return hash;
-  }
-
-  getCompactModelSchemaHash(use: string, contextChain: FlowSchemaContextEdge[] = []): string {
-    const cacheKey = this.createContextVisitKey(use, contextChain);
-    const cached = this.compactModelSchemaHashCache.get(cacheKey);
-    if (cached) {
-      return cached;
-    }
-    const hash = hashString(stableStringify(this.buildCompactModelSnapshotSchemaRef(use, contextChain)));
-    this.compactModelSchemaHashCache.set(cacheKey, hash);
-    return hash;
-  }
-
-  private createSlotUseExpansionKey(parentUse: string, slotKey: string): string {
-    return `${parentUse}::${slotKey}`;
-  }
-
-  private getSlotUseExpansionUses(parentUse: string, slotKey: string): string[] {
-    return this.slotUseExpansions.get(this.createSlotUseExpansionKey(parentUse, slotKey)) || [];
-  }
-
-  resolveSlotAllowedUses(parentUse: string, slotKey: string, slot?: FlowSubModelSlotSchema): string[] {
-    if (!slot) {
-      return [];
-    }
-
-    if (slot.fieldBindingContext) {
-      return _.uniq(this.resolveFieldBindingCandidates(slot.fieldBindingContext).map((candidate) => candidate.use));
-    }
-
-    return _.uniq([...collectAllowedUses(slot), ...this.getSlotUseExpansionUses(parentUse, slotKey)]);
-  }
-
-  private buildModelDocument(
-    use: string,
-    contextChain: FlowSchemaContextEdge[],
-    visited: Set<string>,
-  ): FlowSchemaDocument {
-    const resolved = this.resolveModelSchemaRef(use, contextChain);
-    const baseCoverage = resolved.coverage || { status: 'unresolved', source: 'third-party' as const };
-    const flowDiagnostics = this.collectFlowSchemaDiagnostics(use);
-    const coverage = this.buildDocumentCoverage(baseCoverage, flowDiagnostics.statuses);
-    const dynamicHints = normalizeSchemaHints([
-      ...this.getModelLocalDynamicHintsRef(use, contextChain),
-      ...this.collectNestedDocumentHints(use, contextChain, visited),
-    ]);
-
-    const jsonSchema = this.buildModelSnapshotSchemaRef(use, contextChain);
-    const skeleton = _.cloneDeep(resolved?.skeleton ?? buildSkeletonFromSchema(jsonSchema));
-    const minimalExample = _.cloneDeep(resolved?.docs?.minimalExample ?? resolved?.examples?.[0] ?? skeleton);
-    const hash = this.getModelSchemaHash(use, contextChain);
-
-    return {
-      use,
-      title: resolved?.title || use,
-      jsonSchema,
-      coverage,
-      dynamicHints,
-      examples: resolved?.examples || [],
-      minimalExample,
-      commonPatterns: _.cloneDeep(resolved?.docs?.commonPatterns || []),
-      antiPatterns: _.cloneDeep(resolved?.docs?.antiPatterns || []),
-      skeleton,
-      hash,
-      source: coverage.source,
-    };
-  }
-
-  private buildBundleNode(
-    use: string,
-    contextChain: FlowSchemaContextEdge[],
-    visited: Set<string>,
-    compatibility?: FlowFieldModelCompatibility,
-  ): FlowSchemaBundleNode {
-    const resolved = this.resolveModelSchemaRef(use, contextChain);
-    const visitKey = this.createContextVisitKey(use, contextChain);
-    const node: FlowSchemaBundleNode = {
-      use,
-      title: resolved?.title || use,
-    };
-
-    if (compatibility) {
-      node.compatibility = _.cloneDeep(compatibility);
-    }
-
-    if (visited.has(visitKey) || this.isContextCycle(use, contextChain)) {
-      return node;
-    }
-
-    visited.add(visitKey);
-    try {
-      const subModelCatalog = this.buildBundleSubModelCatalog(use, resolved?.subModelSlots, contextChain, visited);
-      if (subModelCatalog && Object.keys(subModelCatalog).length > 0) {
-        node.subModelCatalog = subModelCatalog;
-      }
-      return node;
-    } finally {
-      visited.delete(visitKey);
-    }
-  }
-
-  private buildBundleSubModelCatalog(
-    parentUse: string,
-    slots: Record<string, FlowSubModelSlotSchema> | undefined,
-    contextChain: FlowSchemaContextEdge[],
-    visited: Set<string>,
-  ): Record<string, FlowSchemaBundleSlotCatalog> | undefined {
-    if (!slots || Object.keys(slots).length === 0) {
-      return undefined;
-    }
-
-    const entries = Object.entries(slots).map(([slotKey, slot]) => {
-      const edgeBase = {
-        parentUse,
-        slotKey,
-      };
-      const fieldBindingCandidates = slot.fieldBindingContext
-        ? this.resolveFieldBindingCandidates(slot.fieldBindingContext)
-        : [];
-      const allowedUses =
-        fieldBindingCandidates.length > 0
-          ? _.uniq(fieldBindingCandidates.map((item) => item.use))
-          : this.resolveSlotAllowedUses(parentUse, slotKey, slot);
-      const catalog: FlowSchemaBundleSlotCatalog = {
-        type: slot.type,
-        candidates:
-          fieldBindingCandidates.length > 0
-            ? fieldBindingCandidates.map((candidate) =>
-                this.buildBundleNode(
-                  candidate.use,
-                  [
-                    ...contextChain,
-                    {
-                      ...edgeBase,
-                      childUse: candidate.use,
-                    },
-                  ],
-                  visited,
-                  candidate.compatibility,
-                ),
-              )
-            : allowedUses.map((childUse) =>
-                this.buildBundleNode(
-                  childUse,
-                  [
-                    ...contextChain,
-                    {
-                      ...edgeBase,
-                      childUse,
-                    },
-                  ],
-                  visited,
-                ),
-              ),
-      };
-
-      if (slot.required !== undefined) {
-        catalog.required = slot.required;
-      }
-
-      if (slot.type === 'array' && typeof slot.minItems === 'number') {
-        catalog.minItems = slot.minItems;
-      }
-
-      if (allowedUses.length === 0) {
-        catalog.open = true;
-      }
-
-      return [slotKey, catalog] as const;
-    });
-
-    return entries.length ? Object.fromEntries(entries) : undefined;
-  }
-
-  private createContextVisitKey(use: string, contextChain: FlowSchemaContextEdge[]): string {
-    return `${use}::${stableStringify(contextChain)}`;
-  }
-
-  private isContextCycle(use: string, contextChain: FlowSchemaContextEdge[]): boolean {
-    if (!contextChain.length) {
-      return false;
-    }
-
-    const ancestorUses = [contextChain[0].parentUse, ...contextChain.slice(0, -1).map((edge) => edge.childUse)];
-    return ancestorUses.includes(use);
-  }
-
-  buildModelSnapshotSchema(use: string, contextChain: FlowSchemaContextEdge[] = []): FlowJsonSchema {
-    return _.cloneDeep(this.buildModelSnapshotSchemaRef(use, contextChain));
-  }
-
-  buildCompactModelSnapshotSchema(use: string, contextChain: FlowSchemaContextEdge[] = []): FlowJsonSchema {
-    return _.cloneDeep(this.buildCompactModelSnapshotSchemaRef(use, contextChain));
-  }
-
-  private buildModelSnapshotSchemaRef(use: string, contextChain: FlowSchemaContextEdge[] = []): FlowJsonSchema {
-    const cacheKey = this.createContextVisitKey(use, contextChain);
-    const cached = this.modelSnapshotSchemaCache.get(cacheKey);
-    if (cached) {
-      return cached;
-    }
-    const schema = this.buildModelSnapshotSchemaInternal(use, contextChain, new Set<string>());
-    const frozen = deepFreezePlainGraph(schema);
-    this.modelSnapshotSchemaCache.set(cacheKey, frozen);
-    return frozen;
-  }
-
-  private buildCompactModelSnapshotSchemaRef(use: string, contextChain: FlowSchemaContextEdge[] = []): FlowJsonSchema {
-    const cacheKey = this.createContextVisitKey(use, contextChain);
-    const cached = this.compactModelSnapshotSchemaCache.get(cacheKey);
-    if (cached) {
-      return cached;
-    }
-    const schema = this.buildCompactModelSnapshotSchemaInternal(use, contextChain);
-    const frozen = deepFreezePlainGraph(schema);
-    this.compactModelSnapshotSchemaCache.set(cacheKey, frozen);
-    return frozen;
-  }
-
-  private buildCompactModelSnapshotSchemaInternal(use: string, contextChain: FlowSchemaContextEdge[]): FlowJsonSchema {
-    const resolved = this.resolveModelSchemaRef(use, contextChain);
-    const subModelsSchema = this.buildCompactSubModelsSchemaFromSlots(use, resolved?.subModelSlots, contextChain);
-    return this.buildSnapshotShellSchema(use, resolved, subModelsSchema);
-  }
-
-  private buildModelSnapshotSchemaInternal(
-    use: string,
-    contextChain: FlowSchemaContextEdge[],
-    visited: Set<string>,
-  ): FlowJsonSchema {
-    const resolved = this.resolveModelSchemaRef(use, contextChain);
-    const visitKey = this.createContextVisitKey(use, contextChain);
-
-    if (visited.has(visitKey) || this.isContextCycle(use, contextChain)) {
-      return this.buildTruncatedSnapshotSchema(use, resolved);
-    }
-
-    visited.add(visitKey);
-    try {
-      return this.buildSnapshotSchemaFromResolved(use, resolved, contextChain, visited);
-    } finally {
-      visited.delete(visitKey);
-    }
-  }
-
-  private buildSnapshotSchemaFromResolved(
-    use: string | undefined,
-    resolved: RegisteredModelSchema,
-    contextChain: FlowSchemaContextEdge[],
-    visited: Set<string>,
-  ): FlowJsonSchema {
-    const subModelsSchema = this.buildSubModelsSchemaFromSlots(
-      use || '',
-      resolved?.subModelSlots,
-      contextChain,
-      visited,
-    );
-    return this.buildSnapshotShellSchema(use, resolved, subModelsSchema);
-  }
-
-  private buildSnapshotShellSchema(
-    use: string | undefined,
-    resolved: RegisteredModelSchema,
-    subModelsSchema: FlowJsonSchema,
-  ): FlowJsonSchema {
-    const flowRegistrySchema = resolved?.flowRegistrySchema || { type: 'object', additionalProperties: true };
-    const stepParamsSchema = resolved?.stepParamsSchema || { type: 'object', additionalProperties: true };
-    return {
-      $schema: JSON_SCHEMA_DRAFT_07,
-      type: 'object',
-      properties: {
-        uid: { type: 'string' },
-        use: use ? { const: use } : { type: 'string' },
-        async: { type: 'boolean' },
-        parentId: { type: 'string' },
-        subKey: { type: 'string' },
-        subType: { type: 'string', enum: ['object', 'array'] },
-        sortIndex: { type: 'number' },
-        stepParams: stepParamsSchema,
-        flowRegistry: mergeSchemas(flowRegistrySchema, resolved?.flowRegistrySchemaPatch) || {
-          type: 'object',
-          additionalProperties: true,
-        },
-        subModels: subModelsSchema,
-      },
-      required: ['uid', 'use'],
-      additionalProperties: true,
-    };
-  }
-
-  private buildTruncatedSnapshotSchema(use: string | undefined, resolved: RegisteredModelSchema): FlowJsonSchema {
-    return this.buildSnapshotShellSchema(use, resolved, {
-      type: 'object',
-      additionalProperties: true,
-    });
-  }
-
-  buildStaticFlowRegistrySchema(use: string, contextChain: FlowSchemaContextEdge[] = []): FlowJsonSchema {
-    const resolved = this.resolveModelSchemaRef(use, contextChain);
-    const schema = mergeSchemas(resolved?.flowRegistrySchema, resolved?.flowRegistrySchemaPatch);
-    if (schema) {
-      return _.cloneDeep(schema);
-    }
-    return { type: 'object', additionalProperties: true };
-  }
-
-  buildStaticStepParamsSchema(use: string, contextChain: FlowSchemaContextEdge[] = []): FlowJsonSchema {
-    const resolved = this.resolveModelSchemaRef(use, contextChain);
-    if (resolved?.stepParamsSchema) {
-      return _.cloneDeep(resolved.stepParamsSchema);
-    }
-    return { type: 'object', additionalProperties: true };
-  }
-
-  buildSubModelsSchema(use: string, contextChain: FlowSchemaContextEdge[] = []): FlowJsonSchema {
-    const resolved = this.resolveModelSchemaRef(use, contextChain);
-    return this.buildSubModelsSchemaFromSlots(use, resolved?.subModelSlots, contextChain, new Set<string>());
-  }
-
-  private buildCompactSubModelsSchemaFromSlots(
-    parentUse: string,
-    slots: Record<string, FlowSubModelSlotSchema> | undefined,
-    contextChain: FlowSchemaContextEdge[] = [],
-  ): FlowJsonSchema {
-    if (!slots || Object.keys(slots).length === 0) {
-      return { type: 'object', additionalProperties: true };
-    }
-
-    const properties: Record<string, FlowJsonSchema> = {};
-    const required: string[] = [];
-    for (const [slotKey, slot] of Object.entries(slots)) {
-      const itemSchema = this.buildCompactSlotTargetSchema(parentUse, slotKey, slot, contextChain);
-      properties[slotKey] =
-        slot.type === 'array'
-          ? {
-              type: 'array',
-              ...(typeof slot.minItems === 'number' ? { minItems: slot.minItems } : {}),
-              items: itemSchema,
-            }
-          : itemSchema;
-      if (slot.required) {
-        required.push(slotKey);
-      }
-    }
-
-    return {
-      type: 'object',
-      properties,
-      ...(required.length ? { required } : {}),
-      additionalProperties: true,
-    };
-  }
-
-  private buildSubModelsSchemaFromSlots(
-    parentUse: string,
-    slots: Record<string, FlowSubModelSlotSchema> | undefined,
-    contextChain: FlowSchemaContextEdge[] = [],
-    visited: Set<string>,
-  ): FlowJsonSchema {
-    if (!slots || Object.keys(slots).length === 0) {
-      return { type: 'object', additionalProperties: true };
-    }
-    const properties: Record<string, FlowJsonSchema> = {};
-    const required: string[] = [];
-    for (const [slotKey, slot] of Object.entries(slots)) {
-      const itemSchema = this.buildSlotTargetSchema(parentUse, slotKey, slot, contextChain, visited);
-      properties[slotKey] =
-        slot.type === 'array'
-          ? {
-              type: 'array',
-              ...(typeof slot.minItems === 'number' ? { minItems: slot.minItems } : {}),
-              items: itemSchema,
-            }
-          : itemSchema;
-      if (slot.required) {
-        required.push(slotKey);
-      }
-    }
-    return {
-      type: 'object',
-      properties,
-      ...(required.length ? { required } : {}),
-      additionalProperties: true,
-    };
-  }
-
-  private buildInferredFlowRegistrySchema(use: string): FlowJsonSchema | undefined {
-    const registered = this.modelSchemas.get(use);
-    const modelClass = registered?.modelClass as any;
-    const flowsMap = modelClass?.globalFlowRegistry?.getFlows?.() as Map<string, any> | undefined;
-    if (!flowsMap?.size) {
-      return undefined;
-    }
-
-    const properties: Record<string, FlowJsonSchema> = {};
-    for (const [flowKey, flowDef] of flowsMap.entries()) {
-      const stepProperties: Record<string, FlowJsonSchema> = {};
-      const steps = flowDef?.steps || {};
-      for (const [stepKey, stepDef] of Object.entries(steps)) {
-        stepProperties[stepKey] = this.buildStepDefinitionSchema(stepDef as StepDefinition);
-      }
-      properties[flowKey] = {
-        type: 'object',
-        properties: {
-          key: { type: 'string' },
-          title: { type: 'string' },
-          manual: { type: 'boolean' },
-          sort: { type: 'number' },
-          on: this.buildFlowOnSchema(),
-          steps: {
-            type: 'object',
-            properties: stepProperties,
-            additionalProperties: false,
-          },
-        },
-        additionalProperties: true,
-      };
-    }
-    return {
-      type: 'object',
-      properties,
-      additionalProperties: true,
-    };
-  }
-
-  private buildInferredStepParamsSchema(use: string): FlowJsonSchema | undefined {
-    const registered = this.modelSchemas.get(use);
-    const modelClass = registered?.modelClass as any;
-    const flowsMap = modelClass?.globalFlowRegistry?.getFlows?.() as Map<string, any> | undefined;
-    if (!flowsMap?.size) {
-      return undefined;
-    }
-
-    const properties: Record<string, FlowJsonSchema> = {};
-    for (const [flowKey, flowDef] of flowsMap.entries()) {
-      const stepProperties: Record<string, FlowJsonSchema> = {};
-      const steps = flowDef?.steps || {};
-      for (const [stepKey, stepDef] of Object.entries(steps)) {
-        const resolved = this.resolveStepParamsSchema(stepDef as StepDefinition, `${use}.${flowKey}.${stepKey}`);
-        stepProperties[stepKey] = resolved.schema || { type: 'object', additionalProperties: true };
-      }
-      properties[flowKey] = {
-        type: 'object',
-        properties: stepProperties,
-        additionalProperties: false,
-      };
-    }
-    return {
-      type: 'object',
-      properties,
-      additionalProperties: true,
-    };
-  }
-
-  buildFlowOnSchema(): FlowJsonSchema {
-    return {
-      anyOf: [
-        { type: 'string' },
-        {
-          type: 'object',
-          properties: {
-            eventName: { type: 'string' },
-            defaultParams: { type: 'object', additionalProperties: true },
-            phase: {
-              type: 'string',
-              enum: ['beforeAllFlows', 'afterAllFlows', 'beforeFlow', 'afterFlow', 'beforeStep', 'afterStep'],
-            },
-            flowKey: { type: 'string' },
-            stepKey: { type: 'string' },
-          },
-          required: ['eventName'],
-          additionalProperties: true,
-        },
-      ],
-    };
-  }
-
-  buildStepDefinitionSchema(step: StepDefinition): FlowJsonSchema {
-    return {
-      type: 'object',
-      properties: {
-        key: { type: 'string' },
-        flowKey: { type: 'string' },
-        title: { type: 'string' },
-        use: { type: 'string' },
-        sort: { type: 'number' },
-        preset: { type: 'boolean' },
-        isAwait: { type: 'boolean' },
-        manual: { type: 'boolean' },
-        on: this.buildFlowOnSchema(),
-        defaultParams: { type: ['object', 'array', 'string', 'number', 'boolean', 'null'] as any },
-        paramsSchemaOverride: { type: 'object', additionalProperties: true },
-      },
-      additionalProperties: true,
-    };
-  }
-
-  resolveStepParamsSchema(step: StepDefinition, path: string): StepSchemaResolution {
-    if (step.paramsSchemaOverride) {
-      return {
-        schema: _.cloneDeep(step.paramsSchemaOverride),
-        hints: normalizeSchemaHints(step.schemaDocs?.dynamicHints),
-        coverage: 'manual',
-      };
-    }
-
-    if (step.use) {
-      const action = this.getAction(step.use);
-      if (action?.schema) {
-        return {
-          schema: _.cloneDeep(action.schema),
-          hints: normalizeSchemaHints([...(action.dynamicHints || []), ...(step.schemaDocs?.dynamicHints || [])]),
-          coverage:
-            action.coverage.status === 'auto' || action.coverage.status === 'manual'
-              ? action.coverage.status
-              : action.coverage.status === 'unresolved'
-                ? 'unresolved'
-                : 'mixed',
-        };
-      }
-      return {
-        schema: { type: 'object', additionalProperties: true },
-        hints: [
-          createFlowHint(
-            {
-              kind: 'unresolved-action',
-              path,
-              message: `${path} references unresolved action "${step.use}".`,
-            },
-            {
-              unresolvedReason: 'missing-action-contribution',
-              recommendedFallback: { use: step.use, params: {} },
-            },
-          ),
-          ...(step.schemaDocs?.dynamicHints || []),
-        ],
-        coverage: 'unresolved',
-      };
-    }
-
-    const inferred = inferParamsSchemaFromUiSchema(path, step.uiSchema as any, path);
-    return {
-      schema: mergeSchemas(inferred.schema, step.paramsSchemaPatch),
-      hints: normalizeSchemaHints([...(inferred.hints || []), ...(step.schemaDocs?.dynamicHints || [])]),
-      coverage: step.paramsSchemaPatch ? 'mixed' : inferred.coverage,
-    };
-  }
-
-  private buildSlotTargetSchema(
-    parentUse: string,
-    slotKey: string,
-    slot: FlowSubModelSlotSchema,
-    contextChain: FlowSchemaContextEdge[],
-    visited: Set<string>,
-  ): FlowJsonSchema {
-    if (slot.fieldBindingContext) {
-      const candidateUses = _.uniq(
-        this.resolveFieldBindingCandidates(slot.fieldBindingContext).map((item) => item.use),
-      );
-      if (candidateUses.length > 0) {
-        const candidateSchemas = candidateUses.map((use) =>
-          this.buildModelSnapshotSchemaInternal(
-            use,
-            [
-              ...contextChain,
-              {
-                parentUse,
-                slotKey,
-                childUse: use,
-              },
-            ],
-            visited,
-          ),
-        );
-
-        if (slot.schema) {
-          return {
-            anyOf: [...candidateSchemas, _.cloneDeep(slot.schema)],
-          };
-        }
-
-        return candidateSchemas.length === 1 ? candidateSchemas[0] : { oneOf: candidateSchemas };
-      }
-    }
-
-    const allowedUses = this.resolveSlotAllowedUses(parentUse, slotKey, slot);
-    if (allowedUses.length > 0) {
-      const knownSchemas = allowedUses.map((use) =>
-        this.buildModelSnapshotSchemaInternal(
-          use,
-          [
-            ...contextChain,
-            {
-              parentUse,
-              slotKey,
-              childUse: use,
-            },
-          ],
-          visited,
-        ),
-      );
-      if (slot.schema) {
-        return {
-          anyOf: [...knownSchemas, _.cloneDeep(slot.schema)],
-        };
-      }
-      if (knownSchemas.length === 1) {
-        return knownSchemas[0];
-      }
-      return {
-        oneOf: knownSchemas,
-      };
-    }
-    if (slot.childSchemaPatch || slot.descendantSchemaPatches?.length) {
-      return this.buildAnonymousSlotSnapshotSchema(parentUse, slotKey, slot, contextChain, visited);
-    }
-    if (slot.schema && !slot.childSchemaPatch && !slot.descendantSchemaPatches?.length) {
-      return _.cloneDeep(slot.schema);
-    }
-    return { type: 'object', additionalProperties: true };
-  }
-
-  private buildCompactSlotTargetSchema(
-    parentUse: string,
-    slotKey: string,
-    slot: FlowSubModelSlotSchema,
-    contextChain: FlowSchemaContextEdge[],
-  ): FlowJsonSchema {
-    if (slot.fieldBindingContext) {
-      const candidateUses = _.uniq(
-        this.resolveFieldBindingCandidates(slot.fieldBindingContext).map((item) => item.use),
-      );
-      if (candidateUses.length > 0) {
-        const candidateSchemas = candidateUses.map((use) =>
-          this.buildCompactSlotCandidateSchema(use, [
-            ...contextChain,
-            {
-              parentUse,
-              slotKey,
-              childUse: use,
-            },
-          ]),
-        );
-
-        if (slot.schema) {
-          return {
-            anyOf: [...candidateSchemas, _.cloneDeep(slot.schema)],
-          };
-        }
-
-        return candidateSchemas.length === 1 ? candidateSchemas[0] : { oneOf: candidateSchemas };
-      }
-    }
-
-    const allowedUses = this.resolveSlotAllowedUses(parentUse, slotKey, slot);
-    if (allowedUses.length > 0) {
-      const knownSchemas = allowedUses.map((use) =>
-        this.buildCompactSlotCandidateSchema(use, [
-          ...contextChain,
-          {
-            parentUse,
-            slotKey,
-            childUse: use,
-          },
-        ]),
-      );
-
-      if (slot.schema) {
-        return {
-          anyOf: [...knownSchemas, _.cloneDeep(slot.schema)],
-        };
-      }
-
-      return knownSchemas.length === 1 ? knownSchemas[0] : { oneOf: knownSchemas };
-    }
-
-    if (slot.childSchemaPatch || slot.descendantSchemaPatches?.length) {
-      return this.buildCompactAnonymousSlotSnapshotSchema(parentUse, slotKey, slot);
-    }
-
-    if (slot.schema && !slot.childSchemaPatch && !slot.descendantSchemaPatches?.length) {
-      return _.cloneDeep(slot.schema);
-    }
-
-    return { type: 'object', additionalProperties: true };
-  }
-
-  private buildCompactSlotCandidateSchema(use: string, contextChain: FlowSchemaContextEdge[]): FlowJsonSchema {
-    const resolved = this.resolveModelSchemaRef(use, contextChain);
-    return this.buildTruncatedSnapshotSchema(use, resolved);
-  }
-
-  private buildCompactAnonymousSlotSnapshotSchema(
-    parentUse: string,
-    slotKey: string,
-    slot: FlowSubModelSlotSchema,
-  ): FlowJsonSchema {
-    const anonymousResolved = this.createAnonymousResolvedSchema(parentUse, slotKey, slot);
-    return this.buildTruncatedSnapshotSchema(undefined, anonymousResolved);
-  }
-
-  private buildAnonymousSlotSnapshotSchema(
-    parentUse: string,
-    slotKey: string,
-    slot: FlowSubModelSlotSchema,
-    contextChain: FlowSchemaContextEdge[],
-    visited: Set<string>,
-  ): FlowJsonSchema {
-    const anonymousResolved = this.createAnonymousResolvedSchema(parentUse, slotKey, slot);
-    return this.buildSnapshotSchemaFromResolved(
-      '',
-      anonymousResolved,
-      [
-        ...contextChain,
-        {
-          parentUse,
-          slotKey,
-          childUse: '',
-        },
-      ],
-      visited,
-    );
-  }
-
-  private createAnonymousResolvedSchema(
-    parentUse: string,
-    slotKey: string,
-    slot: FlowSubModelSlotSchema,
-  ): RegisteredModelSchema {
-    const anonymousResolved: RegisteredModelSchema = {
-      use: '',
-      title: slot.description || `${parentUse || 'AnonymousModel'}.${slotKey}`,
-      examples: [],
-      docs: normalizeSchemaDocs(),
-      dynamicHints: [],
-      coverage: {
-        status: 'unresolved',
-        source: 'third-party',
-      },
-      exposure: 'internal',
-      abstract: false,
-      allowDirectUse: true,
-      suggestedUses: [],
-    };
-
-    const directPatch = resolveChildSchemaPatch(slot, '');
-    if (directPatch) {
-      applyModelSchemaPatch(anonymousResolved, directPatch, 'third-party');
-    }
-
-    return anonymousResolved;
-  }
-
-  private collectNestedDocumentHints(
-    use: string,
-    contextChain: FlowSchemaContextEdge[],
-    visited: Set<string>,
-  ): FlowDynamicHint[] {
-    const visitKey = this.createContextVisitKey(use, contextChain);
-    if (visited.has(visitKey) || this.isContextCycle(use, contextChain)) {
-      return [];
-    }
-
-    visited.add(visitKey);
-    try {
-      const resolved = this.resolveModelSchemaRef(use, contextChain);
-      const hints: FlowDynamicHint[] = [];
-      for (const [slotKey, slot] of Object.entries(resolved.subModelSlots || {})) {
-        const childUses = this.resolveSlotAllowedUses(use, slotKey, slot);
-        for (const childUse of childUses) {
-          const childContext = [
-            ...contextChain,
-            {
-              parentUse: use,
-              slotKey,
-              childUse,
-            },
-          ];
-          const childDocument = this.buildModelDocument(childUse, childContext, visited);
-          const basePath = `${use}.subModels.${slotKey}`;
-          hints.push(...childDocument.dynamicHints.map((hint) => this.prefixNestedHint(hint, basePath, childUse)));
-        }
-      }
-      return normalizeSchemaHints(hints);
-    } finally {
-      visited.delete(visitKey);
-    }
-  }
-
-  private prefixNestedHint(hint: FlowDynamicHint, basePath: string, childUse: string): FlowDynamicHint {
-    if (!hint.path) {
-      return {
-        ...hint,
-        path: basePath,
-      };
-    }
-
-    if (hint.path === childUse) {
-      return {
-        ...hint,
-        path: basePath,
-      };
-    }
-
-    if (hint.path.startsWith(`${childUse}.`)) {
-      return {
-        ...hint,
-        path: `${basePath}.${hint.path.slice(childUse.length + 1)}`,
-      };
-    }
-
-    return {
-      ...hint,
-      path: `${basePath}.${hint.path}`,
-    };
-  }
-
-  private collectContextPatches(use: string, contextChain: FlowSchemaContextEdge[]): ModelPatchContribution[] {
-    if (!contextChain.length) {
-      return [];
-    }
-
-    const contributions: ModelPatchContribution[] = [];
-    const targetEdgeIndex = contextChain.length - 1;
-
-    for (let index = 0; index < contextChain.length; index++) {
-      const edge = contextChain[index];
-      const parentContext = contextChain.slice(0, index);
-      const parentResolved = this.resolveModelSchemaRef(edge.parentUse, parentContext);
-      const slot = parentResolved.subModelSlots?.[edge.slotKey];
-      if (!slot) {
-        continue;
-      }
-
-      const remainingEdges = contextChain.slice(index + 1);
-      for (const patch of slot.descendantSchemaPatches || []) {
-        if (matchesDescendantSchemaPatch(patch, remainingEdges)) {
-          contributions.push({
-            patch: patch.patch,
-            source: parentResolved.coverage.source,
-            strict: parentResolved.coverage.strict,
-          });
-        }
-      }
-
-      if (index === targetEdgeIndex) {
-        const directPatch = resolveChildSchemaPatch(slot, use);
-        if (directPatch) {
-          contributions.push({
-            patch: directPatch,
-            source: parentResolved.coverage.source,
-            strict: parentResolved.coverage.strict,
-          });
-        }
-      }
-    }
-
-    return contributions;
-  }
-
-  private collectModelDynamicHints(use: string, modelClass: ModelConstructor, meta: FlowModelMeta): FlowDynamicHint[] {
-    const hints: FlowDynamicHint[] = [];
-    if (typeof meta.children === 'function') {
-      hints.push(
-        createFlowHint(
-          {
-            kind: 'dynamic-children',
-            path: `${use}.meta.children`,
-            message: `${use} uses function-based children and only static slot hints are available.`,
-          },
-          {
-            unresolvedReason: 'function-children',
-          },
-        ),
-      );
-    }
-    if (typeof meta.createModelOptions === 'function') {
-      hints.push(
-        createFlowHint(
-          {
-            kind: 'dynamic-children',
-            path: `${use}.meta.createModelOptions`,
-            message: `${use} uses function-based createModelOptions and may need manual sub-model slot schema.`,
-          },
-          {
-            unresolvedReason: 'function-create-model-options',
-          },
-        ),
-      );
-    }
-    if (typeof (modelClass as any).defineChildren === 'function') {
-      hints.push(
-        createFlowHint(
-          {
-            kind: 'dynamic-children',
-            path: `${use}.defineChildren`,
-            message: `${use} defines dynamic children. Schema generation only keeps static baseline.`,
-          },
-          {
-            unresolvedReason: 'runtime-define-children',
-          },
-        ),
-      );
-    }
-    return hints;
-  }
-
-  private collectFlowSchemaDiagnostics(use: string): {
-    hints: FlowDynamicHint[];
-    statuses: FlowSchemaCoverage['status'][];
-  } {
-    const registered = this.modelSchemas.get(use);
-    const modelClass = registered?.modelClass as any;
-    const flowsMap = modelClass?.globalFlowRegistry?.getFlows?.() as Map<string, any> | undefined;
-    if (!flowsMap?.size) {
-      return {
-        hints: [],
-        statuses: [],
-      };
-    }
-
-    const hints: FlowDynamicHint[] = [];
-    const statuses: FlowSchemaCoverage['status'][] = [];
-    for (const [flowKey, flowDef] of flowsMap.entries()) {
-      for (const [stepKey, stepDef] of Object.entries(flowDef?.steps || {})) {
-        const resolved = this.resolveStepParamsSchema(stepDef as StepDefinition, `${use}.${flowKey}.${stepKey}`);
-        if (resolved.hints?.length) {
-          hints.push(...resolved.hints);
-        }
-        statuses.push(resolved.coverage);
-      }
-    }
-
-    return {
-      hints: normalizeSchemaHints(hints),
-      statuses,
-    };
-  }
-
-  private buildDocumentCoverage(
-    base: FlowSchemaCoverage,
-    stepStatuses: FlowSchemaCoverage['status'][],
-  ): FlowSchemaCoverage {
-    const statuses = new Set<FlowSchemaCoverage['status']>([base.status, ...stepStatuses].filter(Boolean));
-
-    let status: FlowSchemaCoverage['status'] = base.status;
-    if (statuses.size > 1) {
-      statuses.delete('unresolved');
-      if (statuses.size === 0) {
-        status = 'unresolved';
-      } else {
-        status = 'mixed';
-      }
-    } else if (statuses.size === 1) {
-      status = (Array.from(statuses)[0] || 'unresolved') as FlowSchemaCoverage['status'];
-    }
-
-    return {
-      ...base,
-      status,
-    };
-  }
-
-  private inferSubModelSlotsFromModelClass(
-    use: string,
-    modelClass: ModelConstructor,
-  ): Record<string, FlowSubModelSlotSchema> {
-    const meta = (((modelClass as any).meta || {}) as FlowModelMeta).schema;
-    if (meta?.subModelSlots) {
-      return _.cloneDeep(meta.subModelSlots);
-    }
-
-    const createModelOptions = ((modelClass as any).meta || {}).createModelOptions;
-    if (!_.isPlainObject(createModelOptions) || !_.isPlainObject((createModelOptions as any).subModels)) {
-      return {};
-    }
-
-    const slots: Record<string, FlowSubModelSlotSchema> = {};
-    for (const [slotKey, slotValue] of Object.entries((createModelOptions as any).subModels || {})) {
-      if (Array.isArray(slotValue)) {
-        const first = slotValue[0] as any;
-        slots[slotKey] = {
-          type: 'array',
-          ...(typeof first?.use === 'string' ? { use: first.use } : {}),
-        };
-      } else if (_.isPlainObject(slotValue)) {
-        slots[slotKey] = {
-          type: 'object',
-          ...((slotValue as any).use ? { use: (slotValue as any).use } : {}),
-        };
-      } else {
-        slots[slotKey] = {
-          type: 'object',
-        };
-      }
-    }
-    return slots;
-  }
-}