@memberjunction/core 6.2.0-edge.5 → 6.2.0-edge.7

package/dist/generic/baseEntity.js

@@ -8,16 +8,17 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 var EntityField_1;
-import { Base64DecodedByteLength, DeserializeValidationErrors, Float32VectorToBase64, IsValidBase64, IsMemberOverridden, MJEventType, MJGlobal, NormalizeUUID, OptionalKeyedSpecialization, uuidv4, UUIDsEqual, WarningManager, ComputeContentHashAsync } from '@memberjunction/global';
+import { Base64DecodedByteLength, DeserializeValidationErrors, Float32VectorToBase64, IsValidBase64, IsMemberOverridden, MJEventType, MJGlobal, NormalizeUUID, OptionalKeyedSpecialization, uuidv4, UUIDsEqual, UserCacheKeySegment, WarningManager, ComputeContentHashAsync, EscapeSQLString } from '@memberjunction/global';
 import { GetDataHooks } from './dataHooks.js';
 import { EntityFieldInfo, EntityInfo, EntityFieldTSType, EntityPermissionType, FieldSecurityError, RecordChange, ValidationErrorInfo, ValidationResult } from './entityInfo.js';
 import { EntitySubtypeResolver } from './entitySubtypeResolver.js';
+import { CanonicalPrimaryKeyValue } from './util.js';
 import { BaseEngineRegistry } from './baseEngineRegistry.js';
 import { IsPermittedImageFieldValue, IsValidCssColor, TryParseJsonText } from './extendedTypeValue.js';
 import { EntityDeleteOptions, EntitySaveOptions, ProviderType } from './interfaces.js';
 import { Metadata } from './metadata.js';
 import { RunView } from '../views/runView.js';
-import { LogDebug, LogError, LogStatusEx } from './logging.js';
+import { LogDebug, LogError, LogStatusEx, LogWarning } from './logging.js';
 import { CompositeKey, KeyValuePair } from './compositeKey.js';
 import { RelatedRecordCollection } from './relatedRecordCollection.js';
 import { COMPANION_PAYLOAD_KEY } from './entityCompanion.js';
@@ -25,6 +26,7 @@ import { EmbeddedRecord } from './embeddedRecord.js';
 import { EntitySavePlan, ExecuteEntitySavePlan } from './entitySavePlan.js';
 import { JSONFieldBinding, ValidateJSONFieldValue } from './jsonFieldBinding.js';
 import { BaseRemotableOperation } from './baseRemotableOperation.js';
