Add AsyncCallKey and AsyncCallRecord primitives for async evaluation.

PiperOrigin-RevId: 982639852

Author: l46kok

runtime/planner/BUILD.bazel

@@ -35,3 +35,9 @@ java_library(
     visibility = ["//:internal"],
     exports = ["//runtime/src/main/java/dev/cel/runtime/planner:async_completion_coordinator"],
 )
+
+java_library(
+    name = "async_call_state_tracker",
+    visibility = ["//:internal"],
+    exports = ["//runtime/src/main/java/dev/cel/runtime/planner:async_call_state_tracker"],
+)

runtime/src/main/java/dev/cel/runtime/planner/AsyncCallKey.java

@@ -0,0 +1,320 @@
+// 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.planner;
+
+import static java.util.Objects.requireNonNull;
+
+import dev.cel.runtime.RuntimeEquality;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.Iterator;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+import java.util.function.BiPredicate;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Unique cache key for an asynchronous function invocation at a given AST expression node.
+ *
+ * <p>Equality delegates to {@link RuntimeEquality}, except that {@link Double#NaN} and {@link
+ * Float#NaN} argument values compare equal (and signed zero is normalized) across all arguments and
+ * nested collections/maps so that re-evaluating a node with a NaN argument hits its existing call
+ * record.
+ */
+final class AsyncCallKey {
+  private final long exprId;
+  private final String functionName;
+  private final String overloadId;
+  private final Object[] args;
+  private final RuntimeEquality runtimeEquality;
+  private final int hashCode;
+
+  static AsyncCallKey create(
+      long exprId,
+      String functionName,
+      String overloadId,
+      Object[] args,
+      RuntimeEquality runtimeEquality) {
+    return new AsyncCallKey(exprId, functionName, overloadId, args, runtimeEquality);
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) {
+      return true;
+    }
+    if (!(o instanceof AsyncCallKey)) {
+      return false;
+    }
+    AsyncCallKey other = (AsyncCallKey) o;
+    if (exprId != other.exprId
+        || !functionName.equals(other.functionName)
+        || !overloadId.equals(other.overloadId)
+        || args.length != other.args.length) {
+      return false;
+    }
+    for (int i = 0; i < args.length; i++) {
+      if (!argEquals(args[i], other.args[i], runtimeEquality)) {
+        return false;
+      }
+      if (!Objects.equals(runtimeEquality, other.runtimeEquality)
+          && !argEquals(other.args[i], args[i], other.runtimeEquality)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  @Override
+  public int hashCode() {
+    return hashCode;
+  }
+
+  @SuppressWarnings("ReferenceEquality") // Fast path for identical object references.
+  private static boolean argEquals(
+      @Nullable Object a, @Nullable Object b, RuntimeEquality runtimeEquality) {
+    if (a == b) {
+      return true;
+    }
+    if (a == null || b == null) {
+      return false;
+    }
+    if (a instanceof Number || b instanceof Number) {
+      return a instanceof Number
+          && b instanceof Number
+          && numberEquals((Number) a, (Number) b, runtimeEquality);
+    }
+    if (a instanceof Set || b instanceof Set) {
+      return a instanceof Set
+          && b instanceof Set
+          && setEquals((Set<?>) a, (Set<?>) b, runtimeEquality);
+    }
+    if (a instanceof Iterable || b instanceof Iterable) {
+      return a instanceof Iterable
+          && b instanceof Iterable
+          && iterableEquals((Iterable<?>) a, (Iterable<?>) b, runtimeEquality);
+    }
+    if (a instanceof Map || b instanceof Map) {
+      return a instanceof Map
+          && b instanceof Map
+          && mapEquals((Map<?, ?>) a, (Map<?, ?>) b, runtimeEquality);
+    }
+    if (a instanceof byte[] || b instanceof byte[]) {
+      return a instanceof byte[] && b instanceof byte[] && Arrays.equals((byte[]) a, (byte[]) b);
+    }
+    if (a instanceof Object[] || b instanceof Object[]) {
+      return a instanceof Object[]
+          && b instanceof Object[]
+          && arrayEquals((Object[]) a, (Object[]) b, runtimeEquality);
+    }
+    return celEquals(a, b, runtimeEquality);
+  }
+
+  private static boolean numberEquals(Number a, Number b, RuntimeEquality runtimeEquality) {
+    double da = a.doubleValue();
+    double db = b.doubleValue();
+    // CEL defines NaN != NaN; override so a node re-evaluated with NaN hits its existing record.
+    if (Double.isNaN(da) && Double.isNaN(db)) {
+      return true;
+    }
+    if (da == 0.0d && db == 0.0d) {
+      return celEquals(normalizeSignedZero(a), normalizeSignedZero(b), runtimeEquality);
+    }
+    return celEquals(a, b, runtimeEquality);
+  }
+
+  private static boolean setEquals(Set<?> a, Set<?> b, RuntimeEquality runtimeEquality) {
+    return unorderedMatch(a, b, (x, y) -> argEquals(x, y, runtimeEquality));
+  }
+
+  private static boolean iterableEquals(
+      Iterable<?> a, Iterable<?> b, RuntimeEquality runtimeEquality) {
+    if (a instanceof Collection && b instanceof Collection) {
+      if (((Collection<?>) a).size() != ((Collection<?>) b).size()) {
+        return false;
+      }
+    }
+    Iterator<?> iterA = a.iterator();
+    Iterator<?> iterB = b.iterator();
+    while (iterA.hasNext() && iterB.hasNext()) {
+      if (!argEquals(iterA.next(), iterB.next(), runtimeEquality)) {
+        return false;
+      }
+    }
+    return !iterA.hasNext() && !iterB.hasNext();
+  }
+
+  private static boolean mapEquals(Map<?, ?> a, Map<?, ?> b, RuntimeEquality runtimeEquality) {
+    return unorderedMatch(
+        a.entrySet(),
+        b.entrySet(),
+        (entryA, entryB) ->
+            argEquals(entryA.getKey(), entryB.getKey(), runtimeEquality)
+                && argEquals(entryA.getValue(), entryB.getValue(), runtimeEquality));
+  }
+
+  private static boolean arrayEquals(Object[] a, Object[] b, RuntimeEquality runtimeEquality) {
+    if (a.length != b.length) {
+      return false;
+    }
+    for (int i = 0; i < a.length; i++) {
+      if (!argEquals(a[i], b[i], runtimeEquality)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  private static <T> boolean unorderedMatch(
+      Collection<? extends T> a,
+      Collection<? extends T> b,
+      BiPredicate<? super T, ? super T> matcher) {
+    if (a.size() != b.size()) {
+      return false;
+    }
+    Object[] targetArray = b.toArray();
+    boolean[] matched = new boolean[targetArray.length];
+    for (T elemA : a) {
+      boolean found = false;
+      for (int i = 0; i < targetArray.length; i++) {
+        // Safe downcast because targetArray was created from Collection<? extends T> b.
+        @SuppressWarnings("unchecked")
+        T elemB = (T) targetArray[i];
+        if (!matched[i] && matcher.test(elemA, elemB)) {
+          matched[i] = true;
+          found = true;
+          break;
+        }
+      }
+      if (!found) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Applies CEL heterogeneous equality, treating incomparable argument pairs (which throw unchecked
+   * exceptions from {@link RuntimeEquality#objectEquals}) as unequal.
+   */
+  private static boolean celEquals(Object a, Object b, RuntimeEquality runtimeEquality) {
+    try {
+      return runtimeEquality.objectEquals(a, b);
+    } catch (RuntimeException e) {
+      return false;
+    }
+  }
+
+  /**
+   * Normalizes {@code -0.0} to {@code 0.0} before comparison, because {@link
+   * RuntimeEquality#objectEquals} returns {@code false} for cross-type pairs such as {@code (0L,
+   * -0.0d)}.
+   */
+  private static @Nullable Object normalizeSignedZero(@Nullable Object value) {
+    if (value instanceof Double && (Double) value == 0.0d) {
+      return 0.0d;
+    }
+    if (value instanceof Float && (Float) value == 0.0f) {
+      return 0.0f;
+    }
+    return value;
+  }
+
+  private static int computeHashCode(
+      long exprId,
+      String functionName,
+      String overloadId,
+      Object[] args,
+      RuntimeEquality runtimeEquality) {
+    int result = Objects.hash(exprId, functionName, overloadId);
+    for (Object arg : args) {
+      result = 31 * result + hashArg(arg, runtimeEquality);
+    }
+    return result;
+  }
+
+  /**
+   * Hashes a single argument consistently with {@link #argEquals}.
+   *
+   * <p>Does not delegate to {@link RuntimeEquality#hashCode} because that method hashes {@code
+   * -0.0} and {@code 0.0} differently, which would break the {@link Object#hashCode} contract for
+   * keys containing signed zero.
+   */
+  private static int hashArg(@Nullable Object arg, RuntimeEquality runtimeEquality) {
+    if (arg instanceof Number) {
+      double d = ((Number) arg).doubleValue();
+      // Normalize -0.0d to +0.0d so that values CEL considers equal hash identically.
+      if (d == 0.0d) {
+        return 0;
+      }
+      return Double.hashCode(d);
+    }
+    if (arg instanceof Set) {
+      int h = 0;
+      for (Object elem : (Set<?>) arg) {
+        h += hashArg(elem, runtimeEquality);
+      }
+      return h;
+    }
+    if (arg instanceof Iterable) {
+      return hashSequence((Iterable<?>) arg, runtimeEquality);
+    }
+    if (arg instanceof Map) {
+      int h = 0;
+      for (Map.Entry<?, ?> entry : ((Map<?, ?>) arg).entrySet()) {
+        h += hashArg(entry.getKey(), runtimeEquality) ^ hashArg(entry.getValue(), runtimeEquality);
+      }
+      return h;
+    }
+    if (arg instanceof byte[]) {
+      return Arrays.hashCode((byte[]) arg);
+    }
+    if (arg instanceof Object[]) {
+      return hashArray((Object[]) arg, runtimeEquality);
+    }
+    return runtimeEquality.hashCode(arg);
+  }
+
+  private static int hashSequence(Iterable<?> iterable, RuntimeEquality runtimeEquality) {
+    int h = 1;
+    for (Object elem : iterable) {
+      h = h * 31 + hashArg(elem, runtimeEquality);
+    }
+    return h;
+  }
+
+  private static int hashArray(Object[] array, RuntimeEquality runtimeEquality) {
+    int h = 1;
+    for (Object elem : array) {
+      h = h * 31 + hashArg(elem, runtimeEquality);
+    }
+    return h;
+  }
+
+  private AsyncCallKey(
+      long exprId,
+      String functionName,
+      String overloadId,
+      Object[] args,
+      RuntimeEquality runtimeEquality) {
+    this.exprId = exprId;
+    this.functionName = requireNonNull(functionName);
+    this.overloadId = requireNonNull(overloadId);
+    this.args = requireNonNull(args).clone();
+    this.runtimeEquality = requireNonNull(runtimeEquality);
+    this.hashCode = computeHashCode(exprId, functionName, overloadId, this.args, runtimeEquality);
+  }
+}