@memberjunction/sqlserver-dataprovider 6.2.0-edge.5 → 6.2.0-edge.7

package/dist/SQLServerDataProvider.js

@@ -18,7 +18,9 @@
 import { EntityFieldTSType, ProviderType, LogError, LogStatus, LogStatusEx, CompositeKey, } from '@memberjunction/core';
 import { NodeFileSystemProvider } from './NodeFileSystemProvider.js';
 import { QueueManager } from '@memberjunction/queue';
-import { GenericDatabaseProvider } from '@memberjunction/generic-database-provider';
+import { GenericDatabaseProvider, IsTypedQueryParameterList, IsNamedQueryParameterList, TypedQueryParameter, DescribeStatementFailure } from '@memberjunction/generic-database-provider';
+import { BindTypedParameters } from './typedParameters.js';
+import { MapSQLServerDescribeRows, SQLSERVER_DESCRIBE_SQL } from './statementDescription.js';
 import sql from 'mssql';
 import { BehaviorSubject, Subject, concatMap, from, catchError, of } from 'rxjs';
 import { SQLServerTransactionGroup } from './SQLServerTransactionGroup.js';
@@ -60,7 +62,11 @@ function isStaleConnectionError(error) {
         code === 'ECONNRESET');
 }
 /**
- * Builds a sql.Request, binds parameters, and processes positional placeholders.
+ * Builds a sql.Request and binds `parameters`:
+ * - a SaveParameter list, a TypedQueryParameter list or a NamedQueryParameter list binds each by name;
+ * - a plain object binds each key by name (`{ name: v }` for `@name`);
+ * - a plain array is the LEGACY positional form: `@p0..@pN`, with every `?` in the statement rewritten,
+ *   including one inside a string literal, quoted identifier or comment. Prefer a named form.
  */
 function buildRequest(connectionSource, query, parameters) {
     // Note: The branch looks redundant but is required for TypeScript type narrowing.
@@ -80,10 +86,25 @@ function buildRequest(connectionSource, query, parameters) {
         }
         return { request, processedQuery: query };
     }
