fix(guards): stop TokenError escaping the SQL guard as pipeline_exception

sqlglot's failure modes are siblings under SqlglotError, not a chain: the
parser raises ParseError, the lexer raises TokenError. `_safe_parse` caught
only ParseError, so an unterminated string literal escaped validate_sql,
crashed the pipeline node and was recorded as `pipeline_exception` — a model
failure wearing a transport failure's label, on a project whose runs are
judged clean by exactly that counter.

Observed live: q1399 of the 2026-07-22 student-base run
("Error tokenizing '...T1.last_name = 'Mclean'", pred_sql lost, in_tok 0).

Three consequences, not one: the run's health signal lied; the offending SQL
was dropped from the record; and the question never reached repair_once,
because a raised exception skips routing that invalid_sql would have taken.

Probing the parser for other escapes found a second one: RecursionError on
deeply nested parens, which is not a SqlglotError at all. Both now come back
as violations — the guard's documented contract is to report, never raise.

The same narrow `except ParseError` sat on three more parse sites whose own
docstrings promise a fallback instead of a crash (eval/dataset.extract_gold_
tables, autotune/build_dataset.{extract_tables,sql_parses}, p3f_acceptance).
Corrected there too; measured unreachable on current data (370 distinct gold
SQLs, 9428 bird_train rows all parse), so S1's "parse-fail 0" is unchanged.

Gate §7.3 green: ruff, format 190, mypy 108, pytest 555 passed / 14 skipped
cov 91.05%, hygiene 542, no_raw_compare.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: JuliaEdom

scripts/autotune/build_dataset.py

@@ -54,7 +54,10 @@ def extract_tables(sql: str) -> list[str]:
     """Distinct table names in order of appearance; [] when unparseable."""
     try:
         tree = sqlglot.parse_one(sql, dialect=DIALECT)
-    except sqlglot.errors.ParseError:
+    except (sqlglot.errors.SqlglotError, RecursionError):
+        # TokenError (lexer) is a sibling of ParseError, RecursionError is
+        # neither — all are "unparseable", which this function promises to
+        # answer with [] rather than by killing the dataset build.
         return []
     seen: list[str] = []
     for table in tree.find_all(sqlglot_exp.Table):
@@ -95,7 +98,9 @@ def build_example(row: Any) -> dict[str, str]:
 def sql_parses(sql: str) -> bool:
     try:
         sqlglot.parse_one(sql, dialect=DIALECT)
-    except sqlglot.errors.ParseError:
+    except (sqlglot.errors.SqlglotError, RecursionError):
+        # A parse-check predicate must answer False, never raise: a single
+        # token-broken train row would otherwise abort the whole build.
         return False
     return True
 

scripts/p3f_acceptance.py

@@ -20,7 +20,7 @@
 from typing import Any
 
 from sqlglot import exp, parse_one
-from sqlglot.errors import ParseError
+from sqlglot.errors import SqlglotError
 
 ColumnRef = tuple[str, str]
 
@@ -200,7 +200,9 @@ def _qualified_columns(sql: str) -> tuple[set[ColumnRef], str | None]:
         return set(), None
     try:
         tree = parse_one(sql, read="sqlite")
-    except ParseError as exc:
+    except (SqlglotError, RecursionError) as exc:
+        # SqlglotError covers the lexer's TokenError too (sibling of
+        # ParseError); RecursionError covers pathological nesting.
         return set(), f"SQL parse failed: {exc}"
 
     alias_to_table: dict[str, str] = {}

src/nl_sql/eval/dataset.py

@@ -137,7 +137,11 @@ def extract_gold_tables(sql: str) -> list[str]:
     """
     try:
         tree = sqlglot.parse_one(sql, read="sqlite")
-    except sqlglot.errors.ParseError:
+    except (sqlglot.errors.SqlglotError, RecursionError):
+        # SqlglotError, not ParseError: the lexer raises TokenError, which is a
+        # sibling class — and deep nesting raises RecursionError, which is
+        # neither. All three mean "no AST", which is exactly the fallback case
+        # this docstring promises.
         return _extract_via_regex(sql)
     if tree is None:
         return _extract_via_regex(sql)

src/nl_sql/execution/guards.py

@@ -19,7 +19,7 @@
 
 import sqlglot
 from sqlglot import exp
-from sqlglot.errors import ParseError
+from sqlglot.errors import SqlglotError
 
 from nl_sql.db.connection import Dialect
 
@@ -123,9 +123,21 @@ def _safe_parse(
         # sqlglot.parse returns list[Optional[Expression]] but its internal
         # Expr alias trips strict mypy; cast keeps the public API typed.
         return cast("list[exp.Expression | None]", sqlglot.parse(sql, read=sqlglot_name))
-    except ParseError as exc:
+    except SqlglotError as exc:
+        # sqlglot's failure modes are SIBLINGS, not a chain: the parser raises
+        # ParseError, the lexer raises TokenError (unterminated string or
+        # identifier quote). Catching only ParseError let TokenError escape
+        # validate_sql and kill the whole pipeline run — a model writing bad
+        # SQL then surfaced as `pipeline_exception`, i.e. indistinguishable
+        # from a transport failure (q1399, 2026-07-22 student-base run).
         report.add("parse_error", str(exc))
         return None
+    except RecursionError:
+        # Deeply nested parens exhaust the interpreter stack inside sqlglot,
+        # and RecursionError is not a SqlglotError. No AST is no AST: same
+        # verdict as any other parse failure — reject, never propagate.
+        report.add("parse_too_deep", "SQL nesting is too deep to parse")
+        return None
 
 
 def _check_select_only(parsed: exp.Expression, report: ValidationReport) -> None:

tests/test_execution_guards.py

@@ -216,6 +216,37 @@ def test_garbage_input_is_rejected() -> None:
     assert not report.ok
 
 
+def test_unterminated_string_literal_is_reported_not_raised() -> None:
+    """Lexer-level breakage must come back as a report, not as an exception.
+
+    sqlglot raises TokenError (a *sibling* of ParseError, not a subclass) when
+    a string literal never closes. Real regression: q1399 of the 2026-07-22
+    student-base run, where the escaping TokenError was recorded as
+    `pipeline_exception` — i.e. a model failure disguised as a transport one.
+    """
+    sql = "SELECT T1.member_id FROM member AS T1 WHERE T1.first_name = 'Maya AND T1.last_name = 'Mclean'"
+    report = validate_sql(sql)
+    assert not report.ok
+    assert any(v.code == "parse_error" for v in report.violations)
+
+
+def test_unterminated_identifier_quote_is_reported_not_raised() -> None:
+    report = validate_sql('SELECT "col FROM Artists')
+    assert not report.ok
+    assert any(v.code == "parse_error" for v in report.violations)
+
+
+def test_deeply_nested_sql_is_reported_not_raised() -> None:
+    """Nesting deep enough to exhaust the interpreter stack inside sqlglot.
+
+    RecursionError is not a SqlglotError, so it escapes the parse guard on its
+    own path. No AST means the same verdict as any other parse failure: reject.
+    """
+    report = validate_sql("SELECT " + "(" * 2000 + "1" + ")" * 2000)
+    assert not report.ok
+    assert any(v.code == "parse_too_deep" for v in report.violations)
+
+
 @pytest.mark.parametrize(
     "code",
     [
@@ -226,6 +257,8 @@ def test_garbage_input_is_rejected() -> None:
         "denied_table",
         "generate_series_too_large",
         "select_into",
+        "parse_error",
+        "parse_too_deep",
     ],
 )
 def test_violation_codes_are_documented(code: str) -> None: