feat(sql,core): FROM-less SELECT handshake executed against Elasticsearch (story 20.9)

[fupelaqu]

Closes #251

FROM-less SELECT — the connection handshake (story 20.9, 0.22.0 train)

SELECT 1 is the connection/health idiom of the JDBC/SQLAlchemy ecosystem: Tableau re-issues it on every interaction (measured in the Epic 19 capture — each one aborted browse), Superset's connect test sends it, its engine probe and the Flight sidecar's own schema probe send SELECT 1 LIMIT 100, and connection pools use it as connectionTestQuery. Until now every one of these failed with a parse error.

What this PR does

• New statement kind FromlessSelect (sql): select ~ limit.?, inserted in dqlStatement immediately after searchStatement (| commits to the first succeeding alternative; searchStatement fails on FROM-less input because single requires from). General FROM-less select-list: literals and Painless-translatable constant scalars, multiple items, AS/bare aliases, LIMIT/OFFSET.
• Executed AGAINST Elasticsearch (lead direction 2026-09-02): the statement is rewritten to SELECT <items> FROM softclient4es_handshake LIMIT 1 and rides the unmodified FROM-ful SQL→Painless script_fields pipeline — FROM-less and FROM-ful semantics agree by construction (one code path, one params.__now__ clock per request). A locally-answered handshake would report "connected" against a dead cluster; with ES unreachable, SELECT 1 now fails with the propagated client error — a pool's connectionTestQuery becomes a real test.
• The handshake index: softclient4es_handshake (1 shard / 0 replicas; index.hidden: true on ES ≥ 7.7; single dummy keyword mapping; one seeded doc), created lazily at first use — probe-before-act, race-safe, memoized per client, bounded self-heal (one retry on index_not_found / empty page). Behind a seam (HandshakeEvaluator) so the future Painless-execute-API backend swaps in without touching the statement kind, executor, or tests.
• Invisible to browse: an explicit name filter in TableExecutor's ShowTables arm — the ONE seam both BI browse surfaces traverse (jdbc getTables and Flight GET_TABLES both execute SHOW TABLES through gateway.run), so zero driver/sidecar changes. DESCRIBE TABLE softclient4es_handshake still works, deliberately.
• Guarded: named-reason rejects (post-Every parse rejection from GatewayApi.run is labelled a schema DDL error #262 shape) for column references (own name or embedded), SELECT *, aggregates, window functions (checked before aggregation — WindowFunction extends AggregateFunction), EXCEPT, duplicate output names, unbound ? (top-level and nested — a nested params.paramValue would be a silent NULL at ES), array literals, negative/overflow-negative LIMIT/OFFSET. Guards re-run on the programmatic path (run(statement) never calls validate()). Clauses (WHERE/GROUP BY/HAVING/ORDER BY) and UNION stay grammar-rejected.
• Quota/routing: FromlessSelect takes CoreDqlExtension's structural no-cap arm (result ≤ 1 row; pinned — no CapHitKind.QueryResults increment); the internal rewrite always carries LIMIT 1, so it can never reach scroll/PIT, and the statement's own LIMIT/OFFSET are applied engine-side on the assembled row (LIMIT 0 still connection-checks).
• Docs: documentation/sql/dql_statements.md §"FROM-less SELECT (connection handshake)" — semantics, index disclosure, read-only pre-creation guidance, reject list. Web twin rides the 0.22.0 doc sweep.

Tests

• FromlessSelectParserSpec (accept/reject/round-trip — every accepted form's .sql re-parses to an equal AST, fix(sql): make ALTER COLUMN ... SET|ADD FIELD parse and actually apply #218 fixed point) + FromlessSelectValidateSpec (guard arms parse-first; rewrite shape pins incl. the LIMIT-isolation pin) — sql, Docker-free.
• FromlessSelectGatewaySpec (core, Docker-free, NopeClientApi fixtures): bare no-op client ⇒ handshake fails (nothing answers locally); stubbed client ⇒ row assembly, array unwrap, ensure-flow order + keyword mapping, memoization, LIMIT semantics, multi-statement; failing client ⇒ connection error propagates; probe-403 AND create-403 ⇒ original status preserved + pre-creation guidance appended; SHOW TABLES filter.
• CoreDqlExtensionSpec: FromlessSelect no-cap routing pin (the recorded search statement IS the LIMIT-1 rewrite on the handshake index).
• Testkit template (GatewayApiIntegrationSpec + ReplGatewayIntegrationSpec): value assertions on real ES — SELECT 1 ⇒ one row, column "1", Integer (class-pinned; Scala's cooperative equality would let a Long pass shouldBe 1); UPPER/arithmetic/'125'::BIGINT; NULL; RANDOM fresh per execution; one clock per statement; 1/0 fails loudly; invisibility on every SHOW TABLES pattern + DESCRIBE still working.
• Integration green on all four majors (real Docker clusters, sbt17): ES 6.8 (rest + jest), 7.17, 8.18, 9.0 — GatewayApi + REPL legs each.

Release notes (0.22.0)

1. New statement form: FROM-less SELECT of constant scalar expressions (Support FROM-less SELECT of literal expressions — SELECT 1 is the connection/health idiom of Tableau and Superset and is rejected #251) — executed against Elasticsearch as Painless (connection-check semantics: with the cluster unreachable, SELECT 1 fails). Unblocks Tableau/Superset/DBeaver connection tests and connectionTestQuery pools — which now genuinely test the connection.
2. The driver creates an index in your cluster at first FROM-less SELECT: softclient4es_handshake (1 shard / 0 replicas, one seeded {"dummy":"dummy"} doc, index.hidden on ES ≥ 7.7). Never listed by SHOW TABLES (nor JDBC/Flight browse); never auto-deleted. Read-only deployments: pre-create + seed it as an administrator (docs §FROM-less SELECT) and lazy creation becomes a no-op probe — the BI service account then only needs read on softclient4es_handshake. Without pre-creation, a read-only session's first SELECT 1 fails with the cluster's own security error plus the pre-creation guidance appended.
3. Behaviour change: statements like SELECT 1 that previously failed with a parse error now succeed and return one row (column named "1", INTEGER — matching what the 19.4 shim reported).
4. SELECT <expr> rejections now name the reason (... requires a FROM clause) instead of a grammar-combinator error.
5. Not included (still rejected): column references / * / aggregates / window functions without FROM; WHERE/GROUP BY/HAVING/ORDER BY without FROM; FROM-less UNION ALL; backtick-quoted aliases (Identifier quoting coverage: backticks rejected in every position; double-quoted table names unparseable in FROM #252); CAST(<bare literal> AS T) — pre-existing grammar gap (CAST/TRY_CAST/CONVERT reject bare literal operands — CAST('125' AS BIGINT) does not parse #267), use '<literal>'::T.

Coordination

• Same 0.22.0 train as feat(help): retire the 13 phantom help entries + HelpCorpusSpec corpus-walk anti-drift guard #263 (story 20.7) and fix(core): parse rejections say SQL statement, not schema DDL (Story 20.4) #264 (story 20.4). Trivial rebase expected against fix(core): parse rejections say SQL statement, not schema DDL (Story 20.4) #264 (disjoint regions of GatewayApi.scala; this PR pins only its own reason substrings + statusCode 400, never the Error parsing wording).
• 20.8's BiJdbcTool SELECT 1 step flips from "the defect that aborts the harness" to a valid Support FROM-less SELECT of literal expressions — SELECT 1 is the connection/health idiom of Tableau and Superset and is rejected #251 regression check against a 0.22.0-based driver.

🤖 Generated with Claude Code