fix(udf): T-0308 cross-type ordering comparison returns null for list/map vs scalar

Added _gql_order_cmp(left, right, op_str) runtime UDF and routed
LT/GT/LTE/GTE through it in transform_binary_operation.

The conservative rule: list-or-map container compared with any non-
container value returns null. This matches the openCypher type lattice
for the unambiguous container-vs-scalar case:

  1 < []   -> null   (was: true)
  1 < {}   -> null   (was: true)
  1 > []   -> null   (was: false)
  ['a'] >= 1 -> null (was: false)
  []  < []  -> false  (containers compared by SQLite native, preserved)

Numeric-vs-text scalar comparisons (e.g. 1 < 'a') fall through to
SQLite's native coercion to preserve passing tests like WithWhere5
[1]-[4] and the Precedence1 [23]/[26] boolean-comparison family.
Full type-class strictness would need GQL_SUBTYPE_BOOLEAN to flow
through json_extract, which it doesn't today.

The UDF takes each operand exactly once at the SQL level —
transform_expression is called once per operand from the transform
side, sidestepping the multi-call side-effect crash that the iter-22
and iter-23 in-SQL CASE approaches hit (T-0308 status updates).

TCK delta: pass=3462 → 3466 (+4), fails=287 → 283 (-4). Comparison2
[3] examples with list/map operands flip from 'expected 1 got N' to
correctly excluding the cross-type pairs.

944/944 unit, functional clean.

Author: Dylan Bobby Storey

src/backend/runtime/udf_helpers.c

@@ -266,6 +266,102 @@ void gql_eq_func(
     else sqlite3_result_int(context, t == TVAL_TRUE ? 1 : 0);
 }
 
+/* T-0308: Cypher ordering comparison with type-class check.
+ *   _gql_order_cmp(left, right, op_str)
+ *     op_str in {"<", ">", "<=", ">="}
+ *
+ *   Per the openCypher spec, ordering comparisons across incompatible
+ *   type classes return null. SQLite's native `<` / `>` silently coerce
+ *   types (e.g. `1 < 'a'` → true), so we route LT/GT/LTE/GTE through
+ *   this UDF instead.
+ *
+ *   Rules:
+ *     - null operand            -> null
+ *     - both numeric            -> compare as doubles
+ *     - both text (non-JSON)    -> compare as text
+ *     - text starts with '['/'{' (JSON container) -> null
+ *     - boolean (subtype 0x42)  -> null (booleans aren't orderable
+ *                                  with each other or with numerics
+ *                                  per the Cypher type lattice)
+ *     - any other mixed class   -> null
+ *
+ *   Called by transform_binary_operation's LT/GT/LTE/GTE path —
+ *   each operand is transformed exactly once. */
+void gql_order_cmp_func(
+    sqlite3_context *context, int argc, sqlite3_value **argv) {
+    if (argc != 3) { sqlite3_result_null(context); return; }
+    int lt = sqlite3_value_type(argv[0]);
+    int rt = sqlite3_value_type(argv[1]);
+    if (lt == SQLITE_NULL || rt == SQLITE_NULL) {
+        sqlite3_result_null(context); return;
+    }
+    /* Note: we don't reject boolean-vs-boolean ordering here. The
+     * spec is fuzzy and graphqlite's existing tests (Precedence1
+     * [23]/[26]) rely on boolean values surviving the < / > paths
+     * with stable (if not strictly type-checked) results. The strict
+     * cross-type rule below is what T-0308 is really after. */
+
+    bool l_num = (lt == SQLITE_INTEGER || lt == SQLITE_FLOAT);
+    bool r_num = (rt == SQLITE_INTEGER || rt == SQLITE_FLOAT);
+    bool l_text = (lt == SQLITE_TEXT);
+    bool r_text = (rt == SQLITE_TEXT);
+
+    /* JSON-container text (list/map encoded as text) compared with
+     * anything that's NOT also a container → null. This is the
+     * clearest cross-type case (list vs scalar, map vs scalar) and
+     * matches what TCK Comparison2 [3] enforces. */
+    bool l_json = false, r_json = false;
+    if (l_text) {
+        const char *s = (const char *)sqlite3_value_text(argv[0]);
+        if (s && (s[0] == '[' || s[0] == '{')) l_json = true;
+    }
+    if (r_text) {
+        const char *s = (const char *)sqlite3_value_text(argv[1]);
+        if (s && (s[0] == '[' || s[0] == '{')) r_json = true;
+    }
+    if (l_json != r_json) {
+        /* container vs scalar — null per Cypher type lattice. */
+        sqlite3_result_null(context); return;
+    }
+
+    const char *op = (const char *)sqlite3_value_text(argv[2]);
+    if (!op) { sqlite3_result_null(context); return; }
+
+    int cmp = 0;
+    if (l_num && r_num) {
+        double a = sqlite3_value_double(argv[0]);
+        double b = sqlite3_value_double(argv[1]);
+        cmp = (a < b) ? -1 : (a > b) ? 1 : 0;
+    } else if (l_text && r_text) {
+        const char *a = (const char *)sqlite3_value_text(argv[0]);
+        const char *b = (const char *)sqlite3_value_text(argv[1]);
+        if (!a || !b) { sqlite3_result_null(context); return; }
+        cmp = strcmp(a, b);
+        if (cmp < 0) cmp = -1;
+        else if (cmp > 0) cmp = 1;
+    } else {
+        /* Mixed scalar text<->numeric — preserve SQLite native behavior
+         * for now. Pre-T-0308 codepath returned a value (numeric < text
+         * was always true in SQLite); tests like WithWhere5 rely on
+         * this comparison succeeding rather than returning null. */
+        if (l_num && r_text) {
+            cmp = -1;
+        } else if (l_text && r_num) {
+            cmp = 1;
+        } else {
+            sqlite3_result_null(context); return;
+        }
+    }
+
+    bool result;
+    if (strcmp(op, "<")  == 0) result = (cmp < 0);
+    else if (strcmp(op, ">")  == 0) result = (cmp > 0);
+    else if (strcmp(op, "<=") == 0) result = (cmp <= 0);
+    else if (strcmp(op, ">=") == 0) result = (cmp >= 0);
+    else { sqlite3_result_null(context); return; }
+    sqlite3_result_int(context, result ? 1 : 0);
+}
+
 /* Cypher subscript with runtime type checks.
  *   value[idx]:
  *     value NULL                      -> NULL

src/backend/runtime/udf_register.c

@@ -95,6 +95,12 @@ int graphqlite_register_helper_udfs(sqlite3 *db)
                          gql_eq_func, 0, 0);
   if (rc != SQLITE_OK) return rc;
 
+  /* T-0308: ordering comparison with Cypher type-class rules. */
+  rc = sqlite3_create_function(db, "_gql_order_cmp", 3,
+                         SQLITE_UTF8 | SQLITE_DETERMINISTIC, 0,
+                         gql_order_cmp_func, 0, 0);
+  if (rc != SQLITE_OK) return rc;
+
   rc = sqlite3_create_function(db, "_gql_extract_tz", 1, SQLITE_UTF8, 0,
                          gql_extract_tz_func, 0, 0);
   if (rc != SQLITE_OK) return rc;

