feat: Add keyword/string type coercion to where clause comparisons (#232) (#233)

Implement automatic coercion of keywords to strings in equality operators (=, not=),
and membership operators (in, includes). This improves LLM ergonomics by allowing
keywords generated by LLMs to match string data values without explicit conversion.

- Add normalize_for_comparison helper to coerce non-boolean atoms to strings
- Update safe_eq, safe_in, safe_includes to use coercion
- Exclude booleans from coercion (true/false do not coerce to strings)
- Add comprehensive tests covering keyword/string matching
- Document coercion behavior in Section 7.1 of ptc-lisp-specification.md
- Note that ordering comparisons (>, <, >=, <=) do NOT coerce

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Author: 3 people

docs/ptc-lisp-specification.md

@@ -478,6 +478,25 @@ Check if field is truthy (not `nil` or `false`):
 (where [:user :premium])  ; nested truthy check
 ```
 
+#### Keyword/String Coercion
+
+For the equality operators (`=`, `not=`), `in`, and `includes`, keywords are coerced to strings for comparison. This allows LLM-generated keywords to match string data values:
+
+```clojure
+;; Keyword coerces to string
+(where :status = :active)        ; matches if field is "active"
+(where :status in [:active :pending])  ; both keywords coerce to strings
+(where :tags includes :urgent)   ; keyword "urgent" matches in ["urgent" "bug"]
+```
+
+**Coercion rules:**
+- Keywords (atoms that are not booleans) coerce to their string representation
+- `true` and `false` do **not** coerce (prevent `true` from matching `"true"`)
+- Empty keyword `:""` coerces to empty string `""`
+- Other types (`strings`, `numbers`, `nil`) are unchanged
+
+**Note:** Ordering comparisons (`>`, `<`, `>=`, `<=`) do **not** use coercion. Type mismatches return `false` (same as `nil` handling).
+
 ### 7.2 Combining Predicates
 
 Use `all-of`, `any-of`, `none-of` to combine predicate functions:

lib/ptc_runner/lisp/eval.ex

@@ -545,7 +545,12 @@ defmodule PtcRunner.Lisp.Eval do
   defp safe_eq(nil, nil), do: true
   defp safe_eq(nil, _), do: false
   defp safe_eq(_, nil), do: false
-  defp safe_eq(a, b), do: a == b
+
+  defp safe_eq(a, b) do
+    a_normalized = normalize_for_comparison(a)
+    b_normalized = normalize_for_comparison(b)
+    a_normalized == b_normalized
+  end
 
   defp safe_cmp(nil, _, _op), do: false
   defp safe_cmp(_, nil, _op), do: false
@@ -556,19 +561,42 @@ defmodule PtcRunner.Lisp.Eval do
 
   # `in` operator: field value is member of collection
   defp safe_in(nil, _coll), do: false
-  defp safe_in(value, coll) when is_list(coll), do: value in coll
+
+  defp safe_in(value, coll) when is_list(coll) do
+    normalized_value = normalize_for_comparison(value)
+
+    Enum.any?(coll, fn item ->
+      normalize_for_comparison(item) == normalized_value
+    end)
+  end
+
   defp safe_in(_, _), do: false
 
   # `includes` operator: collection includes value
   defp safe_includes(nil, _value), do: false
-  defp safe_includes(coll, value) when is_list(coll), do: value in coll
+
+  defp safe_includes(coll, value) when is_list(coll) do
+    normalized_value = normalize_for_comparison(value)
+
+    Enum.any?(coll, fn item ->
+      normalize_for_comparison(item) == normalized_value
+    end)
+  end
 
   defp safe_includes(coll, value) when is_binary(coll) and is_binary(value) do
     String.contains?(coll, value)
   end
 
   defp safe_includes(_, _), do: false
 
+  # Coerce keywords to strings for comparison, but preserve other types
+  # This allows LLM-generated keywords to match string data values
+  defp normalize_for_comparison(value) when is_atom(value) and not is_boolean(value) do
+    to_string(value)
+  end
+
+  defp normalize_for_comparison(value), do: value
+
   # Convert Lisp closures to Erlang functions for use with higher-order functions
   # The closure must have 1 parameter (enforced at evaluation time)
   defp closure_to_fun({:closure, patterns, body, closure_env}, ctx, memory, tool_exec) do

test/ptc_runner/lisp/flex_access_test.exs

@@ -60,4 +60,109 @@ defmodule PtcRunner.Lisp.FlexAccessTest do
                PtcRunner.Lisp.run(program, context: context)
     end
   end
+
+  describe "where clause with keyword/string coercion" do
+    test "where = coerces keyword to string for equality" do
+      program = ~S"(->> ctx/items (filter (where :status = :active)))"
+
+      context = %{
+        "items" => [
+          %{"status" => "active", "name" => "A"},
+          %{"status" => "inactive", "name" => "B"}
+        ]
+      }
+
+      assert {:ok, [%{"status" => "active", "name" => "A"}], _, _} =
+               PtcRunner.Lisp.run(program, context: context)
+    end
+
+    test "where not= with keyword/string coercion" do
+      program = ~S"(->> ctx/items (filter (where :status not= :active)))"
+
+      context = %{
+        "items" => [
+          %{"status" => "active", "name" => "A"},
+          %{"status" => "inactive", "name" => "B"}
+        ]
+      }
+
+      assert {:ok, [%{"status" => "inactive", "name" => "B"}], _, _} =
+               PtcRunner.Lisp.run(program, context: context)
+    end
+
+    test "where in coerces keywords in collection to strings" do
+      program = ~S"(->> ctx/items (filter (where :status in [:active :pending])))"
+
+      context = %{
+        "items" => [
+          %{"status" => "active", "name" => "A"},
+          %{"status" => "inactive", "name" => "B"},
+          %{"status" => "pending", "name" => "C"}
+        ]
+      }
+
+      assert {:ok,
+              [%{"status" => "active", "name" => "A"}, %{"status" => "pending", "name" => "C"}],
+              _, _} =
+               PtcRunner.Lisp.run(program, context: context)
+    end
+
+    test "where includes with list membership using keyword/string coercion" do
+      program = ~S"(->> ctx/items (filter (where :tags includes :urgent)))"
+
+      context = %{
+        "items" => [
+          %{"tags" => ["urgent", "bug"], "name" => "A"},
+          %{"tags" => ["feature"], "name" => "B"}
+        ]
+      }
+
+      assert {:ok, [%{"tags" => ["urgent", "bug"], "name" => "A"}], _, _} =
+               PtcRunner.Lisp.run(program, context: context)
+    end
+
+    test "where = does not coerce booleans" do
+      program = ~S"(->> ctx/items (filter (where :active = true)))"
+
+      context = %{
+        "items" => [
+          %{"active" => true, "name" => "A"},
+          %{"active" => "true", "name" => "B"}
+        ]
+      }
+
+      # Only the boolean true should match, not the string "true"
+      assert {:ok, [%{"active" => true, "name" => "A"}], _, _} =
+               PtcRunner.Lisp.run(program, context: context)
+    end
+
+    test "where = does not coerce false to string" do
+      program = ~S"(->> ctx/items (filter (where :active = false)))"
+
+      context = %{
+        "items" => [
+          %{"active" => false, "name" => "A"},
+          %{"active" => "false", "name" => "B"}
+        ]
+      }
+
+      # Only the boolean false should match, not the string "false"
+      assert {:ok, [%{"active" => false, "name" => "A"}], _, _} =
+               PtcRunner.Lisp.run(program, context: context)
+    end
+
+    test "where = coerces empty atom to empty string" do
+      program = ~S'(->> ctx/items (filter (where :value = "")))'
+
+      context = %{
+        "items" => [
+          %{"value" => "", "name" => "A"},
+          %{"value" => "nonempty", "name" => "B"}
+        ]
+      }
+
+      assert {:ok, [%{"value" => "", "name" => "A"}], _, _} =
+               PtcRunner.Lisp.run(program, context: context)
+    end
+  end
 end