rawsql-ts 0.26.0 → 0.27.0

package/dist/esm/transformers/ParameterConditionPlacementOptimizer.js

@@ -1,15 +1,13 @@
-import { SubQuerySource, TableSource, WhereClause } from "../models/Clause";
+import { DistinctOn, SubQuerySource, TableSource, WhereClause } from "../models/Clause";
 import { BinarySelectQuery, SimpleSelectQuery } from "../models/SelectQuery";
 import { ArrayExpression, ArrayQueryExpression, BetweenExpression, BinaryExpression, CaseExpression, CastExpression, ColumnReference, FunctionCall, InlineQuery, JsonPredicateExpression, ParameterExpression, ParenExpression, TupleExpression, TypeValue, UnaryExpression, ValueList } from "../models/ValueComponent";
 import { SelectQueryParser } from "../parsers/SelectQueryParser";
 import { ValueParser } from "../parsers/ValueParser";
-import { SqlFormatter } from "./SqlFormatter";
+import { formatSqlComponent, hasSqlComponentFormatOverride } from "./SqlComponentFormatter";
+import { SelectOutputCollector } from "./SelectOutputCollector";
 const SUPPORTED_OPERATORS = new Set(["=", "<>", "!=", "<", "<=", ">", ">=", "like", "ilike", "in"]);
 const VOLATILE_OR_UNSUPPORTED_FUNCTION_REASON = "Condition contains a function call; volatile and expression predicates are not moved in the safe-only implementation.";
 const normalizeIdentifier = (value) => value.trim().toLowerCase();
