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

package/dist/generic/databaseProviderBase.js

@@ -1,4 +1,5 @@
 import { ProviderBase } from "./providerBase.js";
+import { UserInfo } from "./securityInfo.js";
 import { EntityFieldTSType, EntityPermissionType } from "./entityInfo.js";
 import { BaseEntityResult, SerializeCloneChangeContext } from "./baseEntity.js";
 import { EntitySaveOptions, EntityDeleteOptions } from "./interfaces.js";
@@ -7,7 +8,9 @@ import { TransactionItem } from "./transactionGroup.js";
 import { CompositeKey } from "./compositeKey.js";
 import { LogError } from "./logging.js";
 import { LocalCacheManager } from "./localCacheManager.js";
-import { FormatBinaryChangeValue, ScanSQLForScreening, SQLExpressionValidator, uuidv4 } from "@memberjunction/global";
+import { AssertClientInputWritableForUser } from "./entityValueFieldSecurity.js";
+import { CanonicalPrimaryKeyValue } from "./util.js";
+import { FormatBinaryChangeValue, ScanSQLForScreening, SQLExpressionValidator, uuidv4, EscapeSQLString } from "@memberjunction/global";
 import { GetDialect } from "@memberjunction/sql-dialect";
 // Re-export PlatformSQL types from their canonical location for backward compatibility
 export { IsPlatformSQL } from "./platformSQL.js";