+import { OmitDeniedFieldKeys, OmitFieldsUnreadableByActiveUser } from './entityValueFieldSecurity.js';
 import { SAVE_ENTITY_GRAPH_OPERATION_KEY, } from './saveEntityGraphOperation.js';
 import { finalize, firstValueFrom, from, of, shareReplay, Subject, switchMap } from 'rxjs';
 /**
@@ -79,8 +81,9 @@ let EntityField = class EntityField {
      * `InnerLoad` — reusing it would conflate defaults with omissions. This flag is set only
      * by the hydration paths (via {@link MarkNotLoaded}) when a source omits the key, is
      * cleared by ANY explicit set (an intentional blind write to a read-denied field is a
-     * legitimate write-only update and must save), and is never present on new (unhydrated)
-     * entities — their fields legitimately hold metadata defaults for INSERT.
+     * legitimate write-only update and must save). On a new record it marks only the fields the
+     * record's user may not read; every other field legitimately holds its metadata default for
+     * INSERT.
      */
     get NotLoaded() {
         return this._notLoaded;
@@ -128,6 +131,18 @@ let EntityField = class EntityField {
     SetCreateSuppressed(suppressed) {
         this._createSuppressed = suppressed;
     }
+    /**
+     * Framework-internal: resets all mutable field state in place to match a freshly constructed
+     * `EntityField` instance without allocating a new object or invalidating `BaseEntity` field maps.
+     */
+    ResetForInPlaceHydration() {
+        this._oldValue = null;
+        this._value = null;
+        this._neverSet = true;
+        this._notLoaded = false;
+        this._writtenAfterNotLoaded = false;
+        this._createSuppressed = false;
+    }
     get Name() {
         return this._entityFieldInfo.Name;
     }
@@ -183,7 +198,18 @@ let EntityField = class EntityField {
         return this._entityFieldInfo.HasDefaultValue;
     }
     /**
-     * Sets the value of the field. If the field is read only, nothing happens. If the field is not read only, the value is set and the internal representation of the dirty flag is flipped if the value is different from the old value.
+     * Sets the value of the field.
+     *
+     * - A read-only field accepts ONE set after construction or {@link ResetNeverSetFlag} (how a
+     *   load populates it); later sets are ignored.
+     * - Dirty state is not stored here: {@link Dirty} compares the value with {@link OldValue} when
+     *   it is read. A set during record setup (the first set of a never-set field) also becomes
+     *   the old value, so it is not dirty.
+     * - A set onto a {@link NotLoaded} field clears that flag and is always dirty, whatever the
+     *   value, even one equal to the field's construction state. The write therefore reaches the
+     *   save and its update-permission check.
+     * - No field-level security or active-status check happens here. Those live at
+     *   `BaseEntity.Get`/`Set` and at the save; this accessor is framework-internal.
      */
     set Value(value) {
         // No active-status assertion here — see the Value getter note. Deprecation/disabled checks
@@ -527,6 +553,11 @@ let EntityField = class EntityField {
     }
     /**
      * This method will set the internal Old Value which is used to track dirty state, to the current value of the field. This effectively resets the dirty state of the field to false. Use this method sparingly.
+     *
+     * It also clears the written-after-not-loaded flag: the current value becomes the field's
+     * loaded baseline. The hydration paths rely on that (a reload that supplies the field must not
+     * leave it dirty), so code outside hydration must not call this to "accept" a write onto a
+     * not-loaded field, or the write would be saved without being seen as a change.
      */
     ResetOldValue() {
         this._oldValue = this.Value;
@@ -1059,6 +1090,7 @@ export class BaseEntity {
          * pay nothing for the feature, not even an empty Map per instance.
          */
         this._companions = null;
+        this._finalizeGeneration = 0;
         /**
          * 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.
          *
@@ -1649,20 +1681,35 @@ export class BaseEntity {
         return e instanceof Error ? e.message : String(e);
     }
     /**
-     * The create path's SubtypeSelector lookup memo, partitioned by the provider that ran the lookup. A memo
-     * shared across providers would hand provider B a row loaded through provider A (another connection,
-     * another user's context) or a `null` miss recorded against A's database. Keyed weakly so a
-     * request-scoped provider's memo is collected with it.
+     * The create path's SubtypeSelector lookup memo, partitioned by the provider that ran the lookup and
+     * then by the user it ran for. A memo shared across providers would hand provider B a row loaded
+     * through provider A (another connection) or a `null` miss recorded against A's database. A memo
+     * shared across users would hand one user an entity object shaped to another: an object holds only
+     * the fields its own user may read, so a record loaded for an administrator carries values a
+     * restricted user is denied. Keyed weakly so a request-scoped provider's memo is collected with it.
      */
     static { this._subtypeLookupCache = new WeakMap(); }
     /** Partition key for lookups made by an entity that has no provider at all. */
     static { this._noProviderSubtypeKey = {}; }
-    static subtypeLookupCacheFor(provider) {
+    /**
+     * The memo for one provider and user, or null when no user resolves: an entry keyed without a
+     * user would be shared by every caller, so such a lookup is not memoized at all.
+     */
+    static subtypeLookupCacheFor(provider, user) {
+        const userKey = UserCacheKeySegment(user?.ID);
+        if (userKey === null) {
+            return null;
+        }
         const partitionKey = provider ?? BaseEntity._noProviderSubtypeKey;
-        let cache = BaseEntity._subtypeLookupCache.get(partitionKey);
+        let byUser = BaseEntity._subtypeLookupCache.get(partitionKey);
+        if (!byUser) {
+            byUser = new Map();
+            BaseEntity._subtypeLookupCache.set(partitionKey, byUser);
+        }
+        let cache = byUser.get(userKey);
         if (!cache) {
             cache = new Map();
-            BaseEntity._subtypeLookupCache.set(partitionKey, cache);
+            byUser.set(userKey, cache);
         }
         return cache;
     }
@@ -1866,12 +1913,16 @@ export class BaseEntity {
             return null;
         let currentEntity = this;
         let currentEntityInfo = this.EntityInfo;
+        const actingUser = this.resolveActiveUserOrNull();
         for (let i = 0; i < segments.length - 1; i++) {
             const fieldName = segments[i];
             const fieldInfo = currentEntityInfo.Fields.find(f => f.Name.trim().toLowerCase() === fieldName.toLowerCase());
             if (!fieldInfo) {
                 throw new Error(`Invalid SubtypeSelector path '${path}' on '${this.EntityInfo.Name}': field '${fieldName}' was not found on entity '${currentEntityInfo.Name}'.`);
             }
+            if (!this.subtypeSelectorMayRead(currentEntity, fieldInfo.Name, actingUser)) {
+                return null; // a hop the user may not read gives no subtype, as a denied name field gives no name
+            }
             const fkValue = currentEntity.Get(fieldInfo.Name);
             if (fkValue == null || fkValue === '') {
                 return null;
@@ -1892,34 +1943,54 @@ export class BaseEntity {
         if (!terminalField) {
             throw new Error(`Invalid SubtypeSelector path '${path}' on '${this.EntityInfo.Name}': terminal field '${terminalSegment}' was not found on entity '${currentEntityInfo.Name}'.`);
         }
+        if (!this.subtypeSelectorMayRead(currentEntity, terminalField.Name, actingUser)) {
+            return null;
+        }
         const terminalValue = currentEntity.Get(terminalField.Name);
         if (terminalValue == null || typeof terminalValue !== 'string' || terminalValue.trim() === '') {
             return null;
         }
         return terminalValue.trim();
     }
+    /**
+     * Whether a `SubtypeSelector` hop may read `fieldName` on `record`, which is this record or
+     * one the path reached. Both the record's own user and the user resolving the subtype must be
+     * allowed: a record reached through an engine cache was loaded as the system user and holds
+     * every column, so its own answer says nothing about the acting user.
+     */
+    subtypeSelectorMayRead(record, fieldName, actingUser) {
+        if (!record.IsFieldReadableByActiveUser(fieldName)) {
+            return false;
+        }
+        return record === this || !actingUser || record.EntityInfo.IsFieldReadableByUser(fieldName, actingUser);
+    }
     async getSubtypePathTargetEntity(entityName, pkValue) {
         const cacheKey = `${entityName.trim().toLowerCase()}|${String(pkValue).trim().toLowerCase()}`;
         const provider = this.ProviderToUse;
-        const lookupCache = BaseEntity.subtypeLookupCacheFor(provider);
-        if (lookupCache.has(cacheKey)) {
+        const lookupCache = BaseEntity.subtypeLookupCacheFor(provider, this.resolveActiveUserOrNull());
+        if (lookupCache?.has(cacheKey)) {
             return lookupCache.get(cacheKey) ?? null;
         }
-        // 1. Check BaseEngineRegistry for loaded cached entities
+        const found = await this.findSubtypePathTarget(provider, entityName, pkValue);
+        lookupCache?.set(cacheKey, found);
+        return found;
+    }
+    /**
+     * Finds the record a create-time `SubtypeSelector` hop points at: in a loaded engine cache
+     * first, then by loading it through the provider for this record's user. Null when neither
+     * has it, or the load fails.
+     */
+    async findSubtypePathTarget(provider, entityName, pkValue) {
         const cached = BaseEntity.findSubtypePathTargetInEngineCache(entityName, pkValue);
         if (cached) {
-            lookupCache.set(cacheKey, cached);
             return cached;
         }
-        // 2. Fall back to loading via provider
         if (!provider?.GetEntityObject) {
-            lookupCache.set(cacheKey, null);
             return null;
         }
         try {
             const targetObj = await provider.GetEntityObject(entityName, this._contextCurrentUser);
             if (!targetObj) {
-                lookupCache.set(cacheKey, null);
                 return null;
             }
             let key;
@@ -1931,17 +2002,11 @@ export class BaseEntity {
                 const pkName = targetObj.FirstPrimaryKey.Name; // first-pk-ok: FK target — pkValue is one SubtypeSelector FK column's value
                 key.KeyValuePairs.push(new KeyValuePair(pkName, pkValue));
             }
-            const loaded = await targetObj.InnerLoad(key);
-            if (loaded) {
-                lookupCache.set(cacheKey, targetObj);
-                return targetObj;
-            }
+            return (await targetObj.InnerLoad(key)) ? targetObj : null;
         }
         catch {
-            // On load failure, return null
+            return null; // on load failure, no target
         }
-        lookupCache.set(cacheKey, null);
-        return null;
     }
     /**
      * Finds the record a `SubtypeSelector` hop points at among the entity objects that loaded
@@ -2142,23 +2207,102 @@ export class BaseEntity {
      *               (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();
         this.discardJSONFieldObjects();
+        // Field security: denied values never enter this object (see narrowHydrationSource).
+        data = this.narrowHydrationSource(data);
         // 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 remains as a safety net; ownedFieldsFrom already
-        // dropped columns that belong to another level of the IS-A chain.
-        this.SetMany(this.ownedFieldsFrom(data), true, true, true);
-        // Hydrate is a hydration entry point: keys the source omitted are not-loaded.
-        this.markFieldsOmittedBySourceAsNotLoaded(data);
+        // Populate this entity's fields in place without destroying hydrated EntityField instances
+        // or invalidating _fieldCache / _codeNameCache.
+        this.resetAndApplyOwnedFieldsInPlace(data);
+    }
+    /**
+     * Resets transient record state and applies `fieldData` to this entity's own fields in a
+     * single pass over `this._fields`, reusing existing `EntityField` instances and preserving
+     * `_fieldCache` / `_codeNameCache` when already hydrated.
+     *
+     * Equivalent to `init() + SetMany(ownedFieldsFrom(fieldData), true, true, true) + markFieldsOmittedBySourceAsNotLoaded(fieldData)`
+     * with zero `EntityField` reallocations and zero intermediate `ownedFieldsFrom` object allocation.
+     */
+    resetAndApplyOwnedFieldsInPlace(fieldData) {
+        this._finalizeGeneration++;
+        this._compositeKey = null;
+        this._resultHistory = [];
+        this._recordLoaded = false;
+        this._raw = null;
+        this._rawConverted = null;
+        this.hydrateFieldsIfNeeded();
+        if (!fieldData || typeof fieldData !== 'object' || Array.isArray(fieldData)) {
+            for (let i = 0; i < this._fields.length; i++) {
+                const field = this._fields[i];
+                field.ResetForInPlaceHydration();
+                field.ClearAsNotLoaded();
+            }
+            return;
+        }
+        let normalizedMap = null;
+        let sharedParentMirrors = null;
+        const parentFieldNames = this._parentEntity ? this._parentEntityFieldNames : null;
+        for (let i = 0; i < this._fields.length; i++) {
+            const field = this._fields[i];
+            const match = BaseEntity.findOwnedFieldValueInSource(field, fieldData, () => {
+                if (normalizedMap === null) {
+                    normalizedMap = BaseEntity.buildNormalizedHydrationMap(fieldData);
+                }
+                return normalizedMap;
+            });
+            field.ResetForInPlaceHydration();
+            if (match.found) {
+                this.setFieldValue(field, match.val);
+                field.ResetOldValue();
+                if (parentFieldNames) {
+                    if (parentFieldNames.has(match.key)) {
+                        (sharedParentMirrors ??= {})[match.key] = match.val;
+                    }
+                    else if (parentFieldNames.has(field.Name)) {
+                        (sharedParentMirrors ??= {})[field.Name] = match.val;
+                    }
+                }
+            }
+            else {
+                field.ClearAsNotLoaded();
+            }
+        }
+        if (sharedParentMirrors && this._parentEntity) {
+            this._parentEntity.SetMany(sharedParentMirrors, true, true, true);
+        }
+        this.updateSavedStateFromPrimaryKeys();
+    }
+    static findOwnedFieldValueInSource(field, fieldData, getNormalizedMap) {
+        if (BaseEntity.ownValuePresent(fieldData, field.Name)) {
+            return { found: true, key: field.Name, val: fieldData[field.Name] };
+        }
+        if (field.CodeName !== field.Name && BaseEntity.ownValuePresent(fieldData, field.CodeName)) {
+            return { found: true, key: field.CodeName, val: fieldData[field.CodeName] };
+        }
+        const normalizedMap = getNormalizedMap();
+        const hit = normalizedMap.get(field.Name.trim().toLowerCase()) ??
+            (field.CodeName !== field.Name
+                ? normalizedMap.get(field.CodeName.trim().toLowerCase())
+                : undefined);
+        if (hit !== undefined) {
+            return { found: true, key: hit.key, val: hit.val };
+        }
+        return { found: false, key: field.Name, val: undefined };
+    }
+    static buildNormalizedHydrationMap(fieldData) {
+        const normalizedMap = new Map();
+        const keys = Object.keys(fieldData);
+        for (let kIdx = 0; kIdx < keys.length; kIdx++) {
+            const k = keys[kIdx];
+            const v = fieldData[k];
+            if (v !== undefined) {
+                normalizedMap.set(k.trim().toLowerCase(), { key: k, val: v });
+            }
+        }
+        return normalizedMap;
     }
     /**
      * Columns on `data` that this entity actually defines (by field name or CodeName).
@@ -2410,7 +2554,9 @@ export class BaseEntity {
             }
             const result = await operation.Execute({
                 EntityName: this.EntityInfo.Name,
-                Fields: this.GetAll(),
+                // Without the fields this user may not read: the server refuses a restricted
+                // caller's input that names one, as the transaction-group serializer knows.
+                Fields: OmitFieldsUnreadableByActiveUser(this, this.GetAll()),
                 Companions: await this.SerializeCompanions(),
                 IsExistingRecord: this.IsSaved,
             }, { provider: this.ProviderToUse, user: this.ActiveUser });
@@ -2449,9 +2595,14 @@ export class BaseEntity {
         // 'save' event both carry it; hardcoding 'update' here made every remote graph CREATE
         // report (and notify subscribers) as an update.
         const saveSubType = this.IsSaved ? 'update' : 'create';
+        const changedFieldNames = this.dirtyFieldNames();
         // Root: rebase field values and dirty state onto what the database now holds.
         this.init();
-        this.SetMany(output.Fields, false, true, true);
+        const fields = this.narrowHydrationSource(output.Fields);
+        this.SetMany(fields, false, true, true);
+        // A hydration source like any other: a field the result omitted (the server withheld it, or
+        // this user may not hold it) is not loaded, so its construction state is never resent as data.
+        this.markFieldsOmittedBySourceAsNotLoaded(fields);
         this._recordLoaded = true;
         this._everSaved = true;
         // Children: adopt server-assigned primary keys and computed values. 'result' mode adopts the
@@ -2465,7 +2616,28 @@ export class BaseEntity {
         result.StartedAt = new Date();
         result.EndedAt = new Date();
         this.RegisterResultHistoryEntry(result);
-        this.RaiseEvent('save', null, saveSubType);
+        this.RaiseEvent('save', null, saveSubType, changedFieldNames);
+    }
+    /**
+     * The names of the fields that are dirty right now. Cheaper than walking {@link Fields}: an
+     * object still in raw mode (loaded and never written to) cannot be dirty, so it answers `[]`
+     * without building its field objects.
+     */
+    GetDirtyFieldNames() {
+        if (!this._fieldsHydrated && this._raw !== null && !this._parentEntity) {
+            return [];
+        }
+        const names = [];
+        for (const f of this.Fields) {
+            if (f.Dirty) {
+                names.push(f.Name);
+            }
+        }
+        return names;
+    }
+    /** The names of the fields that are dirty right now, for the `save` event's {@link BaseEntityEvent.ChangedFieldNames}. */
+    dirtyFieldNames() {
+        return this.GetDirtyFieldNames();
     }
     /**
      * Gives every eager companion a chance to populate itself.
@@ -2825,6 +2997,7 @@ export class BaseEntity {
                     entity: level,
                     wasSaved: level._everSaved,
                     wasLoaded: level._recordLoaded,
+                    finalizeGeneration: level._finalizeGeneration,
                     resultHistory: [...level._resultHistory],
                     fields: level.Fields.map(field => ({ field, state: field.GetState() })),
                 });
@@ -2844,7 +3017,7 @@ export class BaseEntity {
      * Puts this record back as a snapshot captured it, after the unit of work that finalized it
      * rolled back.
      *
-     * A save's `finalizeSave()` rebuilds the record's fields from what its write returned, marks it
+     * A save's `finalizeSave()` updates the record's fields from what its write returned, marks it
      * saved and empties its result history. The database undid the write, so the record gets back
      * its saved and loaded flags, its result history, and each field's value and tracking state. A
      * field edited since then keeps the edit, and is compared with its captured baseline again, since
@@ -2854,14 +3027,16 @@ export class BaseEntity {
      * The history matters to the caller: a save records its failure only when nothing else did,
      * judged by the history's length when it started, which an emptied history would make wrong.
      *
-     * A record still holding the captured field objects was never finalized, so nothing about it
-     * changed and it is left alone.
+     * A record whose `_finalizeGeneration` (and field object identities) still matches the snapshot
+     * was never finalized, so nothing about it changed and it is left alone.
      */
     restoreSnapshot(snapshot) {
-        const finalized = snapshot.fields.some(({ field }) => this.GetFieldByName(field.Name) !== field);
+        const finalized = this._finalizeGeneration !== snapshot.finalizeGeneration ||
+            snapshot.fields.some(({ field }) => this.GetFieldByName(field.Name) !== field);
         if (!finalized) {
             return;
         }
+        this._finalizeGeneration = snapshot.finalizeGeneration;
         this._everSaved = snapshot.wasSaved;
         this._recordLoaded = snapshot.wasLoaded;
         this._resultHistory = snapshot.resultHistory;
@@ -3080,7 +3255,7 @@ export class BaseEntity {
     /**
      * Used for raising events within the BaseEntity and can be used by sub-classes to raise events that are specific to the entity.
      */
-    RaiseEvent(type, payload, saveSubType = undefined) {
+    RaiseEvent(type, payload, saveSubType = undefined, changedFieldNames) {
         // Resolve the entity's bound provider once so every consumer (local subscribers
         // AND MJGlobal listeners) receives consistent provider context. This matters in
         // multi-provider scenarios — listeners like LocalCacheManager / BaseEngine need to
@@ -3091,7 +3266,7 @@ export class BaseEntity {
         const provider = this.ProviderToUse;
         // this is the local event handler that is specific to THIS instance of the entity object
         LogDebug(`BaseEntity.RaiseEvent() - ${type === 'save' ? 'save:' + saveSubType : type} event raised for ${this.EntityInfo.Name}, about to call this._eventSubject.next()`);
-        this._eventSubject?.next({ type: type, payload: payload, saveSubType: saveSubType, baseEntity: this, provider });
+        this._eventSubject?.next({ type: type, payload: payload, saveSubType: saveSubType, baseEntity: this, provider, ChangedFieldNames: changedFieldNames });
         // this next call is to MJGlobal to let everyone who cares knows that we had an event on an entity object
         // we broadcast save/delete/load events and their _started counterparts
         if (BaseEntity._globalEventTypes.has(type)) {
@@ -3101,6 +3276,7 @@ export class BaseEntity {
             event.type = type;
             event.saveSubType = saveSubType;
             event.provider = provider;
+            event.ChangedFieldNames = changedFieldNames;
             LogDebug(`BaseEntity.RaiseEvent() - ${type === 'save' ? 'save:' + saveSubType : type} event raised for ${this.EntityInfo.Name}, about to call MJGlobal.RaiseEvent()`);
             MJGlobal.Instance.RaiseEvent({
                 component: this,
@@ -3241,6 +3417,7 @@ export class BaseEntity {
     get TransactionGroup() {
         return this._transactionGroup;
     }
+    /** Set `null` to detach the entity from a group, e.g. once the group has been submitted. */
     set TransactionGroup(group) {
         this._transactionGroup = group;
     }
@@ -3492,11 +3669,14 @@ export class BaseEntity {
      * nothing like field security.
      *
      * Framework-internal value machinery (`Dirty`, `Validate`, `GetAll`, hydration, save-SQL
-     * build) reads `EntityField.Value` directly and never routes through here — that exemption
-     * is load-bearing, not an oversight. Do not "fix" it.
+     * build) reads `EntityField.Value` directly and never routes through here. It needs no gate
+     * of its own: every hydration point leaves a denied field not-loaded and empty for a
+     * restricted user (see {@link narrowHydrationSource}), so there is no denied value for that
+     * machinery to read. This assertion is what turns asking for one into an error rather than a
+     * silent null.
      */
     assertFieldReadable(fieldName) {
-        const denied = this.deniedFieldsForActiveUser(u => this.EntityInfo.GetDeniedReadFields(u));
+        const denied = this.deniedReadFieldsForActiveUser();
         if (denied?.has(fieldName?.trim().toLowerCase())) {
             throw new FieldSecurityError(fieldName, this.EntityInfo.Name);
         }
@@ -3812,6 +3992,53 @@ export class BaseEntity {
         }
         return obj;
     }
+    /**
+     * Whether {@link GetAll} would carry a key for every non-binary field of this entity: the
+     * object holds a value for each one (none is not loaded, or withheld from its user), here or,
+     * for an IS-A child, on an ancestor. Answers the question
+     * `LocalCacheManager.RowHasEveryField(this.EntityInfo, this.GetAll())` answers, without
+     * building the row, and without building field objects for an object in raw mode.
+     */
+    HoldsEveryField() {
+        const infos = this.EntityInfo?.Fields;
+        if (!Array.isArray(infos) || infos.length === 0) {
+            return true;
+        }
+        if (!this._fieldsHydrated && this._raw !== null) {
+            for (const fi of infos) {
+                if (!fi.IsBinaryFieldType && this.rawValueFor(this._raw, fi) === undefined && !this.ancestorHoldsField(fi.Name)) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        for (const field of this.Fields) {
+            if (!field.EntityFieldInfo.IsBinaryFieldType && field.NotLoaded && !this.ancestorHoldsField(field.Name)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** Whether an IS-A ancestor's {@link GetAll} would carry the key `name` (an exact field name). */
+    ancestorHoldsField(name) {
+        return this._parentEntity?.holdsFieldNamed(name) ?? false;
+    }
+    /** Whether this object's {@link GetAll} would carry the key `name`, counting its own ancestors. */
+    holdsFieldNamed(name) {
+        if (!this._fieldsHydrated && this._raw !== null) {
+            const fi = this.EntityInfo?.FieldByName(name);
+            if (fi && fi.Name === name && this.rawValueFor(this._raw, fi) !== undefined) {
+                return true;
+            }
+        }
+        else {
+            const field = this.GetFieldByName(name);
+            if (field && field.Name === name && !field.NotLoaded) {
+                return true;
+            }
+        }
+        return this.ancestorHoldsField(name);
+    }
     /**
      * Returns a partial object that contains only the fields that have changed since the last time the record was saved. This is useful for scenarios where you want to send only the changes to the server or to a client.
      * It is also helpful for quickly finding the fields that are "dirty".
@@ -4039,19 +4266,43 @@ export class BaseEntity {
      * Called only by the hydration entry points ({@link LoadFromData} both modes, {@link Hydrate},
      * {@link InnerLoad}) — never by plain {@link SetMany}, which is an incremental mutation API
      * where omitting a field means "leave it alone," not "this field was never loaded."
-     * Both the field Name and CodeName are checked, matching SetMany's key acceptance.
+     * Both the field Name and CodeName are checked, case-insensitively, matching SetMany's key
+     * acceptance: SetMany applies `{name: 'b'}` to a field called `Name`, so an exact-case lookup
+     * here would mark the value it just applied as not loaded, and GetAll and the save would then
+     * drop it.
      */
     markFieldsOmittedBySourceAsNotLoaded(source) {
         if (!source || typeof source !== 'object')
             return;
+        // Exact keys first: a source keyed by the field names, the usual case, never builds the
+        // case-insensitive key set. It is built once, on the first field the exact check misses.
+        let presentKeys = null;
         for (const field of this.Fields) {
-            if (source[field.Name] === undefined && source[field.CodeName] === undefined) {
+            if (BaseEntity.ownValuePresent(source, field.Name) || BaseEntity.ownValuePresent(source, field.CodeName)) {
+                continue;
+            }
+            presentKeys ??= BaseEntity.normalizedPresentKeys(source);
+            if (!presentKeys.has(field.Name.trim().toLowerCase()) && !presentKeys.has(field.CodeName.trim().toLowerCase())) {
                 // Cleared, not just flagged: otherwise a default from construction, or the previous
                 // record's value on a reload, reads back through Get() as if it had been loaded.
                 field.ClearAsNotLoaded();
             }
         }
     }
+    /** Whether `source` holds `key` as its own property with a value (an inherited `constructor` does not count). */
+    static ownValuePresent(source, key) {
+        return source[key] !== undefined && Object.prototype.hasOwnProperty.call(source, key);
+    }
+    /** The keys of `source` that carry a value, trimmed and lowercased. */
+    static normalizedPresentKeys(source) {
+        const keys = new Set();
+        for (const key of Object.keys(source)) {
+            if (source[key] !== undefined) {
+                keys.add(key.trim().toLowerCase());
+            }
+        }
+        return keys;
+    }
     /**
      * This method will copy the values from the other entity object into the current one. This is useful for things like cloning a record.
      * This method will ONLY copy values for fields that exist in the current entity object. If the other object has fields that don't exist in the current object, they will be ignored.
@@ -4061,8 +4312,15 @@ export class BaseEntity {
      */
     CopyFrom(other, includePrimaryKeys = false, replaceOldValues = false) {
         try {
+            // Field security: a field THIS object's user may not read is skipped, not copied. The
+            // source can be full width (another user's object, or a server-internal one), and
+            // Set() refuses a denied field, which used to end the copy at the first one.
+            const denied = this.deniedReadFieldsForActiveUser();
             // iterate through all of OUR fields and set them to the value of the other object, if they exist in the other object
             for (let field of this.Fields) {
+                if (denied?.has(field.Name.trim().toLowerCase())) {
+                    continue;
+                }
                 if (!field.IsPrimaryKey || includePrimaryKeys) {
                     const otherField = other.GetFieldByName(field.Name);
                     // Skip fields the SOURCE never loaded (D-3): copying their construction
@@ -4086,9 +4344,27 @@ export class BaseEntity {
      * The ContextCurrentUser is a property used to manually set the "current" user for scenarios, primarily on the server side, where the user changes per request. For situations where there is no global CurrentUser in the Metadata.Provider,
      * you MUST set this property to the user you want to use for the current operation. If you used Metadata.GetEntityObject() to get the entity object, this property will be set automatically for you as that method has a parameter that can
      * be provided for the ContextCurrentUser.
+     *
+     * **Field security.** An object holds only what its user may read, so assigning a different
+     * user to an object that already holds a record narrows it to the new user: values the new
+     * user may not read are dropped (the fields become not loaded) from this object, its IS-A
+     * parent, its embedded records and the loaded children of its related-record collections,
+     * which are given the same user. A read-only cache collection's children are the engine's own
+     * instances and are left as they are. Nothing is widened: a field
+     * the previous user could not read stays not loaded for a user who can, because its value was
+     * never loaded. Set the user before loading wherever possible, so the record is loaded at the
+     * right width in the first place.
      */
     set ContextCurrentUser(user) {
+        if (user === this._contextCurrentUser) {
+            return;
+        }
         this._contextCurrentUser = user;
+        this.narrowHeldValuesForActiveUser(false);
+        if (this._parentEntity) {
+            this._parentEntity.ContextCurrentUser = user;
+        }
+        this.notifyCompanionsContextUserChanged(user);
     }
     get ContextCurrentUser() {
         return this._contextCurrentUser;
@@ -4155,6 +4431,11 @@ export class BaseEntity {
                 }
             }
         }
+        // Field security: a new record holds no default for a field its user may not read. The
+        // field is not loaded instead, so GetAll() and every payload built from it leave it out
+        // (the server refuses a restricted caller's input that names it), and the save omits it,
+        // so the column takes its database default.
+        this.narrowHeldValuesForActiveUser(true);
         // Apply caller-supplied values LAST so an explicit PK (or any routed
         // parent field) wins over the generated/adopted value instead of being
         // clobbered by the parent's NewRecord().
@@ -4181,6 +4462,53 @@ export class BaseEntity {
             }
         }
     }
+    /**
+     * Gives every companion this object's new user: embedded records and the loaded children of
+     * related-record collections take it. See {@link ContextCurrentUser}.
+     */
+    notifyCompanionsContextUserChanged(user) {
+        if (!this.HasCompanions) {
+            return;
+        }
+        for (const companion of this.Companions) {
+            companion.OnOwnerContextUserChanged(user);
+        }
+    }
+    /**
+     * Drops every value this object holds that its user may not read: the field is left not
+     * loaded and empty, or, before the fields are built, the key leaves the raw row (as a copy;
+     * the row can be shared). A no-op when field security does not apply or the user is denied
+     * nothing, which is the one boolean most entities pay.
+     *
+     * For the points where the user or the record changes WITHOUT a hydration source to narrow:
+     * a user assigned to an object that already holds a record, and a new record's defaults.
+     *
+     * @param buildFields true to build the fields first when they are not built yet, as a new
+     *        record needs: its defaults live in fields that are only created on first use.
+     */
+    narrowHeldValuesForActiveUser(buildFields) {
+        const denied = this.deniedReadFieldsForActiveUser();
+        if (!denied) {
+            return;
+        }
+        if (!this._fieldsHydrated && !buildFields) {
+            if (this._raw) {
+                this._raw = OmitDeniedFieldKeys(this._raw, denied);
+                this._rawConverted = null;
+            }
+            return;
+        }
+        let cleared = false;
+        for (const field of this.Fields) {
+            if (denied.has(field.Name.trim().toLowerCase()) && (!field.NotLoaded || field.Value !== null)) {
+                field.ClearAsNotLoaded();
+                cleared = true;
+            }
+        }
+        if (cleared) {
+            this.discardJSONFieldObjects(); // a parsed JSON object can hold a value just dropped
+        }
+    }
     /**
      * Returns the active restore context for the next save, if any.
      *
@@ -4681,6 +5009,8 @@ export class BaseEntity {
     }
     finalizeSave(data, saveSubType, options) {
         if (data) {
+            // The 'save' event names the fields this save wrote; init() below clears every dirty flag.
+            const changedFieldNames = this.dirtyFieldNames();
             const effectiveReturnMode = options?.SaveReturnMode ?? this.EntityInfo.SaveReturnMode;
             const hasGetAll = (val) => val instanceof BaseEntity || typeof val.GetAll === 'function';
             const rawFieldData = hasGetAll(data) ? data.GetAll() : data;
@@ -4709,26 +5039,22 @@ export class BaseEntity {
             else {
                 fieldData = rawFieldData;
             }
-            this.init(); // wipe out the current data to flush out the DIRTY flags, load the ID as part of this too
-            // IS-A GetAll() merges the parent, including parent virtuals this entity
-            // does not own (e.g. OrderHeader on Event Order Line). Keep only columns
-            // this entity defines, and ignore anything leftover.
-            this.SetMany(this.ownedFieldsFrom(fieldData), true, true, true);
-            // finalizeSave re-hydrates from the save RESPONSE — a hydration source. Keys it
-            // omitted (e.g. fields the server stripped for field security) must be marked
-            // not-loaded, or the defaults init() just produced would masquerade as confirmed
-            // values and be resent on the NEXT save (the create/update-response corner: a
-            // trigger/system adjustment or concurrent change would be silently stomped).
-            if (typeof fieldData === 'object' && !Array.isArray(fieldData)) {
-                this.markFieldsOmittedBySourceAsNotLoaded(fieldData);
-            }
+            // The save returns the whole row, whoever saved it. The provider has already built the
+            // Record Changes payload from this entity's pre-save state, so narrowing the response
+            // here costs the audit nothing; it only keeps denied values out of this object.
+            fieldData = this.narrowHydrationSource(fieldData);
+            // Reset transient record state and update owned EntityField values in place so
+            // hydrated EntityField instances and _fieldCache/_codeNameCache are preserved across saves.
+            // Deliberately do NOT call discardJSONFieldObjects() here so JSONType references held
+            // across Save() remain attached and live.
+            this.resetAndApplyOwnedFieldsInPlace(fieldData);
             this._everSaved = true; // Mark as saved after successful save
             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);
+            this.RaiseEvent('save', null, saveSubType, changedFieldNames);
             return true;
         }
         else {
@@ -4864,16 +5190,17 @@ export class BaseEntity {
      * entity was hydrated FROM THE DATABASE on every FLS entity. Two distinct resolver behaviours
      * carry that premise, and BOTH are load-bearing:
      *
-     * 1. `StripDeniedReadFieldsFromClientInput` removes client-sent values for fields the caller
-     *    cannot READ, which `SetMany` would otherwise make genuinely dirty with fabricated data.
-     * 2. `entityInfo.EnableFieldLevelSecurity` forces the truth-load branch, so the entity's
+     * 1. `AssertClientInputFieldSecurity` (through `AssertClientInputWritableForUser`) rejects
+     *    client input naming a field the caller cannot READ, or no field at all, which `SetMany`
+     *    would otherwise make genuinely dirty with fabricated data.
+     * 2. `entityInfo.FieldLevelSecurityApplies` forces the truth-load branch, so the entity's
      *    non-dirty baseline is the real stored row rather than the client's `OldValues___`.
      *
      * (2) is not redundant with (1). A value arriving through `LoadFromData` is recorded by the
      * EntityField setter as the field's INITIAL value, so it is not dirty — and this check would
      * never see it, while `GenerateSaveSQL` sends it anyway (it filters on `NotLoaded`, never on
      * `Dirty`). Without the forced truth-load, a caller with Read Allow + Update Deny — the
-     * canonical FLS configuration, and one that leaves (1) with nothing to strip — could write an
+     * canonical FLS configuration, and one that leaves (1) with nothing to reject — could write an
      * update-denied field just by pinning its value in `OldValues___` and never naming it in the
      * mutation. If you are considering relaxing that branch condition, this check is what breaks.
      *
@@ -4906,7 +5233,7 @@ export class BaseEntity {
                 // deliberately skips the readability assertion (hydration / resolver-apply path),
                 // so server-side code can dirty a read-denied field and land here.
                 if (deniedRead === undefined) {
-                    deniedRead = this.deniedFieldsForActiveUser(u => this.EntityInfo.GetDeniedReadFields(u));
+                    deniedRead = this.deniedReadFieldsForActiveUser();
                 }
                 throw deniedRead?.has(key)
                     ? new FieldSecurityError(field.Name, this.EntityInfo.Name)
@@ -4955,15 +5282,32 @@ export class BaseEntity {
                 `omitted field(s) ${suppressed.join(', ')}; each column takes its default`);
         }
     }
+    /**
+     * Whether this object's user may READ the named field: the question `Get()` asks before it
+     * throws a `FieldSecurityError`, answered without throwing.
+     *
+     * For code that reads a field it did not choose, such as a configured path or a display
+     * column, and must treat a denied field as having no value rather than fail. Fails open the
+     * way `Get()` does: true when field security does not apply to this entity (or any IS-A
+     * ancestor) or no user resolves.
+     *
+     * @param fieldName the field's Name, matched case-insensitively
+     */
+    IsFieldReadableByActiveUser(fieldName) {
+        if (!fieldName) {
+            return true;
+        }
+        return !this.deniedReadFieldsForActiveUser()?.has(fieldName.trim().toLowerCase());
+    }
     /**
      * The denied-field set for the acting user, or null when field security does not apply —
-     * the entity has it switched off, no user resolves, or the user is denied nothing.
+     * it is off on the entity and every IS-A ancestor, no user resolves, or the user is denied nothing.
      *
      * Returning null rather than an empty Set lets callers skip their loop entirely, and keeps
      * the three cheap short-circuits in one place instead of repeated at each gate.
      */
     deniedFieldsForActiveUser(select) {
-        if (!this.EntityInfo?.EnableFieldLevelSecurity) {
+        if (!this.EntityInfo?.FieldLevelSecurityApplies) {
             return null; // one boolean for the overwhelming majority of entities
         }
         const u = this.resolveActiveUserOrNull();
@@ -4973,6 +5317,34 @@ export class BaseEntity {
         const denied = select(u);
         return denied.size > 0 ? denied : null;
     }
+    /**
+     * The fields this object's user may not READ, lowercased by Name and CodeName, or null when
+     * field security does not apply. Every readability question this class asks, at hydration,
+     * at the typed accessors and at the save gates, goes through here.
+     */
+    deniedReadFieldsForActiveUser() {
+        return this.deniedFieldsForActiveUser(u => this.EntityInfo.GetDeniedReadFields(u));
+    }
+    /**
+     * A hydration source reduced to what this object's user may hold: the same object when the
+     * user is denied nothing (or field security does not apply), otherwise a shallow copy without
+     * the denied keys, matched case-insensitively under Name and CodeName.
+     *
+     * Every point that fills this object from a row passes the row through here first, which is
+     * what makes the object's width a property of its user rather than of the path that built it.
+     * A key absent from a hydration source already means "not loaded" everywhere (`GetAll`, field
+     * building, the save), so omitting a denied key is all it takes for the value never to enter
+     * the object, and for every accessor and serializer to be correct without a check of its own.
+     *
+     * The caller's row is never modified, because it can be a frozen row shared through a cache,
+     * and an unrestricted user's row is returned by reference, so the raw load path stays zero-copy.
+     */
+    narrowHydrationSource(source) {
+        if (!source || typeof source !== 'object' || Array.isArray(source) || source instanceof Date) {
+            return source;
+        }
+        return OmitDeniedFieldKeys(source, this.deniedReadFieldsForActiveUser());
+    }
     /**
      * {@link ActiveUser}, but null instead of throwing when no provider is configured to resolve
      * one from.
@@ -5040,7 +5412,7 @@ export class BaseEntity {
             if (!this.IsSaved) {
                 this.init(); // wipe out current data if we're loading on top of existing record
             }
-            const data = await this.readRowForLoad(CompositeKey, EntityRelationshipsToLoad);
+            let data = await this.readRowForLoad(CompositeKey, EntityRelationshipsToLoad);
             this.discardJSONFieldObjects(); // a reload replaces the record's data
             if (!data) {
                 // A subtype-hint probe asks whether this row exists, so "no" is an answer, not an error
@@ -5049,6 +5421,9 @@ export class BaseEntity {
                 }
                 return false; // no data loaded, return false
             }
+            // Field security: denied values never enter this object, even from a provider that
+            // did not narrow its SELECT (see narrowHydrationSource).
+            data = this.narrowHydrationSource(data);
             // 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
@@ -5199,6 +5574,16 @@ export class BaseEntity {
      */
     async LoadFromData(data, _replaceOldValues = false) {
         this.discardJSONFieldObjects(); // the record's data is being replaced: parsed JSON objects are stale
+        // An entity object passed as the row is read through its own GetAll(): what ITS user may
+        // read, as a plain row. Kept as the row itself, it would be read through its typed getters,
+        // which answer for the source's user and so return values this object's user is denied
+        // (narrowing below sees only an object's own keys, and an entity's values are not those).
+        if (data instanceof BaseEntity) {
+            data = data.GetAll();
+        }
+        // Field security: a restricted user's object holds a copy of the row without the keys they
+        // are denied; anyone else's keeps the caller's row by reference (see narrowHydrationSource).
+        data = this.narrowHydrationSource(data);
         // 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.
@@ -5302,6 +5687,398 @@ export class BaseEntity {
         await this.deserializeCompanionsFromData(data);
         return true;
     }
+    /**
+     * Framework-internal batch IS-A parent hydration entry point used by
+     * `TransformSimpleObjectToEntityObject` when the provider supports batched `RunViews`.
+     *
+     * Collapses $O(2N)$ per-record child-discovery and child-load queries into at most
+     * 1 batched discovery query + 1 batched `RunViews` call per hierarchy depth level
+     * (and 0 discovery queries when a `SubtypeSelector` / `EntitySubtypeResolver` resolves all rows).
+     */
+    static { this.DEFAULT_ISA_BATCH_CHUNK_SIZE = 500; }
+    /**
+     * Maximum number of primary keys included in a single `WHERE PK IN (...)` batch query
+     * during IS-A child discovery or hydration.
+     */
+    static get ISABatchChunkSize() {
+        return BaseEntity.DEFAULT_ISA_BATCH_CHUNK_SIZE;
+    }
+    async LoadFromDataBatchAsISAParent(peers, md, contextUser) {
+        const loadedParents = [];
+        for (let i = 0; i < peers.length; i++) {
+            const { entity, data } = peers[i];
+            if (IsMemberOverridden(entity, 'LoadFromData', BaseEntity)) {
+                await entity.LoadFromData(data);
+                continue;
+            }
+            const allPksSet = await entity.hydrateSingleISAParentPeer(data);
+            if (allPksSet) {
+                loadedParents.push(entity);
+            }
+        }
+        if (loadedParents.length > 0) {
+            await BaseEntity.hydrateISAChildrenForLevel(loadedParents, md, contextUser);
+        }
+    }
+    async hydrateSingleISAParentPeer(rawData) {
+        this.discardJSONFieldObjects();
+        const dataObj = rawData instanceof BaseEntity
+            ? rawData.GetAll()
+            : rawData;
+        const narrowed = this.narrowHydrationSource(dataObj);
+        if (this._parentEntity && narrowed && typeof narrowed === 'object' && !Array.isArray(narrowed)) {
+            this._parentEntity.Hydrate(narrowed);
+        }
+        const isPlain = Boolean(narrowed && typeof narrowed === 'object' && !Array.isArray(narrowed) && !(narrowed instanceof Date));
+        this.SetMany(narrowed, true, false, true);
+        if (isPlain) {
+            this.markFieldsOmittedBySourceAsNotLoaded(narrowed);
+        }
+        let allPksSet = false;
+        if (this.PrimaryKeys && this.PrimaryKeys.length > 0) {
+            allPksSet = true;
+            for (const pkey of this.PrimaryKeys) {
+                if (pkey.Value === null || pkey.Value === undefined) {
+                    allPksSet = false;
+                    break;
+                }
+            }
+            this._recordLoaded = allPksSet;
+            this._everSaved = allPksSet;
+            if (allPksSet) {
+                this.cacheRecordName();
+            }
+        }
+        else {
+            LogError(`BaseEntity.LoadFromDataBatchAsISAParent() called on ${this.EntityInfo.Name} with no primary keys defined. This is an error state and should not happen.`);
+            this._recordLoaded = false;
+            this._everSaved = false;
+        }
+        await this.deserializeCompanionsFromData(narrowed);
+        return allPksSet;
+    }
+    static async hydrateISAChildrenForLevel(levelEntities, md, contextUser) {
+        const activeParents = levelEntities.filter(e => e._recordLoaded && e.EntityInfo.IsParentType && !e._childEntityDiscoveryDone && e.EntityInfo.ChildEntities.length > 0);
+        if (activeParents.length === 0) {
+            return;
+        }
+        const groupsByEntityId = new Map();
+        for (const p of activeParents) {
+            p._childEntityDiscoveryDone = true;
+            let group = groupsByEntityId.get(p.EntityInfo.ID);
+            if (!group) {
+                group = [];
+                groupsByEntityId.set(p.EntityInfo.ID, group);
+            }
+            group.push(p);
+        }
+        const nextLevelChildren = [];
+        for (const [, groupParents] of groupsByEntityId) {
+            const sampleParent = groupParents[0];
+            if (sampleParent.EntityInfo.AllowMultipleSubtypes) {
+                await BaseEntity.hydrateOverlappingChildrenForGroup(groupParents, contextUser);
+            }
+            else {
+                await BaseEntity.hydrateDisjointChildrenForGroup(groupParents, md, contextUser, nextLevelChildren);
+            }
+        }
+        if (nextLevelChildren.some(c => c.EntityInfo.IsParentType)) {
+            await BaseEntity.hydrateISAChildrenForLevel(nextLevelChildren, md, contextUser);
+        }
+    }
+    static async hydrateOverlappingChildrenForGroup(groupParents, contextUser) {
+        const sampleParent = groupParents[0];
+        const parentInfo = sampleParent.EntityInfo;
+        const entityProvider = sampleParent.ProviderToUse;
+        if (typeof entityProvider?.FindISAChildEntitiesBatch === 'function') {
+            const pks = groupParents.map(p => String(p.PrimaryKey.Values()));
+            const batchMap = await entityProvider.FindISAChildEntitiesBatch(parentInfo, pks, contextUser ?? sampleParent._contextCurrentUser);
+            const pkField = parentInfo.FirstPrimaryKey; // first-pk-ok: IS-A children share the parent's single key
+            for (const p of groupParents) {
+                const rawPk = String(p.PrimaryKey.Values());
+                const pkKey = pkField ? pkField.FormatCanonicalValue(rawPk) : CanonicalPrimaryKeyValue(rawPk, false);
+                const matched = batchMap.get(pkKey) ?? [];
+                p._childEntities = matched.map(name => ({ entityName: name }));
+            }
+        }
+        else {
+            await Promise.all(groupParents.map(p => p.discoverOverlappingChildren()));
+        }
+    }
+    static async hydrateDisjointChildrenForGroup(groupParents, md, contextUser, nextLevelChildren) {
+        const sampleParent = groupParents[0];
+        const parentInfo = sampleParent.EntityInfo;
+        const entityProvider = sampleParent.ProviderToUse;
+        const rvProvider = sampleParent.RunViewProviderToUse;
+        const effectiveUser = contextUser ?? sampleParent._contextCurrentUser;
+        // 1) Evaluate in-memory SubtypeSelector / EntitySubtypeResolver load hints
+        const { hintedByChild, hintedNameByParent, needsDiscovery } = await BaseEntity.partitionParentsBySubtypeLoadHint(groupParents, parentInfo, md, contextUser);
+        // 2) Batch-load hinted child rows in 1 RunViews call; any missing/failed row falls back to discovery
+        if (hintedByChild.size > 0) {
+            const unlinkedFromHints = await BaseEntity.batchLoadAndLinkDisjointChildren(hintedByChild, md, rvProvider, effectiveUser, nextLevelChildren);
+            for (const unlinked of unlinkedFromHints) {
+                // Same diagnostic the per-row path emits when a SubtypeSelector hint names a
+                // child that has no row: operators need the signal that a selector is wrong.
+                const hinted = hintedNameByParent.get(unlinked);
+                if (hinted) {
+                    BaseEntity.logLoadFoundNoRow(hinted, unlinked.PrimaryKey);
+                }
+                needsDiscovery.push(unlinked);
+            }
+        }
+        // 3) Batch-discover remaining unresolved parents in 1 query, then batch-load their child rows in 1 RunViews call
+        if (needsDiscovery.length > 0) {
+            const discoveredByChild = await BaseEntity.batchDiscoverDisjointChildren(parentInfo, needsDiscovery, entityProvider, rvProvider, effectiveUser);
+            if (discoveredByChild.size > 0) {
+                await BaseEntity.batchLoadAndLinkDisjointChildren(discoveredByChild, md, rvProvider, effectiveUser, nextLevelChildren);
+            }
+        }
+    }
+    static async partitionParentsBySubtypeLoadHint(groupParents, parentInfo, md, contextUser) {
+        const hintedByChild = new Map();
+        const hintedNameByParent = new Map();
+        const needsDiscovery = [];
+        for (const p of groupParents) {
+            const hintedName = await p.resolveSubtypeLoadHint();
+            if (hintedName) {
+                const childInfo = md.EntityByName?.(hintedName) ??
+                    parentInfo.ChildEntities.find(c => sameEntityName(c.Name, hintedName));
+                const userForPerm = contextUser ?? p._contextCurrentUser ?? md.CurrentUser;
+                const canRead = childInfo && userForPerm ? childInfo.GetUserPermisions(userForPerm).CanRead : true;
+                if (childInfo && canRead) {
+                    BaseEntity.appendParentToChildGroup(hintedByChild, childInfo.Name, p);
+                    hintedNameByParent.set(p, childInfo.Name);
+                }
+                else {
+                    needsDiscovery.push(p);
+                }
+            }
+            else {
+                needsDiscovery.push(p);
+            }
+        }
+        return { hintedByChild, hintedNameByParent, needsDiscovery };
+    }
+    static appendParentToChildGroup(grouped, childName, parent) {
+        let bucket = grouped.get(childName);
+        if (!bucket) {
+            bucket = [];
+            grouped.set(childName, bucket);
+        }
+        bucket.push(parent);
+    }
+    static buildChildPkInFilter(pkField, rawPkValues) {
+        const formatted = rawPkValues.map(val => {
+            if (!pkField.NeedsQuotes) {
+                // Emit the digits as written: a bigint beyond 2^53 must not be rewritten by Number().
+                const text = String(val).trim();
+                if (/^-?\d+(\.\d+)?$/.test(text)) {
+                    return text;
+                }
+            }
+            return `'${EscapeSQLString(String(val))}'`;
+        });
+        return `${pkField.Name} IN (${formatted.join(', ')})`;
+    }
+    static async batchDiscoverDisjointChildren(parentInfo, parents, entityProvider, rvProvider, contextUser) {
+        const pkField = parentInfo.FirstPrimaryKey; // first-pk-ok: IS-A children share the parent's single key
+        const pkIsUuid = Boolean(pkField?.IsUniqueIdentifier);
+        const grouped = new Map();
+        const pkValues = parents.map(p => String(p.PrimaryKey.Values()));
+        if (typeof entityProvider?.FindISAChildEntitiesBatch === 'function') {
+            const batchMap = await entityProvider.FindISAChildEntitiesBatch(parentInfo, pkValues, contextUser);
+            for (const p of parents) {
+                const pkKey = CanonicalPrimaryKeyValue(String(p.PrimaryKey.Values()), pkIsUuid);
+                const firstMatch = batchMap.get(pkKey)?.[0];
+                if (firstMatch) {
+                    BaseEntity.appendParentToChildGroup(grouped, firstMatch, p);
+                }
+            }
+            return grouped;
+        }
+        if (rvProvider && typeof rvProvider.RunViews === 'function') {
+            return BaseEntity.discoverDisjointChildrenViaRunViews(parentInfo, parents, pkValues, pkIsUuid, rvProvider, contextUser);
+        }
+        // Last-resort per-parent fallback when neither FindISAChildEntitiesBatch nor RunViews exists
+        if (typeof entityProvider?.FindISAChildEntity === 'function') {
+            for (const p of parents) {
+                const found = await entityProvider.FindISAChildEntity(parentInfo, String(p.PrimaryKey.Values()), contextUser);
+                if (found?.ChildEntityName) {
+                    BaseEntity.appendParentToChildGroup(grouped, found.ChildEntityName, p);
+                }
+            }
+        }
+        return grouped;
+    }
+    static async discoverDisjointChildrenViaRunViews(parentInfo, parents, pkValues, pkIsUuid, rvProvider, contextUser) {
+        const grouped = new Map();
+        const validChildren = parentInfo.ChildEntities.filter(c => c.FirstPrimaryKey != null); // first-pk-ok: IS-A children share the parent's single key
+        if (validChildren.length === 0)
+            return grouped;
+        const chunkSize = BaseEntity.ISABatchChunkSize;
+        const winnerByPk = new Map();
+        const rv = new RunView(rvProvider);
+        for (let start = 0; start < pkValues.length; start += chunkSize) {
+            const chunkPks = pkValues.slice(start, start + chunkSize);
+            const probeParams = validChildren.map(child => {
+                const childPk = child.FirstPrimaryKey; // first-pk-ok: IS-A children share the parent's single key
+                return {
+                    EntityName: child.Name,
+                    ExtraFilter: BaseEntity.buildChildPkInFilter(childPk, chunkPks),
+                    Fields: [childPk.Name],
+                    ResultType: 'simple',
+                    // Internal probe: the pre-batch path (InnerLoad) never touched the RunView
+                    // cache. Every distinct IN-list would otherwise become its own filtered
+                    // cache slot that is invalidated (never maintained) on each child save.
+                    BypassCache: true,
+                };
+            });
+            const probeResults = await rv.RunViews(probeParams, contextUser);
+            for (let cIdx = 0; cIdx < validChildren.length; cIdx++) {
+                const child = validChildren[cIdx];
+                const pkName = child.FirstPrimaryKey.Name; // first-pk-ok: IS-A children share the parent's single key
+                const res = probeResults[cIdx];
+                if (!res?.Success || !Array.isArray(res.Results))
+                    continue;
+                for (const row of res.Results) {
+                    const rawVal = row[pkName];
+                    if (rawVal != null) {
+                        const norm = CanonicalPrimaryKeyValue(String(rawVal), pkIsUuid);
+                        if (!winnerByPk.has(norm)) {
+                            winnerByPk.set(norm, child.Name);
+                        }
+                    }
+                }
+            }
+        }
+        for (const p of parents) {
+            const norm = CanonicalPrimaryKeyValue(String(p.PrimaryKey.Values()), pkIsUuid);
+            const childName = winnerByPk.get(norm);
+            if (childName) {
+                BaseEntity.appendParentToChildGroup(grouped, childName, p);
+            }
+        }
+        return grouped;
+    }
+    static async batchLoadAndLinkDisjointChildren(parentsByChildName, md, rvProvider, contextUser, outLinkedChildren) {
+        const unlinkedParents = [];
+        if (!rvProvider || typeof rvProvider.RunViews !== 'function') {
+            for (const [childName, parents] of parentsByChildName) {
+                for (const p of parents) {
+                    const linked = await p.createAndLinkChildEntity(childName);
+                    if (!linked) {
+                        unlinkedParents.push(p);
+                    }
+                }
+            }
+            return unlinkedParents;
+        }
+        const deniedChildLogged = new Set();
+        const slices = BaseEntity.buildDisjointChildQuerySlices(parentsByChildName, md, contextUser, unlinkedParents, deniedChildLogged);
+        if (slices.length === 0) {
+            return unlinkedParents;
+        }
+        const rv = new RunView(rvProvider);
+        const batchResults = await rv.RunViews(slices.map(s => s.param), contextUser);
+        for (let sIdx = 0; sIdx < slices.length; sIdx++) {
+            await BaseEntity.linkDisjointChildSliceResults(slices[sIdx], batchResults[sIdx], unlinkedParents, outLinkedChildren, deniedChildLogged);
+        }
+        return unlinkedParents;
+    }
+    static buildDisjointChildQuerySlices(parentsByChildName, md, contextUser, unlinkedParents, deniedChildLogged) {
+        const chunkSize = BaseEntity.ISABatchChunkSize;
+        const slices = [];
+        for (const [childName, parents] of parentsByChildName) {
+            const childInfo = md.EntityByName?.(childName) ??
+                parents[0]?.EntityInfo.ChildEntities.find(c => sameEntityName(c.Name, childName));
+            const pkField = childInfo?.FirstPrimaryKey; // first-pk-ok: IS-A children share the parent's single key
+            if (!childInfo || !pkField) {
+                for (const p of parents)
+                    unlinkedParents.push(p);
+                continue;
+            }
+            const userForPerm = contextUser ?? parents[0]?._contextCurrentUser ?? md.CurrentUser;
+            const canRead = userForPerm ? childInfo.GetUserPermisions(userForPerm).CanRead : true;
+            if (!canRead) {
+                if (!deniedChildLogged.has(childInfo.Name)) {
+                    deniedChildLogged.add(childInfo.Name);
+                    LogWarning(`BaseEntity: current user cannot read IS-A child '${childInfo.Name}'; matching parent records are returned without their subtype`, 'IS-A');
+                }
+                for (const p of parents)
+                    unlinkedParents.push(p);
+                continue;
+            }
+            for (let start = 0; start < parents.length; start += chunkSize) {
+                const sliceParents = parents.slice(start, start + chunkSize);
+                const pks = sliceParents.map(p => String(p.PrimaryKey.Values()));
+                slices.push({
+                    childName: childInfo.Name,
+                    pkFieldName: pkField.Name,
+                    pkIsUuid: Boolean(pkField.IsUniqueIdentifier),
+                    parents: sliceParents,
+                    param: {
+                        EntityName: childInfo.Name,
+                        ExtraFilter: BaseEntity.buildChildPkInFilter(pkField, pks),
+                        ResultType: 'simple',
+                        // Internal hydration read: see batchDiscoverDisjointChildren — keep these
+                        // per-batch IN-list reads out of the shared RunView cache.
+                        BypassCache: true,
+                    },
+                });
+            }
+        }
+        return slices;
+    }
+    static async linkDisjointChildSliceResults(slice, res, unlinkedParents, outLinkedChildren, deniedChildLogged) {
+        if (!res?.Success || !Array.isArray(res.Results)) {
+            // Not silent: the per-row path surfaced a failed child load; here the parents stay
+            // unlinked (plain parent records) and the cause goes to the log.
+            LogWarning(`BaseEntity: batched IS-A child load of '${slice.childName}' failed (${res?.ErrorMessage || 'no result'}); ${slice.parents.length} parent record(s) continue without their subtype`, 'IS-A');
+            for (const p of slice.parents)
+                unlinkedParents.push(p);
+            return;
+        }
+        const rowByPk = new Map();
+        for (const row of res.Results) {
+            const pkVal = row[slice.pkFieldName];
+            if (pkVal != null) {
+                rowByPk.set(CanonicalPrimaryKeyValue(String(pkVal), slice.pkIsUuid), row);
+            }
+        }
+        for (const p of slice.parents) {
+            const pkKey = CanonicalPrimaryKeyValue(String(p.PrimaryKey.Values()), slice.pkIsUuid);
+            const childRow = rowByPk.get(pkKey);
+            if (!childRow) {
+                unlinkedParents.push(p);
+                continue;
+            }
+            const childEntity = await p.createChildEntityObject(slice.childName);
+            if (!childEntity || !childEntity.CheckPermissions(EntityPermissionType.Read, false)) {
+                // The per-row path threw here (InnerLoad → CheckPermissions(Read, true)). The batch
+                // path degrades to a plain parent record instead, and says so once per slice.
+                if (!deniedChildLogged.has(slice.childName)) {
+                    deniedChildLogged.add(slice.childName);
+                    LogWarning(`BaseEntity: current user cannot read IS-A child '${slice.childName}'; matching parent records are returned without their subtype`, 'IS-A');
+                }
+                unlinkedParents.push(p);
+                continue;
+            }
+            await p.linkHydratedChildFromBatchRow(childEntity, childRow);
+            outLinkedChildren.push(childEntity);
+        }
+    }
+    async linkHydratedChildFromBatchRow(childEntity, childRow) {
+        this.replaceChildParentChain(childEntity);
+        this._childEntity = childEntity;
+        childEntity.discardJSONFieldObjects();
+        const narrowed = childEntity.narrowHydrationSource(childRow);
+        childEntity.resetAndApplyOwnedFieldsInPlace(narrowed);
+        childEntity._recordLoaded = true;
+        childEntity._everSaved = true;
+        childEntity._compositeKey = this.PrimaryKey;
+        childEntity.cacheRecordName();
+        await childEntity.deserializeCompanionsFromData(narrowed);
+    }
     /**
      * Extracts and applies a companion payload carried inside a plain data object, if present.
      *
@@ -5795,20 +6572,53 @@ export class BaseEntity {
         if (childEntities.length === 0) {
             return { HasChildren: false, ChildEntityName: '' };
         }
-        // Use RunView on this instance's provider — a host RunView cannot see
-        // uncommitted child rows on a graph-scoped connection.
-        const rv = new RunView(this.RunViewProviderToUse);
         const pkValue = this.PrimaryKey.Values();
-        for (const childEntity of childEntities) {
+        // Tier 1: Single UNION ALL SQL query on this entity's bound DatabaseProviderBase
+        // (executes inside any active transaction on this.ProviderToUse in 1 round-trip instead of K).
+        const entityProvider = this.ProviderToUse;
+        if (typeof entityProvider?.FindISAChildEntity === 'function') {
+            const found = await entityProvider.FindISAChildEntity(this.EntityInfo, String(pkValue), this._contextCurrentUser);
+            if (found?.ChildEntityName) {
+                return { HasChildren: true, ChildEntityName: found.ChildEntityName };
+            }
+            return { HasChildren: false, ChildEntityName: '' };
+        }
+        // Tier 2: Batched RunViews on this instance's RunView provider (GraphQLDataProvider or test mocks)
+        const rvProvider = this.RunViewProviderToUse;
+        const rv = new RunView(rvProvider);
+        const validChildren = childEntities.filter(c => c.FirstPrimaryKey != null); // first-pk-ok: IS-A children share the parent's single key
+        if (validChildren.length === 0) {
+            return { HasChildren: false, ChildEntityName: '' };
+        }
+        if (rvProvider && typeof rvProvider.RunViews === 'function') {
+            const viewParams = validChildren.map(childEntity => {
+                const pkField = childEntity.FirstPrimaryKey; // first-pk-ok: IS-A children share the parent's single key
+                return {
+                    EntityName: childEntity.Name,
+                    ExtraFilter: `${pkField.Name} = '${EscapeSQLString(String(pkValue))}'`,
+                    ResultType: 'simple',
+                    Fields: [pkField.Name],
+                    MaxRows: 1,
+                };
+            });
+            const results = await rv.RunViews(viewParams, this._contextCurrentUser);
+            for (let i = 0; i < validChildren.length; i++) {
+                const result = results[i];
+                if (result?.Success && result.Results && result.Results.length > 0) {
+                    return { HasChildren: true, ChildEntityName: validChildren[i].Name };
+                }
+            }
+            return { HasChildren: false, ChildEntityName: '' };
+        }
+        for (const childEntity of validChildren) {
             const pkField = childEntity.FirstPrimaryKey; // first-pk-ok: IS-A children share the parent's single key
-            if (!pkField)
-                continue;
             const result = await rv.RunView({
                 EntityName: childEntity.Name,
-                ExtraFilter: `${pkField.Name} = '${pkValue}'`,
+                ExtraFilter: `${pkField.Name} = '${EscapeSQLString(String(pkValue))}'`,
                 ResultType: 'simple',
                 Fields: [pkField.Name],
-                MaxRows: 1
+                MaxRows: 1,
+                SkipTotalRowCount: true
             }, this._contextCurrentUser);
             if (result && result.Success && result.Results && result.Results.length > 0) {
                 return { HasChildren: true, ChildEntityName: childEntity.Name };
@@ -5870,18 +6680,50 @@ export class BaseEntity {
         if (childEntities.length === 0) {
             return { LeafEntityName: entityInfo.Name, IsLeaf: true };
         }
-        const rv = new RunView((provider ?? BaseEntity.Provider));
         const pkValue = primaryKey.Values();
-        for (const child of childEntities) {
+        const candidateEntityProvider = (provider ?? BaseEntity.Provider);
+        if (typeof candidateEntityProvider?.FindISAChildEntity === 'function') {
+            const found = await candidateEntityProvider.FindISAChildEntity(entityInfo, String(pkValue), contextUser);
+            if (found?.ChildEntityName) {
+                const matchedChild = childEntities.find(c => sameEntityName(c.Name, found.ChildEntityName));
+                if (matchedChild) {
+                    return BaseEntity.resolveLeafEntityRecursive(matchedChild, primaryKey, contextUser, provider);
+                }
+            }
+            return { LeafEntityName: entityInfo.Name, IsLeaf: true };
+        }
+        const rvProvider = (provider ?? BaseEntity.Provider);
+        const rv = new RunView(rvProvider);
+        const validChildren = childEntities.filter(c => c.FirstPrimaryKey != null); // first-pk-ok: IS-A children share the parent's single key
+        if (rvProvider && typeof rvProvider.RunViews === 'function' && validChildren.length > 0) {
+            const viewParams = validChildren.map(child => {
+                const childPK = child.FirstPrimaryKey; // first-pk-ok: IS-A children share the parent's single key
+                return {
+                    EntityName: child.Name,
+                    ExtraFilter: `${childPK.Name} = '${EscapeSQLString(String(pkValue))}'`,
+                    ResultType: 'simple',
+                    Fields: [childPK.Name],
+                    MaxRows: 1,
+                };
+            });
+            const results = await rv.RunViews(viewParams, contextUser);
+            for (let i = 0; i < validChildren.length; i++) {
+                const result = results[i];
+                if (result?.Success && result.Results?.length > 0) {
+                    return BaseEntity.resolveLeafEntityRecursive(validChildren[i], primaryKey, contextUser, provider);
+                }
+            }
+            return { LeafEntityName: entityInfo.Name, IsLeaf: true };
+        }
+        for (const child of validChildren) {
             const childPK = child.FirstPrimaryKey; // first-pk-ok: IS-A children share the parent's single key
-            if (!childPK)
-                continue;
             const result = await rv.RunView({
                 EntityName: child.Name,
-                ExtraFilter: `${childPK.Name} = '${pkValue}'`,
+                ExtraFilter: `${childPK.Name} = '${EscapeSQLString(String(pkValue))}'`,
                 ResultType: 'simple',
                 Fields: [childPK.Name],
-                MaxRows: 1
+                MaxRows: 1,
+                SkipTotalRowCount: true
             }, contextUser);
             if (result?.Success && result.Results?.length > 0) {
                 // Found a child — recurse to see if there's an even more specific leaf
@@ -5928,10 +6770,11 @@ export class BaseEntity {
             return;
         const viewParams = validSiblings.map(sibling => ({
             EntityName: sibling.Name,
-            ExtraFilter: `${sibling.FirstPrimaryKey.Name} = '${pkValue}'`, // first-pk-ok: IS-A shared key
+            ExtraFilter: `${sibling.FirstPrimaryKey.Name} = '${EscapeSQLString(String(pkValue))}'`, // first-pk-ok: IS-A shared key
             ResultType: 'simple',
             Fields: [sibling.FirstPrimaryKey.Name], // first-pk-ok: IS-A shared key
-            MaxRows: 1
+            MaxRows: 1,
+            SkipTotalRowCount: true
         }));
         const results = await rv.RunViews(viewParams, this._contextCurrentUser);
         for (let i = 0; i < results.length; i++) {
@@ -6005,7 +6848,7 @@ export class BaseEntity {
         //
         // Returning null is the same answer callers already handle for "this entity has no name
         // field", and every one of them degrades to the primary key.
-        if (!this.EntityInfo.IsFieldReadableByUser(f.Name, this.ActiveUser)) {
+        if (!this.IsFieldReadableByActiveUser(f.Name)) {
             return null;
         }
         return this.Get(f.Name);
@@ -6135,7 +6978,8 @@ export class BaseEntity {
     }
     /**
      * Generates a vector embedding for a single text field using AI engine.
-     * Only generates embeddings for new records or when the source field has changed.
+     * Only generates embeddings for new records, when the source field has changed, or when
+     * {@link IsEmbeddingStale} reports the stored vector came from another model.
      * Stores the vector embedding, the model ID used to generate it and, when the entity has one, the
      * vector's binary companion.
      *
@@ -6153,33 +6997,46 @@ export class BaseEntity {
      * @returns Promise that resolves to true if embedding was generated successfully, false otherwise
      */
     async GenerateEmbedding(field, vectorField, modelField, binaryVectorField) {
+        const clearVector = () => {
+            vectorField.Value = null;
+            if (binaryVectorField)
+                binaryVectorField.Value = null;
+            if (modelField)
+                modelField.Value = null;
+        };
+        // After an edit to a saved record, its stored vector describes the old text, so a failed
+        // re-embed clears it rather than leaving it searchable.
+        const edited = this.IsSaved && field.Dirty;
         try {
             if (this._skipEmbeddings)
                 return true;
-            if (!this.IsSaved || field.Dirty) {
+            const stale = vectorField.Value != null && await this.IsEmbeddingStale(modelField?.Value ?? null);
+            if (!this.IsSaved || field.Dirty || stale) {
                 if (field.Value?.trim().length > 0) {
                     // recalc vector
                     const e = await this.EmbedTextLocal(field.Value);
-                    if (e && e.vector) {
+                    // An empty vector is a failed embed (the BaseEmbeddings convention); don't persist it.
+                    if (e?.vector?.length) {
                         vectorField.Value = JSON.stringify(e.vector);
                         if (binaryVectorField)
                             binaryVectorField.Value = Float32VectorToBase64(e.vector);
                         if (modelField)
                             modelField.Value = e.modelID;
                     }
+                    else if (edited) {
+                        clearVector();
+                    }
                 }
                 else {
-                    vectorField.Value = null;
-                    if (binaryVectorField)
-                        binaryVectorField.Value = null;
-                    if (modelField)
-                        modelField.Value = null;
+                    clearVector();
                 }
             }
             return true;
         }
         catch (e) {
             console.error("Error generating embedding:", e);
+            if (edited)
+                clearVector();
             return false;
         }
     }
@@ -6193,6 +7050,18 @@ export class BaseEntity {
     async EmbedTextLocal(textToEmbed) {
         throw new Error("EmbedTextLocal not implemented in BaseEntity, sub-classes must implement this functionality to use it");
     }
+    /**
+     * Whether a stored vector is stale: it came from a model other than the one this entity embeds
+     * with now, or from an unrecorded one. Asked only for a field that holds a vector. A stale vector
+     * is regenerated on the next save even when its text is unchanged, which is how stored vectors
+     * follow a change of embedding model. The base implementation returns false (only new or changed
+     * text is embedded); server-side sub-classes that embed with the platform's default local model
+     * override it.
+     * @param embeddingModelID - The ID of the AI model that produced the stored vector, or null
+     */
+    async IsEmbeddingStale(embeddingModelID) {
+        return false;
+    }
     /**
      * Specifies if the current object supports the @see EmbedTextLocal method or not - useful to know before calling it for conditional
      * code that has fallbacks as needed. BaseEntity does not implement this method but server-side sub-classes often do, but it is not mandatory for