feat(specializer): SELECT * star expansion — corpus 53 -> 172 match (TASK-46)

Binder::expand_star at the single projection site: plain * and tbl.*
in measured DuckDB order (FROM order, declared column order), EXCLUDE
in bare/paren forms case-insensitively with DuckDB-mirrored binder
errors, mixed *,expr items via item-position expansion. Star over a
joined static table rejects cleanly naming the join key (DuckDB
includes the key and emits duplicate output names there — both
unrepresentable in the typed output model); __THIS__.* under a join
works. ILIKE/EXCEPT/REPLACE/RENAME/COLUMNS() reject by name.
Corpus replay: 53 -> 172 match of 678 (+119), zero FAILs. Gate green
(cargo 129, pytest 627).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: 2 people

backlog/tasks/task-46 - Specializer-SQL-support-SELECT-star-expansion.md

@@ -1,9 +1,10 @@
 ---
 id: TASK-46
 title: 'Specializer SQL support: SELECT * star expansion'
-status: To Do
+status: In Progress
 assignee: []
 created_date: '2026-07-26 11:42'
+updated_date: '2026-07-26 11:55'
 labels: []
 milestone: m-7
 dependencies:
@@ -22,8 +23,26 @@ The single biggest corpus rung: 128 of 625 clean-unsupported corpus cases have `
 
 ## Acceptance Criteria
 <!-- AC:BEGIN -->
-- [ ] #1 Star semantics pinned by measurement against DuckDB 1.5.5 (column order, duplicate-name policy, qualified tbl.*, modifier handling) and recorded as duck_check tests
-- [ ] #2 Corpus replay: star-first-blocker cases flip to match or to a NAMED deeper blocker; zero FAILs; match count and the new first-blocker tally recorded here
-- [ ] #3 Unsupported star forms (if any remain) reject with a clean "unsupported: ..." naming the form
-- [ ] #4 mise gate-specializer green
+- [x] #1 Star semantics pinned by measurement against DuckDB 1.5.5 (column order, duplicate-name policy, qualified tbl.*, modifier handling) and recorded as duck_check tests
+- [x] #2 Corpus replay: star-first-blocker cases flip to match or to a NAMED deeper blocker; zero FAILs; match count and the new first-blocker tally recorded here
+- [x] #3 Unsupported star forms (if any remain) reject with a clean "unsupported: ..." naming the form
+- [x] #4 mise gate-specializer green
 <!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+Stretch plan (recorded 2026-07-26 after the measurement spike; all facts below are measured on DuckDB 1.5.5).
+Corpus star census: 156 plain `SELECT *`, 26 `tbl.*`, 16 `* EXCLUDE`, 13 `COLUMNS(...)`, 3 `* LIKE`, 2 `* REPLACE`, 2 mixed. Wave scope: plain `*`, `tbl.*`, `EXCLUDE` (~198 mentions); COLUMNS()/REPLACE/LIKE/RENAME/EXCEPT/ILIKE reject by name. All forms already parse under sqlparser 0.62 and funnel to the single rejection at frontend.rs:125 — one expansion site.
+Measured pins: expansion order is FROM order then declared column order per table; `SELECT * FROM a JOIN b ON a.k=b.k` emits DUPLICATE column names ('k','x','k','y') — unrepresentable in a pydantic output model, and any star item covering a joined static table necessarily includes its join-key column, whose projection our engine already cleanly rejects; therefore star items that cover a static table reject cleanly naming the key column (covers the duplicate-name shape too). `__THIS__.*` under a join is fine (row columns only). EXCLUDE: paren and bare forms; case-insensitive; unknown name = binder error mirroring DuckDB ("Column \"nope\" in EXCLUDE list not found"); duplicate list entry = error ("Duplicate entry"); unqualified EXCLUDE removes every same-named column.
+1. Binder::expand_star(qualifier, options) -> Vec<(name, SExpr)> using the existing SKind::Col / static_lane constructors; wire into the projection loop (mixed `*, expr` items fall out of item-position expansion); existing duplicate-output-name check stays as the final guard.
+2. duck_check pins for every measured behavior above incl. the EXCLUDE edges (exclude-all, EXCLUDE K case-folding) and clean-unsupported messages for the rejected forms.
+3. Corpus replay re-tally into this ticket (AC #2): flips + newly-surfaced second blockers.
+4. Gate green.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Landed in one pass: Binder::expand_star (frontend.rs) expands `*` and `tbl.*` at the single projection site using the existing SKind::Col / static_lane constructors — no IR/backend/boundary changes, exactly as scoped. EXCLUDE handles bare + paren forms case-insensitively (sqlparser 0.62 carries entries as ObjectName; single-part idents only, qualified entries reject by name); unknown-column and duplicate-entry EXCLUDE mirror DuckDB's binder errors; exclude-all falls through to the existing empty-SELECT bind error (same shape as DuckDB's "SELECT list is empty after resolving * expressions"). Star items covering a joined static table reject cleanly naming the join-key column (DuckDB includes the key AND emits duplicate output names there — both unrepresentable; `__THIS__.*` under a join works). ILIKE/EXCEPT/REPLACE/RENAME/COLUMNS() reject by name. CORPUS RESULT (AC #2): 53 -> 172 match of 678 (+119, a 3.2x coverage jump), 0 FAILs, 506 clean-unsupported. New first-blocker head: BETWEEN 31, comma join 30, dynamic-table alias 30, table-function FROM 24, then the builtin catalogue (array_slice 23, contains 18, damerau_levenshtein 17, ...) — the TASK-47 target list confirmed. Gate green: cargo 129 + pytest 627 (13 xfail incl. the pre-existing substr const-fold pin from master).
+<!-- SECTION:NOTES:END -->

src/specializer/frontend.rs

@@ -115,17 +115,11 @@ pub fn frontend(
 
     let mut out_cols = Vec::new();
     let mut exprs = Vec::new();
-    for item in &select.projection {
-        let (name, e) = match item {
-            SelectItem::UnnamedExpr(e) => (default_name(e), fold(binder.expr(e)?)),
-            SelectItem::ExprWithAlias { expr, alias } => {
-                (alias.value.clone(), fold(binder.expr(expr)?))
-            }
-            SelectItem::Wildcard(_) | SelectItem::QualifiedWildcard(..) => {
-                return Err(unsup("SELECT * (star expansion)"))
-            }
-            SelectItem::ExprWithAliases { .. } => return Err(unsup("multi-alias SELECT item")),
-        };
+    let push_item = |out_cols: &mut Vec<Col>,
+                     exprs: &mut Vec<SExpr>,
+                     name: String,
+                     e: SExpr|
+     -> Result<(), PrepareError> {
         if out_cols.iter().any(|c: &Col| c.name == name) {
             // DuckDB allows duplicate output names; our IR requires unique
             // columns. Rare in real queries — punt cleanly for now.
@@ -139,6 +133,40 @@ pub fn frontend(
             },
         });
         exprs.push(e);
+        Ok(())
+    };
+    for item in &select.projection {
+        match item {
+            SelectItem::UnnamedExpr(e) => push_item(
+                &mut out_cols,
+                &mut exprs,
+                default_name(e),
+                fold(binder.expr(e)?),
+            )?,
+            SelectItem::ExprWithAlias { expr, alias } => push_item(
+                &mut out_cols,
+                &mut exprs,
+                alias.value.clone(),
+                fold(binder.expr(expr)?),
+            )?,
+            SelectItem::Wildcard(opts) => {
+                for (name, e) in binder.expand_star(None, opts)? {
+                    push_item(&mut out_cols, &mut exprs, name, e)?;
+                }
+            }
+            SelectItem::QualifiedWildcard(kind, opts) => {
+                let table = match kind {
+                    sqlparser::ast::SelectItemQualifiedWildcardKind::ObjectName(n) => n.to_string(),
+                    sqlparser::ast::SelectItemQualifiedWildcardKind::Expr(_) => {
+                        return Err(unsup("expression.* wildcard"))
+                    }
+                };
+                for (name, e) in binder.expand_star(Some(&table), opts)? {
+                    push_item(&mut out_cols, &mut exprs, name, e)?;
+                }
+            }
+            SelectItem::ExprWithAliases { .. } => return Err(unsup("multi-alias SELECT item")),
+        };
     }
     if exprs.is_empty() {
         return Err(PrepareError::Bind("SELECT list is empty".to_string()));
@@ -450,6 +478,98 @@ struct Binder<'a> {
 }
 
 impl Binder<'_> {
+    /// Expand `*` / `tbl.*` per DuckDB's measured semantics (1.5.5): FROM
+    /// order, declared column order within a table, EXCLUDE filtered
+    /// case-insensitively. A star item covering a joined static table is
+    /// unsupported: DuckDB's expansion includes the join-key column there
+    /// (and emits duplicate output names for the shared key), neither of
+    /// which the engine models — rejected by name, not silently narrowed.
+    fn expand_star(
+        &self,
+        qualifier: Option<&str>,
+        opts: &sqlparser::ast::WildcardAdditionalOptions,
+    ) -> Result<Vec<(String, SExpr)>, PrepareError> {
+        use sqlparser::ast::ExcludeSelectItem;
+        if opts.opt_ilike.is_some() {
+            return Err(unsup("SELECT * ILIKE (COLUMNS filter)"));
+        }
+        if opts.opt_except.is_some() {
+            return Err(unsup("SELECT * EXCEPT"));
+        }
+        if opts.opt_replace.is_some() {
+            return Err(unsup("SELECT * REPLACE"));
+        }
+        if opts.opt_rename.is_some() {
+            return Err(unsup("SELECT * RENAME"));
+        }
+        fn exclude_name(n: &sqlparser::ast::ObjectName) -> Result<&str, PrepareError> {
+            match n.0.as_slice() {
+                [part] => part
+                    .as_ident()
+                    .map(|i| i.value.as_str())
+                    .ok_or_else(|| unsup("EXCLUDE list entry form")),
+                _ => Err(unsup("qualified name in EXCLUDE list")),
+            }
+        }
+        let exclude: Vec<&str> = match &opts.opt_exclude {
+            None => Vec::new(),
+            Some(ExcludeSelectItem::Single(id)) => vec![exclude_name(id)?],
+            Some(ExcludeSelectItem::Multiple(ids)) => ids
+                .iter()
+                .map(exclude_name)
+                .collect::<Result<Vec<_>, _>>()?,
+        };
+        for (i, a) in exclude.iter().enumerate() {
+            if exclude[..i].iter().any(|b| b.eq_ignore_ascii_case(a)) {
+                // DuckDB rejects this at parse; ours surfaces at bind.
+                return Err(PrepareError::Bind(format!(
+                    "duplicate entry \"{a}\" in EXCLUDE list"
+                )));
+            }
+        }
+
+        let mut cols: Vec<(String, SExpr)> = Vec::new();
+        let mut matched = false;
+        if qualifier.is_none_or(|q| q.eq_ignore_ascii_case(&self.this_name)) {
+            matched = true;
+            for (i, c) in self.in_cols.iter().enumerate() {
+                cols.push((
+                    c.name.clone(),
+                    SExpr {
+                        kind: SKind::Col(i as u32),
+                        ty: c.ty.ty,
+                        nullable: c.ty.nullable,
+                    },
+                ));
+            }
+        }
+        for sj in &self.joins {
+            if qualifier.is_none_or(|q| q.eq_ignore_ascii_case(&sj.name)) {
+                let key = &sj.table.cols[sj.key_cols[0] as usize].name;
+                return Err(unsup(format!(
+                    "star expansion over joined table '{}' (includes join key column '{key}')",
+                    sj.name
+                )));
+            }
+        }
+        if !matched {
+            return Err(PrepareError::Bind(format!(
+                "table '{}' in wildcard does not exist in FROM",
+                qualifier.unwrap_or("?")
+            )));
+        }
+
+        for ex in &exclude {
+            if !cols.iter().any(|(n, _)| n.eq_ignore_ascii_case(ex)) {
+                return Err(PrepareError::Bind(format!(
+                    "column \"{ex}\" in EXCLUDE list not found in FROM clause"
+                )));
+            }
+        }
+        cols.retain(|(n, _)| !exclude.iter().any(|ex| ex.eq_ignore_ascii_case(n)));
+        Ok(cols)
+    }
+
     /// Bind an expression that must have a definite type on its own — a bare
     /// NULL literal here is unsupported (no context to type it).
     fn expr(&self, e: &SqlExpr) -> Result<SExpr, PrepareError> {

src/specializer/tests.rs

@@ -397,6 +397,81 @@ fn bool_column_directly_in_where() {
     assert_eq!(got, rows(&[&["1"]]));
 }
 
+#[test]
+fn star_expands_in_declared_order_with_exclude() {
+    let schema = cols(&[
+        ("a", Ty::I64, false),
+        ("b", Ty::F64, true),
+        ("s", Ty::Str, false),
+    ]);
+    let names = |p: &super::ir::Program| {
+        p.out_cols
+            .iter()
+            .map(|c| c.name.clone())
+            .collect::<Vec<_>>()
+    };
+
+    let p = prep("SELECT * FROM __THIS__", &schema).unwrap();
+    assert_eq!(names(&p), ["a", "b", "s"]);
+    // Nullability and types ride along from the input schema.
+    assert!(p.out_cols[1].ty.nullable && p.out_cols[1].ty.ty == Ty::F64);
+
+    // EXCLUDE is case-insensitive (measured: DuckDB drops k for EXCLUDE (K)),
+    // both paren and bare forms; qualified star + mixed items compose.
+    let p = prep("SELECT * EXCLUDE (B) FROM __THIS__", &schema).unwrap();
+    assert_eq!(names(&p), ["a", "s"]);
+    let p = prep("SELECT * EXCLUDE b FROM __THIS__", &schema).unwrap();
+    assert_eq!(names(&p), ["a", "s"]);
+    let p = prep("SELECT __THIS__.*, a + 1 AS a2 FROM __THIS__", &schema).unwrap();
+    assert_eq!(names(&p), ["a", "b", "s", "a2"]);
+
+    // Star + explicit same column: DuckDB-legal duplicate names stay our
+    // clean unsupported (the output model needs unique fields).
+    match prep("SELECT *, a FROM __THIS__", &schema) {
+        Err(PrepareError::Unsupported(m)) => assert!(m.contains("duplicate output column")),
+        other => panic!("wanted duplicate-name unsupported, got {other:?}"),
+    }
+    // EXCLUDE of an unknown column is a bind error, mirroring DuckDB's
+    // binder message.
+    match prep("SELECT * EXCLUDE (nope) FROM __THIS__", &schema) {
+        Err(PrepareError::Bind(m)) => assert!(m.contains("EXCLUDE list not found")),
+        other => panic!("wanted EXCLUDE bind error, got {other:?}"),
+    }
+    // Excluding everything leaves an empty SELECT — bind error like DuckDB.
+    match prep("SELECT * EXCLUDE (a, b, s) FROM __THIS__", &schema) {
+        Err(PrepareError::Bind(m)) => assert!(m.contains("empty")),
+        other => panic!("wanted empty-list bind error, got {other:?}"),
+    }
+}
+
+#[test]
+fn star_over_joined_table_rejects_by_name() {
+    let schema = cols(&[("a", Ty::I64, false)]);
+    let st = stat("dim", &[("id", Ty::I64, false), ("v", Ty::F64, false)]);
+    for sql in [
+        "SELECT * FROM __THIS__ JOIN dim ON a = dim.id",
+        "SELECT dim.* FROM __THIS__ JOIN dim ON a = dim.id",
+    ] {
+        match prepare(sql, "__THIS__", &schema, std::slice::from_ref(&st)) {
+            Err(PrepareError::Unsupported(m)) => assert!(
+                m.contains("star expansion over joined table") && m.contains("id"),
+                "'{sql}': got '{m}'"
+            ),
+            Err(other) => panic!("'{sql}': wrong error kind: {other}"),
+            Ok(_) => panic!("'{sql}': unexpectedly prepared"),
+        }
+    }
+    // Qualified star over the ROW table under a join is fine.
+    let p = prepare(
+        "SELECT __THIS__.*, dim.v AS v FROM __THIS__ JOIN dim ON a = dim.id",
+        "__THIS__",
+        &schema,
+        std::slice::from_ref(&st),
+    )
+    .unwrap();
+    assert_eq!(p.program.out_cols.len(), 2);
+}
+
 #[test]
 fn unsupported_constructs_are_named_cleanly() {
     let schema = cols(&[("a", Ty::I64, false)]);
@@ -407,7 +482,9 @@ fn unsupported_constructs_are_named_cleanly() {
         ("SELECT sum(a) FROM __THIS__", "function sum"),
         ("SELECT a FROM __THIS__ GROUP BY a", "aggregation"),
         ("SELECT length('x') FROM __THIS__", "function"),
-        ("SELECT * FROM __THIS__", "star expansion"),
+        // Star now expands; the still-unsupported star forms reject by name.
+        ("SELECT * REPLACE (a + 1 AS a) FROM __THIS__", "REPLACE"),
+        ("SELECT COLUMNS('a') FROM __THIS__", "function COLUMNS"),
         ("SELECT a FROM __THIS__ ORDER BY a", "ORDER BY"),
         ("SELECT a, a FROM __THIS__", "duplicate output column"),
         ("SELECT NULL FROM __THIS__", "NULL literal"),

tests/test_duckdb_interpreter.py

@@ -543,3 +543,42 @@ def k(self):
     (m,) = fn.infer_rows([Row()])
     assert m.d == 14
     assert inner == [10]  # the nested call completed via the generic path
+
+
+# --------------------------------------------------------- TASK-46:
+# SELECT * star expansion — measured DuckDB 1.5.5 pins (order, EXCLUDE
+# case-folding, mixed items) verified end-to-end against the oracle.
+
+
+def test_star_expansion_matches_duckdb():
+    rows = [
+        {"a": 1, "b": 2.5, "s": "x"},
+        {"a": 2, "b": None, "s": "y"},
+    ]
+    for sql in [
+        "SELECT * FROM __THIS__",
+        "SELECT __THIS__.* FROM __THIS__",
+        "SELECT * EXCLUDE (b) FROM __THIS__",
+        "SELECT * EXCLUDE B FROM __THIS__",  # case-insensitive, bare form
+        "SELECT *, a * 2 AS a2 FROM __THIS__",
+        "SELECT * EXCLUDE (s), upper(s) AS u FROM __THIS__",
+    ]:
+        duck_check(sql, {"a": "int", "b": "float?", "s": "str"}, rows)
+
+
+def test_star_qualified_over_row_table_under_join():
+    duck_check(
+        "SELECT __THIS__.*, dim.name AS nm FROM __THIS__ JOIN dim ON k = dim.id",
+        {"k": "int"},
+        [{"k": 1}, {"k": 2}, {"k": 99}],
+        statics={"dim": DIM},
+    )
+
+
+def test_star_over_joined_table_rejects_by_name():
+    with pytest.raises(ValueError, match="star expansion over joined table"):
+        DuckDBInferFn(
+            "SELECT * FROM __THIS__ JOIN dim ON k = dim.id",
+            row_tables={"__THIS__": _row_model({"k": "int"})},
+            static_tables={"dim": DIM},
+        )