v0.12.2

v0.12.2 (2026-08-11)

Documentation

• docs: multi-source procedural BFS — why it fails at runtime and the options

A property start filter transpiles in procedural mode (cardinality is
data-dependent) and hits the embedded single-seed RAISE_ERROR when it
matches several nodes. Document the architectural reason (no seed column
in frontier/visited/result), the two workarounds (CTE mode; per-seed
loop), and — in the developer notes — the two designs to lift it, with
the real cost being re-A/B of every memory-optimization flag rather than
the rewrite itself.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> (6ed6450)

Fix

• fix: silent wrong answers in joins, aggregates, naming + loud error contracts

Fixes the ten defects catalogued in docs_help_dev/testing/test-failures-report.md
(F1-F10), each backed by new tests that failed before and pass after.

Silent wrong answers:

• Repeated pattern variable ((a)-[:T]->(a), closed cycles) never emitted the
  closing SINK join pair, returning every path instead of every cycle. The
  shared-variable branch in match_tree now binds the node to the preceding
  relationship's far endpoint before skipping the duplicate data source.
• percentileCont/percentileDisc vanished: the visitor dropped arguments past
  the first (new extra_parameters on the aggregation AST node) and the
  renderer had no pattern (PERCENTILE_CONT({1}) WITHIN GROUP (ORDER BY {0})).
  Pattern-less aggregates now raise instead of emitting the bare operand.
• LIMIT $n / SKIP $s were silently discarded; _extract_int_value now raises
  TranspilerNotSupportedException for non-literal expressions.
• RETURN a.name, b.name emitted two columns both named "name"; colliding
  auto-derived aliases are qualified as a_name/b_name (explicit AS untouched).
• RETURN * / WITH * leaked internal gsql2rsql* columns and anonymous edge
  plumbing; the star now expands to the named variables in scope.

Invalid SQL made valid or loud:

• size(<string>) renders LENGTH() via type dispatch from the operator's input
  schema (AST data_type is often unset at render time).
• list + list renders CONCAT(), with list literals as ARRAY(...) operands.
• WHERE a:Person label predicates raise with a move-into-pattern hint instead
  of rendering a non-boolean WHERE (both grammar paths).
• Unknown functions raise TranspilerNotSupportedException naming what the
  user wrote (raw_name) instead of leaking NotImplementedError(INVALID).
• add_edge derives missing source/sink id properties from the descriptor's
  node_id_columns and rejects only when underivable, so hand-built schemas
  can no longer produce dangling join keys.

Documented (not fixed): relationship uniqueness (edge isomorphism) is not
enforced in fixed-length patterns - guarded by a strict xfail; unbounded VLP
depth cap of 10 is now documented and locked by tests.

Test infrastructure: get_base_spark() probes SparkContext liveness so modules
using the shared session survive legacy modules that call spark.stop().

Suites: non-PySpark 1801 passed / 7 skipped / 1 xfailed; PySpark 261 passed /
6 xfailed; pyright and mypy at 0 errors.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> (41c10d3)

• fix: actionable errors for unknown edge types + user-facing limitations docs

Planner (data_source.py, recursive_traversal.py):

• Unknown relationship types (single-hop AND VLP) used to either fail with
  a generic "Failed to bind relationship" (single-hop) or a confusing
  "Internal error: No enriched data for RecursiveTraversalOperator" three
  phases later in Enrichment (VLP) -- the latter reading as a transpiler
  bug when it's a schema/config mismatch. A typo inside an OR list
  ([:OWNS|KNOWS]) silently transpiled, dropping the bad type instead of
  raising.
• Added validate_edge_verbs_exist()/_describe_available_edge_verbs() in
  data_source.py, called from both binding sites, mirroring the node-type
  diagnostics: lists registered edge types, suggests a case-insensitive
  near-match. Distinguishes "verb exists for no endpoint pair" (typo,
  raises) from "verb exists but not for these endpoints" (silently pruned
  from OR lists -- load-bearing for restricted edge_combinations schemas).
• get_all_edge_schemas() added to SimpleSQLSchemaProvider.

Docs:

• New docs/limitations.md (mkdocs nav: User Guide > Limitations):
  user-facing quick-reference table, CTE vs procedural feature matrix,
  schema-binding error guide, parser notes (backticks, unaliased
  projection aliases, != rejection), correctness/performance caveats.
  user-guide.md's inline section now summarizes and links to it.
• fix_transpiler_bugs skill: new step 7 requiring both limitations docs
  (docs_help_dev/ internal, docs/ user-facing) to be updated whenever a
  fix adds/removes a guardrail or NotSupported path.

Tests: tests/test_unknown_edge_type_errors.py (10 cases: single-hop, VLP,
OR-list typo detection, endpoint-pruning-not-a-typo regression). (554761c)