Add AsyncCallKey and AsyncCallRecord primitives for async evaluation.

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/AccumulatedUnknowns.java

@@ -16,9 +16,8 @@
 
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import dev.cel.common.annotations.Internal;
-import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.HashSet;
 import java.util.Set;
 import org.jspecify.annotations.Nullable;
@@ -35,6 +34,7 @@ public final class AccumulatedUnknowns {
   private static final int MAX_UNKNOWN_ATTRIBUTE_SIZE = 500_000;
   private final Set<Long> exprIds;
   private final Set<CelAttribute> attributes;
+  private final Set<Long> callIds;
 
   Set<Long> exprIds() {
     return exprIds;
@@ -44,6 +44,17 @@ Set<CelAttribute> attributes() {
     return attributes;
   }
 
+  /**
+   * Returns the in-flight asynchronous call IDs this unknown is waiting on.
+   *
+   * <p>The returned set is an unmodifiable <em>view</em> over this mutable accumulator, not a
+   * snapshot: a subsequent {@link #merge} on this instance is visible through it. Callers that
+   * retain the set beyond the current evaluation step must copy it.
+   */
+  public Set<Long> callIds() {
+    return Collections.unmodifiableSet(callIds);
+  }
+
   /**
    * Evaluates if the right hand side is an accumulated unknown, and if so, merges it into the
    * accumulator.
@@ -62,20 +73,29 @@ public AccumulatedUnknowns merge(AccumulatedUnknowns arg) {
     enforceMaxAttributeSize(this.attributes, arg.attributes);
     this.exprIds.addAll(arg.exprIds);
     this.attributes.addAll(arg.attributes);
+    this.callIds.addAll(arg.callIds);
     return this;
   }
 
-  static AccumulatedUnknowns create(Long... ids) {
-    return create(Arrays.asList(ids));
-  }
-
-  static AccumulatedUnknowns create(Collection<Long> ids) {
-    return create(ids, new ArrayList<>());
+  static AccumulatedUnknowns create(long exprId) {
+    return new AccumulatedUnknowns(
+        Collections.singletonList(exprId), Collections.emptyList(), Collections.emptyList());
   }
 
   public static AccumulatedUnknowns create(
       Collection<Long> exprIds, Collection<CelAttribute> attributes) {
-    return new AccumulatedUnknowns(new HashSet<>(exprIds), new HashSet<>(attributes));
+    return new AccumulatedUnknowns(exprIds, attributes, Collections.emptyList());
+  }
+
+  /**
+   * Creates an accumulated unknown for a pending asynchronous call, recording {@code exprId} so the
+   * unknown retains its origin when adapted into a {@link CelUnknownSet}.
+   */
+  public static AccumulatedUnknowns createForAsyncCall(long exprId, long callId) {
+    return new AccumulatedUnknowns(
+        Collections.singletonList(exprId),
+        Collections.emptyList(),
+        Collections.singletonList(callId));
   }
 
   private static void enforceMaxAttributeSize(
@@ -88,8 +108,10 @@ private static void enforceMaxAttributeSize(
     }
   }
 
-  private AccumulatedUnknowns(Set<Long> exprIds, Set<CelAttribute> attributes) {
-    this.exprIds = exprIds;
-    this.attributes = attributes;
+  private AccumulatedUnknowns(
+      Collection<Long> exprIds, Collection<CelAttribute> attributes, Collection<Long> callIds) {
+    this.exprIds = new HashSet<>(exprIds);
+    this.attributes = new HashSet<>(attributes);
+    this.callIds = new HashSet<>(callIds);
   }
 }

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

@@ -16,6 +16,7 @@
 
 import dev.cel.common.annotations.Internal;
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.Optional;
 
 /**
@@ -100,7 +101,7 @@ Optional<Object> maybeUnknowns() {
     }
 
     if (!exprIds.isEmpty()) {
-      return Optional.of(AccumulatedUnknowns.create(exprIds));
+      return Optional.of(AccumulatedUnknowns.create(exprIds, Collections.emptyList()));
     }
 
     return Optional.empty();