fix: stop claiming a table for columns that resolve to none

[funcpp]

Reconstructed from the second commit of #12 (e8e4790), one of the contributions in #15. Same defect, different fix — see Differences from #12.

Defect

ColumnOrigin::Concrete { table, column } is a claim that the output column really derives from table.column. The resolver emitted it in two places where it had proven nothing, putting an invented name in the table slot:

SELECT bare_col
  bare_col <- Concrete { table: "?unknown?", column: "bare_col" }

WITH cte AS (SELECT present FROM source) SELECT missing FROM cte
  missing  <- Concrete { table: "?cte?", column: "missing" }

Neither name can appear in tables.inputs, so the column graph referenced relations the table graph denied existed. A consumer could not separate proven lineage from a guess without matching those sentinel strings.

A third site already produced the same state under a different spelling: when every binding is a CTE or derived table and none has the column, no physical relation is left to attribute it to, and the result was Ambiguous with an empty candidate list.

WITH a AS (SELECT p FROM s1), b AS (SELECT q FROM s2)
SELECT missing FROM a JOIN b ON a.p = b.q      -- Ambiguous { candidates: [] }

Fix

All three sites now produce ColumnOrigin::Unresolved { column }, leaving each variant with exactly one meaning:

Variant	Meaning
Concrete	Proven to come from this table
Ambiguous	A real choice between at least two known relations
Unresolved	Neither — no relation to name

Both invariants are documented on the type and on CatalogProvider::resolve_column.

apply_catalog needs no change. It refines Ambiguous, and Unresolved is not Ambiguous, so a provider that resolves a column by name alone cannot turn an unresolved origin back into a fabricated concrete one. The bug is unrepresentable rather than guarded against.

Differences from #12

#12 reused Ambiguous { candidates: [] } for the two fabrication sites.

• Distinct variant instead of an overloaded one. Ambiguous's doc had to grow a second meaning ("non-empty means genuine ambiguity, empty means unresolved"), and every consumer asking "is this proven?" had to write matches!(o, Ambiguous { candidates, .. } if candidates.is_empty()). This matters per-source, not per-mapping — a set operation mixes both in one mapping:

  SELECT a FROM t UNION ALL SELECT bare
    a <- [Concrete { t.a }, Unresolved { bare }]
  

• No apply_catalog guard. fix: two column lineage correctness bugs (nondeterministic ordering, fabricated origins) #12 had to add && !candidates.is_empty(), described there as load-bearing. It is load-bearing — but only because the two meanings shared a variant. With a distinct variant the guard has nothing to guard.
• Third site included. fix: two column lineage correctness bugs (nondeterministic ordering, fabricated origins) #12 converges two sites onto the third's accidental spelling; this converges all three onto an explicit one, which is what lets Ambiguous mean one thing.
• Not #[non_exhaustive]. ColumnOrigin encodes how much was proven. A consumer that silently ignores a new resolution state is the failure the enum exists to prevent, so a new variant should break their build — the same rule ARCHITECTURE.md already states for sqlparser AST variants. This is why the CLI and the PyO3 bridge had to be updated here instead of falling through a wildcard arm. (Note: feat: expose lineage uncertainty and expand dialects #16 marks ColumnOrigin non-exhaustive; that decision should be revisited when feat: expose lineage uncertainty and expand dialects #16 is reconstructed.)
• Dialect is #[non_exhaustive] (feat: support every dialect sqlparser exposes #18). The asymmetry is deliberate: Dialect is an input consumers construct, ColumnOrigin is an output they branch on.

Surfaces

CLI now distinguishes the two states it previously merged:

SELECT bare_col                       bare_col ← <unresolved:bare_col>
SELECT x FROM a JOIN b ON a.id=b.id   x        ← ?x?
SELECT a FROM t UNION ALL SELECT bare a        ← t.a, <unresolved:bare>

Python gains kind == "unresolved" with column set (table, candidates, base_sources are None); verified against a built wheel.

Known limitation, pinned by a test

A column hidden behind an unexpanded SELECT * inside a CTE or derived table also reads as Unresolved:

WITH cte AS (SELECT * FROM t) SELECT p FROM cte   -- Unresolved { p }
SELECT p FROM (SELECT * FROM t) d                 -- Unresolved { p }

The relation is known and p very likely exists — the star just was not expanded, and a catalog listing t's columns does not help here either. Honest but coarse. Naming it needs an origin that can carry a relation (#16's NamedWildcard), so column_behind_an_unexpanded_star_is_unresolved pins today's behavior to make that change visible when it lands.

Tests

6 new, 99 total. The three sites, the mixed-source case, the star limitation, and both sides of the catalog boundary (an unresolved column stays unresolved; genuine ambiguity is still resolved).

cargo fmt --all --check                                           exit 0
cargo clippy --workspace --all-targets --all-features -D warnings exit 0
cargo test --workspace --all-features                             exit 0

Compatibility

Breaking: new ColumnOrigin variant, and previously-Concrete origins for unresolved columns change shape. 0.3.0, alongside the Dialect variants from #18.

🤖 Generated with Claude Code