@@ -319,6 +322,28 @@ export class DatabaseProviderBase extends ProviderBase {
     get MJCoreSchemaName() {
         return this.ConfigData?.MJCoreSchemaName ?? '__mj';
     }
+    /**
+     * Builds a batched UNION ALL query probing all `childEntities`' `BaseView`s for a set
+     * of parent primary-key values (`WHERE pk IN (...)`), returning `(EntityName, RecordPK, Priority)`.
+     * Dialect providers override this to use platform-native string-literal and CAST syntax.
+     */
+    BuildChildDiscoveryBatchSQL(childEntities, recordPKValues) {
+        if (recordPKValues.length === 0)
+            return '';
+        const escapedKeys = recordPKValues
+            .map(v => `'${EscapeSQLString(String(v))}'`)
+            .join(', ');
+        const unionParts = childEntities
+            .filter(child => child.PrimaryKeys.length > 0)
+            .map((child, idx) => {
+            const schema = child.SchemaName || this.MJCoreSchemaName || '__mj';
+            const sourceRef = this.QuoteSchemaAndView(schema, child.BaseView);
+            const pkRef = this.QuoteIdentifier(child.FirstPrimaryKey.Name); // first-pk-ok: IS-A children share the parent's single key
+            const escapedName = `'${EscapeSQLString(child.Name)}'`;
+            return `SELECT ${escapedName} AS ${this.QuoteIdentifier('EntityName')}, CAST(${pkRef} AS VARCHAR(255)) AS ${this.QuoteIdentifier('RecordPK')}, ${idx + 1} AS ${this.QuoteIdentifier('Priority')} FROM ${sourceRef} WHERE ${pkRef} IN (${escapedKeys})`;
+        });
+        return unionParts.length > 0 ? unionParts.join(' UNION ALL ') : '';
+    }
     /**
      * Combined regex covering UUID functions from ALL platforms.
      * Used by the static convenience method for code that doesn't have a provider instance.
@@ -583,6 +608,91 @@ export class DatabaseProviderBase extends ProviderBase {
         }
         return [];
     }
+    static { this.DEFAULT_ISA_DISCOVERY_BATCH_CHUNK_SIZE = 500; }
+    /**
+     * Maximum number of parent primary keys included in a single `BuildChildDiscoveryBatchSQL`
+     * `WHERE PK IN (...)` statement inside {@link FindISAChildEntitiesBatch}.
+     */
+    get ISADiscoveryBatchChunkSize() {
+        return DatabaseProviderBase.DEFAULT_ISA_DISCOVERY_BATCH_CHUNK_SIZE;
+    }
+    /**
+     * Batch-discovers IS-A child entity types for multiple parent primary keys in a single
+     * UNION ALL SQL query (chunked at {@link ISADiscoveryBatchChunkSize} keys per statement to
+     * stay well within SQL limits).
+     */
+    async FindISAChildEntitiesBatch(entityInfo, recordPKValues, contextUser) {
+        const resultMap = new Map();
+        const childEntities = entityInfo.ChildEntities;
+        if (childEntities.length === 0 || recordPKValues.length === 0) {
+            return resultMap;
+        }
+        // IS-A children share the parent's single key, so the parent's key type decides how values
+        // are canonicalized (UUIDs case-insensitively, anything else by exact text).
+        const pkIsUuid = Boolean(entityInfo.FirstPrimaryKey?.IsUniqueIdentifier); // first-pk-ok: IS-A children share the parent's single key
+        const uniquePKs = this.deduplicateCanonicalPKs(recordPKValues, pkIsUuid);
+        if (uniquePKs.length === 0) {
+            return resultMap;
+        }
+        const priorityByChildName = new Map();
+        for (let i = 0; i < childEntities.length; i++) {
+            priorityByChildName.set(childEntities[i].Name.toLowerCase(), i + 1);
+        }
+        const chunkSize = this.ISADiscoveryBatchChunkSize;
+        const collected = new Map();
+        for (let start = 0; start < uniquePKs.length; start += chunkSize) {
+            const chunk = uniquePKs.slice(start, start + chunkSize);
+            await this.collectISAChildBatchChunk(childEntities, chunk, pkIsUuid, priorityByChildName, collected, contextUser);
+        }
+        for (const [pkKey, entries] of collected) {
+            entries.sort((a, b) => a.priority - b.priority);
+            const names = [];
+            for (const entry of entries) {
+                if (!names.includes(entry.name)) {
+                    names.push(entry.name);
+                }
+            }
+            resultMap.set(pkKey, names);
+        }
+        return resultMap;
+    }
+    deduplicateCanonicalPKs(recordPKValues, pkIsUuid) {
+        const uniquePKs = [];
+        const seen = new Set();
+        for (const rawPk of recordPKValues) {
+            if (!rawPk)
+                continue;
+            const norm = CanonicalPrimaryKeyValue(String(rawPk), pkIsUuid);
+            if (!seen.has(norm)) {
+                seen.add(norm);
+                uniquePKs.push(String(rawPk).trim());
+            }
+        }
+        return uniquePKs;
+    }
+    async collectISAChildBatchChunk(childEntities, chunk, pkIsUuid, priorityByChildName, collected, contextUser) {
+        const batchSQL = this.BuildChildDiscoveryBatchSQL(childEntities, chunk);
+        if (!batchSQL)
+            return;
+        const rows = await this.ExecuteSQL(batchSQL, undefined, undefined, contextUser);
+        if (!rows || rows.length === 0)
+            return;
+        for (const row of rows) {
+            const entityName = row.EntityName ?? row.ChildEntityName;
+            if (!entityName || row.RecordPK == null)
+                continue;
+            const pkKey = CanonicalPrimaryKeyValue(String(row.RecordPK), pkIsUuid);
+            const priority = typeof row.Priority === 'number'
+                ? row.Priority
+                : (priorityByChildName.get(entityName.toLowerCase()) ?? Number.MAX_SAFE_INTEGER);
+            let bucket = collected.get(pkKey);
+            if (!bucket) {
+                bucket = [];
+                collected.set(pkKey, bucket);
+            }
+            bucket.push({ name: entityName, priority });
+        }
+    }
     /**
      * Checks whether a given entity matches the target name, or is an ancestor
      * of the target (i.e., the target is somewhere in its descendant sub-tree).
@@ -710,6 +820,110 @@ export class DatabaseProviderBase extends ProviderBase {
     /**************************************************************************/
     // START ---- Record Dependencies
     /**************************************************************************/
+    /**
+     * High-volume system audit/telemetry entities excluded when `options.IncludeSystemEntities === false`.
+     */
+    static { this._systemDependencyEntityNames = new Set([
+        'mj: record changes',
+        'mj: audit logs',
+        'mj: user record logs',
+        'mj: user recordaccess',
+        'mj: entity record documents',
+    ]); }
+    /**
+     * Normalizes `(contextUserOrOptions, options)` so callers can invoke `GetRecordDependencies`
+     * with either `(entityName, key, options)` or `(entityName, key, contextUser, options)`.
+     */
+    resolveRecordDependencyArgs(contextUserOrOptions, options) {
+        if (options !== undefined) {
+            return { contextUser: contextUserOrOptions, options };
+        }
+        if (!contextUserOrOptions) {
+            return { contextUser: undefined, options: undefined };
+        }
+        if (contextUserOrOptions instanceof UserInfo ||
+            'UserRoles' in contextUserOrOptions ||
+            'Email' in contextUserOrOptions) {
+            return { contextUser: contextUserOrOptions, options: undefined };
+        }
+        return { contextUser: undefined, options: contextUserOrOptions };
+    }
+    /**
+     * Determines whether `relatedEntity` should be included in a record dependency scan
+     * based on `options` (`IncludeSystemEntities`, `EntityNames`) and `contextUser` read permissions.
+     */
+    shouldIncludeDependencyEntity(relatedEntity, options, contextUser) {
+        if (!this.shouldIncludeDependencyEntityName(relatedEntity.Name, options)) {
+            return false;
+        }
+        if (contextUser && typeof relatedEntity.CheckPermissions === 'function') {
+            if (!relatedEntity.CheckPermissions(contextUser, EntityPermissionType.Read, false)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Checks name-based dependency filters (`IncludeSystemEntities` and `EntityNames`)
+     * when only the entity name is available.
+     */
+    shouldIncludeDependencyEntityName(relatedEntityName, options) {
+        const normalizedName = relatedEntityName.trim().toLowerCase();
+        if (options?.IncludeSystemEntities === false) {
+            if (DatabaseProviderBase._systemDependencyEntityNames.has(normalizedName)) {
+                return false;
+            }
+        }
+        if (options?.EntityNames && options.EntityNames.length > 0) {
+            const allowed = options.EntityNames.some(n => n.trim().toLowerCase() === normalizedName);
+            if (!allowed) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Resolves an `EntityDependency[] | string` argument to an `EntityDependency[]` array.
+     * Supports passing either a pre-resolved `EntityDependency[]` list or an `entityName` string.
+     */
+    resolveEntityDependencies(entityDependenciesOrName) {
+        if (Array.isArray(entityDependenciesOrName)) {
+            return entityDependenciesOrName;
+        }
+        const eName = entityDependenciesOrName.trim().toLowerCase();
+        const result = [];
+        for (const re of this.Entities) {
+            const relatedFields = re.Fields.filter(f => f.RelatedEntity?.trim().toLowerCase() === eName && (!f.EntityIDFieldName || f.EntityIDFieldName.trim().length === 0));
+            for (const f of relatedFields) {
+                result.push({
+                    EntityName: entityDependenciesOrName,
+                    RelatedEntityName: re.Name,
+                    FieldName: f.Name,
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Selects `relatedEntity.BaseTable` when `BaseTable` is defined, the entity is not virtual,
+     * and all referenced columns (`PrimaryKeys` plus `referencedFieldNames`) are physical (`!f.IsVirtual`).
+     * Falls back to `relatedEntity.BaseView` when any referenced column is virtual or `BaseTable` is absent.
+     */
+    resolveDependencySourceObject(relatedEntity, referencedFieldNames) {
+        if (!relatedEntity.BaseTable || relatedEntity.BaseTable.trim().length === 0 || relatedEntity.VirtualEntity) {
+            return relatedEntity.BaseView;
+        }
+        if (relatedEntity.PrimaryKeys?.some(pk => pk.IsVirtual === true)) {
+            return relatedEntity.BaseView;
+        }
+        for (const fieldName of referencedFieldNames) {
+            const field = relatedEntity.Fields?.find(f => f.Name?.trim().toLowerCase() === fieldName?.trim().toLowerCase());
+            if (field?.IsVirtual === true) {
+                return relatedEntity.BaseView;
+            }
+        }
+        return relatedEntity.BaseTable;
+    }
     /**
      * Returns a list of record-level dependencies — records in other entities linked to
      * the specified entity/record via foreign keys (hard links) or EntityIDFieldName
@@ -717,10 +931,12 @@ export class DatabaseProviderBase extends ProviderBase {
      *
      * @param entityName The entity name to check
      * @param compositeKey The primary key(s) of the record
-     * @param contextUser Optional context user
+     * @param contextUser Optional context user (or options when called with 3 args)
+     * @param options Optional filtering options (`LinkType`, `IncludeSystemEntities`, `EntityNames`)
      */
-    async GetRecordDependencies(entityName, compositeKey, contextUser) {
+    async GetRecordDependencies(entityName, compositeKey, contextUser, options) {
         try {
+            const { contextUser: resolvedUser, options: resolvedOptions } = this.resolveRecordDependencyArgs(contextUser, options);
             const recordDependencies = [];
             // Validate up front. Reporting "no dependencies" for an entity we cannot resolve would be
             // indistinguishable, to a caller about to delete a record, from "this record is safe to
@@ -728,19 +944,40 @@ export class DatabaseProviderBase extends ProviderBase {
             if (!this.EntityByName(entityName)) {
                 throw new Error(`Entity ${entityName} not found in metadata`);
             }
-            const entityDependencies = await this.GetEntityDependencies(entityName);
-            // Deliberately NO early return when there are no hard (foreign key) dependents. An entity
-            // whose only dependents are polymorphic EntityID/RecordID links is precisely the case the
-            // soft-link query exists to serve, and returning here skipped building it entirely.
-            const hardSQL = entityDependencies.length > 0 ? this.BuildHardLinkDependencySQL(entityDependencies, compositeKey) : '';
-            const softSQL = this.BuildSoftLinkDependencySQL(entityName, compositeKey);
+            const linkType = resolvedOptions?.LinkType ?? 'both';
+            let hardSQL = '';
+            if (linkType === 'both' || linkType === 'hard') {
+                const rawEntityDependencies = await this.GetEntityDependencies(entityName);
+                const entityDependencies = rawEntityDependencies.filter((dep) => {
+                    const relEntity = this.EntityByName(dep.RelatedEntityName);
+                    if (relEntity) {
+                        return this.shouldIncludeDependencyEntity(relEntity, resolvedOptions, resolvedUser);
+                    }
+                    return this.shouldIncludeDependencyEntityName(dep.RelatedEntityName, resolvedOptions);
+                });
+                // Deliberately NO early return when there are no hard (foreign key) dependents. An entity
+                // whose only dependents are polymorphic EntityID/RecordID links is precisely the case the
+                // soft-link query exists to serve, and returning here skipped building it entirely.
+                hardSQL = entityDependencies.length > 0
+                    ? this.BuildHardLinkDependencySQL(entityDependencies, compositeKey, resolvedOptions, resolvedUser)
+                    : '';
+            }
+            const softSQL = linkType === 'both' || linkType === 'soft'
+                ? this.BuildSoftLinkDependencySQL(entityName, compositeKey, resolvedOptions, resolvedUser)
+                : '';
             const sSQL = [hardSQL, softSQL].filter(s => s.length > 0).join(' UNION ALL ');
             if (!sSQL)
                 return recordDependencies;
-            const result = await this.ExecuteSQL(sSQL, undefined, undefined, contextUser);
+            const result = await this.ExecuteSQL(sSQL, undefined, undefined, resolvedUser);
             if (!result || result.length === 0)
                 return recordDependencies;
-            return this.parseRecordDependencyResults(result);
+            return this.parseRecordDependencyResults(result).filter((dep) => {
+                const relEntity = this.EntityByName(dep.RelatedEntityName);
+                if (relEntity) {
+                    return this.shouldIncludeDependencyEntity(relEntity, resolvedOptions, resolvedUser);
+                }
+                return this.shouldIncludeDependencyEntityName(dep.RelatedEntityName, resolvedOptions);
+            });
         }
         catch (e) {
             LogError(e);
@@ -787,10 +1024,16 @@ export class DatabaseProviderBase extends ProviderBase {
                 pkeys[parts[0]] = parts.slice(1).join(CompositeKey.DefaultValueDelimiter);
             });
             depCompositeKey.LoadFromEntityInfoAndRecord(relatedEntityInfo, pkeys);
+            const fieldName = r.FieldName;
+            const fieldInfo = relatedEntityInfo.Fields?.find((f) => f.Name?.trim().toLowerCase() === fieldName?.trim().toLowerCase());
+            const fieldDisplayName = fieldInfo
+                ? (fieldInfo.DisplayNameOrName || fieldInfo.DisplayName || fieldInfo.Name)
+                : undefined;
             recordDependencies.push({
                 EntityName: r.EntityName,
                 RelatedEntityName: r.RelatedEntityName,
-                FieldName: r.FieldName,
+                FieldName: fieldName,
+                FieldDisplayName: fieldDisplayName,
                 PrimaryKey: depCompositeKey,
                 // Both dialects emit this literal on every row of the union: 1/true for the polymorphic
                 // branch, 0/false for the foreign key branch.
@@ -824,6 +1067,27 @@ export class DatabaseProviderBase extends ProviderBase {
     async OnBeforeSaveExecute(_entity, _user, _options, _context) {
         /* no-op by default */
     }
+    /**
+     * Returns true when `Save()` must enlist {@link OnDurableAfterSaveExecute} transactionally
+     * (wrapping direct saves in an {@link EntityTransactionScope}, and awaiting durable action
+     * submission inside `TransactionGroup` save callbacks before group completion).
+     *
+     * Default: `false` (zero extra transaction overhead on ordinary entity saves).
+     */
+    async ShouldEnlistSaveInTransaction(_entity, _user, _options, _isNewRecord) {
+        return false;
+    }
+    /**
+     * Awaited immediately after the save SQL succeeds (inside direct `Save()`'s
+     * {@link EntityTransactionScope} before commit, or inside a `TransactionGroup` item's completion
+     * callback after hydrating DB-generated PKs and before {@link OnAfterSaveExecute}) when
+     * {@link ShouldEnlistSaveInTransaction} returned `true`.
+     * Used by `GenericDatabaseProvider` to enlist durable after-save entity actions atomically in the
+     * same SQL transaction as the entity write.
+     */
+    async OnDurableAfterSaveExecute(_entity, _user, _options, _context) {
+        /* no-op by default */
+    }
     /**
      * Called after a successful save (both direct and transaction-callback paths).
      * Intentionally synchronous (fire-and-forget) — SQL Server overrides to dispatch
@@ -1252,7 +1516,7 @@ export class DatabaseProviderBase extends ProviderBase {
      * because there is nobody to check against.
      */
     CanUserReadRecordName(entity, contextUser) {
-        if (!entity.EnableFieldLevelSecurity) {
+        if (!entity.FieldLevelSecurityApplies) {
             return true;
         }
         if (!contextUser) {
@@ -1490,10 +1754,28 @@ export class DatabaseProviderBase extends ProviderBase {
                         configurable: true,
                     });
                     extraData.entityName = entity.EntityInfo.Name;
-                    entity.TransactionGroup.AddTransaction(new TransactionItem(entity, entityResult.Type === 'create' ? 'Create' : 'Update', sqlDetails.literalSQL ?? sqlDetails.fullSQL, sqlDetails.literalSQL ? null : (sqlDetails.parameters ?? null), extraData, (transactionResult, success) => {
+                    entity.TransactionGroup.AddTransaction(new TransactionItem(entity, entityResult.Type === 'create' ? 'Create' : 'Update', sqlDetails.literalSQL ?? sqlDetails.fullSQL, sqlDetails.literalSQL ? null : (sqlDetails.parameters ?? null), extraData, async (transactionResult, success) => {
                         resumeRefresh();
                         entityResult.EndedAt = new Date();
                         if (success && transactionResult) {
+                            if (bNewRecord) {
+                                let hydratedPk = false;
+                                for (const pkField of entity.EntityInfo.PrimaryKeys) {
+                                    const fieldObj = entity.Fields.find((f) => f.Name === pkField.Name);
+                                    if (fieldObj &&
+                                        (fieldObj.Value === null || fieldObj.Value === undefined) &&
+                                        transactionResult[pkField.Name] != null) {
+                                        fieldObj.Value = transactionResult[pkField.Name];
+                                        hydratedPk = true;
+                                    }
+                                }
+                                if (hydratedPk) {
+                                    entity.PrimaryKey.LoadFromEntityFields(entity.PrimaryKeys);
+                                }
+                            }
+                            if (await this.ShouldEnlistSaveInTransaction(entity, user, options, bNewRecord)) {
+                                await this.OnDurableAfterSaveExecute(entity, user, options, saveContext);
+                            }
                             this.OnAfterSaveExecute(entity, user, options, saveContext);
                             entityResult.Success = true;
                             const mergedResult = preSaveValues
@@ -1503,59 +1785,94 @@ export class DatabaseProviderBase extends ProviderBase {
                         }
                         else {
                             entityResult.Success = false;
-                            entityResult.Message = 'Transaction Failed';
+                            if (!entityResult.Message) {
+                                entityResult.Message = transactionResult instanceof Error
+                                    ? transactionResult.message
+                                    : 'Transaction Failed';
+                            }
                         }
                     }));
                     return true;
                 }
                 else {
                     // ---- Direct execution path ----
+                    const enlistInTx = !bReplay && await this.ShouldEnlistSaveInTransaction(entity, user, options, bNewRecord);
+                    const saveTxScope = enlistInTx ? await this.BeginEntityTransaction() : null;
+                    let saveTxCommitted = false;
                     suspendRefresh();
                     let result;
-                    if (bReplay) {
-                        result = [entity.GetAll()];
-                    }
-                    else {
-                        const execOptions = this.BuildSaveExecuteOptions(entity, sqlDetails);
-                        const rawResult = await this.ExecuteSQL(sqlDetails.fullSQL, sqlDetails.parameters ?? undefined, execOptions, user);
-                        result = await this.PostProcessRows(rawResult, entity.EntityInfo, user);
-                    }
-                    resumeRefresh();
-                    entityResult.EndedAt = new Date();
-                    if (result && result.length > 0) {
-                        this.OnAfterSaveExecute(entity, user, options, saveContext);
-                        entityResult.Success = true;
-                        // In 'datestamps_only' mode, the SP/query returned only the PK and
-                        // __mj_CreatedAt/__mj_UpdatedAt columns. Merge those returned values
-                        // onto the pre-save snapshot so caller-set fields remain intact without
-                        // falsely marking concurrent in-flight mutations as clean.
-                        let mergedRow;
-                        if (preSaveValues) {
-                            mergedRow = { ...preSaveValues, ...result[0] };
-                            Object.defineProperty(mergedRow, '__mj_preMerged', {
-                                value: true,
-                                enumerable: false,
-                                configurable: true,
-                            });
+                    try {
+                        if (bReplay) {
+                            result = [entity.GetAll()];
                         }
                         else {
-                            mergedRow = result[0];
+                            const execOptions = this.BuildSaveExecuteOptions(entity, sqlDetails);
+                            const rawResult = await this.ExecuteSQL(sqlDetails.fullSQL, sqlDetails.parameters ?? undefined, execOptions, user);
+                            result = await this.PostProcessRows(rawResult, entity.EntityInfo, user);
+                        }
+                        resumeRefresh();
+                        entityResult.EndedAt = new Date();
+                        if (result && result.length > 0) {
+                            if (bNewRecord) {
+                                let hydratedPk = false;
+                                for (const pkField of entity.EntityInfo.PrimaryKeys) {
+                                    const fieldObj = entity.Fields.find(f => f.Name === pkField.Name);
+                                    if (fieldObj && (fieldObj.Value === null || fieldObj.Value === undefined) && result[0][pkField.Name] != null) {
+                                        fieldObj.Value = result[0][pkField.Name];
+                                        hydratedPk = true;
+                                    }
+                                }
+                                if (hydratedPk) {
+                                    entity.PrimaryKey.LoadFromEntityFields(entity.PrimaryKeys);
+                                }
+                            }
+                            if (enlistInTx) {
+                                await this.OnDurableAfterSaveExecute(entity, user, options, saveContext);
+                            }
+                            if (saveTxScope) {
+                                await saveTxScope.Commit();
+                                saveTxCommitted = true;
+                            }
                         }
-                        // OnSaveCompleted may return patch fields (e.g., updated lat/lng
-                        // from geocoding) that need to be merged onto the SP result before
-                        // the entity loads the data via finalizeSave().
-                        const patches = await this.OnSaveCompleted(entity, sqlDetails, user, options, saveContext);
-                        if (patches) {
-                            Object.assign(mergedRow, patches);
+                        else {
+                            if (bNewRecord)
+                                throw new Error(`SQL Error: Error creating new record, no rows returned from SQL: ${sqlDetails.literalSQL ?? sqlDetails.fullSQL}`);
+                            else
+                                throw new Error(`SQL Error: Error updating record, no MATCHING rows found within the database: ${sqlDetails.literalSQL ?? sqlDetails.fullSQL}`);
                         }
-                        return mergedRow;
+                    }
+                    catch (innerErr) {
+                        if (saveTxScope && !saveTxCommitted) {
+                            await saveTxScope.Rollback();
+                        }
+                        throw innerErr;
+                    }
+                    this.OnAfterSaveExecute(entity, user, options, saveContext);
+                    entityResult.Success = true;
+                    // In 'datestamps_only' mode, the SP/query returned only the PK and
+                    // __mj_CreatedAt/__mj_UpdatedAt columns. Merge those returned values
+                    // onto the pre-save snapshot so caller-set fields remain intact without
+                    // falsely marking concurrent in-flight mutations as clean.
+                    let mergedRow;
+                    if (preSaveValues) {
+                        mergedRow = { ...preSaveValues, ...result[0] };
+                        Object.defineProperty(mergedRow, '__mj_preMerged', {
+                            value: true,
+                            enumerable: false,
+                            configurable: true,
+                        });
                     }
                     else {
-                        if (bNewRecord)
-                            throw new Error(`SQL Error: Error creating new record, no rows returned from SQL: ${sqlDetails.literalSQL ?? sqlDetails.fullSQL}`);
-                        else
-                            throw new Error(`SQL Error: Error updating record, no MATCHING rows found within the database: ${sqlDetails.literalSQL ?? sqlDetails.fullSQL}`);
+                        mergedRow = result[0];
+                    }
+                    // OnSaveCompleted may return patch fields (e.g., updated lat/lng
+                    // from geocoding) that need to be merged onto the SP result before
+                    // the entity loads the data via finalizeSave().
+                    const patches = await this.OnSaveCompleted(entity, sqlDetails, user, options, saveContext);
+                    if (patches) {
+                        Object.assign(mergedRow, patches);
                     }
+                    return mergedRow;
                 }
             }
             else {
@@ -1987,6 +2304,11 @@ export class DatabaseProviderBase extends ProviderBase {
         duplicateRun.Set('ProcessingStatus', 'In Progress');
         duplicateRun.Set('ApprovalStatus', 'Pending');
         duplicateRun.Set('SourceListID', listEntity.Get('ID'));
+        // Without a document, the server-side Duplicate Run entity defaults to the entity's
+        // duplicate-detection document.
+        if (params.EntityDocumentID) {
+            duplicateRun.Set('EntityDocumentID', params.EntityDocumentID);
+        }
         const saveResult = await duplicateRun.Save();
         if (!saveResult) {
             throw new Error('Failed to save Duplicate Run Entity');
@@ -2023,6 +2345,13 @@ export class DatabaseProviderBase extends ProviderBase {
                     throw new Error(`Record ${key.ToString()} of ${request.EntityName} has a ${child.ChildEntityName} subtype row; merging records another entity extends is not supported yet`);
             }
         }
+        // The field map is client input applied to the surviving record: a caller with any field
+        // denial may name only fields they can read, and a denied name and an unknown name get the
+        // same refusal. Checked before the merge log and the transaction, so a refusal leaves no trace.
+        if (request.FieldMap?.length) {
+            const values = Object.fromEntries(request.FieldMap.map(f => [f.FieldName, f.Value]));
+            AssertClientInputWritableForUser(e, values, contextUser);
+        }
         const result = {
             Success: false,
             RecordMergeLogID: null,