Plan late function bindings, add CelOverloadNotFound exception

PiperOrigin-RevId: 853788116

Author: l46kok

common/exceptions/BUILD.bazel

@@ -52,3 +52,9 @@ java_library(
     # used_by_android
     exports = ["//common/src/main/java/dev/cel/common/exceptions:iteration_budget_exceeded"],
 )
+
+java_library(
+    name = "overload_not_found",
+    # used_by_android
+    exports = ["//common/src/main/java/dev/cel/common/exceptions:overload_not_found"],
+)

common/src/main/java/dev/cel/common/exceptions/BUILD.bazel

@@ -110,3 +110,16 @@ java_library(
         "//common/annotations",
     ],
 )
+
+java_library(
+    name = "overload_not_found",
+    srcs = ["CelOverloadNotFoundException.java"],
+    # used_by_android
+    tags = [
+    ],
+    deps = [
+        ":runtime_exception",
+        "//common:error_codes",
+        "//common/annotations",
+    ],
+)

common/src/main/java/dev/cel/common/exceptions/CelOverloadNotFoundException.java

@@ -0,0 +1,43 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package dev.cel.common.exceptions;
+
+import dev.cel.common.CelErrorCode;
+import dev.cel.common.annotations.Internal;
+import java.util.Collection;
+import java.util.Collections;
+
+/** Indicates that a matching overload could not be found during function dispatch. */
+@Internal
+public final class CelOverloadNotFoundException extends CelRuntimeException {
+
+  public CelOverloadNotFoundException(String functionName) {
+    this(functionName, Collections.emptyList());
+  }
+
+  public CelOverloadNotFoundException(String functionName, Collection<String> overloadIds) {
+    super(formatErrorMessage(functionName, overloadIds), CelErrorCode.OVERLOAD_NOT_FOUND);
+  }
+
+  private static String formatErrorMessage(String functionName, Collection<String> overloadIds) {
+    StringBuilder sb = new StringBuilder();
+    sb.append("No matching overload for function '").append(functionName).append("'.");
+    if (!overloadIds.isEmpty()) {
+      sb.append(" Overload candidates: ").append(String.join(", ", overloadIds));
+    }
+
+    return sb.toString();
+  }
+}

runtime/BUILD.bazel

@@ -16,6 +16,7 @@ java_library(
         "//runtime/src/main/java/dev/cel/runtime:descriptor_message_provider",
         "//runtime/src/main/java/dev/cel/runtime:function_overload",
         "//runtime/src/main/java/dev/cel/runtime:runtime_type_provider",
+        "//runtime/src/main/java/dev/cel/runtime:variable_resolver",
     ],
 )
 
@@ -263,3 +264,10 @@ java_library(
         "//runtime/src/main/java/dev/cel/runtime:concatenated_list_view",
     ],
 )
+
+java_library(
+    name = "variable_resolver",
+    exports = [
+        "//runtime/src/main/java/dev/cel/runtime:variable_resolver",
+    ],
+)

runtime/src/main/java/dev/cel/runtime/BUILD.bazel