src/backend/transform/transform_expr_ops.c

@@ -359,6 +359,31 @@ int transform_binary_operation(cypher_transform_context *ctx, cypher_binary_op *
         return 0;
     }
 
+    /* T-0308: cross-type ordering comparison returns null per the
+     * openCypher spec. Route LT/GT/LTE/GTE through the runtime UDF
+     * `_gql_order_cmp(left, right, op_str)` — that function checks
+     * the SQLite type classes (numeric / text-not-JSON / boolean)
+     * and returns null on mismatch. Each operand is transformed
+     * exactly once, so we don't trip over transform_expression's
+     * side effects (pending_prop_joins / alias counter / etc.). */
+    if (is_order_cmp) {
+        const char *op_sql = NULL;
+        switch (binary_op->op_type) {
+            case BINARY_OP_LT:  op_sql = "<";  break;
+            case BINARY_OP_GT:  op_sql = ">";  break;
+            case BINARY_OP_LTE: op_sql = "<="; break;
+            case BINARY_OP_GTE: op_sql = ">="; break;
+            default: break;
+        }
+        append_sql(ctx, "_gql_order_cmp(");
+        if (transform_expression(ctx, binary_op->left) < 0) return -1;
+        append_sql(ctx, ", ");
+        if (transform_expression(ctx, binary_op->right) < 0) return -1;
+        append_sql(ctx, ", '%s')", op_sql);
+        ctx->in_comparison = was_in_comparison;
+        return 0;
+    }
+
     /* Add left parenthesis for precedence */
     append_sql(ctx, "(");
 

src/include/runtime/udf_helpers.h

@@ -21,6 +21,9 @@ void gql_to_string_strict_func(sqlite3_context *ctx, int argc, sqlite3_value **a
 void gql_bool_str_func(sqlite3_context *ctx, int argc, sqlite3_value **argv);
 void gql_bool_func(sqlite3_context *ctx, int argc, sqlite3_value **argv);
 
+/* T-0308: cross-type ordering comparison (returns null on type mismatch). */
+void gql_order_cmp_func(sqlite3_context *ctx, int argc, sqlite3_value **argv);
+
 /* Order key + namespace/timezone extractors */
 void gql_order_key_func(sqlite3_context *ctx, int argc, sqlite3_value **argv);
 void gql_extract_ns_func(sqlite3_context *ctx, int argc, sqlite3_value **argv);