-const formatSqlComponent = (component) => {
-    return new SqlFormatter().format(component).formattedSql;
-};
 const unwrapParens = (expression) => {
     let candidate = expression;
     while (candidate instanceof ParenExpression) {
@@ -48,8 +46,8 @@ const rebuildWhereWithoutTerms = (query, termsToRemove) => {
     }
     query.whereClause = new WhereClause(rebuilt);
 };
-const cloneValueComponent = (expression) => {
-    return ValueParser.parse(formatSqlComponent(expression));
+const cloneValueComponent = (expression, options) => {
+    return ValueParser.parse(formatSqlComponent(expression, options));
 };
 const cloneColumnReference = (reference) => {
     var _a, _b;
@@ -72,11 +70,12 @@ const appendUnique = (items, value) => {
 export class ParameterConditionPlacementOptimizer {
     plan(input, options = {}) {
         var _a, _b, _c;
-        const parsed = this.parseInput(input);
+        const parsed = this.parseInput(input, options);
         const warnings = [...parsed.warnings];
         const errors = [...parsed.errors];
         if (!parsed.query) {
             return this.buildResult({
+                query: null,
                 sql: parsed.sql,
                 applied: [],
                 skipped: [],
@@ -92,6 +91,7 @@ export class ParameterConditionPlacementOptimizer {
                 message: "Parameter condition placement currently supports only SimpleSelectQuery roots."
             });
             return this.buildResult({
+                query: parsed.query,
                 sql: parsed.sql,
                 applied: [],
                 skipped: [],
@@ -106,40 +106,75 @@ export class ParameterConditionPlacementOptimizer {
         const skipped = [];
         const movedTerms = [];
         for (const term of query.whereClause ? collectTopLevelAndTerms(query.whereClause.condition) : []) {
-            const candidate = this.analyzeCandidate(term);
+            const candidate = this.analyzeCandidate(term, options);
             if (!candidate) {
                 continue;
             }
             if ("code" in candidate) {
-                skipped.push(this.makeSkipped(term, candidate));
+                skipped.push(this.makeSkipped(term, candidate, options));
                 continue;
             }
             const target = this.resolveTarget(query, candidate);
             if ("code" in target) {
-                skipped.push(this.makeSkipped(term, target));
+                skipped.push(this.makeSkipped(term, target, options));
                 continue;
             }
-            const targetColumn = this.resolveTargetColumn(target.query, target.outputColumnName);
-            if ("code" in targetColumn) {
-                skipped.push(this.makeSkipped(term, targetColumn));
-                continue;
+            let appliedReason = "";
+            if (target.kind === "simple") {
+                const targetColumns = this.resolveTargetColumns(query, target.query, candidate.references);
+                if ("code" in targetColumns) {
+                    skipped.push(this.makeSkipped(term, targetColumns, options));
+                    continue;
+                }
+                const placement = this.resolveTargetPlacement(target.query, targetColumns);
+                if ("code" in placement) {
+                    skipped.push(this.makeSkipped(term, placement, options));
+                    continue;
+                }
+                const movedCondition = this.rebaseCondition(candidate.expression, targetColumns, options);
+                target.query.appendWhere(movedCondition);
+                appliedReason = placement.reason;
+            }
+            else {
+                const placements = [];
+                let skip = null;
+                for (const branch of target.branches) {
+                    const placement = this.resolveTargetPlacement(branch.query, branch.targetColumns);
+                    if ("code" in placement) {
+                        skip = placement;
+                        break;
+                    }
+                    placements.push(placement);
+                }
+                if (skip) {
+                    skipped.push(this.makeSkipped(term, skip, options));
+                    continue;
+                }
+                for (const branch of target.branches) {
+                    const movedCondition = this.rebaseCondition(candidate.expression, branch.targetColumns, options);
+                    branch.query.appendWhere(movedCondition);
+                }
+                appliedReason = placements.some(item => /group by/i.test(item.reason))
+                    ? "Condition is distributed to every UNION branch by output column position; grouped branches only receive GROUP BY-key predicates."
+                    : "Condition is distributed to every UNION branch by output column position before unsafe query boundaries.";
             }
-            const movedCondition = this.rebaseCondition(candidate.expression, candidate.column, targetColumn.column);
-            target.query.appendWhere(movedCondition);
             movedTerms.push(term);
             applied.push({
                 kind: "move_condition",
                 conditionSql: candidate.conditionSql,
                 fromScopeId: "scope:root",
                 toScopeId: target.scopeId,
-                reason: "All referenced columns resolve to a single direct upstream output before unsafe query boundaries.",
+                reason: appliedReason,
                 parameterNames: candidate.parameterNames,
-                columnReferences: [columnReferenceText(candidate.column)]
+                columnReferences: candidate.references.map(columnReferenceText)
             });
         }
         rebuildWhereWithoutTerms(query, new Set(movedTerms));
-        const sql = applied.length > 0 ? formatSqlComponent(query) : parsed.sql;
+        const sql = applied.length > 0 || hasSqlComponentFormatOverride(options)
+            ? formatSqlComponent(query, options)
+            : parsed.sql;
         return this.buildResult({
+            query,
             sql,
             applied,
             skipped,
@@ -153,13 +188,22 @@ export class ParameterConditionPlacementOptimizer {
         var _a;
         return this.plan(input, Object.assign(Object.assign({}, options), { dryRun: (_a = options.dryRun) !== null && _a !== void 0 ? _a : false }));
     }
-    parseInput(input) {
+    parseInput(input, options) {
         const warnings = [];
         const errors = [];
         try {
             const sourceSql = typeof input === "string"
                 ? input
-                : formatSqlComponent(input);
+                : formatSqlComponent(input, options);
+            if (typeof input !== "string" && options.cloneInput === false) {
+                return {
+                    query: input,
+                    sql: sourceSql,
+                    formatterGeneratedSource: false,
+                    warnings,
+                    errors
+                };
+            }
             if (typeof input !== "string") {
                 warnings.push({
                     code: "AST_INPUT_FORMATTED",
@@ -190,7 +234,7 @@ export class ParameterConditionPlacementOptimizer {
             };
         }
     }
-    analyzeCandidate(expression) {
+    analyzeCandidate(expression, options) {
         const parameterNames = this.collectParameterNames(expression);
         if (parameterNames.length === 0) {
             return null;
@@ -199,40 +243,22 @@ export class ParameterConditionPlacementOptimizer {
         if (unsupported) {
             return unsupported;
         }
-        const candidate = unwrapParens(expression);
-        if (!(candidate instanceof BinaryExpression)) {
-            return {
-                code: "UNSUPPORTED_PARAMETER_CONDITION",
-                reason: "Only simple binary parameter predicates are moved in the safe-only implementation."
-            };
-        }
-        const operator = candidate.operator.value.trim().toLowerCase();
-        if (!SUPPORTED_OPERATORS.has(operator)) {
-            return {
-                code: "UNSUPPORTED_OPERATOR",
-                reason: `Operator '${candidate.operator.value}' is not supported for safe-only parameter condition placement.`
-            };
-        }
         const columnReferences = this.collectColumnReferences(expression);
-        if (columnReferences.length !== 1) {
+        if (columnReferences.length === 0) {
             return {
                 code: "AMBIGUOUS_COLUMN_REFERENCE",
-                reason: columnReferences.length === 0
-                    ? "Parameter condition has no column reference to anchor the move."
-                    : "Parameter condition references multiple columns; moving it may change semantics."
+                reason: "Parameter condition has no column reference to anchor the move."
             };
         }
-        if (operator === "in" && !this.isSupportedInPredicate(candidate)) {
-            return {
-                code: "UNSUPPORTED_IN_PREDICATE",
-                reason: "Only simple column IN (:parameter) predicates are moved in the safe-only implementation."
-            };
+        const unsupportedShape = this.findUnsupportedParameterPredicateShape(expression);
+        if (unsupportedShape) {
+            return unsupportedShape;
         }
         return {
             expression,
-            conditionSql: formatSqlComponent(expression),
+            conditionSql: formatSqlComponent(expression, options),
             parameterNames,
-            column: columnReferences[0]
+            references: columnReferences
         };
     }
     findUnsupportedExpression(expression) {
@@ -243,13 +269,6 @@ export class ParameterConditionPlacementOptimizer {
             }
             const candidate = unwrapParens(value);
             if (candidate instanceof BinaryExpression) {
-                if (candidate.operator.value.trim().toLowerCase() === "or") {
-                    found = {
-                        code: "OR_PREDICATE_UNSUPPORTED",
-                        reason: "Condition contains OR predicates, which are not moved in the first safe-only implementation."
-                    };
-                    return;
-                }
                 visit(candidate.left);
                 visit(candidate.right);
                 return;
@@ -275,13 +294,6 @@ export class ParameterConditionPlacementOptimizer {
                 };
                 return;
             }
-            if (candidate instanceof BetweenExpression) {
-                found = {
-                    code: "BETWEEN_PREDICATE_UNSUPPORTED",
-                    reason: "BETWEEN predicates are not moved in the first safe-only implementation."
-                };
-                return;
-            }
             if (candidate instanceof UnaryExpression) {
                 visit(candidate.expression);
                 return;
@@ -313,6 +325,39 @@ export class ParameterConditionPlacementOptimizer {
         visit(expression);
         return found;
     }
+    findUnsupportedParameterPredicateShape(expression) {
+        const visit = (value) => {
+            var _a;
+            const candidate = unwrapParens(value);
+            if (candidate instanceof BetweenExpression) {
+                return null;
+            }
+            if (candidate instanceof BinaryExpression) {
+                const operator = candidate.operator.value.trim().toLowerCase();
+                if (operator === "and" || operator === "or") {
+                    return (_a = visit(candidate.left)) !== null && _a !== void 0 ? _a : visit(candidate.right);
+                }
+                if (!SUPPORTED_OPERATORS.has(operator)) {
+                    return {
+                        code: "UNSUPPORTED_OPERATOR",
+                        reason: `Operator '${candidate.operator.value}' is not supported for safe-only parameter condition placement.`
+                    };
+                }
+                if (operator === "in" && !this.isSupportedInPredicate(candidate)) {
+                    return {
+                        code: "UNSUPPORTED_IN_PREDICATE",
+                        reason: "Only simple column IN (:parameter) predicates are moved in the safe-only implementation."
+                    };
+                }
+                return null;
+            }
+            return {
+                code: "UNSUPPORTED_PARAMETER_CONDITION",
+                reason: "Only simple binary, BETWEEN, and whole OR/AND parameter predicates are moved in the safe-only implementation."
+            };
+        };
+        return visit(expression);
+    }
     isSupportedInPredicate(expression) {
         const left = unwrapParens(expression.left);
         const right = unwrapParens(expression.right);
@@ -329,7 +374,7 @@ export class ParameterConditionPlacementOptimizer {
             && right.values.every(value => unwrapParens(value) instanceof ParameterExpression);
     }
     resolveTarget(root, candidate) {
-        const boundary = this.findCurrentQueryBoundary(root);
+        const boundary = this.findRootQueryBoundary(root);
         if (boundary) {
             return boundary;
         }
@@ -339,35 +384,38 @@ export class ParameterConditionPlacementOptimizer {
                 reason: "Condition has no FROM source that can receive the predicate safely."
             };
         }
-        const bindingResult = this.resolveSourceBinding(root, candidate.column);
-        if ("code" in bindingResult) {
-            return bindingResult;
+        const bindings = [];
+        for (const reference of candidate.references) {
+            const binding = this.resolveSourceBinding(root, root, reference);
+            if ("code" in binding) {
+                return binding;
+            }
+            if (!bindings.some(item => item.source === binding.source)) {
+                bindings.push(binding);
+            }
+        }
+        if (bindings.length !== 1) {
+            return {
+                code: "MULTIPLE_SOURCE_REFERENCES",
+                reason: "Parameter condition references multiple source query blocks; moving it may change semantics."
+            };
         }
-        const nullableSide = this.findNullableSideBoundary(root.fromClause, bindingResult);
+        const binding = bindings[0];
+        const nullableSide = this.findNullableSideBoundary(root.fromClause, binding);
         if (nullableSide) {
             return nullableSide;
         }
-        const upstream = this.resolveUpstreamQuery(root, bindingResult, candidate.column.column.name);
+        const upstream = this.resolveUpstreamQuery(root, binding, candidate.references);
         if ("code" in upstream) {
             return upstream;
         }
-        const targetBoundary = this.findTargetQueryBoundary(upstream.query);
-        if (targetBoundary) {
-            return targetBoundary;
-        }
         return upstream;
     }
-    findCurrentQueryBoundary(query) {
-        if (query.selectClause.distinct) {
+    findRootQueryBoundary(query) {
+        if (this.hasDistinctOnBoundary(query)) {
             return {
                 code: "DISTINCT_BOUNDARY",
-                reason: "Condition crosses DISTINCT boundary; moving it may change semantics."
-            };
-        }
-        if (query.groupByClause || query.havingClause) {
-            return {
-                code: "GROUP_BY_BOUNDARY",
-                reason: "Condition crosses GROUP BY boundary; moving it may change semantics."
+                reason: "Condition crosses DISTINCT ON boundary; moving it may change semantics."
             };
         }
         if (this.hasWindowUsage(query)) {
@@ -378,10 +426,19 @@ export class ParameterConditionPlacementOptimizer {
         }
         return null;
     }
-    findTargetQueryBoundary(query) {
-        const commonBoundary = this.findCurrentQueryBoundary(query);
-        if (commonBoundary) {
-            return commonBoundary;
+    resolveTargetPlacement(query, targetColumns) {
+        const hasOrdinaryDistinct = this.hasOrdinaryDistinct(query);
+        if (this.hasDistinctOnBoundary(query)) {
+            return {
+                code: "DISTINCT_BOUNDARY",
+                reason: "Condition crosses DISTINCT ON boundary; moving it may change semantics."
+            };
+        }
+        if (this.hasWindowUsage(query)) {
+            return {
+                code: "WINDOW_BOUNDARY",
+                reason: "Condition crosses WINDOW boundary; moving it may change semantics."
+            };
         }
         if (query.limitClause || query.offsetClause || query.fetchClause) {
             return {
@@ -395,10 +452,35 @@ export class ParameterConditionPlacementOptimizer {
                 reason: "Target query contains an OUTER JOIN boundary that is not moved across in the safe-only implementation."
             };
         }
-        return null;
+        if (query.groupByClause) {
+            const allReferencesAreGroupKeys = targetColumns.every(item => this.isGroupKeyColumn(query, item.targetColumn));
+            if (!allReferencesAreGroupKeys) {
+                return {
+                    code: "GROUP_BY_BOUNDARY",
+                    reason: "Condition references a target column that is not proven to be a GROUP BY key."
+                };
+            }
+            return {
+                reason: "Condition references only GROUP BY keys; it is moved into pre-aggregation WHERE."
+            };
+        }
+        if (query.havingClause) {
+            return {
+                code: "GROUP_BY_BOUNDARY",
+                reason: "Condition crosses HAVING aggregation boundary; moving it may change semantics."
+            };
+        }
+        if (hasOrdinaryDistinct) {
+            return {
+                reason: "Condition references a direct ordinary DISTINCT output column; it is moved into the DISTINCT input WHERE."
+            };
+        }
+        return {
+            reason: "All referenced columns resolve to a single direct upstream output before unsafe query boundaries."
+        };
     }
-    resolveSourceBinding(root, column) {
-        const fromClause = root.fromClause;
+    resolveSourceBinding(contextRoot, query, column) {
+        const fromClause = query.fromClause;
         if (!fromClause) {
             return {
                 code: "NO_FROM_CLAUSE",
@@ -416,10 +498,7 @@ export class ParameterConditionPlacementOptimizer {
                     reason: `Column source alias '${column.getNamespace()}' is not uniquely resolvable.`
                 };
             }
-            if (this.resolveSourceQueryForColumns(root, matches[0].source) instanceof BinarySelectQuery) {
-                return matches[0];
-            }
-            const matchCount = this.getOutputColumnMatchCount(root, matches[0], columnName);
+            const matchCount = this.getOutputColumnMatchCount(contextRoot, matches[0], columnName);
             if (matchCount === 0) {
                 return {
                     code: "COLUMN_NOT_AVAILABLE_UPSTREAM",
@@ -435,13 +514,8 @@ export class ParameterConditionPlacementOptimizer {
             return matches[0];
         }
         const matches = [];
-        let unionSource = null;
         for (const binding of bindings) {
-            if (this.resolveSourceQueryForColumns(root, binding.source) instanceof BinarySelectQuery) {
-                unionSource !== null && unionSource !== void 0 ? unionSource : (unionSource = binding);
-                continue;
-            }
-            const matchCount = this.getOutputColumnMatchCount(root, binding, columnName);
+            const matchCount = this.getOutputColumnMatchCount(contextRoot, binding, columnName);
             if (matchCount > 1) {
                 return {
                     code: "AMBIGUOUS_COLUMN_REFERENCE",
@@ -452,12 +526,6 @@ export class ParameterConditionPlacementOptimizer {
                 matches.push(binding);
             }
         }
-        if (matches.length === 0 && unionSource) {
-            return {
-                code: "UNION_BOUNDARY",
-                reason: "Condition would need distribution into a UNION branch, which is unsupported."
-            };
-        }
         if (matches.length !== 1) {
             return {
                 code: "AMBIGUOUS_COLUMN_REFERENCE",
@@ -468,17 +536,20 @@ export class ParameterConditionPlacementOptimizer {
         }
         return matches[0];
     }
-    resolveUpstreamQuery(root, binding, outputColumnName) {
+    resolveUpstreamQuery(root, binding, references) {
         const source = binding.source.datasource;
         if (source instanceof SubQuerySource) {
             if (source.query instanceof SimpleSelectQuery) {
                 return {
+                    kind: "simple",
                     query: source.query,
                     scopeId: `subquery:${binding.alias}`,
-                    outputColumnName,
                     sourceBinding: binding
                 };
             }
+            if (source.query instanceof BinarySelectQuery) {
+                return this.resolveUnionTarget(root, source.query, `subquery:${binding.alias}`, references);
+            }
             return {
                 code: "UNION_BOUNDARY",
                 reason: "Condition would need distribution into a UNION or non-simple subquery, which is unsupported."
@@ -506,10 +577,7 @@ export class ParameterConditionPlacementOptimizer {
             };
         }
         if (commonTable.query instanceof BinarySelectQuery) {
-            return {
-                code: "UNION_BOUNDARY",
-                reason: "Condition would need distribution into a UNION branch, which is unsupported."
-            };
+            return this.resolveUnionTarget(root, commonTable.query, `cte:${commonTable.getSourceAliasName()}`, references);
         }
         if (!(commonTable.query instanceof SimpleSelectQuery)) {
             return {
@@ -518,35 +586,140 @@ export class ParameterConditionPlacementOptimizer {
             };
         }
         return {
+            kind: "simple",
             query: commonTable.query,
             scopeId: `cte:${commonTable.getSourceAliasName()}`,
-            outputColumnName,
             sourceBinding: binding,
             cteName: commonTable.getSourceAliasName()
         };
     }
-    resolveTargetColumn(query, outputColumnName) {
-        const matches = query.selectClause.items.filter(item => { var _a; return normalizeIdentifier((_a = this.getSelectItemOutputName(item)) !== null && _a !== void 0 ? _a : "") === normalizeIdentifier(outputColumnName); });
-        if (matches.length !== 1) {
+    resolveUnionTarget(root, query, scopeId, references) {
+        const branches = this.collectUnionBranches(query);
+        if ("code" in branches) {
+            return branches;
+        }
+        const outputIndexes = new Map();
+        for (const reference of references) {
+            const outputIndex = this.resolveUnionOutputIndex(root, branches[0], reference.column.name);
+            if ("code" in outputIndex) {
+                return outputIndex;
+            }
+            outputIndexes.set(reference, outputIndex.index);
+        }
+        const branchTargets = [];
+        for (const branch of branches) {
+            const targetColumns = [];
+            for (const [reference, outputIndex] of outputIndexes.entries()) {
+                const targetColumn = this.resolveTargetColumnByOutputIndex(root, branch, outputIndex, reference);
+                if ("code" in targetColumn) {
+                    return targetColumn;
+                }
+                targetColumns.push(targetColumn);
+            }
+            branchTargets.push(this.resolveDeepestBranchTarget(root, branch, targetColumns));
+        }
+        return {
+            kind: "union",
+            scopeId,
+            branches: branchTargets
+        };
+    }
+    resolveTargetColumns(root, query, references) {
+        const resolved = [];
+        for (const reference of references) {
+            const matches = this.collectSelectOutputs(root, query).filter(item => normalizeIdentifier(item.name) === normalizeIdentifier(reference.column.name));
+            if (matches.length !== 1) {
+                return {
+                    code: "AMBIGUOUS_TARGET_COLUMN",
+                    reason: matches.length === 0
+                        ? `Target query does not expose '${reference.column.name}' as a direct output column.`
+                        : `Target query exposes multiple '${reference.column.name}' columns.`
+                };
+            }
+            const value = matches[0].value;
+            if (!(value instanceof ColumnReference)) {
+                return {
+                    code: "EXPRESSION_OUTPUT_UNSUPPORTED",
+                    reason: `Target output '${reference.column.name}' is an expression, not a direct column reference.`
+                };
+            }
+            const sourceResolution = this.verifyColumnResolvableInQuery(query, value);
+            if (sourceResolution) {
+                return sourceResolution;
+            }
+            resolved.push({
+                sourceColumn: reference,
+                targetColumn: value
+            });
+        }
+        return resolved;
+    }
+    resolveTargetColumnByOutputIndex(root, query, outputIndex, sourceColumn) {
+        const output = this.collectSelectOutputs(root, query)[outputIndex];
+        if (!output) {
             return {
-                code: "AMBIGUOUS_TARGET_COLUMN",
-                reason: matches.length === 0
-                    ? `Target query does not expose '${outputColumnName}' as a direct output column.`
-                    : `Target query exposes multiple '${outputColumnName}' columns.`
+                code: "UNION_COLUMN_MISMATCH",
+                reason: `UNION branch does not expose column '${sourceColumn.column.name}' at output position ${outputIndex + 1}.`
             };
         }
-        const value = matches[0].value;
-        if (!(value instanceof ColumnReference)) {
+        if (!(output.value instanceof ColumnReference)) {
             return {
                 code: "EXPRESSION_OUTPUT_UNSUPPORTED",
-                reason: `Target output '${outputColumnName}' is an expression, not a direct column reference.`
+                reason: `UNION branch output at position ${outputIndex + 1} for '${sourceColumn.column.name}' is an expression, not a direct column reference.`
             };
         }
-        const sourceResolution = this.verifyColumnResolvableInQuery(query, value);
+        const sourceResolution = this.verifyColumnResolvableInQuery(query, output.value);
         if (sourceResolution) {
             return sourceResolution;
         }
-        return { column: value };
+        return {
+            sourceColumn,
+            targetColumn: output.value
+        };
+    }
+    resolveDeepestBranchTarget(contextRoot, query, targetColumns, visited = new Set()) {
+        if (visited.has(query) || targetColumns.length === 0) {
+            return { query, targetColumns: [...targetColumns] };
+        }
+        const nextVisited = new Set(visited);
+        nextVisited.add(query);
+        const bindings = [];
+        for (const item of targetColumns) {
+            const binding = this.resolveSourceBinding(contextRoot, query, item.targetColumn);
+            if ("code" in binding) {
+                return { query, targetColumns: [...targetColumns] };
+            }
+            if (!bindings.some(existing => existing.source === binding.source)) {
+                bindings.push(binding);
+            }
+        }
+        if (bindings.length !== 1) {
+            return { query, targetColumns: [...targetColumns] };
+        }
+        const binding = bindings[0];
+        const nullableSide = query.fromClause
+            ? this.findNullableSideBoundary(query.fromClause, binding)
+            : null;
+        if (nullableSide) {
+            return { query, targetColumns: [...targetColumns] };
+        }
+        const upstream = this.resolveUpstreamQuery(contextRoot, binding, targetColumns.map(item => item.targetColumn));
+        if ("code" in upstream || upstream.kind === "union") {
+            return { query, targetColumns: [...targetColumns] };
+        }
+        const upstreamColumns = this.resolveTargetColumns(contextRoot, upstream.query, targetColumns.map(item => item.targetColumn));
+        if ("code" in upstreamColumns) {
+            return { query, targetColumns: [...targetColumns] };
+        }
+        const placement = this.resolveTargetPlacement(upstream.query, upstreamColumns);
+        if ("code" in placement) {
+            return { query, targetColumns: [...targetColumns] };
+        }
+        const rebasedColumns = upstreamColumns.map((item, index) => ({
+            sourceColumn: targetColumns[index].sourceColumn,
+            targetColumn: item.targetColumn
+        }));
+        return this.resolveDeepestBranchTarget(contextRoot, upstream.query, rebasedColumns, nextVisited);
     }
     verifyColumnResolvableInQuery(query, column) {
         if (!query.fromClause) {
@@ -574,13 +747,47 @@ export class ParameterConditionPlacementOptimizer {
             reason: `Unqualified target column '${column.column.name}' is ambiguous in a multi-source destination query.`
         };
     }
-    rebaseCondition(expression, sourceColumn, targetColumn) {
-        const cloned = cloneValueComponent(expression);
+    isGroupKeyColumn(query, column) {
+        const groupBy = query.groupByClause;
+        if (!groupBy || groupBy.mode || groupBy.grouping.length === 0) {
+            return false;
+        }
+        return groupBy.grouping.some(grouping => {
+            const candidate = unwrapParens(grouping);
+            return candidate instanceof ColumnReference
+                && this.sameResolvableColumnInQuery(query, candidate, column);
+        });
+    }
+    sameResolvableColumnInQuery(query, left, right) {
+        if (sameColumnReference(left, right)) {
+            return true;
+        }
+        if (normalizeIdentifier(left.column.name) !== normalizeIdentifier(right.column.name)) {
+            return false;
+        }
+        const leftSource = this.resolveColumnSourceAlias(query, left);
+        const rightSource = this.resolveColumnSourceAlias(query, right);
+        return leftSource !== null && leftSource === rightSource;
+    }
+    resolveColumnSourceAlias(query, column) {
+        if (!query.fromClause) {
+            return null;
+        }
+        const bindings = this.getSourceBindings(query.fromClause);
+        const namespace = normalizeIdentifier(column.getNamespace());
+        if (namespace) {
+            const matches = bindings.filter(binding => normalizeIdentifier(binding.alias) === namespace);
+            return matches.length === 1 ? normalizeIdentifier(matches[0].alias) : null;
+        }
+        return bindings.length === 1 ? normalizeIdentifier(bindings[0].alias) : null;
+    }
+    rebaseCondition(expression, targetColumns, options) {
+        const cloned = cloneValueComponent(expression, options);
         for (const reference of this.collectColumnReferences(cloned)) {
-            if (!sameColumnReference(reference, sourceColumn)) {
-                continue;
+            const target = targetColumns.find(item => sameColumnReference(reference, item.sourceColumn));
+            if (target) {
+                reference.qualifiedName = cloneColumnReference(target.targetColumn).qualifiedName;
             }
-            reference.qualifiedName = cloneColumnReference(targetColumn).qualifiedName;
         }
         return cloned;
     }
@@ -638,12 +845,80 @@ export class ParameterConditionPlacementOptimizer {
             return joinType.includes("left") || joinType.includes("right") || joinType.includes("full") || joinType.includes("outer");
         });
     }
+    hasDistinctOnBoundary(query) {
+        return query.selectClause.distinct instanceof DistinctOn;
+    }
+    hasOrdinaryDistinct(query) {
+        return query.selectClause.distinct !== null && !this.hasDistinctOnBoundary(query);
+    }
     getOutputColumnMatchCount(root, binding, columnName) {
         const target = this.resolveSourceQueryForColumns(root, binding.source);
-        if (!target || !(target instanceof SimpleSelectQuery)) {
+        if (!target) {
             return 0;
         }
-        return target.selectClause.items.filter(item => { var _a; return normalizeIdentifier((_a = this.getSelectItemOutputName(item)) !== null && _a !== void 0 ? _a : "") === normalizeIdentifier(columnName); }).length;
+        if (target instanceof BinarySelectQuery) {
+            const branches = this.collectUnionBranches(target);
+            if ("code" in branches) {
+                return 0;
+            }
+            return this.collectSelectOutputs(root, branches[0]).filter(item => normalizeIdentifier(item.name) === normalizeIdentifier(columnName)).length;
+        }
+        if (!(target instanceof SimpleSelectQuery)) {
+            return 0;
+        }
+        return this.collectSelectOutputs(root, target).filter(item => normalizeIdentifier(item.name) === normalizeIdentifier(columnName)).length;
+    }
+    collectUnionBranches(query) {
+        const branches = [];
+        const visit = (select) => {
+            var _a;
+            if (select instanceof SimpleSelectQuery) {
+                branches.push(select);
+                return null;
+            }
+            if (!(select instanceof BinarySelectQuery)) {
+                return {
+                    code: "UNION_BOUNDARY",
+                    reason: "Condition would need distribution into a non-simple UNION branch, which is unsupported."
+                };
+            }
+            const operator = select.operator.value.trim().toLowerCase();
+            if (operator !== "union" && operator !== "union all") {
+                return {
+                    code: "UNION_BOUNDARY",
+                    reason: `Condition would need distribution through '${select.operator.value}', which is unsupported.`
+                };
+            }
+            return (_a = visit(select.left)) !== null && _a !== void 0 ? _a : visit(select.right);
+        };
+        const skip = visit(query);
+        return skip !== null && skip !== void 0 ? skip : branches;
+    }
+    resolveUnionOutputIndex(root, firstBranch, outputColumnName) {
+        const matches = [];
+        this.collectSelectOutputs(root, firstBranch).forEach((item, index) => {
+            if (normalizeIdentifier(item.name) === normalizeIdentifier(outputColumnName)) {
+                matches.push(index);
+            }
+        });
+        if (matches.length !== 1) {
+            return {
+                code: "AMBIGUOUS_TARGET_COLUMN",
+                reason: matches.length === 0
+                    ? `UNION output does not expose '${outputColumnName}' from its first branch.`
+                    : `UNION first branch exposes multiple '${outputColumnName}' columns.`
+            };
+        }
+        return { index: matches[0] };
+    }
+    collectSelectOutputs(root, query) {
+        var _a, _b, _c, _d;
+        const commonTables = [
+            ...((_b = (_a = query.withClause) === null || _a === void 0 ? void 0 : _a.tables) !== null && _b !== void 0 ? _b : []),
+            ...((_d = (_c = root.withClause) === null || _c === void 0 ? void 0 : _c.tables) !== null && _d !== void 0 ? _d : [])
+        ];
+        const collector = new SelectOutputCollector(null, commonTables.length > 0 ? commonTables : null);
+        return collector.collect(query);
     }
     resolveSourceQueryForColumns(root, source) {
         var _a;
@@ -658,15 +933,6 @@ export class ParameterConditionPlacementOptimizer {
         }
         return null;
     }
-    getSelectItemOutputName(item) {
-        if (item.identifier) {
-            return item.identifier.name;
-        }
-        if (item.value instanceof ColumnReference) {
-            return item.value.column.name;
-        }
-        return null;
-    }
     findCte(root, name) {
         var _a, _b;
         const normalized = normalizeIdentifier(name);
@@ -912,13 +1178,14 @@ export class ParameterConditionPlacementOptimizer {
         visit(expression);
         return names;
     }
-    makeSkipped(expression, draft) {
-        return Object.assign({ conditionSql: formatSqlComponent(expression), scopeId: "scope:root" }, draft);
+    makeSkipped(expression, draft, options) {
+        return Object.assign({ conditionSql: formatSqlComponent(expression, options), scopeId: "scope:root" }, draft);
     }
     buildResult(params) {
         return {
             ok: params.errors.length === 0,
             sql: params.sql,
+            query: params.query,
             applied: params.applied,
             skipped: params.skipped,
             warnings: params.warnings,