[zzylol]

Summary

Settles the design question raised in #216 ("column index vs column name as ref") by moving its already-conclusive rationale from the issue thread into resolve.rs's module doc, next to the code it explains.

The question: should QueryExpr keep positional ColumnId refs (resolved once by Binder), or could it carry name-based ColumnRefs all the way through, the way DataFusion's own logical plan and Calcite do?

The answer (already worked out in #216, not new analysis): resolving once is the better trade for this codebase's shape — one front-end-facing tree feeding several independent downstream passes (canonicalize, cost model, dag_export, schema/type inference, summary binding). Three reasons, now captured in the doc:

1. Names collide across joins — not hypothetical, backed by the real join_predicate_disambiguates_shared_column_name test.
2. A name's meaning shifts as you go up the tree (Project renames, Aggregate collapses/synthesizes columns, Join concatenates schemas).
3. Resolving once centralizes scoping logic in one place instead of ~6 passes each needing their own qualifier-aware, collision-aware name resolver.

No code change — the conclusion is to keep the current design as-is. This is purely documentation so a future "why not just use names" question finds its answer next to resolve_root instead of requiring someone to dig up issue #216.

Test plan

• cargo build --workspace --all-targets
• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo test -p asap-types --lib

Closes #216

🤖 Generated with Claude Code