@api-client/core 0.19.0 → 0.19.2

package/src/modeling/ai/DataDomainDelta.ts

@@ -0,0 +1,798 @@
+import type { DataDomain } from '@api-client/core/modeling/DataDomain.js'
+import type {
+  AiDataModelSchema,
+  AiDomainAssociation,
+  AiDomainAssociationDelta,
+  AiDomainDelta,
+  AiDomainEntityDelta,
+  AiDomainEntityResponseSchema,
+  AiDomainProperty,
+  AiDomainPropertyDelta,
+  AiDomainSemantic,
+} from './types.js'
+import type {
+  DomainAssociation,
+  DomainEntity,
+  DomainEntitySchema,
+  DomainModel,
+  DomainProperty,
+} from '@api-client/core/modeling/index.js'
+import { nanoid } from '@api-client/core/nanoid.js'
+import { type SemanticType, SemanticScope, DataSemantics } from '@api-client/core/modeling/Semantics.js'
+import { DomainEntityKind, DomainPropertyKind, DomainAssociationKind } from '@api-client/core/models/kinds.js'
+
+/**
+ * Normalizes the delta by removing duplicates. For example, when the model
+ * adds and entity more than once to the `modifiedEntities` array, This will merge all the changes into a single entity.
+ * @param delta The delta to normalize.
+ * @returns The normalized delta.
+ */
+function mergeArrayByKey<T>(
+  items: T[] | undefined,
+  mergeFn: (a: T, b: T) => void,
+  keyProp: keyof T = 'key' as keyof T
+): T[] | undefined {
+  if (!items || items.length === 0) return items
+  const map = new Map<unknown, T>()
+  const result: T[] = []
+  for (const item of items) {
+    const k = item[keyProp]
+    if (!k) {
+      result.push({ ...item })
+      continue
+    }
+    const existing = map.get(k)
+    if (existing) {
+      mergeFn(existing, item)
+    } else {
+      const copy = { ...item }
+      map.set(k, copy)
+      result.push(copy)
+    }
+  }
+  return result
+}
+
+/**
+ * A utility class responsible for applying AI-generated modifications (deltas)
+ * to an existing `DataDomain` model. It handles adding, modifying, and deleting
+ * entities, properties, associations, semantics, and models based on the
+ * prescribed changes.
+ *
+ * It also maintains a mapping of AI-generated provisional keys to the
+ * actual nanoid keys used within the data domain to ensure references remain intact.
+ */
+export class DataDomainDelta {
+  /**
+   * The data domain to which the delta will be applied.
+   */
+  protected domain: DataDomain
+
+  /**
+   * The map containing the mappings of AI generated keys to proper nanoids.
+   */
+  protected keyMap: Map<string, string>
+
+  /**
+   * Initializes a new instance of the `DataDomainDelta` class.
+   *
+   * @param domain The target data domain where changes will be applied.
+   * @param keyMap An optional map tracking AI-generated provisional keys to actual domain nanoids.
+   */
+  constructor(domain: DataDomain, keyMap = new Map<string, string>()) {
+    this.domain = domain
+    this.keyMap = keyMap
+  }
+
+  /**
+   * Applies the entire given delta structure to the data domain in a single pass.
+   * Operations include processing added/modified/deleted components across
+   * models, entities, properties, associations, and semantics.
+   *
+   * @param delta The AI-generated delta schema containing all requested changes.
+   */
+  apply(delta: AiDomainDelta): void {
+    if (delta.addedModels) {
+      for (const m of delta.addedModels) {
+        const existing = this.domain.findModel(this.keyMap.get(m.key) || m.key)
+        if (!existing) {
+          let newKey = this.keyMap.get(m.key)
+          if (!newKey) {
+            newKey = nanoid()
+            this.keyMap.set(m.key, newKey)
+          }
+          this.domain.addModel({ key: newKey, info: { name: m.name, description: m.description } })
+        }
+      }
+    }
+
+    if (delta.modifiedModels) {
+      for (const mod of delta.modifiedModels) {
+        const actualKey = this.keyMap.get(mod.key) || mod.key
+        const model = this.domain.findModel(actualKey)
+        if (model) {
+          if (mod.name !== undefined) model.info.name = mod.name
+          if (mod.description !== undefined) model.info.description = mod.description
+        }
+      }
+    }
+
+    if (delta.addedEntities) {
+      for (const e of delta.addedEntities) {
+        this.handleAddEntity(this.domain, e)
+      }
+    }
+
+    if (delta.deletedEntityKeys) {
+      for (const key of delta.deletedEntityKeys) {
+        const actualKey = this.keyMap.get(key) || key
+        this.domain.removeEntity(actualKey)
+      }
+    }
+
+    if (delta.modifiedEntities) {
+      for (const mod of delta.modifiedEntities) {
+        const actualEntityKey = this.keyMap.get(mod.key) || mod.key
+        const entity = this.domain.findEntity(actualEntityKey)
+        if (!entity) {
+          continue
+        }
+
+        if (mod.modelKey) {
+          const currentModel = entity.getParentInstance() as DomainModel
+          const actualModelKey = this.keyMap.get(mod.modelKey) || mod.modelKey
+          if (currentModel.key !== actualModelKey && currentModel.info.name !== mod.modelKey) {
+            const newModel = this.getModel(this.domain, actualModelKey)
+            newModel.attachEntity(entity.key)
+          }
+        }
+
+        if (mod.name) entity.info.name = mod.name
+        if (mod.displayName) entity.info.displayName = mod.displayName
+        if (mod.description) entity.info.description = mod.description
+
+        this.applySemantics(entity, mod.addedSemantics, mod.modifiedSemantics, mod.deletedSemanticIds)
+
+        this.handlePropertyAdds(entity, mod.addedProperties)
+        this.handlePropertyDeletes(this.domain, mod.deletedPropertyKeys)
+        this.handlePropertyMods(this.domain, mod.modifiedProperties)
+        this.handleAssociationAdds(entity, mod.addedAssociations)
+        this.handleAssociationDeletes(this.domain, mod.deletedAssociationKeys)
+        this.handleAssociationMods(this.domain, mod.modifiedAssociations)
+      }
+    }
+
+    if (delta.deletedModelKeys) {
+      for (const key of delta.deletedModelKeys) {
+        const actualKey = this.keyMap.get(key) || key
+        try {
+          this.domain.removeModel(actualKey)
+        } catch {
+          // ignore
+        }
+      }
+    }
+  }
+
+  /**
+   * Internal handler to add a new entity to the data domain based on the provided schema.
+   * It also recursively handles adding the entity's semantics, properties, and associations.
+   *
+   * @param domain The data domain where the entity will reside.
+   * @param e The schema definition of the entity to be added.
+   */
+  protected handleAddEntity(domain: DataDomain, e: AiDomainEntityResponseSchema): void {
+    const targetModel = this.getModel(domain, e.modelKey || 'ai_generated')
+    const entityInput = { ...e }
+    delete entityInput.semantics
+    let entityKey = this.keyMap.get(e.key)
+    if (!entityKey) {
+      entityKey = nanoid()
+      this.keyMap.set(e.key, entityKey)
+    }
+
+    const entityInfo: Partial<DomainEntitySchema> = {
+      ...entityInput,
+      key: entityKey,
+      info: {
+        name: e.name,
+        displayName: e.displayName,
+        description: e.description,
+      },
+    }
+    const createdEntity = targetModel.addEntity(entityInfo)
+    this.applySemantics(createdEntity, e.semantics)
+    if (e.properties) {
+      for (const p of e.properties) {
+        this.handleAddProperty(createdEntity, p)
+      }
+    }
+    if (e.associations) {
+      for (const a of e.associations) {
+        this.handleAddAssociation(createdEntity, a)
+      }
+    }
+  }
+
+  /**
+   * Processes an array of newly added properties for a specific entity.
+   *
+   * @param entity The target domain entity to receive the new properties.
+   * @param adds The list of property definitions to add, if any.
+   */
+  protected handlePropertyAdds(entity: DomainEntity, adds?: AiDomainProperty[]): void {
+    if (!adds) {
+      return
+    }
+    for (const p of adds) {
+      this.handleAddProperty(entity, p)
+    }
+  }
+
+  /**
+   * Internal handler to add a single property to an entity, generating keys
+   * and applying semantics as defined in the AI schema.
+   *
+   * @param entity The target domain entity.
+   * @param p The schema definition of the property to add.
+   */
+  protected handleAddProperty(entity: DomainEntity, p: AiDomainProperty): void {
+    let propKey = p.key ? this.keyMap.get(p.key) : undefined
+    if (!propKey) {
+      propKey = nanoid()
+      if (p.key) {
+        this.keyMap.set(p.key, propKey)
+      }
+    }
+    const prop = entity.addProperty({
+      key: propKey,
+      type: p.type,
+      info: {
+        name: p.name,
+        displayName: p.displayName,
+        description: p.description,
+      },
+      required: p.constraints?.required,
+      unique: p.constraints?.unique,
+      index: p.constraints?.index,
+      primary: p.constraints?.primary,
+      multiple: p.constraints?.multiple,
+      readOnly: p.constraints?.readOnly,
+      writeOnly: p.constraints?.writeOnly,
+      deprecated: p.deprecated,
+      schema: p.schema,
+      tags: p.tags,
+    })
+    this.applySemantics(prop, p.semantics)
+  }
+
+  /**
+   * Processes the deletion of properties by their keys from the given domain.
+   * Fails silently if a key is not found, maintaining fault tolerance.
+   *
+   * @param domain The target data domain.
+   * @param keys The array of property keys (AI-generated or actual) to remove.
+   */
+  handlePropertyDeletes(domain: DataDomain, keys?: string[]): void {
+    if (!keys) {
+      return
+    }
+    for (const key of keys) {
+      const actualKey = this.keyMap.get(key) || key
+      try {
+        domain.removeProperty(actualKey)
+      } catch {
+        // we can ignore in case the model got the wrong key.
+      }
+    }
+  }
+
+  /**
+   * Processes modifications to existing properties within the domain, updating
+   * specific metadata, constraints, schema rules, and semantics based on the delta.
+   *
+   * @param domain The target data domain.
+   * @param mods The list of property modifications to apply.
+   */
+  handlePropertyMods(domain: DataDomain, mods?: AiDomainPropertyDelta[]): void {
+    if (!mods) {
+      return
+    }
+    for (const mod of mods) {
+      const actualKey = this.keyMap.get(mod.key) || mod.key
+      const prop = domain.findProperty(actualKey)
+      if (!prop) {
+        continue
+      }
+      if (mod.name) {
+        prop.info.name = mod.name
+      }
+      if (mod.displayName) {
+        prop.info.displayName = mod.displayName
+      }
+      if (mod.description) {
+        prop.info.description = mod.description
+      }
+      if (mod.type) {
+        prop.type = mod.type
+      }
+      if (mod.deprecated !== undefined) {
+        prop.deprecated = mod.deprecated
+      }
+      if (mod.constraints) {
+        if (mod.constraints.required !== undefined) {
+          prop.required = mod.constraints.required
+        }
+        if (mod.constraints.unique !== undefined) {
+          prop.unique = mod.constraints.unique
+        }
+        if (mod.constraints.index !== undefined) {
+          prop.index = mod.constraints.index
+        }
+        if (mod.constraints.primary !== undefined) {
+          prop.primary = mod.constraints.primary
+        }
+        if (mod.constraints.multiple !== undefined) {
+          prop.multiple = mod.constraints.multiple
+        }
+        if (mod.constraints.readOnly !== undefined) {
+          prop.readOnly = mod.constraints.readOnly
+        }
+        if (mod.constraints.writeOnly !== undefined) {
+          prop.writeOnly = mod.constraints.writeOnly
+        }
+      }
+      if (mod.schema) {
+        if (!prop.schema) {
+          prop.schema = {}
+        }
+        if (mod.schema.defaultValue) {
+          if (!prop.schema.defaultValue) {
+            prop.schema.defaultValue = {
+              value: '',
+              type: 'literal',
+            }
+          }
+          if (mod.schema.defaultValue.type) {
+            prop.schema.defaultValue.type = mod.schema.defaultValue.type
+          }
+          if (mod.schema.defaultValue.value) {
+            prop.schema.defaultValue.value = mod.schema.defaultValue.value
+          }
+        }
+        if (mod.schema.pattern !== undefined) {
+          prop.schema.pattern = mod.schema.pattern
+        }
+        if (mod.schema.minimum !== undefined) {
+          prop.schema.minimum = mod.schema.minimum
+        }
+        if (mod.schema.maximum !== undefined) {
+          prop.schema.maximum = mod.schema.maximum
+        }
+        if (mod.schema.exclusiveMinimum !== undefined) {
+          prop.schema.exclusiveMinimum = mod.schema.exclusiveMinimum
+        }
+        if (mod.schema.exclusiveMaximum !== undefined) {
+          prop.schema.exclusiveMaximum = mod.schema.exclusiveMaximum
+        }
+        if (mod.schema.multipleOf !== undefined) {
+          prop.schema.multipleOf = mod.schema.multipleOf
+        }
+        if (mod.schema.enum !== undefined) {
+          prop.schema.enum = [...mod.schema.enum]
+        }
+        if (mod.schema.examples !== undefined) {
+          prop.schema.examples = [...mod.schema.examples]
+        }
+      }
+      this.applySemantics(prop, mod.addedSemantics, mod.modifiedSemantics, mod.deletedSemanticIds)
+    }
+  }
+
+  /**
+   * Processes an array of newly added associations for a specific entity.
+   *
+   * @param entity The target domain entity referencing the newly created associations.
+   * @param adds An array of association definitions to add, if any.
+   */
+  handleAssociationAdds(entity: DomainEntity, adds: AiDomainAssociation[] | undefined): void {
+    if (!adds) {
+      return
+    }
+    for (const a of adds) {
+      this.handleAddAssociation(entity, a)
+    }
+  }
+
+  /**
+   * Internal handler to append a single association to an entity, effectively creating
+   * a relationship to one or more targets. Attempts an optimized exact O(1) loopup
+   * before falling back to a full domain search.
+   *
+   * @param entity The source domain entity creating the association.
+   * @param a The defining schema for the new association.
+   */
+  handleAddAssociation(entity: DomainEntity, a: AiDomainAssociation): void {
+    let assocKey = this.keyMap.get(a.key)
+    if (!assocKey) {
+      assocKey = nanoid()
+      this.keyMap.set(a.key, assocKey)
+    }
+    const assoc = entity.addAssociation({
+      key: assocKey,
+      info: { name: a.name, displayName: a.displayName, description: a.description },
+      required: a.required,
+      multiple: a.multiple,
+      onDelete: a.onDelete,
+      schema: a.schema,
+    })
+    if (a.targets) {
+      for (const t of a.targets) {
+        const actualTargetKey = this.keyMap.get(t.key) || t.key
+        // 1. Try exact match by key
+        const exactMatch = entity.domain.findEntity(actualTargetKey)
+        if (exactMatch) {
+          if (exactMatch.namespace !== entity.domain.key) {
+            assoc.addTarget(exactMatch.key, exactMatch.namespace)
+          } else {
+            assoc.addTarget(exactMatch.key)
+          }
+        } else {
+          // 2. Try name/display name search
+          const target = entity.domain.search({
+            query: actualTargetKey,
+            includeForeignDomains: true,
+            nodeTypes: [DomainEntityKind],
+          })
+          if (target.length > 0) {
+            const found = target[0]
+            if (found.isForeign) {
+              assoc.addTarget(found.key, found.node.namespace)
+            } else {
+              assoc.addTarget(found.key)
+            }
+          } else {
+            assoc.addTarget(actualTargetKey)
+          }
+        }
+      }
+    }
+    this.applySemantics(assoc, a.semantics)
+  }
+
+  /**
+   * Processes the deletion of associations by their keys from the given domain.
+   * Safely ignores errors if the specified association does not exist.
+   *
+   * @param domain The target data domain.
+   * @param keys An array of association keys to safely remove.
+   */
+  handleAssociationDeletes(domain: DataDomain, keys?: string[]): void {
+    if (!keys) {
+      return
+    }
+    for (const key of keys) {
+      const actualKey = this.keyMap.get(key) || key
+      try {
+        domain.removeAssociation(actualKey)
+      } catch {
+        // we can ignore in case the model got the wrong key.
+      }
+    }
+  }
+
+  /**
+   * Processes modifications to existing associations within the domain.
+   * Updates attributes, semantics, and handles adding/replacing association targets.
+   *
+   * @param domain The target data domain containing the associations.
+   * @param mods An array of requested association modifications.
+   */
+  handleAssociationMods(domain: DataDomain, mods: AiDomainAssociationDelta[] | undefined): void {
+    if (!mods) {
+      return
+    }
+    for (const mod of mods) {
+      const actualKey = this.keyMap.get(mod.key) || mod.key
+      const assoc = domain.findAssociation(actualKey)
+      if (!assoc) {
+        continue
+      }
+      if (mod.name) {
+        assoc.info.name = mod.name
+      }
+      if (mod.displayName) {
+        assoc.info.displayName = mod.displayName
+      }
+      if (mod.description) {
+        assoc.info.description = mod.description
+      }
+      if (mod.required !== undefined) {
+        assoc.required = mod.required
+      }
+      if (mod.onDelete !== undefined) {
+        assoc.onDelete = mod.onDelete
+      }
+
+      if (mod.targets) {
+        // Clear existing targets before adding new ones
+        assoc.targets.splice(0, assoc.targets.length)
+        for (const t of mod.targets) {
+          const actualTargetKey = this.keyMap.get(t.key) || t.key
+          // 1. Try exact match by key
+          const exactMatch = domain.findEntity(actualTargetKey)
+          if (exactMatch) {
+            if (exactMatch.namespace !== domain.key) {
+              assoc.addTarget(exactMatch.key, exactMatch.namespace)
+            } else {
+              assoc.addTarget(exactMatch.key)
+            }
+          } else {
+            // 2. Try name/display name search
+            const targetSearch = domain.search({
+              query: actualTargetKey,
+              includeForeignDomains: true,
+              nodeTypes: [DomainEntityKind],
+            })
+            if (targetSearch.length > 0) {
+              const found = targetSearch[0]
+              if (found.isForeign) {
+                assoc.addTarget(found.key, found.node.namespace)
+              } else {
+                assoc.addTarget(found.key)
+              }
+            } else {
+              assoc.addTarget(actualTargetKey)
+            }
+          }
+        }
+      }
+      this.applySemantics(assoc, mod.addedSemantics, mod.modifiedSemantics, mod.deletedSemanticIds)
+    }
+  }
+
+  /**
+   * Retrieves an existing `DomainModel` by its given key. If the model
+   * does not exist in the domain (e.g., AI generated a brand new model name natively),
+   * a newly instantiated one is created and registered within the domain automatically.
+   *
+   * @param domain The target data domain.
+   * @param modelKey The AI-suggested or actual nanoid key of the model.
+   * @returns The resolved or newly created `DomainModel`.
+   */
+  protected getModel(domain: DataDomain, modelKey: string): DomainModel {
+    const mappedKey = this.keyMap.get(modelKey) || modelKey
+    let m = domain.findModel(mappedKey)
+    if (!m) {
+      // AI generated a new model name (like "shipping"). Use it as the name, let core generate the nanoid key.
+      const newKey = this.keyMap.get(modelKey) || nanoid()
+      this.keyMap.set(modelKey, newKey)
+      m = domain.addModel({ key: newKey, info: { name: modelKey } })
+    }
+    return m
+  }
+
+  /**
+   * Helper function to batch apply semantic patches (add, modify, delete)
+   * to a specific domain component (Entity, Property, or Association).
+   * Validates semantic scopes heavily before applying.
+   *
+   * @param target The domain element (Entity, Property, Association) to receive the semantics.
+   * @param added List of semantic blocks to newly append.
+   * @param modified List of existing semantics to override/update.
+   * @param deleted Array of semantic IDs indicating removals.
+   */
+  protected applySemantics(
+    target: DomainEntity | DomainProperty | DomainAssociation,
+    added?: AiDomainSemantic[],
+    modified?: AiDomainSemantic[],
+    deleted?: SemanticType[]
+  ): void {
+    // Determine the expected scope for the target
+    let expectedScope: SemanticScope
+    if (target.kind === DomainEntityKind) {
+      expectedScope = SemanticScope.Entity
+    } else if (target.kind === DomainPropertyKind) {
+      expectedScope = SemanticScope.Property
+    } else if (target.kind === DomainAssociationKind) {
+      expectedScope = SemanticScope.Association
+    } else {
+      throw new Error(`Unsupported target kind for semantics: ${(target as { kind: string }).kind}`)
+    }
+
+    const isValidSemantic = (id: SemanticType): boolean => {
+      const semanticDef = DataSemantics[id]
+      if (!semanticDef) {
+        return false
+      }
+      if (semanticDef.scope !== expectedScope) {
+        return false
+      }
+      return true
+    }
+
+    if (added) {
+      for (const s of added) {
+        const typeId = this.ensureSemanticId(s.id)
+        if (isValidSemantic(typeId)) {
+          target.addSemantic({ id: typeId, config: s.config })
+        }
+      }
+    }
+    if (modified) {
+      for (const s of modified) {
+        const typeId = this.ensureSemanticId(s.id)
+        if (isValidSemantic(typeId)) {
+          // Technically addSemantic overrides existing if they have the same ID
+          target.addSemantic({ id: typeId, config: s.config })
+        }
+      }
+    }
+    if (deleted) {
+      for (const id of deleted) {
+        const typeId = this.ensureSemanticId(id)
+        if (isValidSemantic(typeId)) {
+          target.removeSemantic(typeId)
+        }
+      }
+    }
+  }
+
+  /**
+   * Forces the given semantic ID to follow the structured format `Semantic#{id}`.
+   *
+   * @param id The raw semantic string given by the LLM/Delta payload.
+   * @returns The corrected semantic ID structured for internal parsing.
+   */
+  protected ensureSemanticId(id: string): SemanticType {
+    let result = id
+    if (!id.startsWith('Semantic#')) {
+      result = `Semantic#${id}`
+    }
+    return result as SemanticType
+  }
+
+  /**
+   * Normalizes the delta by removing duplicates. For example, when the model
+   * adds an entity more than once to the `modifiedEntities` array, this will merge all the changes
+   * into a single entity.
+   * @param delta The delta to normalize.
+   * @returns The normalized delta.
+   */
+  static normalize(delta: AiDomainDelta): AiDomainDelta {
+    const result: AiDomainDelta = { ...delta }
+
+    const mergeProperties = (
+      a: AiDomainProperty | AiDomainPropertyDelta,
+      b: AiDomainProperty | AiDomainPropertyDelta
+    ) => {
+      const aConstraints = a.constraints
+      Object.assign(a, b)
+      if (aConstraints && b.constraints) {
+        a.constraints = { ...aConstraints, ...b.constraints }
+      }
+    }
+
+    const mergeAssociations = (
+      a: AiDomainAssociation | AiDomainAssociationDelta,
+      b: AiDomainAssociation | AiDomainAssociationDelta
+    ) => {
+      Object.assign(a, b)
+    }
+
+    const mergeSemantics = (a: AiDomainSemantic, b: AiDomainSemantic) => {
+      const aConfig = a.config
+      Object.assign(a, b)
+      if (aConfig && b.config) {
+        a.config = { ...aConfig, ...b.config }
+      }
+    }
+
+    const mergeEntities = (a: AiDomainEntityResponseSchema, b: AiDomainEntityResponseSchema) => {
+      const aTags = a.tags
+      const aProps = a.properties
+      const aAssoc = a.associations
+      const aSem = a.semantics
+
+      Object.assign(a, b)
+
+      if (aTags && b.tags) {
+        a.tags = Array.from(new Set([...aTags, ...b.tags]))
+      }
+
+      if (aProps || b.properties) {
+        a.properties = mergeArrayByKey([...(aProps || []), ...(b.properties || [])], mergeProperties)
+      }
+      if (aAssoc || b.associations) {
+        a.associations = mergeArrayByKey([...(aAssoc || []), ...(b.associations || [])], mergeAssociations)
+      }
+      if (aSem || b.semantics) {
+        a.semantics = mergeArrayByKey([...(aSem || []), ...(b.semantics || [])], mergeSemantics, 'id')
+      }
+    }
+
+    const mergeEntityDeltas = (a: AiDomainEntityDelta, b: AiDomainEntityDelta) => {
+      const aTags = a.tags
+      const aAddedProps = a.addedProperties
+      const aModProps = a.modifiedProperties
+      const aDelProps = a.deletedPropertyKeys
+      const aAddedAssoc = a.addedAssociations
+      const aModAssoc = a.modifiedAssociations
+      const aDelAssoc = a.deletedAssociationKeys
+      const aAddedSem = a.addedSemantics
+      const aModSem = a.modifiedSemantics
+      const aDelSem = a.deletedSemanticIds
+
+      Object.assign(a, b)
+
+      if (aTags && b.tags) {
+        a.tags = Array.from(new Set([...aTags, ...b.tags]))
+      }
+
+      if (aAddedProps || b.addedProperties) {
+        a.addedProperties = mergeArrayByKey([...(aAddedProps || []), ...(b.addedProperties || [])], mergeProperties)
+      }
+      if (aModProps || b.modifiedProperties) {
+        a.modifiedProperties = mergeArrayByKey([...(aModProps || []), ...(b.modifiedProperties || [])], mergeProperties)
+      }
+      if (aDelProps && b.deletedPropertyKeys) {
+        a.deletedPropertyKeys = Array.from(new Set([...aDelProps, ...b.deletedPropertyKeys]))
+      }
+
+      if (aAddedAssoc || b.addedAssociations) {
+        a.addedAssociations = mergeArrayByKey(
+          [...(aAddedAssoc || []), ...(b.addedAssociations || [])],
+          mergeAssociations
+        )
+      }
+      if (aModAssoc || b.modifiedAssociations) {
+        a.modifiedAssociations = mergeArrayByKey(
+          [...(aModAssoc || []), ...(b.modifiedAssociations || [])],
+          mergeAssociations
+        )
+      }
+      if (aDelAssoc && b.deletedAssociationKeys) {
+        a.deletedAssociationKeys = Array.from(new Set([...aDelAssoc, ...b.deletedAssociationKeys]))
+      }
+
+      if (aAddedSem || b.addedSemantics) {
+        a.addedSemantics = mergeArrayByKey([...(aAddedSem || []), ...(b.addedSemantics || [])], mergeSemantics, 'id')
+      }
+      if (aModSem || b.modifiedSemantics) {
+        a.modifiedSemantics = mergeArrayByKey(
+          [...(aModSem || []), ...(b.modifiedSemantics || [])],
+          mergeSemantics,
+          'id'
+        )
+      }
+      if (aDelSem && b.deletedSemanticIds) {
+        a.deletedSemanticIds = Array.from(new Set([...aDelSem, ...b.deletedSemanticIds]))
+      }
+    }
+
+    const mergeModels = (a: AiDataModelSchema, b: AiDataModelSchema) => {
+      Object.assign(a, b)
+    }
+
+    if (result.addedEntities) {
+      result.addedEntities = mergeArrayByKey(result.addedEntities, mergeEntities)
+    }
+    if (result.modifiedEntities) {
+      result.modifiedEntities = mergeArrayByKey(result.modifiedEntities, mergeEntityDeltas)
+    }
+    if (result.addedModels) {
+      result.addedModels = mergeArrayByKey(result.addedModels, mergeModels)
+    }
+    if (result.modifiedModels) {
+      result.modifiedModels = mergeArrayByKey(result.modifiedModels, mergeModels)
+    }
+    if (result.deletedModelKeys) {
+      result.deletedModelKeys = Array.from(new Set(result.deletedModelKeys))
+    }
+    if (result.deletedEntityKeys) {
+      result.deletedEntityKeys = Array.from(new Set(result.deletedEntityKeys))
+    }
+
+    return result
+  }
+}