@@ -129,6 +129,7 @@ java_library(
         "//:auto_value",
         "//common:error_codes",
         "//common/annotations",
+        "//common/exceptions:overload_not_found",
         "@maven//:com_google_code_findbugs_annotations",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
@@ -149,6 +150,7 @@ cel_android_library(
         "//:auto_value",
         "//common:error_codes",
         "//common/annotations",
+        "//common/exceptions:overload_not_found",
         "@maven//:com_google_code_findbugs_annotations",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven_android//:com_google_guava_guava",
@@ -477,8 +479,6 @@ RUNTIME_SOURCES = [
     "CelRuntimeFactory.java",
     "CelRuntimeLegacyImpl.java",
     "CelRuntimeLibrary.java",
-    "CelVariableResolver.java",
-    "HierarchicalVariableResolver.java",
     "ProgramImpl.java",
     "UnknownContext.java",
 ]
@@ -729,6 +729,7 @@ java_library(
     deps = [
         ":evaluation_exception",
         ":function_overload",
+        "//common/exceptions:overload_not_found",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
     ],
@@ -742,6 +743,7 @@ cel_android_library(
     deps = [
         ":evaluation_exception",
         ":function_overload_android",
+        "//common/exceptions:overload_not_found",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven_android//:com_google_guava_guava",
     ],
@@ -836,6 +838,7 @@ java_library(
         "//common/types:cel_types",
         "//common/values:cel_value_provider",
         "//common/values:proto_message_value_provider",
+        "//runtime:variable_resolver",
         "//runtime/standard:add",
         "//runtime/standard:int",
         "//runtime/standard:timestamp",
@@ -904,6 +907,7 @@ java_library(
         ":interpretable",
         ":program",
         "//:auto_value",
+        "//runtime:variable_resolver",
         "@maven//:com_google_errorprone_error_prone_annotations",
     ],
 )
@@ -917,6 +921,7 @@ cel_android_library(
         ":function_resolver_android",
         ":interpretable_android",
         ":program_android",
+        ":variable_resolver",
         "//:auto_value",
         "@maven//:com_google_errorprone_error_prone_annotations",
     ],
@@ -1204,6 +1209,19 @@ cel_android_library(
     ],
 )
 
+java_library(
+    name = "variable_resolver",
+    srcs = [
+        "CelVariableResolver.java",
+        "HierarchicalVariableResolver.java",
+    ],
+    # used_by_android
+    tags = [
+    ],
+    deps = [
+    ],
+)
+
 java_library(
     name = "program",
     srcs = ["Program.java"],
@@ -1212,6 +1230,7 @@ java_library(
     deps = [
         ":evaluation_exception",
         ":function_resolver",
+        ":variable_resolver",
         "@maven//:com_google_errorprone_error_prone_annotations",
     ],
 )
@@ -1224,6 +1243,7 @@ cel_android_library(
     deps = [
         ":evaluation_exception",
         ":function_resolver_android",
+        ":variable_resolver",
         "//:auto_value",
         "@maven//:com_google_errorprone_error_prone_annotations",
     ],

runtime/src/main/java/dev/cel/runtime/CelFunctionResolver.java

@@ -15,7 +15,7 @@
 package dev.cel.runtime;
 
 import javax.annotation.concurrent.ThreadSafe;
-import java.util.List;
+import java.util.Collection;
 import java.util.Optional;
 
 /**
@@ -36,5 +36,18 @@ public interface CelFunctionResolver {
    * @throws CelEvaluationException if the overload resolution is ambiguous,
    */
   Optional<CelResolvedOverload> findOverloadMatchingArgs(
-      String functionName, List<String> overloadIds, Object[] args) throws CelEvaluationException;
+      String functionName, Collection<String> overloadIds, Object[] args)
+      throws CelEvaluationException;
+
+  /**
+   * Finds a specific function overload to invoke based on given parameters, scanning all available
+   * overloads if necessary.
+   *
+   * @param functionName the logical name of the function being invoked.
+   * @param args The arguments to pass to the function.
+   * @return an optional value of the resolved overload.
+   * @throws CelEvaluationException if the overload resolution is ambiguous.
+   */
+  Optional<CelResolvedOverload> findOverloadMatchingArgs(String functionName, Object[] args)
+      throws CelEvaluationException;
 }

runtime/src/main/java/dev/cel/runtime/CelLateFunctionBindings.java

@@ -19,7 +19,7 @@
 import com.google.common.collect.ImmutableMap;
 import com.google.errorprone.annotations.Immutable;
 import java.util.Arrays;
-import java.util.List;
+import java.util.Collection;
 import java.util.Optional;
 
 /**
@@ -37,15 +37,23 @@ private CelLateFunctionBindings(ImmutableMap<String, CelResolvedOverload> functi
 
   @Override
   public Optional<CelResolvedOverload> findOverloadMatchingArgs(
-      String functionName, List<String> overloadIds, Object[] args) throws CelEvaluationException {
+      String functionName, Collection<String> overloadIds, Object[] args)
+      throws CelEvaluationException {
     return DefaultDispatcher.findOverloadMatchingArgs(functionName, overloadIds, functions, args);
   }
 
+  @Override
+  public Optional<CelResolvedOverload> findOverloadMatchingArgs(String functionName, Object[] args)
+      throws CelEvaluationException {
+    return DefaultDispatcher.findOverloadMatchingArgs(
+        functionName, functions.keySet(), functions, args);
+  }
+
   public static CelLateFunctionBindings from(CelFunctionBinding... functions) {
     return from(Arrays.asList(functions));
   }
 
-  public static CelLateFunctionBindings from(List<CelFunctionBinding> functions) {
+  public static CelLateFunctionBindings from(Collection<CelFunctionBinding> functions) {
     return new CelLateFunctionBindings(
         functions.stream()
             .collect(

runtime/src/main/java/dev/cel/runtime/CelRuntime.java

@@ -42,16 +42,6 @@ interface Program extends dev.cel.runtime.Program {
     /** Evaluate the expression using {@code message} fields as the source of input variables. */
     Object eval(Message message) throws CelEvaluationException;
 
-    /** Evaluate a compiled program with a custom variable {@code resolver}. */
-    Object eval(CelVariableResolver resolver) throws CelEvaluationException;
-
-    /**
-     * Evaluate a compiled program with a custom variable {@code resolver} and late-bound functions
-     * {@code lateBoundFunctionResolver}.
-     */
-    Object eval(CelVariableResolver resolver, CelFunctionResolver lateBoundFunctionResolver)
-        throws CelEvaluationException;
-
     /**
      * Trace evaluates a compiled program without any variables and invokes the listener as
      * evaluation progresses through the AST.

runtime/src/main/java/dev/cel/runtime/DefaultDispatcher.java

@@ -25,8 +25,10 @@
 import com.google.errorprone.annotations.Immutable;
 import dev.cel.common.CelErrorCode;
 import dev.cel.common.annotations.Internal;
+import dev.cel.common.exceptions.CelOverloadNotFoundException;
 import dev.cel.runtime.FunctionBindingImpl.DynamicDispatchOverload;
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
@@ -46,16 +48,23 @@ public Optional<CelResolvedOverload> findOverload(String functionName) {
     return Optional.ofNullable(overloads.get(functionName));
   }
 
+  @Override
+  public Optional<CelResolvedOverload> findOverloadMatchingArgs(String functionName, Object[] args)
+      throws CelEvaluationException {
+    return findOverloadMatchingArgs(functionName, overloads.keySet(), overloads, args);
+  }
+
   @Override
   public Optional<CelResolvedOverload> findOverloadMatchingArgs(
-      String functionName, List<String> overloadIds, Object[] args) throws CelEvaluationException {
+      String functionName, Collection<String> overloadIds, Object[] args)
+      throws CelEvaluationException {
     return findOverloadMatchingArgs(functionName, overloadIds, overloads, args);
   }
 
   /** Finds the overload that matches the given function name, overload IDs, and arguments. */
   static Optional<CelResolvedOverload> findOverloadMatchingArgs(
       String functionName,
-      List<String> overloadIds,
+      Collection<String> overloadIds,
       Map<String, ? extends CelResolvedOverload> overloads,
       Object[] args)
       throws CelEvaluationException {
@@ -165,7 +174,7 @@ private static Object guardedOp(
       return overload.apply(args);
     }
 
-    throw new IllegalArgumentException("No matching overload for function: " + functionName);
+    throw new CelOverloadNotFoundException(functionName);
   }
 
   DefaultDispatcher(ImmutableMap<String, CelResolvedOverload> overloads) {

runtime/src/main/java/dev/cel/runtime/FunctionBindingImpl.java

@@ -14,10 +14,13 @@
 
 package dev.cel.runtime;
 
+import static com.google.common.collect.ImmutableList.toImmutableList;
+
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableSet;
 import com.google.common.collect.Iterables;
 import com.google.errorprone.annotations.Immutable;
+import dev.cel.common.exceptions.CelOverloadNotFoundException;
 
 @Immutable
 final class FunctionBindingImpl implements CelFunctionBinding {
@@ -135,7 +138,11 @@ public Object apply(Object[] args) throws CelEvaluationException {
         }
       }
 
-      throw new IllegalArgumentException("No matching overload for function: " + functionName);
+      throw new CelOverloadNotFoundException(
+          functionName,
+          overloadBindings.stream()
+              .map(CelFunctionBinding::getOverloadId)
+              .collect(toImmutableList()));
     }
 
     private DynamicDispatchOverload(