fix(plan): bind CTEs lazily in declaration scope (#26035)

## What type of PR is this?

- [ ] API-change
- [x] BUG
- [ ] Improvement
- [ ] Documentation
- [ ] Feature
- [ ] Test and CI
- [ ] Code Refactoring

## Which issue(s) this PR fixes:

issue #26015
issue #26022

## What this PR does / why we need it:

`preprocessCte` eagerly bound every CTE declaration, then the
table-resolution path bound a referenced CTE again. This rejected errors
inside unused CTEs and mutated a shared ROLLUP AST twice, expanding a
one-column ROLLUP into three aggregate branches with a duplicated grand
total.

Removing the eager bind alone would let a CTE incorrectly capture tables
introduced by the declaring query block's FROM clause. This change
records a declaration-scoped binding context for each CTE: it excludes
that query block's later/current FROM bindings while preserving
legitimate outer correlation, visible CTE definitions, masking,
recursive state, default database, snapshot, rewrite, and view lineage.
CTE bodies are then bound lazily from that scope. View dependencies
discovered through the detached scope are forwarded to the root query
owner.

This PR fixes the duplicate-grand-total root cause of #26022. Its
independent synthetic-ROLLUP-key predicate-pushdown bug is intentionally
handled in a separate PR.

## Test

- Focused RED/GREEN `TestCTELazyBinding*` planner regressions
- Existing CTE and ROLLUP planner tests
- Full `pkg/sql/plan` test package
- Focused `-race` run
- `go build -mod=readonly ./pkg/sql/plan`
- `go vet -mod=readonly ./pkg/sql/plan`
- `git diff --check`

---------

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
Co-authored-by: XuPeng-SH <xupeng3112@163.com>

Author: 3 people

pkg/sql/plan/bind_context.go

@@ -68,6 +68,22 @@ func NewBindContext(builder *QueryBuilder, parent *BindContext) *BindContext {
 	return bc
 }
 
+// newCTEDeclarationContext records the name-resolution scope at a WITH
+// declaration without retaining bindings that the declaring query block adds
+// later while binding its FROM clause. The normal child-context constructor
+// carries default-database, snapshot, CTE-state, rewrite, and view metadata;
+// detaching the new context from ctx then leaves only the already-existing
+// outer query blocks available for correlation.
+func newCTEDeclarationContext(builder *QueryBuilder, ctx *BindContext) *BindContext {
+	declarationCtx := NewBindContext(builder, ctx)
+	declarationCtx.parent = ctx.parent
+	declarationCtx.cteByName = ctx.cteByName
+	for name, cteRef := range ctx.boundCtes {
+		declarationCtx.boundCtes[name] = cteRef
+	}
+	return declarationCtx
+}
+
 func (bc *BindContext) rootTag() int32 {
 	if bc.bindingRecurCte() && bc.sinkTag > 0 {
 		return bc.sinkTag

pkg/sql/plan/cte_lazy_binding_test.go

@@ -0,0 +1,224 @@
+// Copyright 2026 Matrix Origin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package plan
+
+import (
+	"testing"
+
+	planpb "github.com/matrixorigin/matrixone/pkg/pb/plan"
+	"github.com/matrixorigin/matrixone/pkg/sql/parsers/tree"
+	"github.com/stretchr/testify/require"
+)
+
+type cteViewTrackingContext struct {
+	CompilerContext
+	views []string
+}
+
+func (c *cteViewTrackingContext) GetViews() []string {
+	return c.views
+}
+
+func (c *cteViewTrackingContext) SetViews(views []string) {
+	c.views = append([]string(nil), views...)
+}
+
+type cteViewTrackingOptimizer struct {
+	ctx CompilerContext
+}
+
+func (o *cteViewTrackingOptimizer) CurrentContext() CompilerContext {
+	return o.ctx
+}
+
+func (o *cteViewTrackingOptimizer) Optimize(stmt tree.Statement) (*Query, error) {
+	logicPlan, err := BuildPlan(o.ctx, stmt, false)
+	if err != nil {
+		return nil, err
+	}
+	return logicPlan.GetQuery(), nil
+}
+
+func collectGroupingFlags(query *Query, rootIDs ...int32) [][]bool {
+	seen := make(map[int32]bool)
+	groupingFlags := make([][]bool, 0)
+	var visit func(int32)
+	visit = func(nodeID int32) {
+		if seen[nodeID] {
+			return
+		}
+		seen[nodeID] = true
+		node := query.Nodes[nodeID]
+		if node.NodeType == planpb.Node_AGG {
+			groupingFlags = append(groupingFlags, append([]bool(nil), node.GroupingFlag...))
+		}
+		for _, childID := range node.Children {
+			visit(childID)
+		}
+	}
+	for _, rootID := range rootIDs {
+		visit(rootID)
+	}
+	return groupingFlags
+}
+
+func requireRepeatedCTEGroupingFlags(t *testing.T, logicPlan *Plan, expected [][]bool) {
+	t.Helper()
+	query := logicPlan.GetQuery()
+	require.NotNil(t, query)
+
+	for _, node := range query.Nodes {
+		if node.NodeType != planpb.Node_JOIN || len(node.Children) != 2 {
+			continue
+		}
+		left := collectGroupingFlags(query, node.Children[0])
+		right := collectGroupingFlags(query, node.Children[1])
+		if len(left) == 0 || len(right) == 0 {
+			continue
+		}
+		require.ElementsMatch(t, expected, left, "left CTE consumer grouping variants")
+		require.ElementsMatch(t, expected, right, "right CTE consumer grouping variants")
+		return
+	}
+	t.Fatal("expected a join with grouping-set CTE consumers on both sides")
+}
+
+func TestCTELazyBindingDeclarationScope(t *testing.T) {
+	mock := NewMockOptimizer(false)
+
+	t.Run("unused invalid body is not bound", func(t *testing.T) {
+		_, err := runOneStmt(mock, t, `
+			with bad as (select missing_column from nation)
+			select 1`)
+		require.NoError(t, err)
+	})
+
+	t.Run("referenced invalid body is bound", func(t *testing.T) {
+		_, err := runOneStmt(mock, t, `
+			with bad as (select missing_column from nation)
+			select * from bad`)
+		require.ErrorContains(t, err, "missing_column")
+	})
+
+	t.Run("body cannot capture declaring block FROM", func(t *testing.T) {
+		_, err := runOneStmt(mock, t, `
+			with qn as (select * from bvt_test2.t2 where t2.b = t3.a)
+			select * from bvt_test2.t3 where exists (select * from qn)`)
+		require.ErrorContains(t, err, "missing FROM-clause entry for table 't3'")
+	})
+
+	t.Run("body can correlate to an outer query block", func(t *testing.T) {
+		_, err := runOneStmt(mock, t, `
+			select (
+				with qn as (select t2.a * t1.a as a from cte_test.t1),
+				     qn2 as (select 3 * a as b from qn)
+				select * from qn2 limit 1
+			)
+			from bvt_test2.t2`)
+		require.NoError(t, err)
+	})
+}
+
+func TestCTELazyBindingRollupSingleExpansion(t *testing.T) {
+	mock := NewMockOptimizer(false)
+	logicPlan, err := runOneStmt(mock, t, `
+		with totals as (
+			select n_regionkey, count(*) as n
+			from nation
+			group by n_regionkey with rollup
+		)
+		select * from totals`)
+	require.NoError(t, err)
+
+	query := logicPlan.GetQuery()
+	require.NotNil(t, query)
+	require.ElementsMatch(t, [][]bool{{true}, {false}}, collectGroupingFlags(query, query.Steps...))
+}
+
+func TestCTELazyBindingRepeatedGroupingSets(t *testing.T) {
+	mock := NewMockOptimizer(false)
+
+	t.Run("rollup keeps both variants for each reference", func(t *testing.T) {
+		logicPlan, err := runOneStmt(mock, t, `
+			with totals as (
+				select n_regionkey, count(*) as n
+				from nation
+				group by n_regionkey with rollup
+			)
+			select *
+			from totals a join totals b on a.n_regionkey = b.n_regionkey`)
+		require.NoError(t, err)
+		requireRepeatedCTEGroupingFlags(t, logicPlan, [][]bool{{true}, {false}})
+	})
+
+	t.Run("cube keeps all variants for each reference", func(t *testing.T) {
+		logicPlan, err := runOneStmt(mock, t, `
+			with totals as (
+				select count(*) as n
+				from nation
+				group by cube(n_regionkey, n_nationkey)
+			)
+			select *
+			from totals a join totals b on a.n = b.n`)
+		require.NoError(t, err)
+		requireRepeatedCTEGroupingFlags(t, logicPlan, [][]bool{
+			{false, false},
+			{true, false},
+			{true, true},
+			{false, true},
+		})
+	})
+}
+
+func TestCTELazyBindingVisibilityGuards(t *testing.T) {
+	mock := NewMockOptimizer(false)
+
+	t.Run("forward reference stays rejected", func(t *testing.T) {
+		_, err := runOneStmt(mock, t, `
+			with qn2 as (select a from qn),
+			     qn as (select a from cte_test.t1)
+			select * from qn2`)
+		require.Error(t, err)
+	})
+
+	t.Run("self reference stays rejected", func(t *testing.T) {
+		_, err := runOneStmt(mock, t, `
+			with qn as (select * from qn)
+			select * from qn`)
+		require.ErrorContains(t, err, "recursive table must be referenced only once")
+	})
+
+	t.Run("recursive reference stays accepted", func(t *testing.T) {
+		_, err := runOneStmt(mock, t, `
+			with recursive c as (
+				select a from cte_test.t1
+				union all
+				select a + 1 from c where a < 3
+			)
+			select * from c`)
+		require.NoError(t, err)
+	})
+}
+
+func TestCTELazyBindingKeepsRootContextOwnership(t *testing.T) {
+	ctx := &cteViewTrackingContext{CompilerContext: NewMockCompilerContext(false)}
+	mock := &cteViewTrackingOptimizer{ctx: ctx}
+
+	_, err := runOneStmt(mock, t, `
+		with qn as (select * from cte_test.v2)
+		select * from qn`)
+	require.NoError(t, err)
+	require.Contains(t, ctx.views, "cte_test#v2")
+}