docs: ADR-0032 + Phase 2 plan — full SQL SELECT grammar
ADR-0030 §3 commissioned a focused ADR for the full SELECT grammar (the "SELECT — full" phase). ADR-0032 records the decisions; docs/plans/20260520-adr-0032-phase-2.md is the implementation plan walking the work. Phase 2's grammar surface: - Five JOIN flavours (INNER, LEFT, RIGHT, FULL OUTER, CROSS). NATURAL/USING/comma-FROM explicitly OOS. - All four set ops (UNION, UNION ALL, INTERSECT, EXCEPT). - WITH and WITH RECURSIVE CTEs, with optional (col-list) renaming. - Scalar subqueries, IN (SELECT …), [NOT] EXISTS as additive primary branches in sql_expr (redeems ADR-0031 §7 OOS-1). - Qualified column refs t.c / alias.c as a name_or_call tail (redeems ADR-0031 §7 OOS-2). - LIMIT n [OFFSET m]; legacy `LIMIT m, n` OOS. - DISTINCT/ALL, t.* projection, bare-alias projection (lifts Phase-1 §4.2's autonomous decision). Walker-capability honesty (§10): ADR-0030 §8's "ambient assistance comes for free" holds for grammar recursion (reuses ADR-0026's Subgrammar + depth cap unchanged) but not for completion scope. Phase 2 adds a new Node::ScopedSubgrammar variant alongside the existing Node::Subgrammar (DSL Expr and sql_expr recursion untouched), a from_scope_stack of ScopeFrames holding from_scope / cte_bindings / projection_aliases, qualified-prefix completion narrowing, and a post-walk fixup pass that re-resolves projection-list identifier highlighting/validity once FROM is parsed (the projection-before-FROM problem). CTE column resolution (§10.3): SELECT * and explicit-projection CTE bodies both yield real column completion past cte_alias.| via a body-projection derivation rule that runs at the body's ScopedSubgrammar exit and writes derived columns back into the binding. Diagnostics (§11): every Phase-2 validation case classified against ADR-0027's ERROR/WARNING guideline. Five new diagnostic.* catalog keys for parse-time-detectable cases (unknown_qualifier, ambiguous_column, projection_alias_misplaced, cte_arity_mismatch, compound_arity_mismatch) plus eight engine.* translation keys. A MatchedPath-walking predicate-warnings variant closes the Phase-1 carry-over gap where SQL WHERE expressions emitted no LIKE-on-numeric / = NULL / type-mismatch warnings — ADR-0027 Amendment 1 finally extends to the SQL surface. Result-column type resolution (§12): rusqlite 0.39.0 exposes column_table_name / column_origin_name / column_database_name behind a `column_metadata` feature; verified. Bare column refs recover their playground type — partially lifts Phase-1 §4.5's bool→0/1 deferral. The implementation plan breaks Phase 2 into seven sub-phases (2a–2g) with explicit exit gates per sub-phase and a cross-cut verification matrix that names every "X comes for free" claim from ADR-0030/0031/0032. The Phase-1 SQL-expression predicate-warning gap is a named row, preventing an analogous silent gap from shipping. The plan encodes the user's standing authorization for the implementer to walk uninterrupted between gates and commit with standard messages — escalation discipline preserved for design ambiguities and real blockers. Pushes remain user-only. New docs/plans/ directory sets a pattern for future phase plans. Status: Accepted.
This commit is contained in:
claude@clouddev1