@memberjunction/core 4.0.0 → 4.1.0

package/dist/generic/baseEntity.js

@@ -1,6 +1,6 @@
 import { MJEventType, MJGlobal, uuidv4, WarningManager } from '@memberjunction/global';
 import { EntityFieldInfo, EntityInfo, EntityFieldTSType, EntityPermissionType, RecordChange, ValidationErrorInfo, ValidationResult } from './entityInfo.js';
-import { EntitySaveOptions } from './interfaces.js';
+import { EntityDeleteOptions, EntitySaveOptions, ProviderType } from './interfaces.js';
 import { Metadata } from './metadata.js';
 import { RunView } from '../views/runView.js';
 import { LogDebug, LogError } from './logging.js';
@@ -466,6 +466,22 @@ export class BaseEntityEvent {
  * Base class used for all entity objects. This class is abstract and is sub-classes for each particular entity using the CodeGen tool. This class provides the basic functionality for loading, saving, and validating entity objects.
  */
 export class BaseEntity {
+    /**
+     * Gets the provider transaction handle for IS-A chain orchestration.
+     */
+    get ProviderTransaction() { return this._providerTransaction; }
+    /**
+     * Sets the provider transaction handle. Used during IS-A save/delete to share
+     * a single database transaction across the entire parent chain.
+     */
+    set ProviderTransaction(value) { this._providerTransaction = value; }
+    /**
+     * Returns the parent entity in the IS-A composition chain, or null if this
+     * entity is not an IS-A child type. Read-only public access for inspection.
+     * Named ISAParentEntity to avoid collision with generated Entity.ParentEntity
+     * string column (which contains the parent entity's name from the view).
+     */
+    get ISAParentEntity() { return this._parentEntity; }
     constructor(Entity, Provider = null) {
         this._Fields = [];
         this._recordLoaded = false;
@@ -476,6 +492,33 @@ export class BaseEntity {
         this._everSaved = false;
         this._isLoading = false;
         this._pendingDelete$ = null;
+        /**************************************************************************
+         * IS-A Type Relationship — Parent Entity Composition
+         *
+         * For IS-A child entities, _parentEntity holds a persistent live reference
+         * to the parent entity instance. All data routing (Set/Get), dirty tracking,
+         * validation, and save/delete orchestration flow through this composition chain.
+         **************************************************************************/
+        /**
+         * Persistent reference to the parent entity in the IS-A chain.
+         * For example, if MeetingEntity IS-A ProductEntity, the MeetingEntity instance
+         * holds a reference to a ProductEntity instance here. This is null for entities
+         * that are not IS-A child types.
+         */
+        this._parentEntity = null;
+        /**
+         * Cached set of field names that belong to parent entities — used for
+         * efficient O(1) lookup during Set/Get routing to determine if a field
+         * should be forwarded to _parentEntity.
+         */
+        this._parentEntityFieldNames = null;
+        /**
+         * Opaque provider-level transaction handle. Used by IS-A save/delete orchestration
+         * to share a single SQL transaction across the parent chain.
+         * On client (GraphQLDataProvider), this remains null.
+         * On server (SQLServerDataProvider), this holds a sql.Transaction.
+         */
+        this._providerTransaction = null;
         this._compositeKey = null;
         // Holds the current pending save observable (if any)
         this._pendingSave$ = null;
@@ -491,6 +534,76 @@ export class BaseEntity {
         this._provider = Provider;
         this.init();
     }
+    /**
+     * Initializes the IS-A parent entity composition chain. For child type entities,
+     * this creates the parent entity instance (and recursively its parent, etc.) and
+     * caches the parent field name set for routing.
+     *
+     * Must be called AFTER EntityInfo is available but BEFORE any Load/NewRecord/Set/Get.
+     * This is called by Metadata.GetEntityObject() after constructing the entity.
+     */
+    async InitializeParentEntity() {
+        if (!this.EntityInfo?.IsChildType)
+            return;
+        const md = new Metadata();
+        const parentEntityInfo = this.EntityInfo.ParentEntityInfo;
+        if (!parentEntityInfo)
+            return;
+        // Create the parent entity via Metadata to ensure proper class factory resolution
+        this._parentEntity = await md.GetEntityObject(parentEntityInfo.Name, this._contextCurrentUser);
+        // Recursive: the parent's InitializeParentEntity() was called by GetEntityObject()
+        // Cache the parent field names for O(1) routing lookups
+        this._parentEntityFieldNames = this.EntityInfo.ParentEntityFieldNames;
+    }
+    /**
+     * Resets this entity to a pristine state and populates it from the provided data object.
+     *
+     * Unlike {@link SetMany}, which incrementally updates existing field values, `Hydrate()`
+     * first resets ALL internal state — fields, composite key cache, loaded/saved flags —
+     * then populates from the provided data as if loading a fresh record from the database.
+     *
+     * This is critical for IS-A (table-per-type) inheritance: when a child entity loads
+     * its record, parent entities in the chain must be fully reset and re-populated from
+     * the child's view data, including the shared primary key. After `init()`, each
+     * EntityField's `_NeverSet` flag is `true`, allowing even ReadOnly PK fields to be
+     * set exactly once via `SetMany`.
+     *
+     * After population, entities are automatically marked as saved/loaded when all PK
+     * values are present (via {@link UpdateSavedStateFromPrimaryKeys}).
+     *
+     * The parent chain is handled recursively: if this entity has an IS-A parent, the
+     * parent is hydrated first (deepest ancestor first) via SetMany's built-in routing.
+     *
+     * @param data - A plain object whose properties map to field names on this entity
+     *               (and potentially parent entities in the IS-A chain).
+     */
+    Hydrate(data) {
+        // Reset this entity to pristine state: clears _compositeKey, _recordLoaded,
+        // _everSaved, and recreates all EntityField instances with _NeverSet = true
+        this.init();
+        // Recursively hydrate parent entities first (deepest ancestor resets first).
+        // After init(), parent fields have fresh _NeverSet=true, so SetMany can set PKs.
+        if (this._parentEntity) {
+            this._parentEntity.Hydrate(data);
+        }
+        // Populate this entity's fields. SetMany also routes parent field values to
+        // _parentEntity via the IS-A routing block (which now includes PK fields).
+        // replaceOldValues=true ensures OldValue matches Value (no false dirty flags).
+        // ignoreNonExistentFields=true because data may contain fields from other
+        // entities in the chain that don't exist on this entity.
+        this.SetMany(data, true, true, true);
+    }
+    /**
+     * Propagates the ProviderTransaction handle down the IS-A parent chain so all
+     * entities in the chain execute on the same database transaction.
+     */
+    PropagateTransactionToParents() {
+        let current = this._parentEntity;
+        while (current) {
+            current.ProviderTransaction = this._providerTransaction;
+            current = current._parentEntity;
+        }
+    }
     /**
      * Returns this provider to be used for a given instance of a BaseEntity derived subclass. If the provider is not set, the BaseEntity.Provider is returned.
      */
@@ -750,7 +863,9 @@ export class BaseEntity {
      * Returns true if the object is Dirty, meaning something has changed since it was last saved to the database, and false otherwise. For new records, this will always return true.
      */
     get Dirty() {
-        return !this.IsSaved || this.Fields.some(f => f.Dirty);
+        return !this.IsSaved ||
+            this.Fields.some(f => f.Dirty) ||
+            (this._parentEntity?.Dirty ?? false);
     }
     /**
      * Returns an array of all primary key fields for the entity. If the entity has a composite primary key, this method will return an array of all primary key fields.
@@ -785,10 +900,30 @@ export class BaseEntity {
     /**
      * Sets the value of a given field. If the field doesn't exist, nothing happens.
      * The field's type is used to convert the value to the appropriate type.
+     *
+     * For IS-A child entities, parent fields are routed to `_parentEntity.Set()` (recursive
+     * for N-level chains). The value is also mirrored on the child's own virtual EntityField
+     * so that code iterating `entity.Fields` still sees it. The authoritative state for parent
+     * fields lives on `_parentEntity`.
+     *
      * @param FieldName
      * @param Value
      */
     Set(FieldName, Value) {
+        // IS-A routing: if this field belongs to a parent entity, route to parent
+        if (this._parentEntity && this._parentEntityFieldNames?.has(FieldName)) {
+            this._parentEntity.Set(FieldName, Value); // recursive for N-level chains
+            // Also mirror the value on our own virtual EntityField for UI compatibility
+            this.SetLocal(FieldName, Value);
+            return;
+        }
+        this.SetLocal(FieldName, Value);
+    }
+    /**
+     * Internal helper that sets a field value directly on THIS entity's own Fields array
+     * without IS-A routing. Used by Set() for own-fields and for mirroring parent field values.
+     */
+    SetLocal(FieldName, Value) {
         const field = this.GetFieldByName(FieldName);
         if (field != null) {
             if (field.EntityFieldInfo.TSType === EntityFieldTSType.Date && (typeof Value === 'string' || typeof Value === 'number')) {
@@ -829,10 +964,18 @@ export class BaseEntity {
     }
     /**
      * Returns the value of the field with the given name. If the field is a date, and the value is a string, it will be converted to a date object.
+     *
+     * For IS-A child entities, parent fields return the authoritative value from `_parentEntity.Get()`
+     * (recursive for N-level chains), NOT the mirrored value on the child's own Fields array.
+     *
      * @param FieldName
      * @returns
      */
     Get(FieldName) {
+        // IS-A routing: return the authoritative value from the parent entity
+        if (this._parentEntity && this._parentEntityFieldNames?.has(FieldName)) {
+            return this._parentEntity.Get(FieldName); // recursive for N-level chains
+        }
         const field = this.GetFieldByName(FieldName);
         if (field != null) {
             // if the field is a date and the value is a string, convert it to a date
@@ -847,6 +990,11 @@ export class BaseEntity {
      * NOTE: Do not call this method directly. Use the {@link From} method instead
      *
      * Sets any number of values on the entity object from the object passed in. The properties of the object being passed in must either match the field name (in most cases) or the CodeName (which is only different from field name if field name has spaces in it)
+     *
+     * For IS-A child entities, all fields are first set on self (including parent fields as mirrors),
+     * then parent fields are extracted and forwarded to `_parentEntity.SetMany()` for authoritative
+     * state, including proper OldValue tracking via the replaceOldValues parameter.
+     *
      * @param object
      * @param ignoreNonExistentFields - if set to true, fields that don't exist on the entity object will be ignored, if false, an error will be thrown if a field doesn't exist
      * @param replaceOldValues - if set to true, the old values of the fields will be reset to the values provided in the object parameter, if false, they will be left alone
@@ -863,7 +1011,8 @@ export class BaseEntity {
                 if (ignoreActiveStatusAssertions) {
                     field.ActiveStatusAssertions = false; // disable active status assertions for this field
                 }
-                this.Set(key, object[key]);
+                // Use SetLocal here so we set on OUR fields (mirrors for parent fields)
+                this.SetLocal(key, object[key]);
                 if (replaceOldValues) {
                     field.ResetOldValue();
                 }
@@ -880,7 +1029,8 @@ export class BaseEntity {
                     if (ignoreActiveStatusAssertions) {
                         field.ActiveStatusAssertions = false; // disable active status assertions for this field
                     }
-                    this.Set(field.Name, object[key]);
+                    // Use SetLocal here so we set on OUR fields (mirrors for parent fields)
+                    this.SetLocal(field.Name, object[key]);
                     if (replaceOldValues) {
                         field.ResetOldValue();
                     }
@@ -889,6 +1039,11 @@ export class BaseEntity {
                     }
                 }
                 else {
+                    // IS-A routing: parent fields may not have local mirrors (virtual EntityField records)
+                    // yet — they'll be handled by the IS-A routing block below, so skip the error/warning
+                    if (this._parentEntityFieldNames?.has(key)) {
+                        continue; // parent field — will be forwarded to _parentEntity below
+                    }
                     // if we get here, we have a field that doesn't match either the field name or the code name, so throw an error
                     if (!ignoreNonExistentFields)
                         throw new Error(`Field ${key} does not exist on ${this.EntityInfo.Name}`);
@@ -899,6 +1054,41 @@ export class BaseEntity {
                 }
             }
         }
+        // IS-A routing: forward parent fields to _parentEntity for authoritative state
+        // This ensures proper OldValue tracking and dirty flags on the parent entity
+        if (this._parentEntity && this._parentEntityFieldNames) {
+            const parentData = {};
+            for (const key of Object.keys(object)) {
+                if (this._parentEntityFieldNames.has(key)) {
+                    parentData[key] = object[key];
+                }
+            }
+            if (Object.keys(parentData).length > 0) {
+                this._parentEntity.SetMany(parentData, true, replaceOldValues, ignoreActiveStatusAssertions);
+            }
+        }
+        // When replaceOldValues is true, this is a load operation (not a user edit).
+        // If all primary keys are set, mark the entity as a saved record. This is critical
+        // for IS-A parent entities whose data is populated via SetMany routing from the child's
+        // load — without this, the parent would think it's a new record and attempt CREATE
+        // instead of UPDATE on save.
+        if (replaceOldValues) {
+            this.UpdateSavedStateFromPrimaryKeys();
+        }
+    }
+    /**
+     * Checks if all primary key fields have values set, and if so, marks the entity as
+     * a saved/loaded record. This enables entities populated via SetMany (e.g., IS-A parent
+     * entities) to correctly recognize themselves as existing records.
+     */
+    UpdateSavedStateFromPrimaryKeys() {
+        if (!this.PrimaryKeys || this.PrimaryKeys.length === 0)
+            return;
+        const allPKsSet = this.PrimaryKeys.every(pk => pk.Value !== null && pk.Value !== undefined);
+        if (allPKsSet) {
+            this._recordLoaded = true;
+            this._everSaved = true;
+        }
     }
     /**
      * NOTE: Do not call this method directly. Use the {@link To} method instead
@@ -922,6 +1112,13 @@ export class BaseEntity {
                 field.ActiveStatusAssertions = tempStatus; // restore the prior status for assertions
             }
         }
+        // IS-A composition: merge parent entity data with own data
+        // Parent data goes first, own fields override (for shared PK 'ID')
+        // Parent's GetAll() recursively collects from its own parent for N-level chains
+        if (this._parentEntity) {
+            const parentData = this._parentEntity.GetAll(oldValues, onlyDirtyFields);
+            return { ...parentData, ...obj };
+        }
         return obj;
     }
     /**
@@ -1096,6 +1293,18 @@ export class BaseEntity {
                 this.Set(kv.FieldName, kv.Value);
             });
         }
+        // IS-A composition: propagate PK value to parent entity chain
+        // Parent needs NewRecord() called first, then share the same PK value
+        if (this._parentEntity) {
+            this._parentEntity.NewRecord();
+            // Propagate PK — child and parent must share the same UUID
+            for (const pk of this.EntityInfo.PrimaryKeys) {
+                const pkValue = this.Get(pk.Name);
+                if (pkValue != null) {
+                    this._parentEntity.Set(pk.Name, pkValue);
+                }
+            }
+        }
         this.RaiseEvent('new_record', null);
         return true;
     }
@@ -1136,9 +1345,44 @@ export class BaseEntity {
         newResult.StartedAt = new Date();
         try {
             const _options = options ? options : new EntitySaveOptions();
+            // IS-A orchestration: determine if this is the initiating save in a parent chain
+            const isISAInitiator = (!!this._parentEntity) && !_options.IsParentEntitySave;
+            // Begin provider transaction if IS-A initiator and NOT in a TransactionGroup
+            // TransactionGroup manages its own atomicity; IS-A just orchestrates save order within it
+            if (isISAInitiator && !this.TransactionGroup) {
+                const txn = await this.ProviderToUse?.BeginISATransaction?.();
+                if (txn) {
+                    this.ProviderTransaction = txn;
+                    this.PropagateTransactionToParents();
+                }
+            }
+            // Save parent chain first (root → branch → immediate parent)
+            // Parent calls Save() recursively which handles its own parents, permissions, validation
+            if (this._parentEntity) {
+                const parentSaveOptions = new EntitySaveOptions();
+                parentSaveOptions.IgnoreDirtyState = _options.IgnoreDirtyState;
+                parentSaveOptions.SkipEntityAIActions = _options.SkipEntityAIActions;
+                parentSaveOptions.SkipEntityActions = _options.SkipEntityActions;
+                parentSaveOptions.ReplayOnly = _options.ReplayOnly;
+                parentSaveOptions.SkipOldValuesCheck = _options.SkipOldValuesCheck;
+                parentSaveOptions.SkipAsyncValidation = _options.SkipAsyncValidation;
+                parentSaveOptions.IsParentEntitySave = true;
+                const parentResult = await this._parentEntity.Save(parentSaveOptions); // we know parent entity exists hre 
+                if (!parentResult) {
+                    // Parent save failed — rollback if we started the transaction
+                    await this.RollbackISATransaction(isISAInitiator);
+                    return false;
+                }
+            }
             const type = this.IsSaved ? EntityPermissionType.Update : EntityPermissionType.Create;
             const saveSubType = this.IsSaved ? 'update' : 'create';
             this.CheckPermissions(type, true); // this will throw an error and exit out if we don't have permission
+            // IS-A disjoint subtype enforcement: on CREATE, ensure parent record
+            // isn't already claimed by another child type (e.g., can't create Meeting
+            // if a Publication already exists with the same Product ID)
+            if (!this.IsSaved && this.EntityInfo.IsChildType && !_options.ReplayOnly) {
+                await this.EnforceDisjointSubtype();
+            }
             if (_options.IgnoreDirtyState || this.Dirty || _options.ReplayOnly) {
                 // Raise save_started event only when we're actually going to save
                 this.RaiseEvent('save_started', null, saveSubType);
@@ -1175,12 +1419,18 @@ export class BaseEntity {
                         const data = await this.ProviderToUse.Save(this, this.ActiveUser, _options);
                         if (!this.TransactionGroup) {
                             // no transaction group, so we have our results here
-                            return this.finalizeSave(data, saveSubType);
+                            const result = this.finalizeSave(data, saveSubType);
+                            // IS-A: commit transaction after successful save (only the initiator commits)
+                            if (isISAInitiator && this.ProviderTransaction) {
+                                await this.ProviderToUse.CommitISATransaction?.(this.ProviderTransaction);
+                                this.ProviderTransaction = null;
+                            }
+                            return result;
                         }
                         else {
                             // we are part of a transaction group, so we return true and subscribe to the transaction groups' events and do the finalization work then
                             this.TransactionGroup.TransactionNotifications$.subscribe(({ success, results, error }) => {
-                                if (success) {
+                                if (success && results) {
                                     const transItem = results.find(r => r.Transaction.BaseEntity === this);
                                     if (transItem) {
                                         this.finalizeSave(transItem.Result, saveSubType); // we get the resulting data from the transaction result, not data above as that will be blank when in a TG
@@ -1206,6 +1456,9 @@ export class BaseEntity {
                 return true; // nothing to save since we're not dirty
         }
         catch (e) {
+            // IS-A: rollback transaction on failure (only the initiator rolls back)
+            const isISAInitiator = this._parentEntity != null && !options?.IsParentEntitySave;
+            await this.RollbackISATransaction(isISAInitiator);
             if (currentResultCount === this.ResultHistory.length) {
                 // this means that NO new results were added to the history anywhere
                 // so we need to add a new result to the history here
@@ -1220,6 +1473,21 @@ export class BaseEntity {
             return false;
         }
     }
+    /**
+     * Helper to rollback an IS-A provider transaction if one is active.
+     * Only called by the IS-A initiator (the leaf entity that started the chain).
+     */
+    async RollbackISATransaction(isInitiator) {
+        if (isInitiator && this.ProviderTransaction) {
+            try {
+                await this.ProviderToUse?.RollbackISATransaction?.(this.ProviderTransaction);
+            }
+            catch (rollbackError) {
+                LogError(`Error rolling back IS-A transaction: ${rollbackError}`);
+            }
+            this.ProviderTransaction = null;
+        }
+    }
     finalizeSave(data, saveSubType) {
         if (data) {
             this.init(); // wipe out the current data to flush out the DIRTY flags, load the ID as part of this too
@@ -1228,6 +1496,8 @@ export class BaseEntity {
             const result = this.LatestResult;
             if (result)
                 result.NewValues = this.Fields.map(f => { return { FieldName: f.CodeName, Value: f.Value }; }); // set the latest values here
+            // Cache the record name for faster lookups (updates cache with potentially new name)
+            this.CacheRecordName();
             this.RaiseEvent('save', null, saveSubType);
             return true;
         }
@@ -1241,6 +1511,23 @@ export class BaseEntity {
     get ActiveUser() {
         return this.ContextCurrentUser || Metadata.Provider.CurrentUser; // use the context user ahead of the Provider.Current User - this is for SERVER side ops where the user changes per request
     }
+    /**
+     * Caches the entity record name in the provider's EntityRecordNameCache for faster lookups.
+     * Called automatically after successful Load(), LoadFromData(), and Save() operations.
+     */
+    CacheRecordName() {
+        // Only cache if we have a valid primary key
+        if (!this.PrimaryKey || !this.PrimaryKey.HasValue) {
+            return;
+        }
+        // Get the record name
+        const recordName = this.GetRecordName();
+        if (!recordName) {
+            return;
+        }
+        // Cache it via the provider's public API
+        Metadata.Provider.SetCachedRecordName(this.EntityInfo.Name, this.PrimaryKey, recordName);
+    }
     /**
      * Utility method that returns true if the given permission being checked is enabled for the current user, and false if not.
      * @param type
@@ -1251,6 +1538,17 @@ export class BaseEntity {
         const u = this.ActiveUser;
         if (!u)
             throw new Error('No user set - either the context user for the entity object must be set, or the Metadata.Provider.CurrentUser must be set');
+        // Virtual entities are read-only — block Create, Update, Delete at the ORM level
+        // This catches server-side code calling .Save()/.Delete() directly, which bypasses the API layer flags
+        if (this.EntityInfo.VirtualEntity &&
+            (type === EntityPermissionType.Create ||
+                type === EntityPermissionType.Update ||
+                type === EntityPermissionType.Delete)) {
+            const msg = `Cannot ${type} on virtual entity '${this.EntityInfo.Name}' — virtual entities are read-only`;
+            if (throwError)
+                throw new Error(msg);
+            return false;
+        }
         // first check if the AllowCreateAPI/AllowUpdateAPI/AllowDeleteAPI settings are flipped on for the entity in question
         switch (type) {
             case EntityPermissionType.Create:
@@ -1322,6 +1620,10 @@ export class BaseEntity {
             for (let field of this.Fields) {
                 field.Value = field.OldValue;
             }
+            // IS-A composition: revert parent entity chain as well
+            if (this._parentEntity) {
+                this._parentEntity.Revert();
+            }
         }
         return true;
     }
@@ -1354,6 +1656,13 @@ export class BaseEntity {
                 LogError(`Error in BaseEntity.Load(${this.EntityInfo.Name}, Key: ${CompositeKey.ToString()}`);
                 return false; // no data loaded, return false
             }
+            // IS-A: hydrate parent chain from loaded data before populating self.
+            // Hydrate resets each parent via init() (giving fresh _NeverSet=true on PK fields)
+            // then populates from data. This must happen before self's SetMany so parents
+            // are in clean state when they receive routed field values.
+            if (this._parentEntity) {
+                this._parentEntity.Hydrate(data);
+            }
             this.SetMany(data, false, true, true); // don't ignore non-existent fields, but DO replace old values
             if (EntityRelationshipsToLoad) {
                 for (let relationship of EntityRelationshipsToLoad) {
@@ -1366,6 +1675,8 @@ export class BaseEntity {
             this._recordLoaded = true;
             this._everSaved = true; // Mark as saved since we loaded from database
             this._compositeKey = CompositeKey; // set the composite key to the one we just loaded
+            // Cache the record name for faster lookups
+            this.CacheRecordName();
             // Raise load completion event
             this.RaiseEvent('load_complete', { CompositeKey });
             return true;
@@ -1429,11 +1740,16 @@ export class BaseEntity {
      * @returns Promise<boolean> - Returns true if the load was successful
      */
     async LoadFromData(data, _replaceOldValues = false) {
+        // IS-A: hydrate parent chain from data before populating self.
+        // Hydrate resets each parent via init() (giving fresh _NeverSet=true on PK fields)
+        // then populates from data, ensuring correct PK and saved state on parents.
+        if (this._parentEntity) {
+            this._parentEntity.Hydrate(data);
+        }
         this.SetMany(data, true, _replaceOldValues, true); // ignore non-existent fields, but DO replace old values based on the provided param
         // now, check to see if we have the primary key set, if so, we should consider ourselves
         // loaded from the database and set the _recordLoaded flag to true along with the _everSaved flag
         if (this.PrimaryKeys && this.PrimaryKeys.length > 0) {
-            // chck each pkey's value to make sur it is set
             this._recordLoaded = true; // all primary keys are set, so we are loaded
             this._everSaved = true; // Mark as saved since we loaded from data
             for (let pkey of this.PrimaryKeys) {
@@ -1442,6 +1758,10 @@ export class BaseEntity {
                     this._everSaved = false; // if any primary key is not set, we cannot consider ourselves loaded
                 }
             }
+            // Cache the record name for faster lookups if successfully loaded
+            if (this._recordLoaded) {
+                this.CacheRecordName();
+            }
         }
         else {
             // this is an error state as every entity must have > 0 primary keys defined
@@ -1460,7 +1780,19 @@ export class BaseEntity {
     Validate() {
         const result = new ValidationResult();
         result.Success = true; // start off with assumption of success, if any field fails, we'll set this to false
+        // IS-A composition: validate parent entity first to collect all chain errors
+        if (this._parentEntity) {
+            const parentResult = this._parentEntity.Validate();
+            if (!parentResult.Success) {
+                result.Success = false;
+                parentResult.Errors.forEach(err => result.Errors.push(err));
+            }
+        }
+        // Validate own fields — for IS-A entities, skip parent field mirrors since
+        // those are validated via _parentEntity above
         for (let field of this.Fields) {
+            if (this._parentEntityFieldNames?.has(field.Name))
+                continue; // skip parent field mirrors — authoritative validation is on _parentEntity
             const err = field.Validate();
             err.Errors.forEach(element => {
                 result.Errors.push(element);
@@ -1541,6 +1873,42 @@ export class BaseEntity {
                 throw new Error('No provider set');
             }
             else {
+                const _options = options ? options : new EntityDeleteOptions();
+                // IS-A orchestration: determine if this is the initiating delete
+                const hasParentChain = this._parentEntity != null;
+                const isISAInitiator = hasParentChain && !_options.IsParentEntityDelete;
+                // IS-A parent delete protection: prevent deleting a parent record
+                // that has child records — FK constraints require child deletion first.
+                // If CascadeDeletes is enabled, auto-delete child records through the chain.
+                if (this.EntityInfo.IsParentType && !_options.IsParentEntityDelete) {
+                    const childCheck = await this.CheckForChildRecords();
+                    if (childCheck.HasChildren) {
+                        if (this.EntityInfo.CascadeDeletes) {
+                            // CascadeDeletes enabled: auto-delete the child record
+                            // This will recursively cascade through the IS-A chain
+                            const cascadeResult = await this.CascadeDeleteChildRecord(childCheck, _options);
+                            if (!cascadeResult) {
+                                throw new Error(`Cascade delete failed for ${childCheck.ChildEntityName} child record ` +
+                                    `of ${this.EntityInfo.Name} '${this.PrimaryKey.Values()}'.`);
+                            }
+                            // After cascade, proceed with our own delete (parent chain will be handled)
+                        }
+                        else {
+                            throw new Error(`Cannot delete ${this.EntityInfo.Name} record '${this.PrimaryKey.Values()}': ` +
+                                `it is referenced as a ${childCheck.ChildEntityName} record. ` +
+                                `Delete the ${childCheck.ChildEntityName} record first, ` +
+                                `or enable CascadeDeletes on the ${this.EntityInfo.Name} entity.`);
+                        }
+                    }
+                }
+                // Begin provider transaction if IS-A initiator and NOT in a TransactionGroup
+                if (isISAInitiator && !this.TransactionGroup) {
+                    const txn = await this.ProviderToUse?.BeginISATransaction?.();
+                    if (txn) {
+                        this.ProviderTransaction = txn;
+                        this.PropagateTransactionToParents();
+                    }
+                }
                 this.CheckPermissions(EntityPermissionType.Delete, true); // this will throw an error and exit out if we don't have permission
                 // Raise delete_started event before the actual delete operation begins
                 this.RaiseEvent('delete_started', null);
@@ -1553,7 +1921,27 @@ export class BaseEntity {
                     includeRelatedEntityData: false,
                     relatedEntityList: null
                 });
-                if (await this.ProviderToUse.Delete(this, options, this.ActiveUser)) {
+                // Delete OWN row first (FK constraint: child must be deleted before parent)
+                if (await this.ProviderToUse.Delete(this, _options, this.ActiveUser)) {
+                    // IS-A: after own delete succeeds, cascade to parent chain
+                    if (hasParentChain) {
+                        const parentDeleteOptions = new EntityDeleteOptions();
+                        parentDeleteOptions.SkipEntityAIActions = _options.SkipEntityAIActions;
+                        parentDeleteOptions.SkipEntityActions = _options.SkipEntityActions;
+                        parentDeleteOptions.ReplayOnly = _options.ReplayOnly;
+                        parentDeleteOptions.IsParentEntityDelete = true;
+                        const parentResult = await this._parentEntity.Delete(parentDeleteOptions);
+                        if (!parentResult) {
+                            // Parent delete failed — rollback if we started the transaction
+                            await this.RollbackISATransaction(isISAInitiator);
+                            return false;
+                        }
+                    }
+                    // IS-A: commit transaction after successful chain delete
+                    if (isISAInitiator && this.ProviderTransaction) {
+                        await this.ProviderToUse.CommitISATransaction?.(this.ProviderTransaction);
+                        this.ProviderTransaction = null;
+                    }
                     if (!this.TransactionGroup) {
                         // NOT part of a transaction - raise event immediately
                         // record deleted correctly
@@ -1584,11 +1972,14 @@ export class BaseEntity {
                     }
                     return true;
                 }
-                else // record didn't save, return false, but also don't wipe out the entity like we do if the Delete() worked
+                else // record didn't delete, return false, but also don't wipe out the entity like we do if the Delete() worked
                     return false;
             }
         }
         catch (e) {
+            // IS-A: rollback transaction on failure (only the initiator rolls back)
+            const isISAInitiator = this._parentEntity != null && !options?.IsParentEntityDelete;
+            await this.RollbackISATransaction(isISAInitiator);
             if (currentResultCount === this.ResultHistory.length) {
                 // this means that NO new results were added to the history anywhere
                 // so we need to add a new result to the history here
@@ -1603,6 +1994,155 @@ export class BaseEntity {
             return false;
         }
     }
+    /**
+     * Checks if this entity has any child records in IS-A child entity tables.
+     * Used for parent delete protection — a parent record cannot be deleted
+     * while child type records referencing it still exist.
+     * @returns Object with HasChildren flag and the name of the child entity found
+     */
+    async CheckForChildRecords() {
+        const childEntities = this.EntityInfo.ChildEntities;
+        if (childEntities.length === 0) {
+            return { HasChildren: false, ChildEntityName: '' };
+        }
+        // Use RunView to check each child entity for records with our PK
+        const rv = new RunView();
+        const pkValue = this.PrimaryKey.Values();
+        for (const childEntity of childEntities) {
+            const pkField = childEntity.PrimaryKeys[0];
+            if (!pkField)
+                continue;
+            const result = await rv.RunView({
+                EntityName: childEntity.Name,
+                ExtraFilter: `${pkField.Name} = '${pkValue}'`,
+                ResultType: 'simple',
+                Fields: [pkField.Name],
+                MaxRows: 1
+            }, this._contextCurrentUser);
+            if (result && result.Success && result.Results && result.Results.length > 0) {
+                return { HasChildren: true, ChildEntityName: childEntity.Name };
+            }
+        }
+        return { HasChildren: false, ChildEntityName: '' };
+    }
+    /**
+     * Cascade-deletes an IS-A child record when the parent entity has CascadeDeletes enabled.
+     * Loads the child entity, then deletes it through the normal IS-A chain. The child's
+     * delete will cascade further down if it also has children and CascadeDeletes.
+     */
+    async CascadeDeleteChildRecord(childCheck, parentOptions) {
+        const md = new Metadata();
+        const childEntity = await md.GetEntityObject(childCheck.ChildEntityName, this._contextCurrentUser);
+        if (!childEntity)
+            return false;
+        // Load the child record using the same PK as this parent
+        const loaded = await childEntity.InnerLoad(this.PrimaryKey);
+        if (!loaded)
+            return false;
+        // If the child entity itself is a parent with cascade, its delete will
+        // handle its own children recursively through _InnerDelete
+        const deleteOptions = new EntityDeleteOptions();
+        deleteOptions.SkipEntityAIActions = parentOptions.SkipEntityAIActions;
+        deleteOptions.SkipEntityActions = parentOptions.SkipEntityActions;
+        deleteOptions.ReplayOnly = parentOptions.ReplayOnly;
+        // Note: do NOT set IsParentEntityDelete — the child is the chain initiator
+        return childEntity.Delete(deleteOptions);
+    }
+    /**
+     * Resolves the leaf (most-derived) entity type for a given parent entity record.
+     * Walks down the IS-A child hierarchy to find which child type a record belongs to.
+     * Returns the child entity name, or the parent's own name if no children exist.
+     * Useful for polymorphic operations where you have a parent record and need
+     * to know its actual leaf type.
+     *
+     * @param entityName The parent entity name
+     * @param primaryKey The primary key to look up
+     * @param contextUser Optional context user for server-side operations
+     * @returns The leaf entity name and whether it was resolved to a child type
+     */
+    static async ResolveLeafEntity(entityName, primaryKey, contextUser) {
+        const md = new Metadata();
+        const entityInfo = md.Entities.find(e => e.Name === entityName);
+        if (!entityInfo) {
+            return { LeafEntityName: entityName, IsLeaf: true };
+        }
+        return BaseEntity.ResolveLeafEntityRecursive(entityInfo, primaryKey, contextUser);
+    }
+    /**
+     * Internal recursive helper for leaf entity resolution.
+     * Walks down the child hierarchy until no more children are found.
+     */
+    static async ResolveLeafEntityRecursive(entityInfo, primaryKey, contextUser) {
+        const childEntities = entityInfo.ChildEntities;
+        if (childEntities.length === 0) {
+            return { LeafEntityName: entityInfo.Name, IsLeaf: true };
+        }
+        const rv = new RunView();
+        const pkValue = primaryKey.Values();
+        for (const child of childEntities) {
+            const childPK = child.PrimaryKeys[0];
+            if (!childPK)
+                continue;
+            const result = await rv.RunView({
+                EntityName: child.Name,
+                ExtraFilter: `${childPK.Name} = '${pkValue}'`,
+                ResultType: 'simple',
+                Fields: [childPK.Name],
+                MaxRows: 1
+            }, contextUser);
+            if (result?.Success && result.Results?.length > 0) {
+                // Found a child — recurse to see if there's an even more specific leaf
+                return BaseEntity.ResolveLeafEntityRecursive(child, primaryKey, contextUser);
+            }
+        }
+        // No child found — this entity IS the leaf
+        return { LeafEntityName: entityInfo.Name, IsLeaf: true };
+    }
+    /**
+     * Enforces disjoint subtype constraint during IS-A child entity creation.
+     * A parent record can only be ONE child type at a time. Checks all sibling
+     * child types (excluding self) for records with the same PK value.
+     * Throws if a sibling child record is found.
+     *
+     * Only runs on Database providers — client-side (Network/GraphQL) skips this
+     * because the server-side save will perform the check authoritatively.
+     */
+    async EnforceDisjointSubtype() {
+        // Skip on client-side providers — the server will enforce this during its save
+        const md = this.ProviderToUse;
+        if (md.ProviderType !== ProviderType.Database)
+            return;
+        const parentEntityInfo = this.EntityInfo.ParentEntityInfo;
+        if (!parentEntityInfo)
+            return;
+        const siblingChildEntities = parentEntityInfo.ChildEntities.filter(e => e.ID !== this.EntityInfo.ID);
+        if (siblingChildEntities.length === 0)
+            return;
+        const pkValue = this.PrimaryKey.Values();
+        if (!pkValue)
+            return;
+        // Build all sibling queries and execute them in a single batch
+        const rv = new RunView();
+        const validSiblings = siblingChildEntities.filter(s => s.PrimaryKeys[0]);
+        if (validSiblings.length === 0)
+            return;
+        const viewParams = validSiblings.map(sibling => ({
+            EntityName: sibling.Name,
+            ExtraFilter: `${sibling.PrimaryKeys[0].Name} = '${pkValue}'`,
+            ResultType: 'simple',
+            Fields: [sibling.PrimaryKeys[0].Name],
+            MaxRows: 1
+        }));
+        const results = await rv.RunViews(viewParams, this._contextCurrentUser);
+        for (let i = 0; i < results.length; i++) {
+            const result = results[i];
+            if (result?.Success && result.Results?.length > 0) {
+                const sibling = validSiblings[i];
+                throw new Error(`Cannot create ${this.EntityInfo.Name} record: ID '${pkValue}' already exists as ${sibling.Name}. ` +
+                    `A ${parentEntityInfo.Name} record can only be one child type at a time.`);
+            }
+        }
+    }
     /**
      * Called before an Action is executed by the AI Engine
      * This is intended to be overriden by subclass as needed, these methods called at the right time by the execution context