feat: Validate tool function arities at registration time (#42) (#68)

* feat: Validate tool function arities at registration time

Move tool function arity validation from call-time to registration-time
(when tools are passed to PtcRunner.run/2). This provides earlier error
detection, better error messages, and fail-fast behavior for library users.

Changes:
- Add validate_tools/1 private function in PtcRunner to check all tools
  have arity 1 at registration time
- Update run/2 to validate tools before creating context
- Return {:error, {:validation_error, msg}} for invalid tools
- Error message identifies which tools have wrong arity
- Update existing test at line 3214 to expect validation_error
- Add 6 new tests covering:
  - Arity-0 and arity-2 function detection
  - Non-function value detection
  - Multiple invalid tools reporting
  - Valid arity-1 functions passing validation
  - Empty tools map handling

Fixes #42

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

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

* fix: Remove dead code in operations.ex

Remove unreachable catch-all branch that checked for non-arity-1 functions.
Since tools are now validated at registration time via validate_tools/1,
all tools in the registry are guaranteed to be arity-1 functions.

Changes:
- Remove guard clause 'when is_function(tool_fn, 1)' from pattern match
- Remove catch-all '_tool_fn' branch that is now unreachable
- Simplify case statement to only handle nil (not found) and tool_fn (execute)

🤖 Generated with Claude Code

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

---------

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

Author: 3 people

lib/ptc_runner.ex

@@ -67,14 +67,17 @@ defmodule PtcRunner do
          :ok <- Validator.validate(ast) do
       context_map = Keyword.get(opts, :context, %{})
       tools = Keyword.get(opts, :tools, %{})
-      context = Context.new(context_map, tools)
 
-      sandbox_opts = [
-        timeout: Keyword.get(opts, :timeout, 1000),
-        max_heap: Keyword.get(opts, :max_heap, 1_250_000)
-      ]
+      with :ok <- validate_tools(tools) do
+        context = Context.new(context_map, tools)
 
-      Sandbox.execute(ast, context, sandbox_opts)
+        sandbox_opts = [
+          timeout: Keyword.get(opts, :timeout, 1000),
+          max_heap: Keyword.get(opts, :max_heap, 1_250_000)
+        ]
+
+        Sandbox.execute(ast, context, sandbox_opts)
+      end
     else
       {:error, reason} -> {:error, reason}
     end
@@ -107,4 +110,21 @@ defmodule PtcRunner do
       {:error, reason} -> raise "PtcRunner error: #{inspect(reason)}"
     end
   end
+
+  defp validate_tools(tools) do
+    invalid_tools =
+      tools
+      |> Enum.reject(fn {_name, fun} -> is_function(fun, 1) end)
+      |> Enum.map(fn {name, _fun} -> name end)
+
+    case invalid_tools do
+      [] ->
+        :ok
+
+      names ->
+        {:error,
+         {:validation_error,
+          "Tools must be functions with arity 1. Invalid: #{Enum.join(names, ", ")}"}}
+    end
+  end
 end

lib/ptc_runner/operations.ex

@@ -369,7 +369,7 @@ defmodule PtcRunner.Operations do
       nil ->
         {:error, {:execution_error, "Tool '#{tool_name}' not found"}}
 
-      tool_fn when is_function(tool_fn, 1) ->
+      tool_fn ->
         try do
           case tool_fn.(args) do
             {:error, reason} ->
@@ -381,9 +381,6 @@ defmodule PtcRunner.Operations do
         rescue
           e -> {:error, {:execution_error, "Tool '#{tool_name}' raised: #{Exception.message(e)}"}}
         end
-
-      _tool_fn ->
-        {:error, {:execution_error, "Tool '#{tool_name}' is not a function with arity 1"}}
     end
   end
 

test/ptc_runner_test.exs

@@ -3221,8 +3221,74 @@ defmodule PtcRunnerTest do
         "tool": "wrong_arity"
       }})
 
-      {:error, {:execution_error, msg}} = PtcRunner.run(program, tools: tools)
-      assert String.contains?(msg, "is not a function with arity 1")
+      {:error, {:validation_error, msg}} = PtcRunner.run(program, tools: tools)
+      assert String.contains?(msg, "Tools must be functions with arity 1")
+      assert String.contains?(msg, "wrong_arity")
+    end
+
+    test "tool validation catches arity-2 function" do
+      tools = %{
+        "bad_tool" => fn _a, _b -> "two args" end
+      }
+
+      program = ~s({"program": {"op": "literal", "value": 42}})
+
+      {:error, {:validation_error, msg}} = PtcRunner.run(program, tools: tools)
+      assert String.contains?(msg, "Tools must be functions with arity 1")
+      assert String.contains?(msg, "bad_tool")
+    end
+
+    test "tool validation catches non-function values" do
+      tools = %{
+        "not_a_function" => "string value"
+      }
+
+      program = ~s({"program": {"op": "literal", "value": 42}})
+
+      {:error, {:validation_error, msg}} = PtcRunner.run(program, tools: tools)
+      assert String.contains?(msg, "Tools must be functions with arity 1")
+      assert String.contains?(msg, "not_a_function")
+    end
+
+    test "tool validation reports multiple invalid tools" do
+      tools = %{
+        "tool1" => fn -> "zero args" end,
+        "tool2" => "not a function",
+        "tool3" => fn _a, _b -> "two args" end,
+        "valid_tool" => fn _args -> "valid" end
+      }
+
+      program = ~s({"program": {"op": "literal", "value": 42}})
+
+      {:error, {:validation_error, msg}} = PtcRunner.run(program, tools: tools)
+      assert String.contains?(msg, "Tools must be functions with arity 1")
+      # All three invalid tools should be mentioned
+      assert String.contains?(msg, "tool1")
+      assert String.contains?(msg, "tool2")
+      assert String.contains?(msg, "tool3")
+    end
+
+    test "tool validation passes with valid arity-1 functions" do
+      tools = %{
+        "add" => fn %{"a" => a, "b" => b} -> a + b end,
+        "multiply" => fn %{"x" => x, "y" => y} -> x * y end
+      }
+
+      program = ~s({"program": {
+        "op": "call",
+        "tool": "add",
+        "args": {"a": 2, "b": 3}
+      }})
+
+      {:ok, result, _metrics} = PtcRunner.run(program, tools: tools)
+      assert result == 5
+    end
+
+    test "tool validation passes with empty tools map" do
+      program = ~s({"program": {"op": "literal", "value": 42}})
+
+      {:ok, result, _metrics} = PtcRunner.run(program, tools: %{})
+      assert result == 42
     end
 
     test "missing tool field raises validation error" do