@memberjunction/sqlserver-dataprovider 6.2.0-edge.4 → 6.2.0-edge.6

package/dist/SQLServerDataProvider.js

@@ -22,6 +22,7 @@ import { GenericDatabaseProvider } from '@memberjunction/generic-database-provid
 import sql from 'mssql';
 import { BehaviorSubject, Subject, concatMap, from, catchError, of } from 'rxjs';
 import { SQLServerTransactionGroup } from './SQLServerTransactionGroup.js';
+import { EXECUTED_VARIABLE_SUFFIX, IsSaveParameterList, RenderSaveSQL, SaveParameterCollector, } from './saveParameters.js';
 import { SQLServerProviderConfigData } from './types.js';
 import { EscapeSQLString, IsByteArray, TryBase64ToBytes } from '@memberjunction/global';
 import { SQLServerDialect } from '@memberjunction/sql-dialect';
@@ -72,6 +73,13 @@ function buildRequest(connectionSource, query, parameters) {
     else {
         request = new sql.Request(connectionSource);
     }
+    if (IsSaveParameterList(parameters)) {
+        // A save or delete statement (saveParameters.ts): named inputs typed from the columns.
+        for (const p of parameters) {
+            request.input(p.Name, p.Type, p.Value);
+        }
+        return { request, processedQuery: query };
+    }
     let processedQuery = query;
     if (parameters) {
         if (Array.isArray(parameters)) {
@@ -150,22 +158,20 @@ async function executeSQLCore(query, parameters, context, options, isRetry = fal
         error.code = 'POOL_CLOSED';
         throw error;
     }
-    // Handle logging
-    let logPromise;
-    if (options && !options.ignoreLogging && context.logSqlStatement) {
-        logPromise = context.logSqlStatement(query, parameters, options.description, options.ignoreLogging, options.isMutation, options.simpleSQLFallback, options.contextUser);
-    }
-    else {
-        logPromise = Promise.resolve();
-    }
     try {
         const { request, processedQuery } = buildRequest(connectionSource, query, parameters);
-        // Execute query and logging in parallel
-        const [result] = await Promise.all([
-            options?.timeoutMs ? QueryWithTimeout(request, processedQuery, options.timeoutMs) : request.query(processedQuery),
-            logPromise
-        ]);
-        return result;
+        const queryPromise = options?.timeoutMs
+            ? QueryWithTimeout(request, processedQuery, options.timeoutMs)
+            : request.query(processedQuery);
+        if (options && !options.ignoreLogging && context.logSqlStatement) {
+            const literalSQL = options.literalSQL;
+            const [result] = await Promise.all([
+                queryPromise,
+                context.logSqlStatement(literalSQL ?? query, literalSQL ? undefined : parameters, options.description, options.ignoreLogging, options.isMutation, options.simpleSQLFallback, options.contextUser)
+            ]);
+            return result;
+        }
+        return await queryPromise;
     }
     catch (error) {
         // Retry once for stale connection errors on non-transactional queries.
@@ -185,10 +191,11 @@ async function executeSQLCore(query, parameters, context, options, isRetry = fal
                 .map((e) => e?.message ?? String(e))
                 .join(' | ')}`
             : '';
+        const literalSQL = options?.literalSQL;
         const errorMessage = `Error executing SQL
     Error: ${error?.message ? error.message : error}${precedingMsgs}
-    Query: ${query}
-    Parameters: ${parameters ? JSON.stringify(parameters) : 'None'}`;
+    Query: ${literalSQL ?? query}
+    Parameters: ${literalSQL || !parameters ? 'None' : JSON.stringify(parameters)}`;
         // Preserve the original error type (ConnectionError vs RequestError) so callers
         // can structurally distinguish infrastructure failures from query-level errors.
         // Attach the detailed message while keeping the error's class identity and code.
@@ -206,8 +213,6 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         this._refreshSuspendCount = 0;
         /** Refresh() calls waiting for `_refreshSuspendCount` to reach zero. */
         this._refreshResumeWaiters = [];
-        this._needsDatetimeOffsetAdjustment = false;
-        this._datetimeOffsetTestComplete = false;
         /**
          * Per-entity base-view column order — the view's column NAMES in physical (`column_id`) order,
          * keyed by `'<schema>.<baseview>'` lowercased. Populated in {@link Config} (after metadata
@@ -239,7 +244,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
          * ENOTBEGUN on a finished handle. A query on an explicit handle a caller passed in — an IS-A chain
          * sharing its own transaction — is never subject to that check.
          */
-        this._sqlQueue$ = new Subject();
+        this._sqlQueue$ = null;
         /**
          * Handles whose commit or rollback has run — or whose commit FAILED, which dooms them just the same.
          * The ambient check in runQueueItem consults this as well as `_transaction`, because a failed
@@ -247,16 +252,19 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
          * already being dequeued; without the marker that item would run on the doomed handle.
          */
         this._endedHandles = new WeakSet();
-        // Transaction state management
-        this._transactionState$ = new BehaviorSubject(false);
+        // Transaction state management — lazy-allocated so read-only per-request providers
+        // avoid allocating RxJS Subject/BehaviorSubject instances when no transaction is opened.
+        this._isTransactionActive = false;
+        this._transactionState$ = null;
     }
     /**
      * Returns the SQL Server dialect instance so that platform-specific tokens
      * (batch separator, quoted identifiers, etc.) are sourced from
      * `@memberjunction/sql-dialect` rather than hardcoded strings.
      */
+    static { this._dialectInstance = new SQLServerDialect(); }
     getDialect() {
-        return new SQLServerDialect();
+        return SQLServerDataProvider._dialectInstance;
     }
     QuoteIdentifier(name) {
         // Double embedded closing brackets so a name containing `]` cannot terminate the
@@ -276,6 +284,29 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
     }
     /** Longest an explicit Refresh() waits for in-flight saves before giving up (returning false). */
     static { this.REFRESH_WAIT_TIMEOUT_MS = 30_000; }
+    static { this._needsDatetimeOffsetAdjustment = false; }
+    static { this._datetimeOffsetTestComplete = false; }
+    static { this._datetimeOffsetTestPromise = null; }
+    /** When the last datetimeoffset probe failed (ms since epoch), or null if it hasn't failed since the last success. */
+    static { this._datetimeOffsetTestFailedAt = null; }
+    /** After a failed probe, callers use the safe default for this long before probing again. */
+    static { this.DATETIMEOFFSET_PROBE_RETRY_MS = 30_000; }
+    get _needsDatetimeOffsetAdjustment() {
+        return SQLServerDataProvider._needsDatetimeOffsetAdjustment;
+    }
+    set _needsDatetimeOffsetAdjustment(value) {
+        SQLServerDataProvider._needsDatetimeOffsetAdjustment = value;
+    }
+    get _datetimeOffsetTestComplete() {
+        return SQLServerDataProvider._datetimeOffsetTestComplete;
+    }
+    set _datetimeOffsetTestComplete(value) {
+        SQLServerDataProvider._datetimeOffsetTestComplete = value;
+        if (!value) {
+            SQLServerDataProvider._datetimeOffsetTestPromise = null;
+            SQLServerDataProvider._datetimeOffsetTestFailedAt = null;
+        }
+    }
     /**
      * Process-wide view-column-order cache, scoped PER CONNECTION POOL and shared across provider
      * instances. MJServer creates 1–2 fresh, fully-Config()'d provider instances per GraphQL request
@@ -296,6 +327,24 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
      * migrations/CodeGen are picked up without a server restart.
      */
     static { this._viewColumnOrderCacheByPool = new WeakMap(); }
+    ensureSqlQueue() {
+        if (!this._sqlQueue$) {
+            this._sqlQueue$ = new Subject();
+        }
+        return this._sqlQueue$;
+    }
+    ensureTransactionStateSubject() {
+        if (!this._transactionState$) {
+            this._transactionState$ = new BehaviorSubject(this._isTransactionActive);
+        }
+        return this._transactionState$;
+    }
+    setTransactionActiveState(active) {
+        this._isTransactionActive = active;
+        if (this._transactionState$) {
+            this._transactionState$.next(active);
+        }
+    }
     /**
      * Observable that emits the current transaction state (true when active, false when not)
      * External code can subscribe to this to know when transactions start and end
@@ -306,7 +355,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
      * });
      */
     get TransactionState$() {
-        return this._transactionState$.asObservable();
+        return this.ensureTransactionStateSubject().asObservable();
     }
     /** @deprecated Use {@link TransactionState$}. */
     get transactionState$() {
@@ -338,7 +387,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
     get IsTransactionActive() {
         // Always return instance-level state
         // Request-specific state should be accessed via getTransactionContext
-        return this._transactionState$.value;
+        return this._isTransactionActive;
     }
     /** @deprecated Use {@link IsTransactionActive}. */
     get isTransactionActive() {
@@ -370,8 +419,6 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
     async Config(configData, providerToUse) {
         try {
             this._pool = configData.ConnectionPool; // Now expects a ConnectionPool instead of DataSource
-            // Initialize the instance queue processor
-            this.initializeQueueProcessor();
             const configured = await super.Config(configData, providerToUse); // now parent class can do it's config
             // After metadata is loaded, capture each base view's REAL column order so the save-capture
             // @ResultTable is declared to match it (see _viewColumnOrderCache + getAllEntityColumnsSQL).
@@ -500,7 +547,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         // Each instance gets its own queue processor, but only do this ONCE if we get this method called more than once we don't need to reinit
         // the sub, taht would cause duplicate rprocessing.
         if (!this._queueSubscription) {
-            this._queueSubscription = this._sqlQueue$.pipe(concatMap(item => from(this.runQueueItem(item)).pipe(
+            this._queueSubscription = this.ensureSqlQueue().pipe(concatMap(item => from(this.runQueueItem(item)).pipe(
             // runQueueItem settles the item's own promise on success; only failure is handled here
             catchError(error => {
                 item.reject(error);
@@ -600,7 +647,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         // Build array of SQL statements for batch execution
         const sqlStatements = [];
         for (const { query } of items) {
-            // CacheValidationSQL should return MaxUpdatedAt and RowCount
+            // CacheValidationSQL returns MaxUpdatedAt and a row count (TotalRows or RowCount)
             sqlStatements.push(query.CacheValidationSQL);
         }
         try {
@@ -610,17 +657,8 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
             for (let i = 0; i < items.length; i++) {
                 const { index } = items[i];
                 const resultSet = resultSets[i];
-                if (resultSet && resultSet.length > 0) {
-                    const row = resultSet[0];
-                    results.set(index, {
-                        success: true,
-                        rowCount: row.RowCount,
-                        maxUpdatedAt: row.MaxUpdatedAt ? new Date(row.MaxUpdatedAt).toISOString() : undefined,
-                    });
-                }
-                else {
-                    results.set(index, { success: true, rowCount: 0, maxUpdatedAt: undefined });
-                }
+                // Shared reader: accepts the documented `TotalRows` as well as `RowCount`.
+                results.set(index, this.QueryCacheStatusFromRow(resultSet?.[0]));
             }
         }
         catch (e) {
@@ -656,9 +694,11 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         if (items.length === 0) {
             return results;
         }
-        // Build array of SQL statements for batch execution
+        // Build array of SQL statements for batch execution (recording per-item resolution errors
+        // in `results` without aborting valid sibling items in the batch)
         const sqlStatements = [];
-        for (const { entityInfo, whereSQL, item } of items) {
+        const validItems = [];
+        for (const { index, entityInfo, whereSQL, item } of items) {
             // The freshness probe MUST target the same physical view the read targets. For a
             // DataSource:'Materialized' read that's the materialized_vw<CodeName> wrapper (a full SELECT *
             // snapshot of the base view, so it carries __mj_UpdatedAt) — NOT the live base view. Probing the
@@ -668,15 +708,27 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
             // still supplies a materialized cacheStatus.) Use the status-gated resolveEffectiveBaseView (not the
             // unconditional GetEffectiveBaseView) so a Building/DriftHold/Disabled/never-minted snapshot probes the
             // LIVE base view — mirroring the read path — instead of a held or missing materialized_vw wrapper.
-            const effectiveView = await this.resolveEffectiveBaseView(entityInfo, item.params, contextUser);
-            sqlStatements.push(this.BuildCacheStatusSQL(entityInfo, effectiveView, whereSQL));
+            try {
+                const effectiveTarget = await this.resolveEffectiveBaseViewTarget(entityInfo, item.params, contextUser);
+                sqlStatements.push(this.BuildCacheStatusSQL(entityInfo, effectiveTarget.viewName, whereSQL, effectiveTarget.schemaName));
+                validItems.push({ index });
+            }
+            catch (err) {
+                results.set(index, {
+                    success: false,
+                    errorMessage: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        if (sqlStatements.length === 0) {
+            return results;
         }
         try {
             // Execute the batched SQL using existing ExecuteSQLBatch method
             const resultSets = await this.ExecuteSQLBatch(sqlStatements, undefined, undefined, contextUser);
             // Process each result set and map to the corresponding item index
-            for (let i = 0; i < items.length; i++) {
-                const { index } = items[i];
+            for (let i = 0; i < validItems.length; i++) {
+                const { index } = validItems[i];
                 const resultSet = resultSets[i];
                 if (resultSet && resultSet.length > 0) {
                     const row = resultSet[0];
@@ -704,24 +756,25 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         }
         return results;
     }
-    async executeSQLForUserViewRunLogging(viewId, entityInfo, effectiveBaseView, whereSQL, orderBySQL, user) {
+    async executeSQLForUserViewRunLogging(viewId, entityInfo, effectiveBaseView, whereSQL, orderBySQL, user, schemaNameOverride) {
         // entityInfo + effectiveBaseView are passed in (no reverse-lookup by base-view name) so the logged
-        // read honors DataSource:'Materialized' — effectiveBaseView is the materialized wrapper view then,
-        // and the entity's live base view otherwise.
+        // read honors DataSource:'Materialized' and AlternateBaseView — effectiveBaseView is the materialized
+        // or alternate view then, and the entity's live base view otherwise.
         //
         // UserViewRunDetail.RecordID is a single NVARCHAR(255) holding ONE bare key value per row, and the
         // read-back below is `<pk> IN (SELECT RecordID ...)` — a one-column predicate. A composite key has
         // no single column to log or match on, so refuse rather than record (and re-read) a truncated key.
         this.assertSingleColumnPrimaryKey(entityInfo, 'SaveViewResults (user view run logging)');
         const pkName = entityInfo.FirstPrimaryKey.Name; // first-pk-ok: guarded above — view-run RecordID holds one bare key value, PrimaryKeys.length === 1 enforced
+        const targetSchema = schemaNameOverride ?? entityInfo.SchemaName;
         const sSQL = `
             DECLARE @ViewIDList TABLE ( ID NVARCHAR(255) );
-            INSERT INTO @ViewIDList (ID) (SELECT ${pkName} FROM [${entityInfo.SchemaName}].${effectiveBaseView} WHERE (${whereSQL}))
+            INSERT INTO @ViewIDList (ID) (SELECT ${pkName} FROM [${targetSchema}].${effectiveBaseView} WHERE (${whereSQL}))
             EXEC [${this.MJCoreSchemaName}].spCreateUserViewRunWithDetail(${viewId},${user.Email}, @ViewIDLIst)
             `;
         const runIDResult = await this.ExecuteSQL(sSQL, undefined, undefined, user);
         const runID = runIDResult[0].UserViewRunID;
-        const sRetSQL = `SELECT * FROM [${entityInfo.SchemaName}].${effectiveBaseView} WHERE ${pkName} IN
+        const sRetSQL = `SELECT * FROM [${targetSchema}].${effectiveBaseView} WHERE ${pkName} IN
                                     (SELECT RecordID FROM [${this.MJCoreSchemaName}].vwUserViewRunDetails WHERE UserViewRunID=${runID})
                                  ${orderBySQL && orderBySQL.length > 0 ? ` ORDER BY ${orderBySQL}` : ''}`;
         return { executeViewSQL: sRetSQL, runID };
@@ -742,7 +795,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
      * @param entityName
      * @param compositeKey
      */
-    BuildSoftLinkDependencySQL(entityName, compositeKey) {
+    BuildSoftLinkDependencySQL(entityName, compositeKey, options, contextUser) {
         // we need to go through ALL of the entities in the system and find all of the EntityFields that have a non-null EntityIDFieldName
         // for each of these, we generate a SQL Statement that will return the EntityName, RelatedEntityName, FieldName, and the primary key values of the related entity
         //
@@ -753,11 +806,17 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         if (!targetEntity) {
             throw new Error(`Entity ${entityName} not found in metadata`);
         }
-        // The canonical stored encoding of the target record's key - `ID|<guid>` (see CompositeKey.ToRecordID).
-        // A RecordID column holds this, not the bare primary key value.
-        const targetRecordID = compositeKey.ToRecordID();
+        // Single-primary-key records referenced by polymorphic tables may store either the canonical
+        // `ID|<guid>` encoding (`CompositeKey.ToRecordID()`) OR the bare primary key value (`<guid>`).
+        const targetRecordID = this.escapeSQLLiteral(compositeKey.ToRecordID());
+        const bareValue = compositeKey.KeyValuePairs.length === 1
+            ? this.escapeSQLLiteral(String(compositeKey.KeyValuePairs[0].Value ?? ''))
+            : '';
         let sSQL = '';
         this.Entities.forEach((entity) => {
+            if (!this.shouldIncludeDependencyEntity(entity, options, contextUser)) {
+                return;
+            }
             // we build a string that will concatenate all of the primary key values into a single string, this is because the primary key could be a composite key
             // we do this in SQL by combining the pirmary key name and value for each row using the default separator defined by the CompositeKey class
             // the output of this should be like the following 'Field1|Value1||Field2|Value2||Field3|Value3' where the || is the CompositeKey.DefaultFieldDelimiter and the | is the CompositeKey.DefaultValueDelimiter
@@ -767,6 +826,10 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
                 // each field in f must be processed
                 if (sSQL.length > 0)
                     sSQL += ' UNION ALL ';
+                const sourceObject = this.resolveDependencySourceObject(entity, [f.Name, f.EntityIDFieldName]);
+                const recordIDPredicate = bareValue && bareValue !== targetRecordID
+                    ? `[${f.Name}] IN ('${targetRecordID}', '${bareValue}')`
+                    : `[${f.Name}] = '${targetRecordID}'`;
                 // there is a layer of indirection here because each ROW in each of the entity records for this entity/field combination could point to a DIFFERENT
                 // entity. We find out which entity it is pointed to via the EntityIDFieldName in the field definition, so we have to filter the rows in the entity
                 // based on that.
@@ -782,10 +845,10 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
                             1 AS IsSoftLink,
                             '${f.EntityIDFieldName}' AS EntityIDFieldName
                         FROM
-                            [${entity.SchemaName}].[${entity.BaseView}]
+                            [${entity.SchemaName}].[${sourceObject}]
                         WHERE
                             [${f.EntityIDFieldName}] = '${targetEntity.ID}' AND
-                            [${f.Name}] = '${this.escapeSQLLiteral(targetRecordID)}'`;
+                            ${recordIDPredicate}`;
             });
         });
         return sSQL;
@@ -798,13 +861,22 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
     escapeSQLLiteral(value) {
         return value.replace(/'/g, "''");
     }
-    BuildHardLinkDependencySQL(entityDependencies, compositeKey) {
+    BuildHardLinkDependencySQL(entityDependenciesOrName, compositeKey, options, contextUser) {
+        const entityDependencies = this.resolveEntityDependencies(entityDependenciesOrName);
         let sSQL = '';
         for (const entityDependency of entityDependencies) {
             const entityInfo = this.Entities.find((e) => e.Name.trim().toLowerCase() === entityDependency.EntityName?.trim().toLowerCase());
-            const quotes = entityInfo.FirstPrimaryKey.NeedsQuotes ? "'" : ''; // first-pk-ok: a foreign key targets a single column; quoting follows that FK target's type
             const relatedEntityInfo = this.Entities.find((e) => e.Name.trim().toLowerCase() === entityDependency.RelatedEntityName?.trim().toLowerCase());
-            const primaryKeySelectString = `CONCAT(${entityInfo.PrimaryKeys.map((pk) => `'${pk.Name}|', CAST([${pk.Name}] AS NVARCHAR(MAX))`).join(`,'${CompositeKey.DefaultFieldDelimiter}',`)})`;
+            if (!entityInfo || !relatedEntityInfo)
+                continue;
+            if (!this.shouldIncludeDependencyEntity(relatedEntityInfo, options, contextUser))
+                continue;
+            const fkField = relatedEntityInfo.Fields.find((f) => f.Name.trim().toLowerCase() === entityDependency.FieldName?.trim().toLowerCase());
+            if (fkField?.EntityIDFieldName && fkField.EntityIDFieldName.trim().length > 0)
+                continue;
+            const pksToProject = relatedEntityInfo.PrimaryKeys?.length ? relatedEntityInfo.PrimaryKeys : entityInfo.PrimaryKeys;
+            const primaryKeySelectString = `CONCAT(${pksToProject.map((pk) => `'${pk.Name}|', CAST([${pk.Name}] AS NVARCHAR(MAX))`).join(`,'${CompositeKey.DefaultFieldDelimiter}',`)})`;
+            const sourceObject = this.resolveDependencySourceObject(relatedEntityInfo, [entityDependency.FieldName]);
             if (sSQL.length > 0)
                 sSQL += ' UNION ALL ';
             sSQL += `SELECT
@@ -815,7 +887,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
                         0 AS IsSoftLink,
                         NULL AS EntityIDFieldName
                     FROM
-                        [${relatedEntityInfo.SchemaName}].[${relatedEntityInfo.BaseView}]
+                        [${relatedEntityInfo.SchemaName}].[${sourceObject}]
                     WHERE
                         [${entityDependency.FieldName}] = ${this.GetRecordDependencyLinkSQL(entityDependency, entityInfo, relatedEntityInfo, compositeKey)}`;
         }
@@ -826,7 +898,8 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         if (!f) {
             throw new Error(`Field ${dep.FieldName} not found in Entity ${relatedEntity.Name}`);
         }
-        if (f.RelatedEntityFieldName?.trim().toLowerCase() === 'id') {
+        const relFieldName = f.RelatedEntityFieldName?.trim().toLowerCase();
+        if (!relFieldName || relFieldName === 'id' || relFieldName === entity.FirstPrimaryKey?.Name?.trim().toLowerCase()) { // first-pk-ok: a foreign key targets a single column; default FK target is the first primary key
             // simple link to first primary key, most common scenario for linkages
             // Key values arrive from remote callers — render through the shared sanitizer.
             return SQLServerDataProvider.RenderKeyValueLiteral(CompositeKey.GetValueByIndex(0), entity.FirstPrimaryKey.NeedsQuotes, entity.FirstPrimaryKey.Name, entity.Name); // first-pk-ok: a foreign key targets a single column; quoting follows that FK target's type
@@ -881,19 +954,24 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
      * @param bNewRecord - Whether this is a new record (create) or existing record (update)
      * @param spName - The stored procedure name to call
      * @param user - The user context for the operation
+     * @param transaction - The transaction the save will run in, when one is already open. A read
+     *   the save's Record Change snapshot needs runs in it, so it sees that transaction's earlier
+     *   writes and never waits on the locks they hold.
      * @returns The full SQL statement for the save operation
      *
      * @security This method handles field-level encryption transparently.
      *           Fields marked with Encrypt=true will have their values encrypted
      *           before being included in the SQL statement.
      */
-    async GetSaveSQL(entity, bNewRecord, _spName, user) {
+    async GetSaveSQL(entity, bNewRecord, _spName, user, transaction) {
         // SQLServerTransactionGroup-batched saves regenerate per-item SQL when
         // transaction variables get rebound. `_spName` is preserved for back-compat
         // with that caller; the dialect-driven pipeline derives it from entity
-        // metadata via `GetCreateUpdateSPName`.
-        const result = await this.GenerateSaveSQL(entity, bNewRecord, user);
-        return result.fullSQL;
+        // metadata via `GetCreateUpdateSPName`. Outside a TransactionGroup,
+        // `fullSQL` holds `@p$0` parameter placeholders, so return `literalSQL`
+        // for standalone callers.
+        const result = await this.GenerateSaveSQLReadingOn(entity, bNewRecord, user, transaction);
+        return result.literalSQL ?? result.fullSQL;
     }
     /**
      * Queue the AI action task only once the save is durable: through {@link RunAfterCommit}, so it
@@ -906,6 +984,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
             await QueueManager.AddTask('Entity AI Action', params, null, user);
         }, 'Entity AI Action', postCommitToken);
     }
+    static { this._entityColumnsSQLCache = new WeakMap(); }
     getAllEntityColumnsSQL(entityInfo) {
         // This builds the column list for the @ResultTable/@ResultChangesTable that captures
         // `SELECT * FROM <BaseView>` via a POSITIONAL `INSERT INTO @table EXEC ...`. SQL Server maps the
@@ -930,10 +1009,17 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         // — the only case where a base-column-after-a-join could mis-route by position — we WARN loudly
         // (warnOnViewOrderFallback), because the metadata order can no longer be checked against the view and
         // a silent fallback there would let the very bug this fix prevents persist undetected.
-        let orderedFields;
-        let fallbackReason;
         const viewKey = `${entityInfo.SchemaName}.${entityInfo.BaseView}`.toLowerCase();
         const viewOrder = this._viewColumnOrderCache.get(viewKey);
+        const cached = SQLServerDataProvider._entityColumnsSQLCache.get(entityInfo);
+        if (cached &&
+            cached.viewOrderRef === viewOrder &&
+            cached.fieldCount === entityInfo.Fields.length &&
+            !cached.usedFallback) {
+            return cached.sql;
+        }
+        let orderedFields;
+        let fallbackReason;
         if (!viewOrder) {
             fallbackReason = `base view not captured in the column-order cache (cache load failed at Config, or a custom/overridden sproc whose view was not read)`;
         }
@@ -941,16 +1027,16 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
             fallbackReason = `base view exposes ${viewOrder.length} column(s) but the entity declares ${entityInfo.Fields.length} field(s) — cannot align 1:1 by position`;
         }
         else {
-            const fieldByName = new Map(entityInfo.Fields.map((f) => [f.Name.toLowerCase(), f]));
-            const mapped = viewOrder.map((colName) => fieldByName.get(colName.toLowerCase()));
-            if (mapped.every((f) => f !== undefined)) {
+            const mapped = viewOrder.map((colName) => entityInfo.FieldByName(colName));
+            if (mapped.every((f) => f !== null && f !== undefined)) {
                 orderedFields = mapped; // every view column resolved 1:1 to a field
             }
             else {
-                const unmatched = viewOrder.filter((colName) => !fieldByName.has(colName.toLowerCase()));
+                const unmatched = viewOrder.filter((colName) => !entityInfo.FieldByName(colName));
                 fallbackReason = `view column(s) without a matching EntityField: ${unmatched.join(', ')}`;
             }
         }
+        const usedFallback = !orderedFields;
         if (!orderedFields) {
             this.warnIfBaseFieldSequencedAfterVirtual(entityInfo);
             this.warnOnViewOrderFallback(entityInfo, fallbackReason);
@@ -963,8 +1049,35 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
             sRet += '[' + f.Name + '] ' + f.SQLFullType + ' ' + (f.AllowsNull || f.IsVirtual ? 'NULL' : 'NOT NULL');
             outputCount++;
         }
+        SQLServerDataProvider._entityColumnsSQLCache.set(entityInfo, {
+            viewOrderRef: viewOrder,
+            fieldCount: entityInfo.Fields.length,
+            usedFallback,
+            sql: sRet,
+        });
         return sRet;
     }
+    /**
+     * Builds the column declarations for `@ResultTable` when `entityInfo.SaveReturnMode === 'datestamps_only'`.
+     *
+     * Matches the exact column order emitted by CodeGen's `buildCRUDReturnSelect` via
+     * {@link EntityInfo.DatestampReturnFields} (primary key(s), followed by `__mj_CreatedAt` and `__mj_UpdatedAt`),
+     * ensuring positional `INSERT INTO @ResultTable EXEC spCreate/spUpdate` alignment.
+     */
+    getDatestampEntityColumnsSQL(entityInfo) {
+        return entityInfo.DatestampReturnFields
+            .map((f) => `${this.QuoteIdentifier(f.Name)} ${f.SQLFullType} ${f.AllowsNull || f.IsVirtual ? 'NULL' : 'NOT NULL'}`)
+            .join(',\n');
+    }
+    /**
+     * Selects the `@ResultTable` column declarations matching the compiled stored procedure's
+     * return shape (`returnContext.spReturnsDatestampsOnly`).
+     */
+    getSaveResultTableColumnsSQL(entityInfo, returnContext) {
+        return returnContext.spReturnsDatestampsOnly
+            ? this.getDatestampEntityColumnsSQL(entityInfo)
+            : this.getAllEntityColumnsSQL(entityInfo);
+    }
     /** Entities already warned about base-after-virtual field-order skew — so we warn once, not every save. */
     static { this._fieldOrderWarnedEntities = new Set(); }
     /**
@@ -1063,7 +1176,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         if (value && field.Type.trim().toLowerCase() === 'datetimeoffset') {
             return { kind: 'use', value: new Date(value).toISOString() };
         }
-        if (!isUpdate && field.Type.trim().toLowerCase() === 'uniqueidentifier' && !field.IsPrimaryKey) {
+        if (!isUpdate && field.IsUniqueIdentifier && !field.IsPrimaryKey) {
             if (typeof value === 'string' && value.includes('()')) {
                 return { kind: 'skip' };
             }
@@ -1083,14 +1196,53 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
      * `EntityFieldInfo.NeedsClearCompanion`.
      */
     RenderSaveCallBinding(entity, fieldValues, isUpdate, _spName) {
-        return this.renderSaveCallBindingWithSuffix(entity, fieldValues, isUpdate, this.allocateSaveCallSuffix(entity));
+        // The statement that runs uses one constant variable suffix and a parameter per value, so its
+        // text repeats across records. The per-record suffix is kept for the literal form.
+        const params = new SaveParameterCollector();
+        const binding = this.renderSaveCallBindingWithSuffix(entity, fieldValues, isUpdate, EXECUTED_VARIABLE_SUFFIX, params);
+        const saveBinding = { ...binding, parameters: params.Parameters, recordSuffix: this.allocateSaveCallSuffix(entity) };
+        return saveBinding;
+    }
+    /** The binding as RenderSaveCallBinding built it; throws for any other shape. */
+    asSaveBinding(binding, caller) {
+        if (binding.kind !== 'mssql-declare-exec' || !('recordSuffix' in binding)) {
+            throw new Error(`SQLServerDataProvider.${caller}: unexpected binding kind '${binding.kind}'`);
+        }
+        return binding;
+    }
+    /**
+     * The fragment for a statement built with typed parameters. A transaction-group item gets the
+     * literal form only, as before: the group combines and regenerates its items' SQL as text. A
+     * statement with no values to bind runs as built, which is already valid SQL.
+     *
+     * `literalSQL` is exposed as a lazy memoized getter so saves with SQL logging off avoid running
+     * the `RenderSaveSQL` regex substitution pass on every write.
+     */
+    toSaveFragment(entity, executedSQL, parameters, recordSuffix) {
+        if (entity.TransactionGroup) {
+            return { sql: RenderSaveSQL(executedSQL, parameters, recordSuffix) };
+        }
+        let cachedLiteralSQL;
+        const fragment = parameters.length > 0 ? { sql: executedSQL, parameters: [...parameters] } : { sql: executedSQL };
+        Object.defineProperty(fragment, 'literalSQL', {
+            enumerable: true,
+            configurable: true,
+            get() {
+                if (cachedLiteralSQL === undefined) {
+                    cachedLiteralSQL = RenderSaveSQL(executedSQL, parameters, recordSuffix);
+                }
+                return cachedLiteralSQL;
+            },
+        });
+        return fragment;
     }
     /**
-     * The binding for a given variable suffix. Split out of RenderSaveCallBinding so the update
-     * replay form can re-render a subset of the fields under the SAME suffix without allocating
-     * another one (inside a TransactionGroup that would consume a `_n` ordinal).
+     * The binding for a given variable suffix, with each value bound through `params`. Split out of
+     * RenderSaveCallBinding so the update replay form can re-render a subset of the fields under the
+     * SAME suffix without allocating another one (inside a TransactionGroup that would consume a `_n`
+     * ordinal).
      */
-    renderSaveCallBindingWithSuffix(entity, fieldValues, isUpdate, uniqueSuffix) {
+    renderSaveCallBindingWithSuffix(entity, fieldValues, isUpdate, uniqueSuffix, params) {
         const declarations = [];
         const setStatements = [];
         const execParams = [];
@@ -1104,7 +1256,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
             const hasValue = value !== null && value !== undefined;
             const binaryLiteral = hasValue && f.IsBinaryFieldType ? this.FormatBinaryLiteral(f, value) : undefined;
             if (hasValue) {
-                setStatements.push(`SET ${varName} = ${binaryLiteral ?? this.generateSetStatementValue(f, value)}`);
+                setStatements.push(`SET ${varName} = ${params.AddField(f, binaryLiteral ?? this.generateSetStatementValue(f, value))}`);
             }
             execParams.push(`@${f.CodeName}=${varName}`);
             simpleParams += this.generateSingleSPParam(f, value, bFirst, binaryLiteral);
@@ -1117,12 +1269,12 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         // UPDATE: tail-append PK declarations from the loaded entity's PrimaryKey.
         if (isUpdate && execParams.length > 0) {
             for (const pkv of entity.PrimaryKey.KeyValuePairs) {
-                const f = entity.EntityInfo.Fields.find((x) => x.Name.trim().toLowerCase() === pkv.FieldName.trim().toLowerCase());
+                const f = entity.EntityInfo.FieldByName(pkv.FieldName);
                 if (!f)
                     continue;
                 const varName = `@${f.CodeName}${uniqueSuffix}`;
                 declarations.push(`${varName} ${f.SQLFullType.toUpperCase()}`);
-                setStatements.push(`SET ${varName} = ${this.generateSetStatementValue(f, pkv.Value)}`);
+                setStatements.push(`SET ${varName} = ${params.AddField(f, this.generateSetStatementValue(f, pkv.Value))}`);
                 execParams.push(`@${f.CodeName}=${varName}`);
                 const pkeyQuotes = f.NeedsQuotes ? "'" : '';
                 simpleParams += `, @${f.CodeName} = ${pkeyQuotes}${pkv.Value}${pkeyQuotes}`;
@@ -1165,23 +1317,21 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
      * there is nothing to look up).
      */
     RenderReplaySaveSQL(binding, entity, fieldValues) {
-        if (binding.kind !== 'mssql-declare-exec') {
-            throw new Error(`SQLServerDataProvider.RenderReplaySaveSQL: unexpected binding kind '${binding.kind}'`);
-        }
+        const saveBinding = this.asSaveBinding(binding, 'RenderReplaySaveSQL');
         const info = entity.EntityInfo;
         const pks = info.PrimaryKeys;
         if (pks.length === 0 || !pks.every((pk) => fieldValues.has(pk))) {
             return undefined;
         }
         const schema = info.SchemaName;
-        const where = pks.map((pk) => `[${pk.Name}] = @${pk.CodeName}${binding.suffix}`).join(' AND ');
+        const where = pks.map((pk) => `[${pk.Name}] = @${pk.CodeName}${saveBinding.suffix}`).join(' AND ');
         const createSpName = this.GetCreateUpdateSPName(entity, true);
-        const createBranch = `IF NOT EXISTS (SELECT 1 FROM [${schema}].[${info.BaseTable}] WHERE ${where})\nBEGIN\n    EXEC [${schema}].${createSpName} ${binding.callArgsSQL}\nEND`;
+        const createBranch = `IF NOT EXISTS (SELECT 1 FROM [${schema}].[${info.BaseTable}] WHERE ${where})\nBEGIN\n    EXEC [${schema}].${createSpName} ${saveBinding.callArgsSQL}\nEND`;
         const hasUpdateProc = info.AllowUpdateAPI && info.spUpdateGenerated && !info.VirtualEntity;
         const updateBranch = hasUpdateProc
-            ? `\nELSE\nBEGIN\n    EXEC [${schema}].${this.GetCreateUpdateSPName(entity, false)} ${binding.callArgsSQL}\nEND`
+            ? `\nELSE\nBEGIN\n    EXEC [${schema}].${this.GetCreateUpdateSPName(entity, false)} ${saveBinding.callArgsSQL}\nEND`
             : '';
-        return `${this.renderDeclareSetHead(binding)}${createBranch}${updateBranch}`;
+        return RenderSaveSQL(`${this.renderDeclareSetHead(saveBinding)}${createBranch}${updateBranch}`, saveBinding.parameters, saveBinding.recordSuffix);
     }
     /**
      * Replay form of an UPDATE for the SQL log (never executed): `EXEC spUpdate` with only the
@@ -1194,9 +1344,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
      * (spUpdateGenerated off) makes no ISNULL promise, so it keeps the full-row form.
      */
     RenderReplayUpdateSQL(binding, entity, changedFieldValues) {
-        if (binding.kind !== 'mssql-declare-exec') {
-            throw new Error(`SQLServerDataProvider.RenderReplayUpdateSQL: unexpected binding kind '${binding.kind}'`);
-        }
+        const saveBinding = this.asSaveBinding(binding, 'RenderReplayUpdateSQL');
         const info = entity.EntityInfo;
         if (!info.spUpdateGenerated) {
             return undefined;
@@ -1205,9 +1353,10 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
             const key = entity.PrimaryKey.ToString().replace(/[\r\n]+/g, ' ');
             return `-- ${info.Name} (${key}): saved with no field changes; nothing to replay`;
         }
-        const changed = this.renderSaveCallBindingWithSuffix(entity, changedFieldValues, true, binding.suffix);
+        const params = new SaveParameterCollector();
+        const changed = this.renderSaveCallBindingWithSuffix(entity, changedFieldValues, true, saveBinding.suffix, params);
         const spName = this.GetCreateUpdateSPName(entity, false);
-        return `${this.renderDeclareSetHead(changed)}EXEC [${info.SchemaName}].${spName} ${changed.callArgsSQL}`;
+        return RenderSaveSQL(`${this.renderDeclareSetHead(changed)}EXEC [${info.SchemaName}].${spName} ${changed.callArgsSQL}`, params.Parameters, saveBinding.recordSuffix);
     }
     /** `DECLARE ...\n\nSET ...\n\n` when the binding declares variables, else empty. */
     renderDeclareSetHead(binding) {
@@ -1218,58 +1367,66 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
      * shape: `DECLARE ... ; SET ... ; EXEC [schema].sp callArgs`. When
      * record-change tracking is on, this output is further wrapped by
      * `WrapSaveCallWithRecordChange`.
+     *
+     * When `returnContext.needsDatestampProjection` is true (either passed by
+     * `GenericDatabaseProvider.GenerateSaveSQL` or resolved from `options`),
+     * delegates to {@link ProjectSaveCallToDatestamps}.
      */
-    WrapSaveCallForResult(binding, entity, spName) {
-        if (binding.kind !== 'mssql-declare-exec') {
-            throw new Error(`SQLServerDataProvider.WrapSaveCallForResult: unexpected binding kind '${binding.kind}'`);
+    WrapSaveCallForResult(binding, entity, spName, options, returnContext) {
+        const resolvedReturn = returnContext ?? this.ResolveSaveReturnContext(entity, options);
+        if (resolvedReturn.needsDatestampProjection) {
+            return this.ProjectSaveCallToDatestamps(binding, entity, spName, resolvedReturn);
         }
-        const execSQL = `EXEC [${entity.EntityInfo.SchemaName}].${spName} ${binding.callArgsSQL}`;
-        return { sql: `${this.renderDeclareSetHead(binding)}${execSQL}` };
+        const saveBinding = this.asSaveBinding(binding, 'WrapSaveCallForResult');
+        const execSQL = `EXEC [${entity.EntityInfo.SchemaName}].${spName} ${saveBinding.callArgsSQL}`;
+        return this.toSaveFragment(entity, `${this.renderDeclareSetHead(saveBinding)}${execSQL}`, saveBinding.parameters, saveBinding.recordSuffix);
+    }
+    /**
+     * Captures the stored procedure's output into `@ResultTable` and projects only
+     * `returnContext.datestampSelectColumnsSQL` (`SELECT [ID], [__mj_CreatedAt], [__mj_UpdatedAt] FROM @ResultTable;`)
+     * when a caller requests `SaveReturnMode: 'datestamps_only'` at runtime on an entity whose
+     * compiled stored procedure returns the full row.
+     */
+    ProjectSaveCallToDatestamps(binding, entity, spName, returnContext) {
+        const saveBinding = this.asSaveBinding(binding, 'ProjectSaveCallToDatestamps');
+        const execSQL = `EXEC [${entity.EntityInfo.SchemaName}].${spName} ${saveBinding.callArgsSQL}`;
+        const resultTableColumnsSQL = this.getSaveResultTableColumnsSQL(entity.EntityInfo, returnContext);
+        const sql = `${this.renderDeclareSetHead(saveBinding)}DECLARE @ResultTable TABLE (\n    ${resultTableColumnsSQL}\n);\n\nINSERT INTO @ResultTable\n${execSQL};\n\nSELECT ${returnContext.datestampSelectColumnsSQL} FROM @ResultTable;`;
+        return this.toSaveFragment(entity, sql, saveBinding.parameters, saveBinding.recordSuffix);
     }
     /**
      * Wraps the save SQL with SQL Server's @ResultTable + inline
      * `spCreateRecordChange_Internal` EXEC pattern. The CONCAT-built `@ID`
      * inline supports composite-key entities.
+     *
+     * Consumes {@link SaveReturnContext} resolved by `GenericDatabaseProvider`:
+     * - `@ResultTable` column declarations match the compiled stored procedure's return mode
+     *   (`returnContext.spReturnsDatestampsOnly`).
+     * - The final `SELECT` from `@ResultTable` uses `returnContext.finalSelectColumnsSQL`.
      */
-    WrapSaveCallWithRecordChange(_saveSQL, binding, payload, entity) {
-        if (binding.kind !== 'mssql-declare-exec') {
-            throw new Error(`SQLServerDataProvider.WrapSaveCallWithRecordChange: unexpected binding kind '${binding.kind}'`);
-        }
-        const recordChangesEntityInfo = this.Entities.find((e) => e.Name === 'MJ: Record Changes');
+    WrapSaveCallWithRecordChange(_saveSQL, binding, payload, entity, options, returnContext) {
+        const saveBinding = this.asSaveBinding(binding, 'WrapSaveCallWithRecordChange');
+        const params = new SaveParameterCollector(saveBinding.parameters);
+        const recordChangesEntityInfo = this.EntityByName('MJ: Record Changes');
         const spName = this.GetCreateUpdateSPName(entity, payload.type === 'Create');
         const concatPKIDString = `CONCAT(${entity.EntityInfo.PrimaryKeys
             .map((pk) => `'${pk.CodeName}','${CompositeKey.DefaultValueDelimiter}',[${pk.Name}]`)
             .join(`,'${CompositeKey.DefaultFieldDelimiter}',`)})`;
         // Build the inline `EXEC spCreateRecordChange_Internal` from the payload,
         // referencing `@ID` (set below from the result table).
-        const lineageClause = payload.source === 'Restore'
-            ? `,
-                                                                                        @Source='Restore',
-                                                                                        @RestoredFromID='${payload.restoredFromID}',
-                                                                                        @RestoreReason=${payload.restoreReason ? `N'${payload.restoreReason.replace(/'/g, "''")}'` : 'NULL'}`
-            : payload.source === 'Clone'
-                ? `,
-                                                                                        @Source='Clone',
-                                                                                        @ChangeContext=N'${EscapeSQLString(payload.changeContext)}'`
-                : '';
-        const recordChangeEXEC = `EXEC [${this.MJCoreSchemaName}].spCreateRecordChange_Internal @EntityName='${entity.EntityInfo.Name}',
-                                                                                        @RecordID=@ID,
-                                                                                        @UserID='${payload.userID}',
-                                                                                        @Type='${payload.type}',
-                                                                                        @ChangesJSON='${payload.changesJSON}',
-                                                                                        @ChangesDescription='${payload.changesDescription}',
-                                                                                        @FullRecordJSON='${payload.fullRecordJSON}',
-                                                                                        @Status='Complete',
-                                                                                        @Comments=null${lineageClause}`;
-        const execSQL = `EXEC [${entity.EntityInfo.SchemaName}].${spName} ${binding.callArgsSQL}`;
+        const recordChangeEXEC = this.renderRecordChangeEXEC(entity.EntityInfo.Name, '@ID', payload, params);
+        const execSQL = `EXEC [${entity.EntityInfo.SchemaName}].${spName} ${saveBinding.callArgsSQL}`;
+        const resolvedReturn = returnContext ?? this.ResolveSaveReturnContext(entity, options);
+        const resultTableColumnsSQL = this.getSaveResultTableColumnsSQL(entity.EntityInfo, resolvedReturn);
+        const finalSelectSQL = `SELECT ${resolvedReturn.finalSelectColumnsSQL} FROM @ResultTable;`;
         const sql = `
-                    ${binding.preambleSQL}
+                    ${saveBinding.preambleSQL}
 
                     DECLARE @ResultTable TABLE (
-                        ${this.getAllEntityColumnsSQL(entity.EntityInfo)}
+                        ${resultTableColumnsSQL}
                     );
 
-                    ${binding.setSQL}
+                    ${saveBinding.setSQL}
 
                     INSERT INTO @ResultTable
                     ${execSQL};
@@ -1288,8 +1445,44 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
                         ${recordChangeEXEC};
                     END;
 
-                    SELECT * FROM @ResultTable;`;
-        return { sql };
+                    ${finalSelectSQL}`;
+        return this.toSaveFragment(entity, sql, params.Parameters, saveBinding.recordSuffix);
+    }
+    /**
+     * `EXEC spCreateRecordChange_Internal …` for a payload. With `params`, each per-change value is
+     * bound as a parameter typed from its Record Changes column, and the literal it replaces is kept
+     * for the rendered form; without, the literals are written in directly. The entity name and change
+     * type stay literal: they are constant for an entity and operation.
+     */
+    renderRecordChangeEXEC(entityName, recordIDSQL, payload, params) {
+        const bind = (fieldName, literal) => (params ? params.AddField(this.recordChangeField(fieldName), literal) : literal);
+        const lineageClause = payload.source === 'Restore'
+            ? `,
+                                                                                        @Source='Restore',
+                                                                                        @RestoredFromID=${bind('RestoredFromID', `'${payload.restoredFromID}'`)},
+                                                                                        @RestoreReason=${payload.restoreReason ? bind('RestoreReason', `N'${payload.restoreReason.replace(/'/g, "''")}'`) : 'NULL'}`
+            : payload.source === 'Clone'
+                ? `,
+                                                                                        @Source='Clone',
+                                                                                        @ChangeContext=${bind('ChangeContext', `N'${EscapeSQLString(payload.changeContext)}'`)}`
+                : '';
+        return `EXEC [${this.MJCoreSchemaName}].spCreateRecordChange_Internal @EntityName=N'${entityName}',
+                                                                                        @RecordID=${recordIDSQL},
+                                                                                        @UserID=${bind('UserID', `'${payload.userID}'`)},
+                                                                                        @Type='${payload.type}',
+                                                                                        @ChangesJSON=${bind('ChangesJSON', `N'${payload.changesJSON}'`)},
+                                                                                        @ChangesDescription=${bind('ChangesDescription', `N'${payload.changesDescription}'`)},
+                                                                                        @FullRecordJSON=${bind('FullRecordJSON', `N'${payload.fullRecordJSON}'`)},
+                                                                                        @Status='Complete',
+                                                                                        @Comments=null${lineageClause}`;
+    }
+    /** A field of `MJ: Record Changes`, whose column types type the Record Change parameters. */
+    recordChangeField(fieldName) {
+        const field = this.EntityByName('MJ: Record Changes')?.FieldByName(fieldName);
+        if (!field) {
+            throw new Error(`SQLServerDataProvider: field "${fieldName}" of "MJ: Record Changes" is not in the metadata`);
+        }
+        return field;
     }
     /**
      * Generates the value portion of a SET statement for a field
@@ -1460,32 +1653,22 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         return unicodePrefix + quoteString + pVal + quoteString;
     }
     GetLogRecordChangeSQL(newData, oldData, entityName, recordID, entityInfo, type, user, wrapRecordIdInQuotes, restoreContext, cloneContext) {
+        return this.renderLogRecordChangeSQL(newData, oldData, entityName, recordID, entityInfo, type, user, wrapRecordIdInQuotes, restoreContext, cloneContext);
+    }
+    /**
+     * Renders the `spCreateRecordChange_Internal` call for `GetLogRecordChangeSQL` (literal form) and
+     * for the delete batch (`params` supplied, so the payload values bind as typed inputs).
+     */
+    renderLogRecordChangeSQL(newData, oldData, entityName, recordID, entityInfo, type, user, wrapRecordIdInQuotes, restoreContext, cloneContext, params) {
         // Dialect-agnostic payload assembly is hoisted into DatabaseProviderBase
         // so SQL Server and PostgreSQL share one implementation. We only render
         // the T-SQL EXEC wrapper here.
         const payload = this.BuildRecordChangePayload(newData, oldData, String(recordID), entityInfo, type, user, restoreContext, "'", cloneContext);
         if (!payload)
             return null;
-        const quotes = wrapRecordIdInQuotes ? "'" : '';
-        const lineageClause = payload.source === 'Restore'
-            ? `,
-                                                                                        @Source='Restore',
-                                                                                        @RestoredFromID='${payload.restoredFromID}',
-                                                                                        @RestoreReason=${payload.restoreReason ? `N'${payload.restoreReason.replace(/'/g, "''")}'` : 'NULL'}`
-            : payload.source === 'Clone'
-                ? `,
-                                                                                        @Source='Clone',
-                                                                                        @ChangeContext=N'${EscapeSQLString(payload.changeContext)}'`
-                : '';
-        return `EXEC [${this.MJCoreSchemaName}].spCreateRecordChange_Internal @EntityName='${entityName}',
-                                                                                        @RecordID=${quotes}${recordID}${quotes},
-                                                                                        @UserID='${payload.userID}',
-                                                                                        @Type='${payload.type}',
-                                                                                        @ChangesJSON='${payload.changesJSON}',
-                                                                                        @ChangesDescription='${payload.changesDescription}',
-                                                                                        @FullRecordJSON='${payload.fullRecordJSON}',
-                                                                                        @Status='Complete',
-                                                                                        @Comments=null${lineageClause}`;
+        const recordIDSQL = wrapRecordIdInQuotes ? `N'${EscapeSQLString(String(recordID))}'` : String(recordID);
+        const boundRecordID = params && wrapRecordIdInQuotes ? params.AddField(this.recordChangeField('RecordID'), recordIDSQL) : recordIDSQL;
+        return this.renderRecordChangeEXEC(entityName, boundRecordID, payload, params);
     }
     /**
      * Implements the abstract BuildRecordChangeSQL from DatabaseProviderBase.
@@ -1510,22 +1693,33 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         return result.fullSQL;
     }
     /**
-     * This function generates both the full SQL (with record change metadata) and the simple stored procedure call for delete
-     * @returns Object with fullSQL and simpleSQL properties
+     * Generates the delete statement with both full SQL (including record changes) and simple SQL.
+     * With `params`, primary-key and Record Change values are bound as `@p0, @p1, …` and their
+     * literals are kept on the parameters for `RenderSaveSQL`.
+     * For a TrackRecordChanges entity with CascadeDeletes, the full SQL runs the proc uncaptured and selects the key twice:
+     * first whether the row existed (read by transaction groups), last whether it was deleted (read by direct execution).
      */
-    getDeleteSQLWithDetails(entity, user, skipRecordChanges = false) {
-        let sSQL = '';
+    getDeleteSQLWithDetails(entity, user, skipRecordChanges = false, params) {
         const spName = entity.EntityInfo.spDelete ? entity.EntityInfo.spDelete : `spDelete${entity.EntityInfo.BaseTableCodeName}`;
-        const sParams = entity.PrimaryKey.KeyValuePairs.map((kv) => {
-            const f = entity.EntityInfo.Fields.find((f) => f.Name.trim().toLowerCase() === kv.FieldName.trim().toLowerCase());
-            const quotes = f.NeedsQuotes ? "'" : '';
-            return `@${f.CodeName}=${quotes}${kv.Value}${quotes}`;
-        }).join(', ');
+        const pkRefs = entity.PrimaryKey.KeyValuePairs.map((kv) => {
+            const f = entity.EntityInfo.FieldByName(kv.FieldName);
+            if (!f) {
+                throw new Error(`SQLServerDataProvider.getDeleteSQLWithDetails: primary key field "${kv.FieldName}" not found on "${entity.EntityInfo.Name}"`);
+            }
+            // Quoted keys are escaped by generateSetStatementValue; an unquoted (numeric) key must be a plain number.
+            const literal = f.NeedsQuotes
+                ? this.generateSetStatementValue(f, kv.Value)
+                : SQLServerDataProvider.RenderKeyValueLiteral(kv.Value, false, f.Name, entity.EntityInfo.Name);
+            // One reference per key, reused by every statement below that names the key.
+            return { Field: f, Ref: params ? params.AddField(f, literal) : literal };
+        });
+        const sParams = pkRefs.map((pk) => `@${pk.Field.CodeName}=${pk.Ref}`).join(', ');
         const sSimpleSQL = `EXEC [${entity.EntityInfo.SchemaName}].[${spName}] ${sParams}`;
-        const recordChangesEntityInfo = this.Entities.find((e) => e.Name === 'MJ: Record Changes');
+        const recordChangesEntityInfo = this.EntityByName('MJ: Record Changes');
+        let sSQL;
         if (entity.EntityInfo.TrackRecordChanges && !skipRecordChanges && entity.EntityInfo.Name.trim().toLowerCase() !== 'record changes') {
             // don't track changes for the record changes entity
-            const oldData = entity.GetAll(true); // get all the OLD values
+            const oldData = this.RecordChangeDeleteSnapshot(entity, entity.GetAll(true)); // the OLD values, full width
             const sTableDeclare = entity.PrimaryKeys.map((pk) => {
                 return `${pk.CodeName} ${pk.EntityFieldInfo.SQLFullType}`;
             }).join(', ');
@@ -1542,6 +1736,40 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
             const sReturnList = entity.PrimaryKeys.map((pk) => {
                 return `@${pk.CodeName} AS [${pk.Name}]`;
             }).join(', ');
+            const recordChangeSQL = this.renderLogRecordChangeSQL(null /*pass in null for new data for deleted records*/, oldData, entity.EntityInfo.Name, sCombinedPrimaryKey, entity.EntityInfo, 'Delete', user, true, entity.RestoreContext, entity.CloneContext, params);
+            if (entity.EntityInfo.CascadeDeletes) {
+                // A cascading spDelete EXECs other procs (spUpdate* to null references, spDelete* for
+                // children) and each emits its own result set, spUpdate*'s being the full row. Capturing the
+                // call with INSERT INTO @ResultTable EXEC takes every one of them, so the first full row fails
+                // with error 213. Run the proc uncaptured instead and judge success by whether the row is
+                // gone. The key is selected first (transaction groups read the first result set) and last
+                // (direct execution reads the last, see ValidateDeleteResult); NULL when nothing was deleted.
+                // The checks read the base view, not the table: runtime logins hold SELECT on base views
+                // only, and for a soft-delete entity the view hides the row spDelete just soft-deleted.
+                const sView = `[${entity.EntityInfo.SchemaName}].[${entity.EntityInfo.BaseView}]`;
+                const sWhere = pkRefs.map((pk) => `[${pk.Field.Name}]=${pk.Ref}`).join(' AND ');
+                const sKeyWhen = (flag) => pkRefs.map((pk) => `CASE WHEN ${flag} = 1 THEN ${pk.Ref} END AS [${pk.Field.Name}]`).join(', ');
+                sSQL = `
+                    DECLARE @MJDeleteRowExisted BIT = CASE WHEN EXISTS (SELECT 1 FROM ${sView} WHERE ${sWhere}) THEN 1 ELSE 0 END
+                    SELECT ${sKeyWhen('@MJDeleteRowExisted')}
+
+                    IF @MJDeleteRowExisted = 1
+                        ${sSimpleSQL}
+
+                    DECLARE @MJDeleteRowDeleted BIT = CASE WHEN @MJDeleteRowExisted = 1 AND NOT EXISTS (SELECT 1 FROM ${sView} WHERE ${sWhere}) THEN 1 ELSE 0 END
+                    IF @MJDeleteRowDeleted = 1
+                    BEGIN
+                        DECLARE @ResultChangesTable TABLE (
+                            ${this.getAllEntityColumnsSQL(recordChangesEntityInfo)}
+                        )
+
+                        INSERT INTO @ResultChangesTable
+                        ${recordChangeSQL}
+                    END
+
+                    SELECT ${sKeyWhen('@MJDeleteRowDeleted')}`;
+                return { fullSQL: sSQL, simpleSQL: sSimpleSQL };
+            }
             sSQL = `
                     IF OBJECT_ID('tempdb..#ResultTable') IS NOT NULL
                         DROP TABLE #ResultTable
@@ -1562,7 +1790,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
                         )
 
                         INSERT INTO @ResultChangesTable
-                        ${this.GetLogRecordChangeSQL(null /*pass in null for new data for deleted records*/, oldData, entity.EntityInfo.Name, sCombinedPrimaryKey, entity.EntityInfo, 'Delete', user, true, entity.RestoreContext, entity.CloneContext)}
+                        ${recordChangeSQL}
                     END
 
                     SELECT ${sReturnList}`;
@@ -1585,10 +1813,22 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
     // WrapSaveCallWithRecordChange (see this file's "Save Grammar" section
     // above). See plans/sp-save-builder-generic-layer-refactor.md (rev 4).
     GenerateDeleteSQL(entity, user, options) {
-        const sqlDetails = this.getDeleteSQLWithDetails(entity, user, options?.SkipRecordChanges === true);
+        const params = new SaveParameterCollector();
+        const sqlDetails = this.getDeleteSQLWithDetails(entity, user, options?.SkipRecordChanges === true, params);
+        const fragment = this.toSaveFragment(entity, sqlDetails.fullSQL, params.Parameters, '');
+        let cachedSimpleSQL;
         return {
-            fullSQL: sqlDetails.fullSQL,
-            simpleSQL: sqlDetails.simpleSQL,
+            fullSQL: fragment.sql,
+            get simpleSQL() {
+                if (cachedSimpleSQL === undefined) {
+                    cachedSimpleSQL = RenderSaveSQL(sqlDetails.simpleSQL, params.Parameters, '');
+                }
+                return cachedSimpleSQL;
+            },
+            parameters: fragment.parameters ?? null,
+            get literalSQL() {
+                return fragment.literalSQL;
+            },
         };
     }
     OnSuspendRefresh() {
@@ -1713,8 +1953,10 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         }
         // For transactional queries, use the instance queue to ensure serialization
         // This prevents EREQINPROG errors when multiple queries try to use the same transaction
+        this.initializeQueueProcessor();
+        const queue = this.ensureSqlQueue();
         return new Promise((resolve, reject) => {
-            this._sqlQueue$.next({
+            queue.next({
                 kind: 'query',
                 query,
                 parameters,
@@ -1774,21 +2016,35 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
             this.AssertAmbientTransactionUsable();
             transaction = this._transaction;
         }
+        const shouldLogSql = !loggingOptions?.ignoreLogging && (this.HasActiveSqlLoggingSessions ||
+            Object.prototype.hasOwnProperty.call(this, '_logSqlStatement') ||
+            Object.getPrototypeOf(this) !== SQLServerDataProvider.prototype);
+        if (shouldLogSql && !this._boundLogSqlStatement) {
+            this._boundLogSqlStatement = this._logSqlStatement.bind(this);
+        }
+        if (!this._boundClearTransaction) {
+            this._boundClearTransaction = () => {
+                this._transaction = null;
+            };
+        }
         // Create the execution context
         const context = {
             pool: this._pool,
             transaction: transaction,
-            logSqlStatement: this._logSqlStatement.bind(this),
-            clearTransaction: () => {
-                this._transaction = null;
-            }
+            logSqlStatement: shouldLogSql ? this._boundLogSqlStatement : undefined,
+            clearTransaction: this._boundClearTransaction
         };
         // Convert logging options to internal format
         const options = loggingOptions ? {
             description: loggingOptions.description,
             ignoreLogging: loggingOptions.ignoreLogging,
             isMutation: loggingOptions.isMutation,
-            simpleSQLFallback: loggingOptions.simpleSQLFallback,
+            get simpleSQLFallback() {
+                return loggingOptions.simpleSQLFallback;
+            },
+            get literalSQL() {
+                return loggingOptions.literalSQL;
+            },
             contextUser: loggingOptions.contextUser,
             // A statement inside a transaction follows the transaction's limits (see ExecuteSQLOptions).
             timeoutMs: transaction ? undefined : loggingOptions.timeoutMs
@@ -1811,7 +2067,12 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
                 description: options?.description,
                 ignoreLogging: options?.ignoreLogging,
                 isMutation: options?.isMutation,
-                simpleSQLFallback: options?.simpleSQLFallback,
+                get simpleSQLFallback() {
+                    return options?.simpleSQLFallback;
+                },
+                get literalSQL() {
+                    return options?.literalSQL;
+                },
                 contextUser: contextUser,
                 ignoreAmbientTransaction: options?.ignoreAmbientTransaction,
                 timeoutMs: options?.timeoutMs,
@@ -2118,8 +2379,19 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         if (this._datetimeOffsetTestComplete) {
             return this._needsDatetimeOffsetAdjustment;
         }
-        // Run the test
-        await this.testDatetimeOffsetHandling();
+        // A recent probe failed: keep its safe default until the backoff passes, rather than re-probing
+        // (and logging the failure again) on every call while the database is unreachable.
+        const failedAt = SQLServerDataProvider._datetimeOffsetTestFailedAt;
+        if (failedAt !== null && Date.now() - failedAt < SQLServerDataProvider.DATETIMEOFFSET_PROBE_RETRY_MS) {
+            return this._needsDatetimeOffsetAdjustment;
+        }
+        // Deduplicate concurrent tests across per-request provider instances
+        if (!SQLServerDataProvider._datetimeOffsetTestPromise) {
+            SQLServerDataProvider._datetimeOffsetTestPromise = this.testDatetimeOffsetHandling().finally(() => {
+                SQLServerDataProvider._datetimeOffsetTestPromise = null;
+            });
+        }
+        await SQLServerDataProvider._datetimeOffsetTestPromise;
         return this._needsDatetimeOffsetAdjustment;
     }
     /**
@@ -2164,13 +2436,15 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
             }
             // Mark the test as complete
             this._datetimeOffsetTestComplete = true;
+            SQLServerDataProvider._datetimeOffsetTestFailedAt = null;
         }
         catch (e) {
             // If the test fails, log the error but don't prevent initialization
             console.error('SQLServerDataProvider: Failed to test datetimeoffset handling:', e);
-            // Default to assuming adjustment is needed for safety
+            // Default to assuming adjustment is needed for safety on this provider,
+            // but leave _datetimeOffsetTestComplete false so a call after the backoff retries.
             this._needsDatetimeOffsetAdjustment = true;
-            this._datetimeOffsetTestComplete = true;
+            SQLServerDataProvider._datetimeOffsetTestFailedAt = Date.now();
         }
     }
     /**
@@ -2247,12 +2521,12 @@ DECLARE ${varName} NVARCHAR(MAX) = (
 );
 IF ${varName} IS NOT NULL
     EXEC [${this.MJCoreSchemaName}].spCreateRecordChange_Internal
-        @EntityName='${safeEntityName}',
-        @RecordID='${recordID}',
+        @EntityName=N'${safeEntityName}',
+        @RecordID=N'${recordID}',
         @UserID='${safeUserId}',
         @Type='Update',
-        @ChangesJSON='${safeChangesJSON}',
-        @ChangesDescription='${safeChangesDesc}',
+        @ChangesJSON=N'${safeChangesJSON}',
+        @ChangesDescription=N'${safeChangesDesc}',
         @FullRecordJSON=${varName},
         @Status='Complete',
         @Comments=NULL${lineageClause};`;
@@ -2270,7 +2544,7 @@ IF ${varName} IS NOT NULL
         const transaction = new sql.Transaction(this._pool);
         await transaction.begin();
         this._transaction = transaction;
-        this._transactionState$.next(true);
+        this.setTransactionActiveState(true);
     }
     /**
      * Internal mssql transaction interface to safely inspect `_activeRequest` without `any`.
@@ -2305,8 +2579,10 @@ IF ${varName} IS NOT NULL
      * that queued ambient queries behind it are rejected rather than run on the doomed handle.
      */
     enqueueTransactionAction(description, handle, run) {
+        this.initializeQueueProcessor();
+        const queue = this.ensureSqlQueue();
         return new Promise((resolve, reject) => {
-            this._sqlQueue$.next({ kind: 'action', description, handle, run, resolve, reject });
+            queue.next({ kind: 'action', description, handle, run, resolve, reject });
         });
     }
     async CommitPhysicalTransaction() {
@@ -2331,13 +2607,13 @@ IF ${varName} IS NOT NULL
             // AbandonPhysicalTransaction can roll the doomed handle back — nulling it first, as the old
             // `finally` did, made that abandon a no-op and leaked the server-side transaction (#4447).
             this._transaction = null;
-            this._transactionState$.next(false);
+            this.setTransactionActiveState(false);
         });
     }
     async AbandonPhysicalTransaction() {
         const stale = this._transaction;
         this._transaction = null;
-        this._transactionState$.next(false);
+        this.setTransactionActiveState(false);
         if (stale) {
             try {
                 // Through the queue, like commit and rollback: the handle is already nulled above, so any
@@ -2371,7 +2647,7 @@ IF ${varName} IS NOT NULL
         }
         finally {
             this._transaction = null;
-            this._transactionState$.next(false);
+            this.setTransactionActiveState(false);
         }
     }
     async OnBeginFailedAtDepthZero() {