fix(cypher): preserve partial WHERE and optional COUNT semantics (#5)

## Summary
- Preserve three-valued `WHERE` evaluation while only the seed alias is bound, so later aliases are not pruned early.
- Make `COUNT(variable)` ignore unbound optional matches.
- Adapt upstream Cypher work `458b0db1` through `6166934d`.

## Provenance and gates
- Agent Run: `luna-cbm-cypher-20260920-r1`; source revision `a43b2201`; worker commit `42ca613c`.
- Agent-Workflow reports a valid completion receipt. Independent review, evaluation, acceptance, and integration are pending.
- `git diff --check main...HEAD` passed. No tests were run for this PR request.


<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **Bug Fixes**
  * WHERE filters now handle conditions involving relationship matches more accurately, including combinations of `AND`, `OR`, `NOT`, and `XOR`.
  * `COUNT(variable)` now excludes rows where the variable is unbound, including after a `WITH` clause. `COUNT(*)` continues to count all rows.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

## Review follow-up

Addressed in 89e3ace.

1. **COUNT in WITH aggregation**: fixed. `binding_has_value` now sits above both accumulators, and `with_agg_accumulate` skips COUNT under the same condition as the RETURN path. New test `cypher_exec_with_optional_bound_terminal_count_ignores_unbound` checks that HandleOrder gets 0.
2. **Multi-alias function conditions in the early pass**: fixed. `eval_condition_partial` returns UNKNOWN when any function argument references an unbound variable, including when the first argument is a literal. New test `cypher_exec_where_coalesce_multi_alias` uses `coalesce(a.nosuch, b.name) = "LogError"`.

Both new tests fail without the cypher.c change (198 passed, 2 failed) and pass with it. `scripts/test.sh --suites cypher`: 200 passed. `make lint-ci lint-tidy-diff` passes.

Not changed: `COUNT(t.prop)` still counts a bound node whose property is missing. As noted in the review, this is not a regression.


Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: ngallodev

src/cypher/cypher.c

@@ -2750,6 +2750,103 @@ static bool eval_where(const cbm_where_clause_t *w, binding_t *b) {
     return is_and;
 }
 
+/* Three-valued WHERE evaluation for the early (seed-row) pass in
+ * execute_single: only the first MATCH alias is bound there, so a leaf on
+ * any other alias is UNKNOWN rather than true. The two-valued evaluator
+ * returns true for an unbound alias, which NOT / XOR then invert -- pruning
+ * every seed before relationship expansion (distilled from PR #1245). The
+ * full evaluation reruns after expansion (Step 3), so the early pass only has
+ * to prune on a definite false. Allocation-free, O(expression nodes). */
+typedef enum { CYP_PARTIAL_FALSE = 0, CYP_PARTIAL_TRUE, CYP_PARTIAL_UNKNOWN } cyp_partial_t;
+
+static cyp_partial_t partial_and(cyp_partial_t l, cyp_partial_t r) {
+    if (l == CYP_PARTIAL_FALSE || r == CYP_PARTIAL_FALSE) {
+        return CYP_PARTIAL_FALSE;
+    }
+    return (l == CYP_PARTIAL_TRUE && r == CYP_PARTIAL_TRUE) ? CYP_PARTIAL_TRUE
+                                                            : CYP_PARTIAL_UNKNOWN;
+}
+
+static cyp_partial_t partial_or(cyp_partial_t l, cyp_partial_t r) {
+    if (l == CYP_PARTIAL_TRUE || r == CYP_PARTIAL_TRUE) {
+        return CYP_PARTIAL_TRUE;
+    }
+    return (l == CYP_PARTIAL_FALSE && r == CYP_PARTIAL_FALSE) ? CYP_PARTIAL_FALSE
+                                                              : CYP_PARTIAL_UNKNOWN;
+}
+
+/* A condition whose alias is not bound yet is UNKNOWN; a literal-only LHS
+ * (func condition with no variable arg) has nothing to wait for. */
+static cyp_partial_t eval_condition_partial(const cbm_condition_t *c, binding_t *b) {
+    if (c->variable && !binding_get(b, c->variable) && !binding_get_edge(b, c->variable)) {
+        return CYP_PARTIAL_UNKNOWN;
+    }
+    /* Multi-arg function: any unbound variable arg makes it UNKNOWN. */
+    for (int i = 0; c->func && i < c->arg_count; i++) {
+        const char *av = c->args[i].variable;
+        if (av && !binding_get(b, av) && !binding_get_edge(b, av)) {
+            return CYP_PARTIAL_UNKNOWN;
+        }
+    }
+    return eval_condition(c, b) ? CYP_PARTIAL_TRUE : CYP_PARTIAL_FALSE;
+}
+
+static cyp_partial_t eval_expr_partial(const cbm_expr_t *e, // NOLINT(misc-no-recursion)
+                                       binding_t *b) {
+    if (!e) {
+        return CYP_PARTIAL_TRUE;
+    }
+    if (e->type == EXPR_CONDITION) {
+        return eval_condition_partial(&e->cond, b);
+    }
+    cyp_partial_t left = eval_expr_partial(e->left, b);
+    if (e->type == EXPR_NOT) {
+        if (left == CYP_PARTIAL_UNKNOWN) {
+            return CYP_PARTIAL_UNKNOWN;
+        }
+        return left == CYP_PARTIAL_TRUE ? CYP_PARTIAL_FALSE : CYP_PARTIAL_TRUE;
+    }
+    /* Same short-circuits as eval_expr: a definite left decides AND / OR. */
+    if (e->type == EXPR_AND && left == CYP_PARTIAL_FALSE) {
+        return CYP_PARTIAL_FALSE;
+    }
+    if (e->type == EXPR_OR && left == CYP_PARTIAL_TRUE) {
+        return CYP_PARTIAL_TRUE;
+    }
+    cyp_partial_t right = eval_expr_partial(e->right, b);
+    if (e->type == EXPR_AND) {
+        return partial_and(left, right);
+    }
+    if (e->type == EXPR_OR) {
+        return partial_or(left, right);
+    }
+    /* EXPR_XOR */
+    if (left == CYP_PARTIAL_UNKNOWN || right == CYP_PARTIAL_UNKNOWN) {
+        return CYP_PARTIAL_UNKNOWN;
+    }
+    return left != right ? CYP_PARTIAL_TRUE : CYP_PARTIAL_FALSE;
+}
+
+static cyp_partial_t eval_where_partial(const cbm_where_clause_t *w, binding_t *b) {
+    if (!w) {
+        return CYP_PARTIAL_TRUE;
+    }
+    if (w->root) {
+        return eval_expr_partial(w->root, b);
+    }
+    /* Legacy flat evaluation */
+    if (w->count == 0) {
+        return CYP_PARTIAL_TRUE;
+    }
+    bool is_and = (w->op && strcmp(w->op, "AND") == 0) != 0;
+    cyp_partial_t result = is_and ? CYP_PARTIAL_TRUE : CYP_PARTIAL_FALSE;
+    for (int i = 0; i < w->count; i++) {
+        cyp_partial_t r = eval_condition_partial(&w->conditions[i], b);
+        result = is_and ? partial_and(result, r) : partial_or(result, r);
+    }
+    return result;
+}
+
 /* Check if a string value looks like a regex pattern. */
 static bool looks_like_regex(const char *s) {
     if (!s) {
@@ -3751,6 +3848,10 @@ static void distinct_list_add(char ***list, int *count, const char *val) {
     }
     int idx = (*count)++;
     *list = safe_realloc(*list, (size_t)(idx + SKIP_ONE) * sizeof(char *));
+    if (!*list) {
+        *count = 0; /* safe_realloc freed the old list */
+        return;
+    }
     (*list)[idx] = heap_strdup(val);
 }
 
@@ -3908,12 +4009,35 @@ static int with_agg_find_or_create(with_agg_t **aggs, int *agg_cnt, int *agg_cap
     return found;
 }
 
+/* True when the aggregate's argument is bound (COUNT skips unbound OPTIONAL). */
+static bool binding_has_value(binding_t *b, const char *var, const char *prop) {
+    if (!var || strcmp(var, "*") == 0) {
+        return true;
+    }
+    char full[CBM_SZ_256];
+    if (prop) {
+        (void)snprintf(full, sizeof(full), "%s.%s", var, prop);
+    } else {
+        (void)snprintf(full, sizeof(full), "%s", var);
+    }
+    for (int i = 0; i < b->var_count; i++) {
+        if (strcmp(b->var_names[i], full) == 0) {
+            return true;
+        }
+    }
+    return binding_get_edge(b, var) != NULL || binding_get(b, var) != NULL;
+}
+
 /* Accumulate aggregation values for a binding */
 static void with_agg_accumulate(with_agg_t *agg, cbm_return_clause_t *wc, binding_t *b) {
     for (int ci = 0; ci < wc->count; ci++) {
         if (!is_aggregate_func(wc->items[ci].func)) {
             continue;
         }
+        if (strcmp(wc->items[ci].func, "COUNT") == 0 &&
+            !binding_has_value(b, wc->items[ci].variable, wc->items[ci].property)) {
+            continue;
+        }
         agg->counts[ci]++;
         const char *raw = binding_get_virtual(b, wc->items[ci].variable, wc->items[ci].property);
         if (wc->items[ci].distinct && strcmp(wc->items[ci].func, "COUNT") == 0) {
@@ -4347,6 +4471,10 @@ static void ret_agg_accumulate(ret_agg_entry_t *entry, cbm_return_clause_t *ret,
         if (!is_aggregate_func(ret->items[ci].func)) {
             continue;
         }
+        if (strcmp(ret->items[ci].func, "COUNT") == 0 &&
+            !binding_has_value(b, ret->items[ci].variable, ret->items[ci].property)) {
+            continue;
+        }
         entry->counts[ci]++;
         const char *raw = binding_get_virtual(b, ret->items[ci].variable, ret->items[ci].property);
         double dv = strtod(raw, NULL);
@@ -4885,7 +5013,7 @@ static int execute_single(cbm_store_t *store, cbm_query_t *q, const char *projec
         binding_t b = {0};
         b.store = store;
         binding_set(&b, var_name, &scanned[i]);
-        bool pass = !q->where || eval_where(q->where, &b);
+        bool pass = eval_where_partial(q->where, &b) != CYP_PARTIAL_FALSE;
         if (pass) {
             bindings[bind_count++] = b;
         } else {

src/foundation/recursion_whitelist.h

@@ -8,8 +8,8 @@
  *   - parse_or_expr, parse_xor_expr, parse_and_expr, parse_not_expr
  *   - parse_atom_expr, parse_post_where, cbm_parse
  *
- * Cypher expression evaluator (bounded by WHERE clause depth ~5):
- *   - eval_expr
+ * Cypher expression evaluators (bounded by WHERE clause depth ~5):
+ *   - eval_expr, eval_expr_partial
  *
  * Glob pattern matcher (bounded by pattern nesting ~3):
  *   - glob_match, glob_match_star, glob_match_doublestar
@@ -25,9 +25,9 @@
  * To add a function: add it below AND add NOLINT(misc-no-recursion) on
  * the function definition line. The lint gate verifies both match.
  */
-#define CBM_RECURSION_WHITELIST                                                               \
-    "parse_or_expr", "parse_xor_expr", "parse_and_expr", "parse_not_expr", "parse_atom_expr", \
-        "parse_post_where", "cbm_parse", "eval_expr", "glob_match", "glob_match_star",        \
-        "glob_match_doublestar", "glob_match_doublestar_slash", "glob_match_doublestar_any",  \
-        "parse_bool_expr", "parse_bool_atom", "r_collect_imports",                            \
+#define CBM_RECURSION_WHITELIST                                                                 \
+    "parse_or_expr", "parse_xor_expr", "parse_and_expr", "parse_not_expr", "parse_atom_expr",   \
+        "parse_post_where", "cbm_parse", "eval_expr", "eval_expr_partial", "glob_match",        \
+        "glob_match_star", "glob_match_doublestar", "glob_match_doublestar_slash",              \
+        "glob_match_doublestar_any", "parse_bool_expr", "parse_bool_atom", "r_collect_imports", \
         "find_first_descendant_by_kind", "find_first_descendant_of"

tests/test_cypher.c

@@ -1673,6 +1673,59 @@ TEST(cypher_exec_count) {
     PASS();
 }
 
+TEST(cypher_exec_optional_bound_terminal_count_ignores_unbound) {
+    cbm_store_t *s = setup_cypher_store();
+    cbm_cypher_result_t r = {0};
+
+    int rc = cbm_cypher_execute(s,
+                                "MATCH (f:Function) OPTIONAL MATCH (t)-[:CALLS]->(f) "
+                                "RETURN f.name, COUNT(t) AS cnt",
+                                "test", 0, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 4);
+
+    for (int i = 0; i < r.row_count; i++) {
+        const char *name = r.rows[i][0];
+        const char *count = r.rows[i][1];
+        if (strcmp(name, "HandleOrder") == 0) {
+            ASSERT_STR_EQ(count, "0");
+        } else if (strcmp(name, "ValidateOrder") == 0 || strcmp(name, "SubmitOrder") == 0 ||
+                   strcmp(name, "LogError") == 0) {
+            ASSERT_STR_EQ(count, "1");
+        } else {
+            ASSERT_TRUE(false);
+        }
+    }
+
+    cbm_cypher_result_free(&r);
+    cbm_store_close(s);
+    PASS();
+}
+
+TEST(cypher_exec_with_optional_bound_terminal_count_ignores_unbound) {
+    cbm_store_t *s = setup_cypher_store();
+    cbm_cypher_result_t r = {0};
+
+    int rc = cbm_cypher_execute(s,
+                                "MATCH (f:Function) OPTIONAL MATCH (t)-[:CALLS]->(f) "
+                                "WITH f, COUNT(t) AS c RETURN f.name, c",
+                                "test", 0, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 4);
+
+    for (int i = 0; i < r.row_count; i++) {
+        if (strcmp(r.rows[i][0], "HandleOrder") == 0) {
+            ASSERT_STR_EQ(r.rows[i][1], "0");
+        } else {
+            ASSERT_STR_EQ(r.rows[i][1], "1");
+        }
+    }
+
+    cbm_cypher_result_free(&r);
+    cbm_store_close(s);
+    PASS();
+}
+
 TEST(cypher_exec_limit) {
     cbm_store_t *s = setup_cypher_store();
     cbm_cypher_result_t r = {0};
@@ -2078,9 +2131,10 @@ TEST(cypher_optional_match_target_still_allowed_issue1919) {
 TEST(cypher_with_alias_stays_in_scope_issue1919) {
     cbm_store_t *s = setup_cypher_store();
     cbm_cypher_result_t r = {0};
-    int rc = cbm_cypher_execute(
-        s, "MATCH (f:Function)-[:CALLS]->(g) WITH f.name AS caller, g AS callee RETURN caller, callee.name",
-        "test", 0, &r);
+    int rc = cbm_cypher_execute(s,
+                                "MATCH (f:Function)-[:CALLS]->(g) WITH f.name AS caller, g AS "
+                                "callee RETURN caller, callee.name",
+                                "test", 0, &r);
     ASSERT_EQ(rc, 0);
     ASSERT_NULL(r.error);
     ASSERT_TRUE(r.row_count > 0);
@@ -2828,6 +2882,91 @@ TEST(cypher_exec_where_not) {
     PASS();
 }
 
+/* Regression (distilled from PR #1245, Andrew Hundt): the early WHERE pass in
+ * execute_single runs on seed rows with only the first alias bound. A
+ * comparison on an unbound alias used to evaluate to true, which NOT / XOR
+ * then inverted -- so every seed was pruned before CALLS expansion and the
+ * query returned zero rows. Unbound leaves must stay UNKNOWN there. */
+TEST(cypher_exec_where_not_on_relationship_target) {
+    cbm_store_t *s = setup_cypher_store();
+    cbm_cypher_result_t r = {0};
+    int rc = cbm_cypher_execute(s,
+                                "MATCH (a:Function)-[:CALLS]->(b:Function) "
+                                "WHERE NOT b.name CONTAINS \"Order\" RETURN b.name",
+                                "test", 0, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 1);
+    ASSERT_STR_EQ(r.rows[0][0], "LogError");
+    cbm_cypher_result_free(&r);
+    cbm_store_close(s);
+    PASS();
+}
+
+TEST(cypher_exec_where_mixed_alias_and) {
+    cbm_store_t *s = setup_cypher_store();
+    cbm_cypher_result_t r = {0};
+    int rc = cbm_cypher_execute(
+        s,
+        "MATCH (a:Function)-[:CALLS]->(b:Function) "
+        "WHERE a.name = \"HandleOrder\" AND NOT b.name CONTAINS \"Order\" RETURN b.name",
+        "test", 0, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 1);
+    ASSERT_STR_EQ(r.rows[0][0], "LogError");
+    cbm_cypher_result_free(&r);
+    cbm_store_close(s);
+    PASS();
+}
+
+TEST(cypher_exec_where_mixed_alias_or) {
+    cbm_store_t *s = setup_cypher_store();
+    cbm_cypher_result_t r = {0};
+    int rc = cbm_cypher_execute(
+        s,
+        "MATCH (a:Function)-[:CALLS]->(b:Function) "
+        "WHERE a.name = \"NoSuchFunction\" OR NOT b.name CONTAINS \"Order\" RETURN b.name",
+        "test", 0, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 1);
+    ASSERT_STR_EQ(r.rows[0][0], "LogError");
+    cbm_cypher_result_free(&r);
+    cbm_store_close(s);
+    PASS();
+}
+
+TEST(cypher_exec_where_mixed_alias_xor) {
+    cbm_store_t *s = setup_cypher_store();
+    cbm_cypher_result_t r = {0};
+    int rc =
+        cbm_cypher_execute(s,
+                           "MATCH (a:Function)-[:CALLS]->(b:Function) "
+                           "WHERE a.name = \"HandleOrder\" XOR b.name = \"LogError\" RETURN b.name",
+                           "test", 0, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 1);
+    ASSERT_STR_EQ(r.rows[0][0], "ValidateOrder");
+    cbm_cypher_result_free(&r);
+    cbm_store_close(s);
+    PASS();
+}
+
+/* coalesce(a.nosuch, b.name) has first variable a (bound in the seed) but also
+ * needs b; the early pass must treat it as UNKNOWN, not evaluate b as "". */
+TEST(cypher_exec_where_coalesce_multi_alias) {
+    cbm_store_t *s = setup_cypher_store();
+    cbm_cypher_result_t r = {0};
+    int rc = cbm_cypher_execute(s,
+                                "MATCH (a:Function)-[:CALLS]->(b:Function) "
+                                "WHERE coalesce(a.nosuch, b.name) = \"LogError\" RETURN b.name",
+                                "test", 0, &r);
+    ASSERT_EQ(rc, 0);
+    ASSERT_EQ(r.row_count, 1);
+    ASSERT_STR_EQ(r.rows[0][0], "LogError");
+    cbm_cypher_result_free(&r);
+    cbm_store_close(s);
+    PASS();
+}
+
 TEST(cypher_exec_where_in) {
     cbm_store_t *s = setup_cypher_store();
     cbm_cypher_result_t r = {0};
@@ -4368,6 +4507,8 @@ SUITE(cypher) {
     RUN_TEST(cypher_exec_calls_with_where);
     RUN_TEST(cypher_exec_inbound);
     RUN_TEST(cypher_exec_count);
+    RUN_TEST(cypher_exec_optional_bound_terminal_count_ignores_unbound);
+    RUN_TEST(cypher_exec_with_optional_bound_terminal_count_ignores_unbound);
     RUN_TEST(cypher_exec_limit);
     RUN_TEST(cypher_exec_order_by);
     RUN_TEST(cypher_exec_variable_length);
@@ -4418,6 +4559,11 @@ SUITE(cypher) {
     RUN_TEST(cypher_exec_where_neq_bang);
     RUN_TEST(cypher_exec_where_ends_with);
     RUN_TEST(cypher_exec_where_not);
+    RUN_TEST(cypher_exec_where_not_on_relationship_target);
+    RUN_TEST(cypher_exec_where_mixed_alias_and);
+    RUN_TEST(cypher_exec_where_mixed_alias_or);
+    RUN_TEST(cypher_exec_where_mixed_alias_xor);
+    RUN_TEST(cypher_exec_where_coalesce_multi_alias);
     RUN_TEST(cypher_exec_where_in);
     RUN_TEST(cypher_exec_where_not_in);
     RUN_TEST(cypher_exec_where_is_null);