Add plumbing for executor, async evaluation option. Define program API contracts

PiperOrigin-RevId: 975218617

Author: l46kok

.bazelrc

@@ -16,7 +16,7 @@ build --java_language_version=11
 common --javacopt=-Xlint:-options
 
 # Remove flag once https://github.com/google/cel-spec/issues/508 and rules_jvm_external is fixed.
-common --incompatible_autoload_externally=proto_library,cc_proto_library,java_proto_library,java_test
+common --incompatible_autoload_externally=proto_library,cc_proto_library,java_proto_library,java_test,java_import
 
 # Limit repository cache size by not caching extracted repository contents
 build --repo_contents_cache=

publish/BUILD.bazel

@@ -29,6 +29,10 @@ COMMON_TARGETS = [
 # keep sorted
 RUNTIME_TARGETS = [
     "//runtime/src/main/java/dev/cel/runtime",
+    "//runtime/src/main/java/dev/cel/runtime:async_call",
+    "//runtime/src/main/java/dev/cel/runtime:async_drain_strategy",
+    "//runtime/src/main/java/dev/cel/runtime:async_observer",
+    "//runtime/src/main/java/dev/cel/runtime:async_options",
     "//runtime/src/main/java/dev/cel/runtime:base",
     "//runtime/src/main/java/dev/cel/runtime:interpreter",
     "//runtime/src/main/java/dev/cel/runtime:late_function_binding",

runtime/BUILD.bazel

@@ -9,6 +9,10 @@ package(
 java_library(
     name = "runtime",
     exports = [
+        ":async_call",
+        ":async_drain_strategy",
+        ":async_observer",
+        ":async_options",
         ":descriptor_message_provider",
         ":evaluation_exception",
         ":function_overload",
@@ -340,6 +344,11 @@ java_library(
     exports = ["//runtime/src/main/java/dev/cel/runtime:function_overload"],
 )
 
+cel_android_library(
+    name = "function_overload_android",
+    exports = ["//runtime/src/main/java/dev/cel/runtime:function_overload_android"],
+)
+
 java_library(
     name = "descriptor_message_provider",
     visibility = ["//:internal"],
@@ -379,3 +388,43 @@ cel_android_library(
     name = "partial_vars_android",
     exports = ["//runtime/src/main/java/dev/cel/runtime:partial_vars_android"],
 )
+
+java_library(
+    name = "async_call",
+    exports = ["//runtime/src/main/java/dev/cel/runtime:async_call"],
+)
+
+cel_android_library(
+    name = "async_call_android",
+    exports = ["//runtime/src/main/java/dev/cel/runtime:async_call_android"],
+)
+
+java_library(
+    name = "async_drain_strategy",
+    exports = ["//runtime/src/main/java/dev/cel/runtime:async_drain_strategy"],
+)
+
+cel_android_library(
+    name = "async_drain_strategy_android",
+    exports = ["//runtime/src/main/java/dev/cel/runtime:async_drain_strategy_android"],
+)
+
+java_library(
+    name = "async_observer",
+    exports = ["//runtime/src/main/java/dev/cel/runtime:async_observer"],
+)
+
+cel_android_library(
+    name = "async_observer_android",
+    exports = ["//runtime/src/main/java/dev/cel/runtime:async_observer_android"],
+)
+
+java_library(
+    name = "async_options",
+    exports = ["//runtime/src/main/java/dev/cel/runtime:async_options"],
+)
+
+cel_android_library(
+    name = "async_options_android",
+    exports = ["//runtime/src/main/java/dev/cel/runtime:async_options_android"],
+)

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

@@ -784,6 +784,7 @@ cel_android_library(
 java_library(
     name = "function_overload",
     srcs = [
+        "CelAsyncFunctionOverload.java",
         "CelFunctionOverload.java",
         "OptimizedFunctionOverload.java",
     ],
@@ -800,9 +801,12 @@ java_library(
 cel_android_library(
     name = "function_overload_android",
     srcs = [
+        "CelAsyncFunctionOverload.java",
         "CelFunctionOverload.java",
         "OptimizedFunctionOverload.java",
     ],
+    tags = [
+    ],
     deps = [
         ":evaluation_exception",
         ":unknown_attributes_android",
@@ -817,6 +821,7 @@ java_library(
     tags = [
     ],
     deps = [
+        ":async_options",
         ":descriptor_type_resolver",
         ":dispatcher",
         ":evaluation_exception",
@@ -867,6 +872,7 @@ java_library(
     tags = [
     ],
     deps = [
+        ":async_options",
         ":descriptor_message_provider",
         ":descriptor_type_resolver",
         ":dispatcher",
@@ -922,6 +928,7 @@ java_library(
     ],
     deps = [
         ":activation",
+        ":async_options",
         ":evaluation_exception",
         ":evaluation_listener",
         ":function_binding",
@@ -946,6 +953,7 @@ java_library(
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
         "@maven//:com_google_protobuf_protobuf_java",
+        "@maven//:org_jspecify_jspecify",
     ],
 )
 
@@ -1277,17 +1285,134 @@ cel_android_library(
     ],
 )
 
+java_library(
+    name = "async_call",
+    srcs = ["CelAsyncCall.java"],
+    tags = [
+    ],
+    deps = [
+        "@maven//:com_google_code_findbugs_annotations",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:com_google_guava_guava",
+    ],
+)
+
+cel_android_library(
+    name = "async_call_android",
+    srcs = ["CelAsyncCall.java"],
+    tags = [
+    ],
+    deps = [
+        "@maven//:com_google_code_findbugs_annotations",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven_android//:com_google_guava_guava",
+    ],
+)
+
+java_library(
+    name = "async_drain_strategy",
+    srcs = [
+        "CelAsyncDrainAction.java",
+        "CelAsyncDrainStrategy.java",
+    ],
+    tags = [
+    ],
+    deps = [
+        ":async_call",
+        "//:auto_value",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:com_google_guava_guava",
+    ],
+)
+
+cel_android_library(
+    name = "async_drain_strategy_android",
+    srcs = [
+        "CelAsyncDrainAction.java",
+        "CelAsyncDrainStrategy.java",
+    ],
+    tags = [
+    ],
+    deps = [
+        ":async_call_android",
+        "//:auto_value",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven_android//:com_google_guava_guava",
+    ],
+)
+
+java_library(
+    name = "async_observer",
+    srcs = ["CelAsyncObserver.java"],
+    tags = [
+    ],
+    deps = [
+        ":async_call",
+        "@maven//:com_google_code_findbugs_annotations",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:org_jspecify_jspecify",
+    ],
+)
+
+cel_android_library(
+    name = "async_observer_android",
+    srcs = ["CelAsyncObserver.java"],
+    tags = [
+    ],
+    deps = [
+        ":async_call_android",
+        "@maven//:com_google_code_findbugs_annotations",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:org_jspecify_jspecify",
+    ],
+)
+
+java_library(
+    name = "async_options",
+    srcs = ["CelAsyncEvaluationOptions.java"],
+    tags = [
+    ],
+    deps = [
+        ":async_drain_strategy",
+        ":async_observer",
+        "//:auto_value",
+        "@maven//:com_google_code_findbugs_annotations",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:org_jspecify_jspecify",
+    ],
+)
+
+cel_android_library(
+    name = "async_options_android",
+    srcs = ["CelAsyncEvaluationOptions.java"],
+    tags = [
+    ],
+    deps = [
+        ":async_drain_strategy_android",
+        ":async_observer_android",
+        "//:auto_value",
+        "@maven//:com_google_code_findbugs_annotations",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:org_jspecify_jspecify",
+    ],
+)
+
 java_library(
     name = "program",
     srcs = ["Program.java"],
     tags = [
     ],
     deps = [
+        ":activation",
         ":evaluation_exception",
         ":function_resolver",
+        ":interpretable",
         ":partial_vars",
         ":variable_resolver",
+        "//common/annotations",
         "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:com_google_guava_guava",
+        "@maven//:org_jspecify_jspecify",
     ],
 )
 
@@ -1297,11 +1422,16 @@ cel_android_library(
     tags = [
     ],
     deps = [
+        ":activation_android",
         ":evaluation_exception",
         ":function_resolver_android",
+        ":interpretable_android",
         ":partial_vars_android",
         ":variable_resolver",
+        "//common/annotations",
         "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:org_jspecify_jspecify",
+        "@maven_android//:com_google_guava_guava",
     ],
 )
 

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

@@ -0,0 +1,42 @@
+// 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.runtime;
+
+import com.google.common.collect.ImmutableList;
+import javax.annotation.concurrent.ThreadSafe;
+import java.time.Duration;
+
+/** Describes a pending or completed asynchronous function call. */
+@ThreadSafe
+public interface CelAsyncCall {
+
+  /** Returns the unique incremental tracking ID assigned to this call. */
+  long callId();
+
+  /** Returns the AST expression node ID where the call is located. */
+  long exprId();
+
+  /** Returns the name of the function being invoked. */
+  String functionName();
+
+  /** Returns the specific overload ID being invoked. */
+  String overloadId();
+
+  /** Returns the arguments passed to the function call. */
+  ImmutableList<Object> arguments();
+
+  /** Returns the elapsed duration of the async function execution. */
+  Duration elapsedDuration();
+}

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

@@ -0,0 +1,57 @@
+// 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.runtime;
+
+import static com.google.common.base.Preconditions.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.auto.value.AutoValue;
+import com.google.errorprone.annotations.Immutable;
+import java.time.Duration;
+
+/** Dictates what asynchronous evaluation should do after inspecting completions. */
+@AutoValue
+@Immutable
+public abstract class CelAsyncDrainAction {
+
+  CelAsyncDrainAction() {}
+
+  /** Indicates that the AST should be re-evaluated immediately. */
+  public abstract boolean shouldReevaluate();
+
+  /**
+   * Indicates how long the evaluator should wait for additional completions before deciding to
+   * re-evaluate. A duration of ZERO with reevaluate=false means wait indefinitely for the next
+   * completion.
+   */
+  public abstract Duration waitDuration();
+
+  public static CelAsyncDrainAction waitDuration(Duration duration) {
+    checkNotNull(duration);
+    checkArgument(!duration.isNegative(), "duration must not be negative");
+    if (duration.isZero()) {
+      return reevaluate();
+    }
+    return new AutoValue_CelAsyncDrainAction(false, duration);
+  }
+
+  public static CelAsyncDrainAction reevaluate() {
+    return new AutoValue_CelAsyncDrainAction(true, Duration.ZERO);
+  }
+
+  public static CelAsyncDrainAction waitForMore() {
+    return new AutoValue_CelAsyncDrainAction(false, Duration.ZERO);
+  }
+}