fix(sql): make Parser.apply total, and fix N-ary relation predicates (#250)

[fupelaqu]

Closes #250
Closes #280
Closes #281

Epic 21 story 21.4. This branch also carries the epic's opening commit — build.sbt 0.22.0 →
0.23.0-SNAPSHOT (9dca152b, nothing else in it).

1. Parser.apply is total (#250)

It is typed Either[ParserError, Statement] and did not honour it. Five production call sites
match on that Either with no try of their own — SQLImplicits.queryToStatement (an implicit
conversion), IndicesApi ×3 (update/delete/insert by query) and the searchAs macro (where a throw
is a raw scalac crash) — plus one sibling-repo consumer, arrow's Flight JOIN planner. The measured
repro is jOOQ's rendering of RLIKE as (name like_regex 'Jo.*'): the only crash row of the
259-row Epic 19 census probe.

Two halves, covering disjoint surfaces — not two nets over one hole.

err owns the grammar. All five throw sites under parser/ are gone (#250 named three;
the audit found five). The three WhereParser helpers return Either[String, …] with both
@tailrec preserved, and their four combinator callers — where, having, FromParser.on,
case_condition — emit err(reason). err, never failure: a failure there falls through
opt(where) and silently drops the clause, the #213 data-loss mode. case_condition also gains the
default arm it never had (a MatchError escapes exactly like a throw, and no source scan can see
it). processTokens is narrowed to private[parser].

A NonFatal boundary catch owns what err structurally cannot reach. single calls .update()
inside its own action, so the AST-update pass runs during the parse, and two sites there crash —
SingleSearch.bucketNames indexes select.fields(n - 1) unchecked (a bare index, no throw
token, so no grep-based guard can ever see it) and Bucket.update throws on a non-positive
ordinal. The try wraps the whole method body: normalize dereferences query.length, so
Parser(null) throws before parse runs. The message is labelled
Internal parser error: <Class>[: <detail>], and both accessors it reads are themselves guarded —
getSimpleName can raise InternalError on JDK 8 and a custom getMessage can throw, either of
which would escape the very method whose point is totality.

Nothing that parses today is lost to the err conversions: every input that reaches one used to
throw, which aborted the whole parse.

ParserError gains cause: Option[Throwable] = None, set only by the boundary catch and threaded
through all five core parse sites — it is the only stack trace an internal parser fault ever
produces. Both ElasticResult.attempt(Parser(...)) wrappers and their now-unreachable
ElasticFailure arms are removed (attempt catches exactly NonFatal, and so does apply), along
with GatewayApi.parseFailureReason and its four tests. Inputs that used to throw now get an honest
400 instead of no status at all. PipelineApi's reason is bounded by the same excerpt the SQL
route uses. Parser.apply no longer prints the combinator message to stderr.

2. ⚠️ Two shapes that used to be accepted are now rejected (#280)

Each previously parsed into a statement that was not the one written:

input	used to parse as	now
DELETE FROM orders WHERE id = 1 AND	DELETE FROM orders — empties the index	WHERE clause requires criteria
SELECT a FROM t WHERE a = 1)	… WHERE a = 1, ) discarded	Unbalanced parentheses

Two silent-truncation arms of processTokensHelper are converted for the same reason, after
instrumenting both and confirming across sql/core/bridge/macros that nothing reaches them with
data to lose (the catch-all: never reached; the Nil fallback: 26 times, always a dangling
operator).

3. A silent wrong answer is FIXED: N-ary relation predicates (#281)

NESTED / CHILD / PARENT accepted exactly two criteria. With three or more the statement
still parsed, but the relation scope collapsed to the first criterion and the rest escaped onto
the parent document; with OR the operator spanned the relation boundary. Fixed at the arity's
source and reduced through processTokens, so a relation body is exactly the tree the same
expression produces at top level. An unmatched opening parenthesis is now rejected too.

This was found by the code review, not by the implementation, and it falsified an invariant written
into a source comment — extractSubTokens is not the only route to an unmatched ).

Verification

sql 604 · core 857 · macros-tests 19 · all five bridge suites 126 (the bridge/ template,
the hand-maintained es6/bridge/, es7, es8, and es9 under sbt17). sql and core green on
2.13.16 and 2.12.20 (+ sql/test, + core/test — + compile does not reach test sources).
scalafmtCheck + test:scalafmtCheck clean. No Docker.

⚠️ es7, es8 and es9 each reported the stale test count on the first run after the template edit
and the real one only on the second, logging Copying bridge template sources. Never accept a first
run after touching bridge/src/test.

Guards that can actually fail. ParserTotalitySpec asserts not-throwing as its own assertion
first, then that the rejection came from the grammar and not from the boundary catch. That third
assertion is the point: without it every case is unfalsifiable, because restoring a throw still
yields a Left whose message contains the same reason. Verified by restoring one throw and
observing 7 tests go red. Plus a parser/** source scan with no allow-list, self-guarded
against scanning nothing (asserted, never assumed); a tree-equivalence property over ten shapes
(single, all-AND, all-OR, mixed AND/OR both ways, explicit grouping, NOT forms) proving
CHILD(X) ≡ WHERE X; and generated-ES-query assertions in both bridge copies — all-AND and
all-OR pins alone are association-insensitive and prove only that nesting exists, not that it is
right.

Parse-cost check (AD-11), measured and honestly inconclusive: ParserSpec (304 tests), two
sessions of 10 runs per tree, warm-up discarded — baseline median 3.50 s (2.90–4.40), patched
3.75 s (2.89–4.61). The +7 % sits inside the noise band and a shorter round showed the opposite
ordering. No measurable regression at this resolution — deliberately not rounded up to a "zero
cost" claim.

Known, measured, tracked separately

• NESTED(…) without a JOIN UNNEST(<path>) AS <alias> emits match_all — pre-existing, at every
  arity; this PR only makes the 3-or-more spelling reach it.
• The relation type is guessed from the first criterion's name prefix.
• NOT c = 3 renders as c NOT = 3, which does not re-parse — pre-existing, identical at top level.
• A valid GROUP BY on a digit-bearing column (city2, q4) is reported as
  400 Internal parser error instead of crashing. Not newly broken; semantics owned by story 21.3,
  where three pinned sites carry the instruction retarget, never delete.

Release notes (0.23.0)

See the story's release-note block. Headline items: the two newly-rejected shapes; the N-ary
relation fix (if you have such a query, its results were wrong and will now change);
statusCode None → Some(400) on the previously-throwing route; Internal parser error: … as a
distinguishable label carrying the cause; the parser no longer writing to stderr; and two
binary-incompatible sql API changes — ParserError arity (so equals/hashCode/toString
change) and processTokens narrowed to private[parser] with a new return type.

🤖 Generated with Claude Code