@memberjunction/core-entities-server 5.16.0 → 5.18.0

package/dist/custom/MJQueryEntityServer.server.js

@@ -4,16 +4,11 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { BaseEntity, LogError, Metadata, TypeScriptTypeFromSQLType } from "@memberjunction/core";
-import { QueryCompositionEngine } from "@memberjunction/generic-database-provider";
+import { BaseEntity, LogError, Metadata, } from "@memberjunction/core";
 import { MJQueryEntity } from "@memberjunction/core-entities";
 import { RegisterClass, MJGlobal, UUIDsEqual } from "@memberjunction/global";
-import { AIEngine } from "@memberjunction/aiengine";
-import { AIPromptRunner } from "@memberjunction/ai-prompts";
-import { AIPromptParams } from "@memberjunction/ai-core-plus";
-import { removeNPrefix, convertIdentifiers, convertCommonFunctions, convertDateFunctions, convertCharIndex, convertStuff, convertIIF, convertConvertFunction, convertCastTypes, convertTopToLimit, convertStringConcat, removeCollate, } from "@memberjunction/sql-converter";
 import { EmbedTextLocalHelper } from "./util.js";
-import { SQLParser } from "@memberjunction/sql-parser";
+import { RunExtractionPipeline, CleanupQueryData, ConvertTSQLToPostgreSQL, } from "./query-extraction/index.js";
 let MJQueryEntityServer = class MJQueryEntityServer extends MJQueryEntity {
     constructor() {
         super(...arguments);
@@ -34,10 +29,9 @@ let MJQueryEntityServer = class MJQueryEntityServer extends MJQueryEntity {
     get QueryPermissions() {
         return this._queryPermissions;
     }
+    // ─── Embedding Methods ───────────────────────────────────────────────────────
     /**
      * Simple proxy to local helper method for embeddings. Needed for BaseEntity sub-classes that want to use embeddings built into BaseEntity
-     * @param textToEmbed
-     * @returns
      */
     async EmbedTextLocal(textToEmbed) {
         return EmbedTextLocalHelper(this, textToEmbed);
@@ -64,51 +58,38 @@ let MJQueryEntityServer = class MJQueryEntityServer extends MJQueryEntity {
             this.EmbeddingModelID = result.modelID;
         }
     }
+    // ─── Save / Delete Overrides ─────────────────────────────────────────────────
     async Save(options) {
         try {
-            // Check if this is a new record or if SQL/Description has changed
             const sqlField = this.GetFieldByName('SQL');
             const nameField = this.GetFieldByName('Name');
             const descriptionField = this.GetFieldByName('Description');
             const userQuestionField = this.GetFieldByName('UserQuestion');
             const shouldExtractData = !this.IsSaved || sqlField.Dirty;
             const shouldGenerateEmbedding = !this.IsSaved || nameField.Dirty || descriptionField.Dirty || userQuestionField.Dirty;
-            // Generate embedding from composite text (Name + UserQuestion + Description) for better semantic search
+            // Generate embedding from composite text for better semantic search
             if (shouldGenerateEmbedding) {
                 await this.GenerateCompositeEmbedding();
             }
             else if (!this.Description || this.Description.trim().length === 0) {
-                // Clear embedding if description is empty
                 this.EmbeddingVector = null;
                 this.EmbeddingModelID = null;
             }
-            // Auto-set Reusable=true for queries in Golden-Queries/ categories.
-            // Golden Queries are composable building blocks, so they should always be reusable.
-            if (this.CategoryID) {
-                const categoryPath = this.buildCategoryPathFromID(this.CategoryID);
-                if (categoryPath.toLowerCase().startsWith('golden-queries/') || categoryPath.toLowerCase() === 'golden-queries') {
-                    this.Reusable = true;
-                }
-            }
-            // Save the query first without AI processing (no transaction needed for basic save)
+            // Save the query first without AI processing
             const saveResult = await super.Save(options);
             if (!saveResult) {
                 return false;
             }
             // Extract and sync parameters AFTER saving, outside of any transaction
-            // This prevents connection pool exhaustion from long-running AI operations
             if (shouldExtractData && this.SQL && this.SQL.trim().length > 0) {
                 await this.extractAndSyncDataAsync();
-                // Auto-convert SQL to other dialects if configured
                 await this.autoConvertDialectsAsync();
-                await this.RefreshRelatedMetadata(true); // sync the related metadata so this entity is correct
+                await this.RefreshRelatedMetadata(true);
             }
             else if (!this.SQL || this.SQL.trim().length === 0) {
-                // If SQL is empty, ensure UsesTemplate is false and remove all related data
-                // This can also happen asynchronously since it's cleanup work
                 this.UsesTemplate = false;
                 await this.cleanupEmptyQueryAsync();
-                await this.RefreshRelatedMetadata(true); // sync the related metadata so this entity is correct
+                await this.RefreshRelatedMetadata(true);
             }
             return true;
         }
@@ -120,14 +101,11 @@ let MJQueryEntityServer = class MJQueryEntityServer extends MJQueryEntity {
     }
     async Delete(options) {
         try {
-            // Perform the actual delete operation
             const deleteResult = await super.Delete(options);
             if (!deleteResult) {
                 return false;
             }
-            // CRITICAL: Refresh metadata cache after deletion to prevent stale query references
-            // This ensures that MJAPI and any other services using cached metadata
-            // immediately see that this query no longer exists
+            // Refresh metadata cache after deletion to prevent stale query references
             await this.RefreshRelatedMetadata(true);
             return true;
         }
@@ -137,11 +115,12 @@ let MJQueryEntityServer = class MJQueryEntityServer extends MJQueryEntity {
             return false;
         }
     }
+    // ─── Pipeline Delegation ─────────────────────────────────────────────────────
     /**
      * Builds a category path string from a CategoryID by walking up the category hierarchy.
-     * Returns a path like "Golden-Queries/Sales" or "Golden-Queries".
+     * Returns a slash-delimited path like "Ground-Truth-Queries/Sales" or "Ground-Truth-Queries".
      */
-    buildCategoryPathFromID(categoryID) {
+    BuildCategoryPathFromID(categoryID) {
         const categories = Metadata.Provider.QueryCategories;
         const segments = [];
         let currentID = categoryID;
@@ -155,14 +134,29 @@ let MJQueryEntityServer = class MJQueryEntityServer extends MJQueryEntity {
         return segments.join('/');
     }
     /**
-     * Asynchronous version of extractAndSyncData that runs outside the main save operation
-     * to prevent connection pool exhaustion
+     * Builds the QuerySyncContext from this entity instance for use by the extraction pipeline.
+     */
+    buildSyncContext() {
+        return {
+            queryID: this.ID,
+            queryName: this.Name,
+            sql: this.SQL,
+            isSaved: this.IsSaved,
+            contextUser: this.ContextCurrentUser,
+            metadataProvider: this.ProviderToUse,
+            runViewProvider: this.RunViewProviderToUse,
+        };
+    }
+    /**
+     * Runs the extraction pipeline and saves the UsesTemplate flag.
+     * On error, sets UsesTemplate=false and attempts to save so the query remains usable.
      */
     async extractAndSyncDataAsync() {
         try {
-            await this.extractAndSyncData();
-            // Save the query again to update the UsesTemplate flag and any changes from AI processing
-            // This is a separate, fast operation that doesn't involve AI
+            const ctx = this.buildSyncContext();
+            const pipelineResult = await RunExtractionPipeline(ctx);
+            this.UsesTemplate = pipelineResult.usesTemplate;
+            // Save the query again to persist UsesTemplate and any changes from AI processing
             const updateResult = await super.Save();
             if (!updateResult) {
                 LogError('Failed to save query after AI processing completed');
@@ -170,8 +164,6 @@ let MJQueryEntityServer = class MJQueryEntityServer extends MJQueryEntity {
         }
         catch (e) {
             LogError('Error in async AI processing:', e);
-            // Set UsesTemplate to false on error and save
-            // This ensures the query is still usable even if AI extraction fails
             this.UsesTemplate = false;
             try {
                 await super.Save();
@@ -182,17 +174,14 @@ let MJQueryEntityServer = class MJQueryEntityServer extends MJQueryEntity {
         }
     }
     /**
-     * Asynchronous cleanup for empty queries
+     * Cleans up all extraction data when SQL is empty, then saves the updated UsesTemplate flag.
      */
     async cleanupEmptyQueryAsync() {
         try {
-            await Promise.all([
-                this.removeAllQueryParameters(),
-                this.removeAllQueryFields(),
-                this.removeAllQueryEntities(),
-                this.removeAllQuerySQLRecordsAsync()
-            ]);
-            // Save the updated UsesTemplate flag
+            const ctx = this.buildSyncContext();
+            await CleanupQueryData(ctx);
+            // Also remove dialect records (not managed by the pipeline)
+            await this.removeAllQuerySQLRecordsAsync();
             const updateResult = await super.Save();
             if (!updateResult) {
                 LogError('Failed to save query after cleanup');
@@ -202,1081 +191,66 @@ let MJQueryEntityServer = class MJQueryEntityServer extends MJQueryEntity {
             LogError('Error in async cleanup:', e);
         }
     }
-    async extractAndSyncData() {
-        try {
-            if (!this.SQL) {
-                this.UsesTemplate = false;
-                return;
-            }
-            // ── Deterministic analysis via SQLParser (source of truth) ──
-            const analysis = SQLParser.Analyze(this.SQL);
-            const deterministicParams = SQLParser.ExtractParameterInfo(this.SQL);
-            const hasTemplateParameters = analysis.hasTemplateExpressions && deterministicParams.length > 0;
-            // Extract entity metadata deterministically (for LLM context and entity sync)
-            const entityMetadata = await this.extractEntityMetadataFromSQL();
-            // ── LLM enrichment (descriptions and sample values only) ──
-            const llmResult = await this.runLLMEnrichment(entityMetadata);
-            // ── Merge: deterministic structure + LLM descriptions ──
-            const syncPromises = [];
-            // Parameters: SQLParser provides name, type, isRequired, defaultValue.
-            // LLM provides description and sampleValue as enrichment.
-            if (hasTemplateParameters) {
-                const enrichedParams = this.mergeParametersWithLLM(deterministicParams, llmResult);
-                syncPromises.push(this.syncQueryParameters(enrichedParams));
-            }
-            else {
-                syncPromises.push(this.removeAllQueryParameters());
-            }
-            // Fields: deterministic for SELECT *, LLM for explicit column lists
-            const selectStarFields = this.buildFieldsForSelectStar();
-            if (selectStarFields) {
-                syncPromises.push(this.syncQueryFields(selectStarFields));
-            }
-            else if (llmResult?.selectClause && Array.isArray(llmResult.selectClause) && llmResult.selectClause.length > 0) {
-                syncPromises.push(this.syncQueryFields(llmResult.selectClause));
-            }
-            // Entities: deterministic SQL parsing (more reliable than LLM)
-            if (entityMetadata.length > 0) {
-                syncPromises.push(this.syncQueryEntities(entityMetadata));
-            }
-            // Dependencies: deterministic composition token parsing (no LLM)
-            syncPromises.push(this.extractAndSyncQueryDependencies());
-            await Promise.all(syncPromises);
-            this.UsesTemplate = hasTemplateParameters;
-        }
-        catch (e) {
-            LogError(`Query "${this.Name}" extraction error:`, e);
-            this.UsesTemplate = false;
-        }
-    }
-    /**
-     * Runs the LLM enrichment prompt to get descriptions and sample values.
-     * Returns null if the LLM is unavailable or fails (non-fatal).
-     */
-    async runLLMEnrichment(entityMetadata) {
-        try {
-            await AIEngine.Instance.Config(false, this.ContextCurrentUser, this.ProviderToUse);
-            const aiPrompt = AIEngine.Instance.Prompts.find(p => p.Name === 'SQL Query Parameter Extraction' &&
-                p.Category === 'MJ: System');
-            if (!aiPrompt) {
-                console.warn('AI prompt for SQL Query Parameter Extraction not found. Descriptions will use heuristics.');
-                return null;
-            }
-            const promptRunner = new AIPromptRunner();
-            const params = new AIPromptParams();
-            params.prompt = aiPrompt;
-            params.data = { templateText: this.SQL, entities: entityMetadata };
-            params.contextUser = this.ContextCurrentUser;
-            const result = await promptRunner.ExecutePrompt(params);
-            if (!result.success || !result.result) {
-                console.warn(`Query "${this.Name}" - LLM enrichment failed, using heuristic descriptions.`);
-                return null;
-            }
-            return result.result;
-        }
-        catch (e) {
-            console.warn(`Query "${this.Name}" - LLM enrichment error, using heuristic descriptions:`, e);
-            return null;
-        }
-    }
-    /**
-     * Merges deterministic parameter extraction (SQLParser) with LLM enrichment.
-     *
-     * SQLParser is the authority for: name, type, isRequired, defaultValue
-     * LLM provides: description, sampleValue (with heuristic fallbacks if LLM unavailable)
-     */
-    mergeParametersWithLLM(deterministicParams, llmResult) {
-        const llmParams = llmResult?.parameters ?? [];
-        return deterministicParams.map(dp => {
-            // Find matching LLM parameter by name (case-insensitive)
-            const llmMatch = llmParams.find(lp => lp.name.toLowerCase() === dp.name.toLowerCase());
-            return {
-                name: dp.name,
-                type: dp.type === 'unknown' ? (llmMatch?.type ?? 'string') : dp.type,
-                isRequired: dp.isRequired,
-                description: llmMatch?.description ?? this.generateParameterDescription(dp),
-                usage: llmMatch?.usage ?? dp.usageLocations,
-                defaultValue: dp.defaultValue !== null ? String(dp.defaultValue) : (llmMatch?.defaultValue ?? null),
-                sampleValue: llmMatch?.sampleValue ?? this.generateSampleValue(dp),
-            };
-        });
-    }
-    /**
-     * Generates a deterministic description for a parameter when LLM is unavailable.
-     * Uses the parameter name, type, and filter information to create a meaningful description.
-     */
-    generateParameterDescription(param) {
-        const typeDescriptions = {
-            'string': 'text value',
-            'number': 'numeric value',
-            'date': 'date value',
-            'boolean': 'true/false flag',
-            'array': 'list of values',
-        };
-        const typeDesc = typeDescriptions[param.type] || 'value';
-        const requiredDesc = param.isRequired ? 'Required' : 'Optional';
-        const humanName = param.name.replace(/([A-Z])/g, ' $1').trim();
-        const defaultDesc = param.defaultValue !== null ? ` (default: ${param.defaultValue})` : '';
-        return `${requiredDesc} ${typeDesc} for ${humanName}${defaultDesc}`;
-    }
-    /**
-     * Generates a deterministic sample value based on the parameter type.
-     */
-    generateSampleValue(param) {
-        if (param.defaultValue !== null)
-            return String(param.defaultValue);
-        switch (param.type) {
-            case 'string': return 'Example';
-            case 'number': return '10';
-            case 'date': return '2024-01-01';
-            case 'boolean': return 'true';
-            case 'array': return 'Value1,Value2';
-            default: return null;
-        }
-    }
-    /**
-     * Extracts entity metadata from the SQL to provide context to the LLM for parameter type inference.
-     * Uses SQLParser for robust SQL parsing with MJ template support.
-     */
-    async extractEntityMetadataFromSQL() {
-        const md = this.ProviderToUse;
-        const results = [];
-        if (!this.SQL)
-            return results;
-        try {
-            const tableRefs = SQLParser.ExtractTableRefs(this.SQL);
-            const columnRefs = SQLParser.ExtractColumnRefs(this.SQL);
-            for (const tableRef of tableRefs) {
-                const matchingEntity = md.Entities.find(e => (e.BaseView.toLowerCase() === tableRef.TableName.toLowerCase() ||
-                    e.BaseTable.toLowerCase() === tableRef.TableName.toLowerCase()) &&
-                    e.SchemaName.toLowerCase() === tableRef.SchemaName.toLowerCase());
-                if (matchingEntity) {
-                    const relevantFields = matchingEntity.Fields
-                        .filter(f => {
-                        const fieldLower = f.Name.toLowerCase();
-                        for (const colRef of columnRefs) {
-                            const colLower = colRef.ColumnName.toLowerCase();
-                            if (colLower === fieldLower)
-                                return true;
-                            if (colRef.TableQualifier) {
-                                const qualLower = colRef.TableQualifier.toLowerCase();
-                                if ((qualLower === tableRef.Alias.toLowerCase() ||
-                                    qualLower === tableRef.TableName.toLowerCase()) &&
-                                    colLower === fieldLower) {
-                                    return true;
-                                }
-                            }
-                        }
-                        return f.IsPrimaryKey;
-                    })
-                        .slice(0, 20)
-                        .map(f => ({
-                        name: f.Name,
-                        type: f.Type,
-                        isPrimaryKey: f.IsPrimaryKey
-                    }));
-                    if (relevantFields.length > 0) {
-                        results.push({
-                            name: matchingEntity.Name,
-                            schemaName: matchingEntity.SchemaName,
-                            baseView: matchingEntity.BaseView,
-                            fields: relevantFields
-                        });
-                    }
-                }
-            }
-            return results;
-        }
-        catch (error) {
-            console.warn(`Error in extractEntityMetadataFromSQL: ${error}`);
-            return results;
-        }
-    }
-    async syncQueryParameters(extractedParams) {
-        // Filter out any parameter named "query" that came from {{query:"..."}} composition tokens.
-        // The AI extraction prompt should skip these, but this is a safety net.
-        const compositionTokenRegex = /\{\{query:"[^"]+"\}\}/;
-        const filteredParams = extractedParams.filter(p => {
-            if (p.name === 'query' && this.SQL && compositionTokenRegex.test(this.SQL)) {
-                return false;
-            }
-            return true;
-        });
-        extractedParams = filteredParams;
-        // Use the entity's provider instead of creating new Metadata instance
-        // Use same casting pattern as RefreshRelatedMetadata method
-        const md = this.ProviderToUse;
-        try {
-            // Get existing query parameters
-            const rv = this.RunViewProviderToUse;
-            const existingParams = [];
-            if (this.IsSaved) {
-                const existingParamsResult = await rv.RunView({
-                    EntityName: 'MJ: Query Parameters',
-                    ExtraFilter: `QueryID='${this.ID}'`,
-                    ResultType: 'entity_object'
-                }, this.ContextCurrentUser);
-                if (!existingParamsResult.Success) {
-                    throw new Error(`Failed to load existing query parameters: ${existingParamsResult.ErrorMessage}`);
-                }
-                existingParams.push(...existingParamsResult.Results || []);
-            }
-            // Convert extracted param names to lowercase for comparison
-            const extractedParamNames = extractedParams.map(p => p.name.toLowerCase());
-            // Find parameters to add, update, or remove
-            const paramsToAdd = extractedParams.filter(p => !existingParams.some(ep => ep.Name.toLowerCase() === p.name.toLowerCase()));
-            const paramsToUpdate = existingParams.filter(ep => extractedParams.some(p => p.name.toLowerCase() === ep.Name.toLowerCase()));
-            const paramsToRemove = existingParams.filter(ep => !extractedParamNames.includes(ep.Name.toLowerCase()));
-            // Prepare all save/delete operations
-            const promises = [];
-            // Add new parameters
-            for (const param of paramsToAdd) {
-                const newParam = await md.GetEntityObject('MJ: Query Parameters', this.ContextCurrentUser);
-                newParam.QueryID = this.ID;
-                newParam.Name = param.name;
-                // Normalize type to lowercase for case-insensitive matching
-                const normalizedType = param.type?.toLowerCase();
-                switch (normalizedType) {
-                    case "array":
-                    case "boolean":
-                    case "string":
-                    case "date":
-                    case "number":
-                        newParam.Type = normalizedType;
-                        break;
-                    case "object":
-                        // Object type is supported in Nunjucks/RunQuery but not yet in database schema
-                        // Store as string for now - the actual validation happens at runtime
-                        console.log(`Query "${this.Name}" - Parameter "${param.name}" is type "object", storing as "string" (runtime will handle object validation)`);
-                        newParam.Type = 'string';
-                        break;
-                    default:
-                        console.warn(`Query "${this.Name}" - Unknown parameter type "${param.type}" for parameter "${param.name}", defaulting to "string"`);
-                        newParam.Type = 'string';
-                }
-                newParam.IsRequired = param.isRequired;
-                newParam.DefaultValue = param.defaultValue;
-                newParam.Description = param.description;
-                newParam.SampleValue = param.sampleValue;
-                newParam.DetectionMethod = 'AI'; // Structure from SQLParser AST, descriptions enriched by LLM
-                promises.push(newParam.Save());
-            }
-            // Update existing parameters if properties changed
-            for (const existingParam of paramsToUpdate) {
-                const extractedParam = extractedParams.find(p => p.name.toLowerCase() === existingParam.Name.toLowerCase());
-                if (extractedParam) {
-                    let hasChanges = false;
-                    // Normalize type to lowercase for case-insensitive comparison
-                    const normalizedType = extractedParam.type?.toLowerCase();
-                    const validTypes = ['array', 'boolean', 'string', 'date', 'number'];
-                    const isValidType = validTypes.includes(normalizedType);
-                    let targetType;
-                    if (isValidType) {
-                        targetType = normalizedType;
-                    }
-                    else if (normalizedType === 'object') {
-                        // Object type is supported in Nunjucks/RunQuery but not yet in database schema
-                        console.log(`Query "${this.Name}" - Parameter "${extractedParam.name}" is type "object", storing as "string" (runtime will handle object validation)`);
-                        targetType = 'string';
-                    }
-                    else {
-                        console.warn(`Query "${this.Name}" - Unknown parameter type "${extractedParam.type}" for parameter "${extractedParam.name}", defaulting to "string"`);
-                        targetType = 'string';
-                    }
-                    // Check each property for changes
-                    if (existingParam.Type !== targetType) {
-                        existingParam.Type = targetType;
-                        hasChanges = true;
-                    }
-                    if (existingParam.IsRequired !== extractedParam.isRequired) {
-                        existingParam.IsRequired = extractedParam.isRequired;
-                        hasChanges = true;
-                    }
-                    if (existingParam.DefaultValue !== extractedParam.defaultValue) {
-                        existingParam.DefaultValue = extractedParam.defaultValue;
-                        hasChanges = true;
-                    }
-                    if (existingParam.Description !== extractedParam.description) {
-                        existingParam.Description = extractedParam.description;
-                        hasChanges = true;
-                    }
-                    if (existingParam.SampleValue !== extractedParam.sampleValue) {
-                        existingParam.SampleValue = extractedParam.sampleValue;
-                        hasChanges = true;
-                    }
-                    if (existingParam.DetectionMethod !== 'AI') {
-                        existingParam.DetectionMethod = 'AI';
-                        hasChanges = true;
-                    }
-                    if (hasChanges) {
-                        promises.push(existingParam.Save());
-                    }
-                }
-            }
-            // Remove parameters that are no longer in the SQL
-            for (const paramToRemove of paramsToRemove) {
-                promises.push(paramToRemove.Delete());
-            }
-            // Execute all operations in parallel
-            if (promises.length > 0) {
-                await Promise.all(promises);
-            }
-        }
-        catch (e) {
-            LogError(`Query "${this.Name}" - Failed to sync parameters:`, e);
-            throw e;
-        }
-    }
-    async removeAllQueryParameters() {
-        try {
-            if (this.IsSaved) {
-                // Get all existing query parameters
-                const rv = this.RunViewProviderToUse;
-                const existingParamsResult = await rv.RunView({
-                    EntityName: 'MJ: Query Parameters',
-                    ExtraFilter: `QueryID='${this.ID}'`,
-                    ResultType: 'entity_object'
-                }, this.ContextCurrentUser);
-                if (!existingParamsResult.Success) {
-                    throw new Error(`Failed to load existing query parameters: ${existingParamsResult.ErrorMessage}`);
-                }
-                const existingParams = existingParamsResult.Results || [];
-                // Delete all existing parameters
-                const deletePromises = existingParams.map(param => param.Delete());
-                if (deletePromises.length > 0) {
-                    await Promise.all(deletePromises);
-                }
-            }
-        }
-        catch (e) {
-            LogError('Failed to remove query parameters:', e);
-            throw e; // Re-throw since we're in a transaction
-        }
-    }
-    /**
-     * Detects if the SQL uses SELECT * and if so, builds the complete field list deterministically
-     * from entity metadata without relying on the AI (which can't enumerate * columns).
-     * Returns null if the SQL doesn't use SELECT * or if entities can't be resolved.
-     */
-    buildFieldsForSelectStar() {
-        if (!this.SQL)
-            return null;
-        // Check if SELECT clause contains * (possibly with table alias like "a.*")
-        const selectStarRegex = /\bSELECT\s+(?:(?:TOP\s+\d+|DISTINCT)\s+)?(\*|[\w.]+\.\*)\s+FROM\b/i;
-        if (!selectStarRegex.test(this.SQL))
-            return null;
-        const md = this.ProviderToUse;
-        try {
-            const tableRefs = SQLParser.ExtractTableRefs(this.SQL);
-            const expandedFields = [];
-            for (const tableRef of tableRefs) {
-                const matchingEntity = md.Entities.find(e => (e.BaseView.toLowerCase() === tableRef.TableName.toLowerCase() ||
-                    e.BaseTable.toLowerCase() === tableRef.TableName.toLowerCase()) &&
-                    e.SchemaName.toLowerCase() === tableRef.SchemaName.toLowerCase());
-                if (matchingEntity) {
-                    for (const entityField of matchingEntity.Fields) {
-                        if (!expandedFields.some(f => f.name === entityField.Name)) {
-                            expandedFields.push({
-                                name: entityField.Name,
-                                description: entityField.Description || `${entityField.Name} field from ${matchingEntity.Name}`,
-                                type: TypeScriptTypeFromSQLType(entityField.Type).toLowerCase(),
-                                optional: false,
-                                sourceEntity: matchingEntity.Name,
-                                sourceFieldName: entityField.Name,
-                                isComputed: false,
-                                isSummary: false
-                            });
-                        }
-                    }
-                }
-            }
-            // Also check for {{query:"..."}} composition tokens in FROM clause
-            if (expandedFields.length === 0) {
-                const compositionRefs = SQLParser.ExtractCompositionRefs(this.SQL);
-                for (const ref of compositionRefs) {
-                    const referencedQuery = Metadata.Provider.Queries.find(q => q.Name.toLowerCase() === ref.queryName.toLowerCase());
-                    if (referencedQuery && referencedQuery.Fields.length > 0) {
-                        for (const qField of referencedQuery.Fields) {
-                            if (!expandedFields.some(f => f.name === qField.Name)) {
-                                expandedFields.push({
-                                    name: qField.Name,
-                                    description: qField.Description || `${qField.Name} from query "${referencedQuery.Name}"`,
-                                    type: TypeScriptTypeFromSQLType(qField.SQLBaseType).toLowerCase(),
-                                    optional: false,
-                                    sourceEntity: qField.SourceEntityID ? md.Entities.find(e => UUIDsEqual(e.ID, qField.SourceEntityID))?.Name || null : null,
-                                    sourceFieldName: qField.SourceFieldName || null,
-                                    isComputed: qField.IsComputed || false,
-                                    isSummary: qField.IsSummary || false
-                                });
-                            }
-                        }
-                    }
-                }
-            }
-            return expandedFields.length > 0 ? expandedFields : null;
-        }
-        catch (error) {
-            console.warn(`Query "${this.Name}" - Error in buildFieldsForSelectStar:`, error);
-            return null;
-        }
-    }
-    /**
-     * Finds an entity by name, checking both Name (which may have "MJ: " prefix) and DisplayName.
-     * The AI often returns entity names without the "MJ: " prefix, so we need to match both.
-     */
-    findEntityByName(md, name) {
-        const lower = name.toLowerCase();
-        return md.Entities.find(e => e.Name.toLowerCase() === lower || (e.DisplayName && e.DisplayName.toLowerCase() === lower));
-    }
-    /**
-     * Expands wildcard (*) entries in the extracted fields list.
-     * When AI returns a field with name="*" or sourceFieldName="*", we expand it into
-     * individual field entries by looking up the source from metadata.
-     * If the AI didn't provide a sourceEntity, we parse the SQL's FROM clause to find it.
-     */
-    expandWildcardFields(extractedFields, md) {
-        // Check if any field is a wildcard that needs expansion
-        const hasWildcard = extractedFields.some(f => f.name === '*' || f.sourceFieldName === '*');
-        if (!hasWildcard)
-            return extractedFields;
-        const expandedFields = [];
-        for (const field of extractedFields) {
-            const isWildcard = field.name === '*' || field.sourceFieldName === '*';
-            if (!isWildcard) {
-                expandedFields.push(field);
-                continue;
-            }
-            // If we have a sourceEntity, try to resolve from it
-            if (field.sourceEntity) {
-                const sourceEntityInfo = this.findEntityByName(md, field.sourceEntity);
-                if (sourceEntityInfo) {
-                    for (const entityField of sourceEntityInfo.Fields) {
-                        expandedFields.push({
-                            name: entityField.Name,
-                            description: entityField.Description || `${entityField.Name} field from ${sourceEntityInfo.Name}`,
-                            type: TypeScriptTypeFromSQLType(entityField.Type).toLowerCase(),
-                            optional: field.optional,
-                            sourceEntity: sourceEntityInfo.Name,
-                            sourceFieldName: entityField.Name,
-                            isComputed: false,
-                            isSummary: false
-                        });
-                    }
-                    continue;
-                }
-                // sourceEntity didn't match an entity — try as a query name
-                const composedQuery = Metadata.Provider.Queries.find(q => q.Name.toLowerCase() === field.sourceEntity.toLowerCase());
-                if (composedQuery && composedQuery.Fields.length > 0) {
-                    for (const qField of composedQuery.Fields) {
-                        expandedFields.push({
-                            name: qField.Name,
-                            description: qField.Description || `${qField.Name} from query "${composedQuery.Name}"`,
-                            type: TypeScriptTypeFromSQLType(qField.SQLBaseType).toLowerCase(),
-                            optional: field.optional,
-                            sourceEntity: qField.SourceEntityID ? md.Entities.find(e => UUIDsEqual(e.ID, qField.SourceEntityID))?.Name || null : null,
-                            sourceFieldName: qField.SourceFieldName || null,
-                            isComputed: qField.IsComputed || false,
-                            isSummary: qField.IsSummary || false
-                        });
-                    }
-                    continue;
-                }
-                expandedFields.push(field);
-                continue;
-            }
-            // No sourceEntity and no match — keep the raw entry as-is
-            expandedFields.push(field);
-        }
-        return expandedFields;
-    }
-    async syncQueryFields(extractedFields) {
-        // Use the entity's provider instead of creating new Metadata instance
-        // Use same casting pattern as RefreshRelatedMetadata method
-        const md = this.ProviderToUse;
-        // Expand any wildcard (*) entries before processing
-        const fieldsToSync = this.expandWildcardFields(extractedFields, md);
-        try {
-            const existingFields = [];
-            if (this.IsSaved) {
-                // Get existing query fields
-                const rv = this.RunViewProviderToUse;
-                const existingFieldsResult = await rv.RunView({
-                    EntityName: 'MJ: Query Fields',
-                    ExtraFilter: `QueryID='${this.ID}'`,
-                    ResultType: 'entity_object'
-                }, this.ContextCurrentUser);
-                if (!existingFieldsResult.Success) {
-                    throw new Error(`Failed to load existing query fields: ${existingFieldsResult.ErrorMessage}`);
-                }
-                existingFields.push(...existingFieldsResult.Results || []);
-            }
-            // Convert field names to lowercase for comparison (using expanded fieldsToSync)
-            const fieldNamesToSync = fieldsToSync.map(f => f.name.toLowerCase());
-            // Find fields to add, update, or remove
-            const fieldsToAdd = fieldsToSync.filter(f => !existingFields.some(ef => ef.Name.toLowerCase() === f.name.toLowerCase()));
-            const fieldsToUpdate = existingFields.filter(ef => fieldsToSync.some(f => f.name.toLowerCase() === ef.Name.toLowerCase()));
-            const fieldsToRemove = existingFields.filter(ef => !fieldNamesToSync.includes(ef.Name.toLowerCase()));
-            // Prepare all save/delete operations
-            const promises = [];
-            // Add new fields
-            for (let i = 0; i < fieldsToAdd.length; i++) {
-                const field = fieldsToAdd[i];
-                const newField = await md.GetEntityObject('MJ: Query Fields', this.ContextCurrentUser);
-                newField.QueryID = this.ID;
-                newField.Name = field.name;
-                newField.Description = field.description;
-                newField.Sequence = i + 1;
-                // Map type to SQL types
-                switch (field.type) {
-                    case 'number':
-                        newField.SQLBaseType = 'decimal';
-                        newField.SQLFullType = 'decimal(18,2)';
-                        break;
-                    case 'date':
-                        newField.SQLBaseType = 'datetime';
-                        newField.SQLFullType = 'datetime';
-                        break;
-                    case 'boolean':
-                        newField.SQLBaseType = 'bit';
-                        newField.SQLFullType = 'bit';
-                        break;
-                    default:
-                        newField.SQLBaseType = 'nvarchar';
-                        newField.SQLFullType = 'nvarchar(MAX)';
-                }
-                // Set computed/summary flags
-                newField.IsComputed = field.isComputed || field.dynamicName || false;
-                newField.IsSummary = field.isSummary || false;
-                if (field.computationDescription) {
-                    newField.ComputationDescription = field.computationDescription;
-                }
-                // Set source entity tracking
-                if (field.sourceEntity) {
-                    // Look up entity ID from entity name (check both Name and DisplayName for "MJ: " prefix)
-                    const sourceEntityInfo = this.findEntityByName(md, field.sourceEntity);
-                    if (sourceEntityInfo) {
-                        newField.SourceEntityID = sourceEntityInfo.ID;
-                    }
-                }
-                newField.SourceFieldName = field.sourceFieldName || (field.dynamicName ? field.name : null);
-                promises.push(newField.Save());
-            }
-            // Update existing fields if properties changed
-            for (const existingField of fieldsToUpdate) {
-                const extractedField = fieldsToSync.find(f => f.name.toLowerCase() === existingField.Name.toLowerCase());
-                if (extractedField) {
-                    let hasChanges = false;
-                    if (existingField.Description !== extractedField.description) {
-                        existingField.Description = extractedField.description;
-                        hasChanges = true;
-                    }
-                    const newIsComputed = extractedField.isComputed || extractedField.dynamicName || false;
-                    if (existingField.IsComputed !== newIsComputed) {
-                        existingField.IsComputed = newIsComputed;
-                        hasChanges = true;
-                    }
-                    const newIsSummary = extractedField.isSummary || false;
-                    if (existingField.IsSummary !== newIsSummary) {
-                        existingField.IsSummary = newIsSummary;
-                        hasChanges = true;
-                    }
-                    if (extractedField.computationDescription && existingField.ComputationDescription !== extractedField.computationDescription) {
-                        existingField.ComputationDescription = extractedField.computationDescription;
-                        hasChanges = true;
-                    }
-                    // Update source entity tracking
-                    if (extractedField.sourceEntity) {
-                        const sourceEntityInfo = this.findEntityByName(md, extractedField.sourceEntity);
-                        if (sourceEntityInfo && !UUIDsEqual(existingField.SourceEntityID, sourceEntityInfo.ID)) {
-                            existingField.SourceEntityID = sourceEntityInfo.ID;
-                            hasChanges = true;
-                        }
-                    }
-                    else if (existingField.SourceEntityID != null) {
-                        existingField.SourceEntityID = null;
-                        hasChanges = true;
-                    }
-                    const newSourceFieldName = extractedField.sourceFieldName || (extractedField.dynamicName ? extractedField.name : null);
-                    if (existingField.SourceFieldName !== newSourceFieldName) {
-                        existingField.SourceFieldName = newSourceFieldName;
-                        hasChanges = true;
-                    }
-                    if (existingField.Sequence !== fieldsToSync.indexOf(extractedField) + 1) {
-                        existingField.Sequence = fieldsToSync.indexOf(extractedField) + 1;
-                        hasChanges = true;
-                    }
-                    if (hasChanges) {
-                        promises.push(existingField.Save());
-                    }
-                }
-            }
-            // Remove fields that are no longer in the SQL
-            for (const fieldToRemove of fieldsToRemove) {
-                promises.push(fieldToRemove.Delete());
-            }
-            // Execute all operations in parallel
-            if (promises.length > 0) {
-                await Promise.all(promises);
-            }
-        }
-        catch (e) {
-            LogError(`Query "${this.Name}" - Failed to sync fields:`, e);
-            throw e;
-        }
-    }
-    async syncQueryEntities(extractedEntities) {
-        // Use the entity's provider instead of creating new Metadata instance
-        // Use same casting pattern as RefreshRelatedMetadata method
-        const md = this.ProviderToUse;
-        try {
-            // Get existing query entities
-            const existingEntities = [];
-            if (this.IsSaved) {
-                const rv = this.RunViewProviderToUse;
-                const existingEntitiesResult = await rv.RunView({
-                    EntityName: 'MJ: Query Entities',
-                    ExtraFilter: `QueryID='${this.ID}'`,
-                    ResultType: 'entity_object'
-                }, this.ContextCurrentUser);
-                if (!existingEntitiesResult.Success) {
-                    throw new Error(`Failed to load existing query entities: ${existingEntitiesResult.ErrorMessage}`);
-                }
-                existingEntities.push(...existingEntitiesResult.Results || []);
-            }
-            // Look up MJ entity IDs for the extracted entities using pre-loaded metadata
-            // Since extractEntityMetadataFromSQL already matched entities, we just need to find them by name
-            const entityMappings = extractedEntities.map(extracted => {
-                // Find matching entity in metadata by name (already matched during extraction)
-                const matchingEntity = md.Entities.find(e => e.Name === extracted.name &&
-                    e.SchemaName.toLowerCase() === extracted.schemaName.toLowerCase());
-                if (matchingEntity) {
-                    return {
-                        extracted,
-                        entityID: matchingEntity.ID,
-                        entityName: matchingEntity.Name
-                    };
-                }
-                return null;
-            }).filter(m => m !== null);
-            // Find entities to add or remove
-            const entitiesToAdd = entityMappings.filter(mapping => !existingEntities.some(ee => UUIDsEqual(ee.EntityID, mapping.entityID)));
-            const entitiesToRemove = existingEntities.filter(ee => !entityMappings.some(mapping => UUIDsEqual(mapping.entityID, ee.EntityID)));
-            // Prepare all save/delete operations
-            const promises = [];
-            // Add new query entity relationships
-            for (const mapping of entitiesToAdd) {
-                if (mapping) {
-                    const newEntity = await md.GetEntityObject('MJ: Query Entities', this.ContextCurrentUser);
-                    newEntity.QueryID = this.ID;
-                    newEntity.EntityID = mapping.entityID;
-                    newEntity.DetectionMethod = 'AI'; // Using 'AI' as it's the closest match to automated detection
-                    newEntity.AutoDetectConfidenceScore = 1.0; // 100% confidence since we're using deterministic SQL parsing
-                    promises.push(newEntity.Save());
-                }
-            }
-            // Remove entities that are no longer in the SQL
-            for (const entityToRemove of entitiesToRemove) {
-                promises.push(entityToRemove.Delete());
-            }
-            // Execute all operations in parallel
-            if (promises.length > 0) {
-                await Promise.all(promises);
-            }
-        }
-        catch (e) {
-            LogError(`Query "${this.Name}" - Failed to sync entities:`, e);
-            throw e;
-        }
-    }
-    async removeAllQueryFields() {
-        try {
-            if (!this.IsSaved)
-                return; // Nothing to remove if not saved
-            const rv = this.RunViewProviderToUse;
-            const existingFieldsResult = await rv.RunView({
-                EntityName: 'MJ: Query Fields',
-                ExtraFilter: `QueryID='${this.ID}'`,
-                ResultType: 'entity_object'
-            }, this.ContextCurrentUser);
-            if (!existingFieldsResult.Success) {
-                throw new Error(`Failed to load existing query fields: ${existingFieldsResult.ErrorMessage}`);
-            }
-            const existingFields = existingFieldsResult.Results || [];
-            const deletePromises = existingFields.map(field => field.Delete());
-            if (deletePromises.length > 0) {
-                await Promise.all(deletePromises);
-            }
-        }
-        catch (e) {
-            LogError('Failed to remove query fields:', e);
-            throw e;
-        }
-    }
-    async removeAllQueryEntities() {
-        try {
-            if (!this.IsSaved)
-                return; // Nothing to remove if not saved
-            const rv = this.RunViewProviderToUse;
-            const existingEntitiesResult = await rv.RunView({
-                EntityName: 'MJ: Query Entities',
-                ExtraFilter: `QueryID='${this.ID}'`,
-                ResultType: 'entity_object'
-            }, this.ContextCurrentUser);
-            if (!existingEntitiesResult.Success) {
-                throw new Error(`Failed to load existing query entities: ${existingEntitiesResult.ErrorMessage}`);
-            }
-            const existingEntities = existingEntitiesResult.Results || [];
-            const deletePromises = existingEntities.map(entity => entity.Delete());
-            if (deletePromises.length > 0) {
-                await Promise.all(deletePromises);
-            }
-        }
-        catch (e) {
-            LogError('Failed to remove query entities:', e);
-            throw e;
-        }
-    }
-    /**
-     * Deterministically extracts {{query:"..."}} composition references from this query's SQL
-     * and syncs the QueryDependency records accordingly. No LLM needed — uses regex parsing.
-     */
-    async extractAndSyncQueryDependencies() {
-        const compositionEngine = new QueryCompositionEngine();
-        const sql = this.SQL;
-        if (!sql || !compositionEngine.HasCompositionTokens(sql)) {
-            // No composition tokens — remove any stale dependency records
-            await this.removeAllQueryDependencies();
-            return;
-        }
-        // Parse all {{query:"..."}} tokens
-        const tokens = compositionEngine.ParseCompositionTokens(sql);
-        if (tokens.length === 0) {
-            await this.removeAllQueryDependencies();
-            return;
-        }
-        // Resolve each token to a QueryInfo to get its ID
-        const extractedDeps = this.resolveTokensToQueryDependencies(tokens);
-        // Check for cycles before syncing
-        const cycleError = await this.detectDependencyCycles(extractedDeps);
-        if (cycleError) {
-            LogError(`Query "${this.Name}" creates circular dependency: ${cycleError}. Dependencies will not be synced.`);
-            return;
-        }
-        await this.syncQueryDependencies(extractedDeps);
-    }
-    /**
-     * Resolves parsed composition tokens to dependency records with QueryIDs.
-     */
-    resolveTokensToQueryDependencies(tokens) {
-        const allQueries = Metadata.Provider.Queries;
-        const deps = [];
-        for (const token of tokens) {
-            const queryName = token.QueryName.toLowerCase();
-            // Try category-qualified lookup first
-            let matchedQuery;
-            if (token.CategorySegments.length > 0) {
-                const expectedPath = `/${token.CategorySegments.join('/')}/`;
-                matchedQuery = allQueries.find(q => q.Name.toLowerCase() === queryName &&
-                    q.CategoryPath.toLowerCase() === expectedPath.toLowerCase());
-            }
-            // Fall back to name-only
-            if (!matchedQuery) {
-                const nameMatches = allQueries.filter(q => q.Name.toLowerCase() === queryName);
-                if (nameMatches.length === 1) {
-                    matchedQuery = nameMatches[0];
-                }
-            }
-            if (!matchedQuery) {
-                LogError(`Query "${this.Name}": Referenced query not found: "${token.FullPath}". Dependency will not be tracked.`);
-                continue;
-            }
-            // Validate the referenced query is marked Reusable
-            if (!matchedQuery.Reusable) {
-                throw new Error(`Query "${this.Name}" references "${token.FullPath}" via composition syntax, ` +
-                    `but "${matchedQuery.Name}" is not marked as Reusable. ` +
-                    `Set Reusable=true on "${matchedQuery.Name}" before using it in {{query:"..."}} references.`);
-            }
-            // Extract alias from SQL context (look for the token followed by whitespace + identifier)
-            const alias = this.extractAliasFromSQL(token.FullToken);
-            // Build parameter mapping
-            let parameterMapping = null;
-            if (token.Parameters.length > 0) {
-                parameterMapping = {};
-                for (const param of token.Parameters) {
-                    if (param.StaticValue !== null) {
-                        parameterMapping[param.Name] = param.StaticValue;
-                    }
-                    else if (param.PassThroughName !== null) {
-                        parameterMapping[param.Name] = `@${param.PassThroughName}`;
-                    }
-                }
-            }
-            deps.push({
-                dependsOnQueryID: matchedQuery.ID,
-                referencePath: token.FullPath,
-                alias,
-                parameterMapping
-            });
-        }
-        return deps;
-    }
-    /**
-     * Extracts the SQL alias following a {{query:"..."}} token from this query's SQL.
-     */
-    extractAliasFromSQL(fullToken) {
-        if (!this.SQL)
-            return null;
-        const tokenIndex = this.SQL.indexOf(fullToken);
-        if (tokenIndex < 0)
-            return null;
-        const afterToken = this.SQL.substring(tokenIndex + fullToken.length);
-        const aliasMatch = /^\s+(\w+)/i.exec(afterToken);
-        // Make sure it's not a SQL keyword
-        if (aliasMatch) {
-            const keywords = new Set(['ON', 'WHERE', 'AND', 'OR', 'JOIN', 'LEFT', 'RIGHT', 'INNER', 'OUTER', 'CROSS', 'FULL', 'GROUP', 'ORDER', 'HAVING', 'UNION', 'EXCEPT', 'INTERSECT', 'LIMIT', 'OFFSET', 'FETCH']);
-            if (!keywords.has(aliasMatch[1].toUpperCase())) {
-                return aliasMatch[1];
-            }
-        }
-        return null;
-    }
-    /**
-     * Detects circular dependencies by walking the dependency graph.
-     * Returns a descriptive error string if a cycle is found, or null if clean.
-     */
-    async detectDependencyCycles(proposedDeps) {
-        const allDependencies = Metadata.Provider.QueryDependencies;
-        const visited = new Set();
-        const stack = new Set();
-        const hasCycle = (queryID, path) => {
-            if (stack.has(queryID)) {
-                const queryName = Metadata.Provider.Queries.find(q => UUIDsEqual(q.ID, queryID))?.Name || queryID;
-                return [...path, queryName].join(' → ');
-            }
-            if (visited.has(queryID))
-                return null;
-            visited.add(queryID);
-            stack.add(queryID);
-            const queryName = Metadata.Provider.Queries.find(q => UUIDsEqual(q.ID, queryID))?.Name || queryID;
-            path.push(queryName);
-            // Get existing dependencies for this query
-            const deps = allDependencies.filter(d => d.QueryID === queryID);
-            for (const dep of deps) {
-                const result = hasCycle(dep.DependsOnQueryID, [...path]);
-                if (result)
-                    return result;
-            }
-            stack.delete(queryID);
-            return null;
-        };
-        // Check each proposed dependency
-        for (const dep of proposedDeps) {
-            // Simulate: dep.dependsOnQueryID → (its dependencies) → ... → back to this.ID?
-            const visited2 = new Set();
-            const stack2 = new Set([this.ID]);
-            const checkFromDep = (queryID, path) => {
-                if (UUIDsEqual(queryID, this.ID)) {
-                    return [...path, this.Name].join(' → ');
-                }
-                if (visited2.has(queryID))
-                    return null;
-                visited2.add(queryID);
-                const queryName = Metadata.Provider.Queries.find(q => UUIDsEqual(q.ID, queryID))?.Name || queryID;
-                path.push(queryName);
-                const deps = allDependencies.filter(d => d.QueryID === queryID);
-                for (const d of deps) {
-                    const result = checkFromDep(d.DependsOnQueryID, [...path]);
-                    if (result)
-                        return result;
-                }
-                return null;
-            };
-            const result = checkFromDep(dep.dependsOnQueryID, [this.Name]);
-            if (result)
-                return result;
-        }
-        return null;
-    }
-    /**
-     * Syncs extracted query dependencies against existing QueryDependency records.
-     * Follows the same add/update/delete pattern as syncQueryParameters/Fields/Entities.
-     */
-    async syncQueryDependencies(extractedDeps) {
-        const md = new Metadata();
-        try {
-            const existingDeps = [];
-            if (this.IsSaved) {
-                const rv = this.RunViewProviderToUse;
-                const existingResult = await rv.RunView({
-                    EntityName: 'MJ: Query Dependencies',
-                    ExtraFilter: `QueryID='${this.ID}'`,
-                    ResultType: 'entity_object'
-                }, this.ContextCurrentUser);
-                if (!existingResult.Success) {
-                    throw new Error(`Failed to load existing query dependencies: ${existingResult.ErrorMessage}`);
-                }
-                existingDeps.push(...(existingResult.Results || []));
-            }
-            // Compare: match on DependsOnQueryID + ReferencePath for uniqueness
-            const depsToAdd = extractedDeps.filter(d => !existingDeps.some(ed => UUIDsEqual(ed.DependsOnQueryID, d.dependsOnQueryID) &&
-                ed.ReferencePath === d.referencePath));
-            const depsToUpdate = existingDeps.filter(ed => extractedDeps.some(d => UUIDsEqual(ed.DependsOnQueryID, d.dependsOnQueryID) &&
-                ed.ReferencePath === d.referencePath));
-            const depsToRemove = existingDeps.filter(ed => !extractedDeps.some(d => UUIDsEqual(ed.DependsOnQueryID, d.dependsOnQueryID) &&
-                ed.ReferencePath === d.referencePath));
-            const promises = [];
-            // Add new dependencies
-            for (const dep of depsToAdd) {
-                const newDep = await md.GetEntityObject('MJ: Query Dependencies', this.ContextCurrentUser);
-                newDep.QueryID = this.ID;
-                newDep.DependsOnQueryID = dep.dependsOnQueryID;
-                newDep.ReferencePath = dep.referencePath;
-                newDep.Alias = dep.alias;
-                newDep.ParameterMapping = dep.parameterMapping ? JSON.stringify(dep.parameterMapping) : null;
-                newDep.DetectionMethod = 'Auto';
-                promises.push(newDep.Save());
-            }
-            // Update existing dependencies (check for changes)
-            for (const existingDep of depsToUpdate) {
-                const extractedDep = extractedDeps.find(d => UUIDsEqual(existingDep.DependsOnQueryID, d.dependsOnQueryID) &&
-                    existingDep.ReferencePath === d.referencePath);
-                if (extractedDep) {
-                    let hasChanges = false;
-                    if (existingDep.Alias !== extractedDep.alias) {
-                        existingDep.Alias = extractedDep.alias;
-                        hasChanges = true;
-                    }
-                    const newMapping = extractedDep.parameterMapping ? JSON.stringify(extractedDep.parameterMapping) : null;
-                    if (existingDep.ParameterMapping !== newMapping) {
-                        existingDep.ParameterMapping = newMapping;
-                        hasChanges = true;
-                    }
-                    if (hasChanges) {
-                        promises.push(existingDep.Save());
-                    }
-                }
-            }
-            // Remove stale dependencies
-            for (const depToRemove of depsToRemove) {
-                promises.push(depToRemove.Delete());
-            }
-            if (promises.length > 0) {
-                await Promise.all(promises);
-            }
-        }
-        catch (e) {
-            LogError(`Query "${this.Name}" - Failed to sync dependencies:`, e);
-            throw e;
-        }
-    }
-    /**
-     * Removes all QueryDependency records for this query.
-     */
-    async removeAllQueryDependencies() {
-        try {
-            if (!this.IsSaved)
-                return;
-            const rv = this.RunViewProviderToUse;
-            const existingResult = await rv.RunView({
-                EntityName: 'MJ: Query Dependencies',
-                ExtraFilter: `QueryID='${this.ID}'`,
-                ResultType: 'entity_object'
-            }, this.ContextCurrentUser);
-            if (!existingResult.Success) {
-                throw new Error(`Failed to load existing query dependencies: ${existingResult.ErrorMessage}`);
-            }
-            const existingDeps = existingResult.Results || [];
-            const deletePromises = existingDeps.map(dep => dep.Delete());
-            if (deletePromises.length > 0) {
-                await Promise.all(deletePromises);
-            }
-        }
-        catch (e) {
-            LogError('Failed to remove query dependencies:', e);
-            throw e;
-        }
-    }
+    // ─── Dialect Conversion ──────────────────────────────────────────────────────
     /**
      * Auto-converts the query's SQL to other dialects based on the queryDialects
      * configuration stored in GlobalObjectStore. Best-effort: failures never block the save.
      */
     async autoConvertDialectsAsync() {
         try {
-            // Read config from GlobalObjectStore (set by MJServer at startup)
             const config = MJGlobal.Instance.GetGlobalObjectStore()?.['queryDialects'];
             if (!config?.autoConvertOnSave || !config.targetPlatforms?.length) {
-                return; // Auto-convert disabled or no targets configured
+                return;
             }
             if (!this.SQL || this.SQL.trim().length === 0) {
-                return; // Nothing to convert
+                return;
             }
             const md = this.ProviderToUse;
             const dialects = md.SQLDialects;
-            // Determine source dialect from query's SQLDialectID
             const sourceDialect = this.SQLDialectID
                 ? dialects.find(d => UUIDsEqual(d.ID, this.SQLDialectID))
-                : dialects.find(d => d.PlatformKey === 'sqlserver'); // Default to T-SQL
+                : dialects.find(d => d.PlatformKey === 'sqlserver');
             if (!sourceDialect) {
                 console.warn(`Query "${this.Name}" - Could not determine source dialect, skipping auto-convert`);
                 return;
             }
-            // Process each target platform independently
             for (const targetPlatformKey of config.targetPlatforms) {
-                try {
-                    // Skip if target is same as source
-                    if (targetPlatformKey === sourceDialect.PlatformKey) {
-                        continue;
-                    }
-                    const targetDialect = dialects.find(d => d.PlatformKey === targetPlatformKey);
-                    if (!targetDialect) {
-                        console.warn(`Query "${this.Name}" - Target dialect "${targetPlatformKey}" not found, skipping`);
-                        continue;
-                    }
-                    // Currently only T-SQL → PostgreSQL is supported
-                    if (sourceDialect.PlatformKey !== 'sqlserver' || targetPlatformKey !== 'postgresql') {
-                        console.warn(`Query "${this.Name}" - Conversion from "${sourceDialect.PlatformKey}" to "${targetPlatformKey}" not yet supported`);
-                        continue;
-                    }
-                    const convertedSQL = this.convertTSQLToPostgreSQL(this.SQL);
-                    await this.upsertQuerySQLRecord(targetDialect, convertedSQL, md);
-                }
-                catch (platformError) {
-                    // Per-platform isolation: failing on one target doesn't affect others
-                    console.warn(`Query "${this.Name}" - Auto-convert to "${targetPlatformKey}" failed:`, platformError);
-                }
+                await this.convertToTargetDialect(sourceDialect, targetPlatformKey, md, dialects);
             }
         }
         catch (e) {
-            // Best-effort: never block the save
             console.warn(`Query "${this.Name}" - Auto-convert dialects failed:`, e);
         }
     }
     /**
-     * Converts T-SQL to PostgreSQL using SQLConverter ExpressionHelper transforms.
-     * Applies the standard transform pipeline for statement-level conversions.
+     * Converts and persists SQL for a single target dialect. Logs warnings on skip/failure.
      */
-    convertTSQLToPostgreSQL(sql) {
-        let result = sql;
-        result = removeNPrefix(result);
-        result = convertIdentifiers(result);
-        result = convertCommonFunctions(result);
-        result = convertDateFunctions(result);
-        result = convertCharIndex(result);
-        result = convertStuff(result);
-        result = convertIIF(result);
-        result = convertConvertFunction(result);
-        result = convertCastTypes(result);
-        result = convertTopToLimit(result);
-        result = convertStringConcat(result);
-        result = removeCollate(result);
-        return result;
+    async convertToTargetDialect(sourceDialect, targetPlatformKey, md, dialects) {
+        try {
+            if (targetPlatformKey === sourceDialect.PlatformKey) {
+                return;
+            }
+            const targetDialect = dialects.find(d => d.PlatformKey === targetPlatformKey);
+            if (!targetDialect) {
+                console.warn(`Query "${this.Name}" - Target dialect "${targetPlatformKey}" not found, skipping`);
+                return;
+            }
+            if (sourceDialect.PlatformKey !== 'sqlserver' || targetPlatformKey !== 'postgresql') {
+                console.warn(`Query "${this.Name}" - Conversion from "${sourceDialect.PlatformKey}" to "${targetPlatformKey}" not yet supported`);
+                return;
+            }
+            const convertedSQL = ConvertTSQLToPostgreSQL(this.SQL);
+            await this.upsertQuerySQLRecord(targetDialect, convertedSQL, md);
+        }
+        catch (platformError) {
+            console.warn(`Query "${this.Name}" - Auto-convert to "${targetPlatformKey}" failed:`, platformError);
+        }
     }
     /**
      * Creates or updates a QuerySQL record for the given dialect.
      */
     async upsertQuerySQLRecord(targetDialect, convertedSQL, md) {
         const rv = this.RunViewProviderToUse;
-        // Look for existing QuerySQL record for this query + dialect
         const existingResult = await rv.RunView({
             EntityName: 'MJ: Query SQLs',
             ExtraFilter: `QueryID='${this.ID}' AND SQLDialectID='${targetDialect.ID}'`,
@@ -1288,11 +262,9 @@ let MJQueryEntityServer = class MJQueryEntityServer extends MJQueryEntity {
         }
         let record;
         if (existingResult.Results?.length > 0) {
-            // Update existing
             record = existingResult.Results[0];
         }
         else {
-            // Create new
             record = await md.GetEntityObject('MJ: Query SQLs', this.ContextCurrentUser);
             record.QueryID = this.ID;
             record.SQLDialectID = targetDialect.ID;
@@ -1329,6 +301,7 @@ let MJQueryEntityServer = class MJQueryEntityServer extends MJQueryEntity {
             console.warn(`Query "${this.Name}" - Failed to remove QuerySQL records:`, e);
         }
     }
+    // ─── Load Overrides ──────────────────────────────────────────────────────────
     async Load(ID, EntityRelationshipsToLoad) {
         const result = await super.Load(ID, EntityRelationshipsToLoad);
         await this.RefreshRelatedMetadata(false);
@@ -1339,25 +312,24 @@ let MJQueryEntityServer = class MJQueryEntityServer extends MJQueryEntity {
         await this.RefreshRelatedMetadata(false);
         return result;
     }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- BaseEntity.LoadFromData uses `any` for the data parameter
     async LoadFromData(data, _replaceOldValues) {
         const result = await super.LoadFromData(data, _replaceOldValues);
         await this.RefreshRelatedMetadata(false);
         return result;
     }
+    // ─── Metadata Refresh ────────────────────────────────────────────────────────
     /**
      * Refreshes this record's related metadata from the provider, refreshing
-     * all the way up from the database if refreshFromDB is true, otherwise from
-     * cache.
-     * @param refreshFromDB
+     * all the way up from the database if refreshFromDB is true, otherwise from cache.
      */
     async RefreshRelatedMetadata(refreshFromDB) {
         const md = this.ProviderToUse;
         if (refreshFromDB) {
             const globalMetadataProvider = Metadata.Provider;
-            await globalMetadataProvider.Refresh(md); // we pass in our metadata provider because that is the connection we want to use if we are in the midst of a transaction
+            await globalMetadataProvider.Refresh(md);
             if (globalMetadataProvider !== md) {
-                // If the global metadata provider is different, we need to refresh it
-                await md.Refresh(); // will refresh FROM the global provider, meaning we do NOT hit the DB again, we just copy the data into our MD instance that is part of our trans scope
+                await md.Refresh();
             }
         }
         this._queryPermissions = md.QueryPermissions.filter(p => UUIDsEqual(p.QueryID, this.ID));