Make the agent SQL dialect accept what agents actually write, and say what it does

[kirill-markin]

Promotes integration-agent-sql-dialect-ergonomics (5 commits, 4 reviewed items) to main.

Why

Measured from Langfuse over 2026-07-07 to 2026-08-06: 170 dialect rejections across 2711 sql tool calls (6.3%). Turns that hit at least one rejection are 29.7% of turns but account for 62.4% of all SQL tool calls, with a median of 13 calls per turn against 3 for clean turns. The recovery loop, not the single rejection, is where the cost sits.

Two groups covered 68% of rejections:

Class	Rejections
Parenthesized AND/OR groups in WHERE	58 (34%)
Columns that do not exist (cards.deck_id 35, decks.description 11, bare tag 4, …)	57 (33.5%)
NOT LIKE, array comparison, other predicate forms	19 (11%)

What changed

Grammar. The flat disjunctive-normal-form predicate list became a recursive boolean expression tree, so explicit parentheses parse and evaluate with AND binding tighter than OR. Added NOT LIKE, ILIKE, and array comparison (tags = ('a','b') exact set equality, tags = () for untagged). UPDATE and DELETE resolve target rows through the same evaluator, so they gain the forms too.

Truthful contract. Decks are saved tag filters; cards have no deck membership; decks have no description. OVERLAP and MATCH — implemented all along, documented nowhere, used once each in 2711 calls — are now advertised, with OVERLAP named as the way to filter writes by tag since UNNEST is SELECT-only. Schema discovery must be its own tool call: 78 of 157 discovery calls were batched with the statements that depended on them, which cannot work because a batch is composed before any statement runs.

Two silent wrong answers converted to clear errors. LIKE against a non-text column matched no rows at all and told the agent nothing existed — LOWER(tags) LIKE '%english%' appeared 9 times in the window, wrong every time. And broad UPDATE/DELETE truncated the match set to 100 rows and reported success, so a DELETE matching 250 rows deleted 100 and returned affectedCount: 100 while every surface promised a rejection past 100.

Review

Three cumulative reviews ran across the feature. They caught four published-contract defects that no per-item review could see, because each lived in one item and contradicted another:

• an invented end-to-end ceiling of 5000 rows per write batch, false because of the independent MAX_SQL_RESULT_CHARS limit;
• MATCH described as scanning a single column when it scans every value of the row;
• negated IN on an array column described as matching every row when it matches none;
• tags = (...) documented ambiguously as "array comparison" with no documented "all of these tags" form, so an agent wanting both tags would silently get an incomplete answer — the exact failure class this feature exists to remove, on a form the feature itself introduced.

The mutation truncation above was also a cumulative finding: the truncation predated the feature, but the feature made it the recommended path.

CI

GitHub Actions has been in a multi-hour major_outage; the last successful run in this repository was 14:11 UTC. Items 1 and 2 merged with green checks including backend tests and typecheck. Items 3 and 4 have no run — GitHub stopped dispatching workflow runs entirely. Do not merge this PR until required checks are green.

Accepted residuals

• The new LIKE is not supported for column: <name> message does not name the offending construct when the agent wrote LOWER(tags) = 'english', which compiles to the same predicate. Safe to reword; no smoke script asserts it.
• The claim that deleted_at and metadata can never appear in ORDER BY is over-broad: the grouped path does not consult sortable, so they are accepted as a GROUP BY key. Over-restrictive, so it produces no rejections.
• Pre-existing, unchanged: OVERLAP against a non-array column and IS NULL on a non-nullable array column return zero rows silently; column IN (...) on an array column matches nothing (now documented); the LIKE pattern is recompiled per row; an empty top-level WHERE on a mutation matches all rows.
• The bulk-write arithmetic exists as separate hand-maintained copies across the tool contract, the setup envelope, and the OpenAPI specs. Sharing one constant is deliberate follow-up.

🤖 Generated with Claude Code