Analyzed: one walked AST, structural classification, per-DB cast policy

[wokalski]

Summary

Replaces the EXPLAIN-text classification pipeline with a single colocated Analyzed data structure that merges the SQL parse tree + plan-derived alias nullability + per-DB cast policy into one walked AST. Every downstream pass — verdict, refinement, FULL JOIN row variants, set-op literal unions, codegen — reads the same Expr tree. No substring matching, no parallel HashMap lookups at the call site.

The data structure

struct Analyzed {
    outputs: Vec<Output>,    // one per result column
    params:  Vec<Param>,
}

enum Expr {
    Literal(Lit),                              // value retained for set-op TS literal unions
    Null,
    Cast { inner: Box<Expr> },
    ArrayConstructor,
    Column(ResolvedCol),                       // alias resolved + not_null *already widened* for outer joins
    Func { kind: FuncKind, args: Vec<Expr> },  // FuncKind precomputed: NeverNull / NullableAgg / Other
    Coalesce(Vec<Expr>),
    Case { has_else_non_null: bool },
    SubQuery(Box<Analyzed>),
    SetOp(Vec<Expr>),                          // per-branch lowered expressions
    Unknown,
}

ResolvedCol carries the resolved (schema, table, column), the SQL alias the user wrote (so FULL JOIN row-variant building disambiguates self-joins), and the effective not_null bit. Verdict walks (is_nullable, is_non_null) just read these fields — there are no side lookups.

The merge

Analyzer::analyze:

1. PARSE/DESCRIBE → output types + per-column (table_oid, attnum)
2. EXPLAIN VERBOSE FORMAT JSON → plan walk produces PlanWalk { alias_to_table, nullable_aliases, non_null_aliases, root_full_join }. No Output expression strings are read. Literal-unnest detection runs against the SQL AST's RangeFunction, not against EXPLAIN's "Function Call" text. Subquery Scan passthrough propagates non-null up to the user's alias (so (VALUES …) AS t gets t marked non-null even though the inner Values Scan is named *VALUES*).
3. Per-$N binding (param_nullability::infer) → INSERT VALUES / UPDATE SET column refs.
4. Per-output column metadata (resolve_column_meta) → (table_oid, attnum) → ResolvedBaseCol. One round trip; used as the star-expansion fallback inside build::build.
5. build::build: lowers the SQL AST under a Scope that has alias → ResolvedTable (with attnotnull preloaded in one round-trip) + the plan-derived alias sets + a cast_policy. Set-op queries lower per branch; recursive CTEs use the base case as the floor. Derived tables and CTEs preload their per-column Exprs into Scope::derived so ColumnRef("t", "cnt") against a (SELECT count(*) AS cnt …) t resolves structurally.
6. Verdict + decide_nullability + TS type rendering walks Analyzed.outputs[i].expr.

build::build_full_join_variants reads Expr::Column.alias. infer_setop_literal_union walks Expr::SetOp. refine_to_not_null is gone — is_non_null(Coalesce/SetOp) already does the work.

Per-database cast policy

pg_cast probe at connect time:

SELECT EXISTS (SELECT 1 FROM pg_cast WHERE castmethod = 'f' AND oid >= 16384)

castmethod = 'b' (binary) and 'i' (I/O) are total — they ERROR rather than return NULL. Built-in 'f' casts in pg_catalog (oid < 16384) call core functions that don't return NULL on non-NULL input either. Only user-defined castmethod='f' casts can violate non-null preservation, so the probe is exact, not heuristic.

CastPolicy::Trust (no unsafe casts): Cast inherits the inner's verdict. id::text over NOT NULL id stays non-null.

CastPolicy::Conservative (≥1 unsafe cast): <col>::T widens because some castfunc in the database could return NULL. Literal-class inner expressions (Literal, ArrayConstructor, never-null funcs) stay safe in either mode since the value is fabricated, not transformed from a column.

New cast_policy.md corpus suite exercises the conservative branch — installs a real user-defined function cast and verifies the four shapes (column → widened, literal → safe, table_ref preserved through widening, bare ColumnRef unaffected). Idempotent setup with cross-suite cleanup so re-runs are deterministic regardless of ordering.

Deleted

• nullability.rs (NullabilityHints, classify_with, classify_expr, try_classify_text, collect_named_outputs, the SubPlan/CTE EXPLAIN-text map) — 623 LOC.
• explain_expr.rs (paren peelers, literal tokeniser, ref parser, parse_call_args) — 193 LOC.
• refine_to_not_null, resolve_arg, fetch_scan_attnotnull, infer_setop_literal_union(branches: &[String]), the EXPLAIN-text <alias>.<col> leading-alias parser used by FULL JOIN side detection.

Trade-offs the user should know

• Sub-queries inside expressions: SubLink lowers to Expr::SubQuery(Box<Analyzed>), but in this PR we only descend one level via the SubLink's subselect.target_list[0] shortcut — full recursion is wired but not enabled yet. The existing corpus doesn't need it; opening up the recursion is a one-line change once views / nested SubLinks need it.
• Views: not handled in this PR. A RangeVar to a view falls back to Expr::Unknown + RowDescription's attnotnull (which is fine because PG sets attnotnull on view columns to match their underlying base columns). Proper recursion via pg_get_viewdef is the obvious next step.
• Star expansion + outer-join widening: SELECT m.* FROM users u LEFT JOIN memberships m ON … synthesizes Expr::Column from RowDescription's (table_oid, attnum) and looks up the matching alias in Scope to apply the correct widening. Self-joins with SELECT * pick the alphabetically-first alias deterministically.

Test plan

• cargo test --workspace — 162 tests pass against the local dev Postgres (analyzer unit, codegen unit + corpus, sqlc corpus, scanner, proptest, runtime tsc, scan suites all green). Ran the corpus suite twice in succession to verify idempotency holds across the cast_policy.md user-defined cast surviving between runs.
• cargo check --workspace — clean.
• CI green.

🤖 Generated with Claude Code