+    if (IsTypedQueryParameterList(parameters)) {
+        // Named inputs declared with the types of the columns they are compared with (typedParameters.ts).
+        BindTypedParameters(request, parameters);
+        return { request, processedQuery: query };
+    }
+    if (IsNamedQueryParameterList(parameters)) {
+        // Named inputs whose type the driver infers; the statement already references them by name.
+        for (const p of parameters) {
+            request.input(p.Name, p.Value);
+        }
+        return { request, processedQuery: query };
+    }
     let processedQuery = query;
     if (parameters) {
         if (Array.isArray(parameters)) {
-            // Handle positional parameters (legacy TypeORM style)
+            // LEGACY positional form: values bind as @p0..@pN and EVERY `?` in the text is rewritten to the
+            // next @pN, a `?` inside a string literal, quoted identifier or comment included. Kept for
+            // existing callers; MJ's own SQL passes named parameters (an object, NamedQueryParameter or
+            // TypedQueryParameter lists), which leave the text alone.
             parameters.forEach((value, index) => {
                 request.input(`p${index}`, value);
             });
@@ -244,7 +265,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
@@ -252,8 +273,10 @@ 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
@@ -312,19 +335,66 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
      * `sys.columns` scan in {@link loadViewColumnOrderCache} ran once or twice on EVERY request
      * (issue #3102 — ~9.6k scans/day in production vs the ~2 needed).
      *
-     * Keyed by the `ConnectionPool` object (NOT by `schema.view` alone) because one process can hold
-     * providers to different databases (RW + RO datasources, multi-DB tooling) where the same
-     * `schema.view` has different physical column orders — a process-global map would serve one
-     * database's column order to another's provider and silently reintroduce the positional
-     * `@ResultTable` mis-routing this cache exists to prevent. A WeakMap lets pools (and their cache)
-     * be collected if a pool is discarded.
+     * Keyed by normalized database target AND login (`user@server:port[/instance]/database`) when
+     * `ConnectionPool.config` exposes them — so pools opened with the same login against the SAME
+     * database (per-request RW providers around the boot-time pool) share one `sys.columns` scan and
+     * one cross-pool invalidation domain, while pools pointing to DIFFERENT databases, or using a
+     * different login (read-only, CodeGen), stay isolated: `sys.columns` only lists objects the login
+     * can see, so one login's scan must never stand in for another's. Pools without `config.user`
+     * (token/integrated auth) share by target alone. Falls back to `_viewColumnOrderCacheByPool`
+     * (`WeakMap`) when a pool object does not expose `config.server` + `config.database` (e.g.
+     * lightweight test doubles).
      *
      * The value is the load PROMISE (not the resolved Map) so concurrent per-request Config() calls
      * de-duplicate onto a single in-flight scan. Invalidated on metadata refresh (see
      * {@link Refresh} / {@link InvalidateViewColumnOrderCache}) so view changes from
-     * migrations/CodeGen are picked up without a server restart.
+     * migrations/CodeGen are picked up across all pools targeting that database without a server restart.
      */
     static { this._viewColumnOrderCacheByPool = new WeakMap(); }
+    static { this._viewColumnOrderCacheByDbKey = new Map(); }
+    static { this.DEFAULT_SQL_SERVER_PORT = 1433; }
+    static viewColumnOrderDbKey(pool) {
+        const cfg = pool?.config;
+        if (typeof cfg?.server === 'string' &&
+            cfg.server.trim().length > 0 &&
+            typeof cfg?.database === 'string' &&
+            cfg.database.trim().length > 0) {
+            const host = cfg.server.trim().toLowerCase();
+            const port = typeof cfg.port === 'number' && cfg.port > 0
+                ? cfg.port
+                : SQLServerDataProvider.DEFAULT_SQL_SERVER_PORT;
+            const instance = typeof cfg.options?.instanceName === 'string' && cfg.options.instanceName.trim().length > 0
+                ? `/${cfg.options.instanceName.trim().toLowerCase()}`
+                : '';
+            const db = cfg.database.trim().toLowerCase();
+            // The login is part of the identity: sys.columns only lists objects the login can see, so a
+            // scan made through the read-only or CodeGen login must never be served to the read-write
+            // pool (or vice versa) — a view missing from the map falls back to metadata order, the very
+            // misrouting this cache exists to prevent (#3102). Pools sharing server, database AND login
+            // still share one scan.
+            const user = typeof cfg.user === 'string' && cfg.user.trim().length > 0 ? cfg.user.trim().toLowerCase() : '';
+            return `mssql://${user}@${host}:${port}${instance}/${db}`;
+        }
+        return null;
+    }
+    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
@@ -335,7 +405,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
      * });
      */
     get TransactionState$() {
-        return this._transactionState$.asObservable();
+        return this.ensureTransactionStateSubject().asObservable();
     }
     /** @deprecated Use {@link TransactionState$}. */
     get transactionState$() {
@@ -367,7 +437,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() {
@@ -426,10 +496,18 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
      */
     async loadViewColumnOrderCache() {
         const pool = this._pool;
-        let scanPromise = SQLServerDataProvider._viewColumnOrderCacheByPool.get(pool);
+        const dbKey = SQLServerDataProvider.viewColumnOrderDbKey(pool);
+        let scanPromise = dbKey !== null
+            ? SQLServerDataProvider._viewColumnOrderCacheByDbKey.get(dbKey)
+            : SQLServerDataProvider._viewColumnOrderCacheByPool.get(pool);
         if (!scanPromise) {
             scanPromise = this.scanViewColumnOrder();
-            SQLServerDataProvider._viewColumnOrderCacheByPool.set(pool, scanPromise);
+            if (dbKey !== null) {
+                SQLServerDataProvider._viewColumnOrderCacheByDbKey.set(dbKey, scanPromise);
+            }
+            else {
+                SQLServerDataProvider._viewColumnOrderCacheByPool.set(pool, scanPromise);
+            }
         }
         try {
             this._viewColumnOrderCache = await scanPromise;
@@ -437,7 +515,12 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         catch (e) {
             // best-effort: an empty cache makes getAllEntityColumnsSQL fall back to the metadata-derived order.
             // Drop the shared entry (only if it's still OUR failed promise) so a later Config() can retry.
-            if (SQLServerDataProvider._viewColumnOrderCacheByPool.get(pool) === scanPromise) {
+            if (dbKey !== null) {
+                if (SQLServerDataProvider._viewColumnOrderCacheByDbKey.get(dbKey) === scanPromise) {
+                    SQLServerDataProvider._viewColumnOrderCacheByDbKey.delete(dbKey);
+                }
+            }
+            else if (SQLServerDataProvider._viewColumnOrderCacheByPool.get(pool) === scanPromise) {
                 SQLServerDataProvider._viewColumnOrderCacheByPool.delete(pool);
             }
             this._viewColumnOrderCache = new Map();
@@ -484,6 +567,10 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
      */
     static InvalidateViewColumnOrderCache(pool) {
         SQLServerDataProvider._viewColumnOrderCacheByPool.delete(pool);
+        const dbKey = SQLServerDataProvider.viewColumnOrderDbKey(pool);
+        if (dbKey !== null) {
+            SQLServerDataProvider._viewColumnOrderCacheByDbKey.delete(dbKey);
+        }
     }
     /**
      * Metadata refresh invalidates this pool's shared view-column-order cache before re-running
@@ -527,7 +614,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);
@@ -674,9 +761,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
@@ -686,15 +775,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];
@@ -722,24 +823,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 };
@@ -760,7 +862,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
         //
@@ -771,11 +873,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
@@ -785,6 +893,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.
@@ -800,10 +912,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;
@@ -816,13 +928,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
@@ -833,7 +954,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)}`;
         }
@@ -844,7 +965,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
@@ -899,20 +1021,23 @@ 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`. Outside a TransactionGroup,
         // `fullSQL` holds `@p$0` parameter placeholders, so return `literalSQL`
         // for standalone callers.
-        const result = await this.GenerateSaveSQL(entity, bNewRecord, user);
+        const result = await this.GenerateSaveSQLReadingOn(entity, bNewRecord, user, transaction);
         return result.literalSQL ?? result.fullSQL;
     }
     /**
@@ -1661,7 +1786,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         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(', ');
@@ -1896,8 +2021,9 @@ 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,
@@ -1997,7 +2123,10 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
      * This method can be used to execute raw SQL statements outside of the MJ infrastructure.
      * *CAUTION* - use this method with great care.
      * @param query
-     * @param parameters
+     * @param parameters - Named parameters: an object (`{ name: value }`, referenced `@name`), or a list of
+     *   `NamedQueryParameter` / `TypedQueryParameter`. A plain array of values is the LEGACY positional form:
+     *   it binds `@p0..@pN` and rewrites every `?` in `query`, a `?` inside a string literal, quoted
+     *   identifier or comment included, so it is only safe for statement text with no other `?`.
      * @returns
      */
     async ExecuteSQL(query, parameters = null, options, contextUser) {
@@ -2027,6 +2156,21 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
             throw e; // force caller to handle
         }
     }
+    /**
+     * Describes the first result set of `sqlText` with `sys.dm_exec_describe_first_result_set` (mode 2):
+     * names, order, exact types, nullability and the view or table column each pass-through column
+     * comes from. SQL Server compiles the statement without executing it. A statement the server
+     * cannot compile gives a failure carrying the server's message.
+     */
+    async DescribeStatement(sqlText, contextUser) {
+        try {
+            const rows = await this.ExecuteSQL(SQLSERVER_DESCRIBE_SQL, [new TypedQueryParameter('tsql', 'nvarchar(max)', sqlText)], { description: 'DescribeStatement', ignoreLogging: true }, contextUser);
+            return MapSQLServerDescribeRows(rows);
+        }
+        catch (e) {
+            return DescribeStatementFailure(e instanceof Error ? e.message : String(e));
+        }
+    }
     // ─── Colocated vector host (IColocatedVectorHost) ────────────────
     // Lets a colocated vector provider (e.g. SQLServerVectorDatabase, SQL Server 2025 native
     // vectors) store and query vectors in THIS database, reusing this connection — instead of
@@ -2406,7 +2550,7 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
         const unionParts = childEntities
             .filter(child => child.PrimaryKeys.length > 0)
             .map(child => {
-            const schema = child.SchemaName || '__mj';
+            const schema = child.SchemaName || this.MJCoreSchemaName || '__mj';
             const sourceRef = dialect.QuoteSchema(schema, child.BaseView);
             const pkRef = dialect.QuoteIdentifier(child.FirstPrimaryKey.Name); // first-pk-ok: IS-A child shares its parent's single-column key by design
             const nameLit = dialect.QuoteStringLiteral(child.Name);
@@ -2416,6 +2560,27 @@ export class SQLServerDataProvider extends GenericDatabaseProvider {
             return '';
         return unionParts.join(' UNION ALL ');
     }
+    BuildChildDiscoveryBatchSQL(childEntities, recordPKValues) {
+        if (recordPKValues.length === 0)
+            return '';
+        const dialect = this.getDialect();
+        const inList = recordPKValues.map(v => dialect.QuoteStringLiteral(v)).join(', ');
+        const aliasEntityName = dialect.QuoteColumnAlias('EntityName');
+        const aliasRecordPK = dialect.QuoteColumnAlias('RecordPK');
+        const aliasPriority = dialect.QuoteColumnAlias('Priority');
+        const unionParts = childEntities
+            .filter(child => child.PrimaryKeys.length > 0)
+            .map((child, idx) => {
+            const schema = child.SchemaName || this.MJCoreSchemaName || '__mj';
+            const sourceRef = dialect.QuoteSchema(schema, child.BaseView);
+            const pkRef = dialect.QuoteIdentifier(child.FirstPrimaryKey.Name); // first-pk-ok: IS-A shared key
+            const nameLit = dialect.QuoteStringLiteral(child.Name);
+            return `SELECT ${nameLit} AS ${aliasEntityName}, CAST(${pkRef} AS NVARCHAR(255)) AS ${aliasRecordPK}, ${idx + 1} AS ${aliasPriority} FROM ${sourceRef} WHERE ${pkRef} IN (${inList})`;
+        });
+        if (unionParts.length === 0)
+            return '';
+        return unionParts.join(' UNION ALL ');
+    }
     /**************************************************************************
      * IS-A Overlapping Subtype — Record Change Propagation
      *
@@ -2485,7 +2650,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`.
@@ -2521,8 +2686,9 @@ IF ${varName} IS NOT NULL
      */
     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() {
@@ -2547,13 +2713,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
@@ -2587,7 +2753,7 @@ IF ${varName} IS NOT NULL
         }
         finally {
             this._transaction = null;
-            this._transactionState$.next(false);
+            this.setTransactionActiveState(false);
         }
     }
     async OnBeginFailedAtDepthZero() {