[Draft] Accumulated unknowns (#749)

PiperOrigin-RevId: 783626490

Author: l46kok

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

@@ -0,0 +1,64 @@
+// Copyright 2025 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 aj
+//
+//      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.errorprone.annotations.CanIgnoreReturnValue;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.List;
+
+/**
+ * An internal representation used for fast accumulation of unknown expr IDs and attributes. For
+ * safety, this object should never be returned as an evaluated result and instead be adapted into
+ * an immutable CelUnknownSet.
+ */
+final class AccumulatedUnknowns {
+
+  private final List<Long> exprIds;
+  private final List<CelAttribute> attributes;
+
+  List<Long> exprIds() {
+    return exprIds;
+  }
+
+  List<CelAttribute> attributes() {
+    return attributes;
+  }
+
+  @CanIgnoreReturnValue
+  AccumulatedUnknowns merge(AccumulatedUnknowns arg) {
+    this.exprIds.addAll(arg.exprIds);
+    this.attributes.addAll(arg.attributes);
+    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(Collection<Long> exprIds, Collection<CelAttribute> attributes) {
+    return new AccumulatedUnknowns(new ArrayList<>(exprIds), new ArrayList<>(attributes));
+  }
+
+  private AccumulatedUnknowns(List<Long> exprIds, List<CelAttribute> attributes) {
+    this.exprIds = exprIds;
+    this.attributes = attributes;
+  }
+}

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

@@ -271,6 +271,7 @@ java_library(
     ],
     exports = [":base"],
     deps = [
+        ":accumulated_unknowns",
         ":base",
         ":concatenated_list_view",
         ":dispatcher",
@@ -306,6 +307,7 @@ cel_android_library(
     srcs = INTERPRETER_SOURCES,
     visibility = ["//visibility:private"],
     deps = [
+        ":accumulated_unknowns_android",
         ":base_android",
         ":concatenated_list_view",
         ":dispatcher_android",
@@ -849,15 +851,13 @@ java_library(
         ":cel_value_runtime_type_provider",
         ":dispatcher",
         ":evaluation_exception",
-        ":evaluation_listener",
         ":function_binding",
         ":function_resolver",
         ":interpretable",
         ":interpreter",
         ":lite_runtime",
         ":runtime_equality",
         ":runtime_helpers",
-        ":standard_functions",
         ":type_resolver",
         "//:auto_value",
         "//common:cel_ast",
@@ -880,15 +880,13 @@ cel_android_library(
         ":cel_value_runtime_type_provider_android",
         ":dispatcher_android",
         ":evaluation_exception",
-        ":evaluation_listener_android",
         ":function_binding_android",
         ":function_resolver",
         ":interpretable_android",
         ":interpreter_android",
         ":lite_runtime_android",
         ":runtime_equality_android",
         ":runtime_helpers_android",
-        ":standard_functions_android",
         ":type_resolver_android",
         "//:auto_value",
         "//common:cel_ast_android",
@@ -1034,6 +1032,7 @@ java_library(
     tags = [
     ],
     deps = [
+        ":accumulated_unknowns",
         ":evaluation_exception",
         ":unknown_attributes",
         "//common/annotations",
@@ -1047,6 +1046,7 @@ cel_android_library(
     srcs = ["InterpreterUtil.java"],
     visibility = ["//visibility:private"],
     deps = [
+        ":accumulated_unknowns_android",
         ":evaluation_exception",
         ":unknown_attributes_android",
         "//common/annotations",
@@ -1105,3 +1105,23 @@ java_library(
     # used_by_android
     visibility = ["//visibility:private"],
 )
+
+java_library(
+    name = "accumulated_unknowns",
+    srcs = ["AccumulatedUnknowns.java"],
+    visibility = ["//visibility:private"],
+    deps = [
+        ":unknown_attributes",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+    ],
+)
+
+cel_android_library(
+    name = "accumulated_unknowns_android",
+    srcs = ["AccumulatedUnknowns.java"],
+    visibility = ["//visibility:private"],
+    deps = [
+        ":unknown_attributes_android",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+    ],
+)

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

@@ -32,7 +32,7 @@ class CallArgumentChecker {
   private final ArrayList<Long> exprIds;
   private final RuntimeUnknownResolver resolver;
   private final boolean acceptPartial;
-  private Optional<CelUnknownSet> unknowns;
+  private Optional<AccumulatedUnknowns> unknowns;
 
   private CallArgumentChecker(RuntimeUnknownResolver resolver, boolean acceptPartial) {
     this.exprIds = new ArrayList<>();
@@ -61,29 +61,30 @@ static CallArgumentChecker createAcceptingPartial(RuntimeUnknownResolver resolve
     return new CallArgumentChecker(resolver, true);
   }
 
-  private static Optional<CelUnknownSet> mergeOptionalUnknowns(
-      Optional<CelUnknownSet> lhs, Optional<CelUnknownSet> rhs) {
+  private static Optional<AccumulatedUnknowns> mergeOptionalUnknowns(
+      Optional<AccumulatedUnknowns> lhs, Optional<AccumulatedUnknowns> rhs) {
     return lhs.isPresent() ? rhs.isPresent() ? Optional.of(lhs.get().merge(rhs.get())) : lhs : rhs;
   }
 
   /** Determine if the call argument is unknown and accumulate if so. */
   void checkArg(DefaultInterpreter.IntermediateResult arg) {
     // Handle attribute tracked unknowns.
-    Optional<CelUnknownSet> argUnknowns = maybeUnknownFromArg(arg);
+    Optional<AccumulatedUnknowns> argUnknowns = maybeUnknownFromArg(arg);
     unknowns = mergeOptionalUnknowns(unknowns, argUnknowns);
 
     // support for ExprValue unknowns.
-    if (InterpreterUtil.isUnknown(arg.value())) {
-      CelUnknownSet unknownSet = (CelUnknownSet) arg.value();
-      exprIds.addAll(unknownSet.unknownExprIds());
+    if (InterpreterUtil.isAccumulatedUnknowns(arg.value())) {
+      AccumulatedUnknowns unknownSet = (AccumulatedUnknowns) arg.value();
+      exprIds.addAll(unknownSet.exprIds());
     }
   }
 
-  private Optional<CelUnknownSet> maybeUnknownFromArg(DefaultInterpreter.IntermediateResult arg) {
-    if (arg.value() instanceof CelUnknownSet) {
-      CelUnknownSet celUnknownSet = (CelUnknownSet) arg.value();
+  private Optional<AccumulatedUnknowns> maybeUnknownFromArg(
+      DefaultInterpreter.IntermediateResult arg) {
+    if (arg.value() instanceof AccumulatedUnknowns) {
+      AccumulatedUnknowns celUnknownSet = (AccumulatedUnknowns) arg.value();
       if (!celUnknownSet.attributes().isEmpty()) {
-        return Optional.of((CelUnknownSet) arg.value());
+        return Optional.of((AccumulatedUnknowns) arg.value());
       }
     }
     if (!acceptPartial) {
@@ -99,7 +100,7 @@ Optional<Object> maybeUnknowns() {
     }
 
     if (!exprIds.isEmpty()) {
-      return Optional.of(CelUnknownSet.create(exprIds));
+      return Optional.of(AccumulatedUnknowns.create(exprIds));
     }
 
     return Optional.empty();

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

@@ -33,9 +33,4 @@ public interface CelEvaluationListener {
    * @param evaluatedResult Evaluated result.
    */
   void callback(CelExpr expr, Object evaluatedResult);
-
-  /** Construct a listener that does nothing. */
-  static CelEvaluationListener noOpListener() {
-    return (arg1, arg2) -> {};
-  }
 }

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

@@ -59,7 +59,7 @@ static CelUnknownSet create(Iterable<Long> unknownExprIds) {
     return create(ImmutableSet.of(), ImmutableSet.copyOf(unknownExprIds));
   }
 
-  private static CelUnknownSet create(
+  static CelUnknownSet create(
       ImmutableSet<CelAttribute> attributes, ImmutableSet<Long> unknownExprIds) {
     return new AutoValue_CelUnknownSet(attributes, unknownExprIds);
   }

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

@@ -21,6 +21,7 @@
 import com.google.common.base.Joiner;
 import com.google.common.base.Preconditions;
 import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableSet;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import com.google.errorprone.annotations.Immutable;
 import javax.annotation.concurrent.ThreadSafe;
@@ -137,20 +138,24 @@ static final class DefaultInterpretable implements Interpretable, UnknownTrackin
     @Override
     public Object eval(GlobalResolver resolver) throws CelEvaluationException {
       // Result is already unwrapped from IntermediateResult.
-      return eval(resolver, CelEvaluationListener.noOpListener());
+      return evalTrackingUnknowns(
+          RuntimeUnknownResolver.fromResolver(resolver), Optional.empty(), Optional.empty());
     }
 
     @Override
     public Object eval(GlobalResolver resolver, CelEvaluationListener listener)
         throws CelEvaluationException {
       return evalTrackingUnknowns(
-          RuntimeUnknownResolver.fromResolver(resolver), Optional.empty(), listener);
+          RuntimeUnknownResolver.fromResolver(resolver), Optional.empty(), Optional.of(listener));
     }
 
     @Override
     public Object eval(GlobalResolver resolver, FunctionResolver lateBoundFunctionResolver)
         throws CelEvaluationException {
-      return eval(resolver, lateBoundFunctionResolver, CelEvaluationListener.noOpListener());
+      return evalTrackingUnknowns(
+          RuntimeUnknownResolver.fromResolver(resolver),
+          Optional.of(lateBoundFunctionResolver),
+          Optional.empty());
     }
 
     @Override
@@ -162,19 +167,32 @@ public Object eval(
       return evalTrackingUnknowns(
           RuntimeUnknownResolver.fromResolver(resolver),
           Optional.of(lateBoundFunctionResolver),
-          listener);
+          Optional.of(listener));
     }
 
     @Override
     public Object evalTrackingUnknowns(
         RuntimeUnknownResolver resolver,
         Optional<? extends FunctionResolver> functionResolver,
-        CelEvaluationListener listener)
+        Optional<CelEvaluationListener> listener)
         throws CelEvaluationException {
       ExecutionFrame frame = newExecutionFrame(resolver, functionResolver, listener);
       IntermediateResult internalResult = evalInternal(frame, ast.getExpr());
 
-      return internalResult.value();
+      Object underlyingValue = internalResult.value();
+
+      return maybeAdaptToCelUnknownSet(underlyingValue);
+    }
+
+    private static Object maybeAdaptToCelUnknownSet(Object val) {
+      if (!(val instanceof AccumulatedUnknowns)) {
+        return val;
+      }
+
+      AccumulatedUnknowns unknowns = (AccumulatedUnknowns) val;
+
+      return CelUnknownSet.create(
+          ImmutableSet.copyOf(unknowns.attributes()), ImmutableSet.copyOf(unknowns.exprIds()));
     }
 
     /**
@@ -196,15 +214,13 @@ ExecutionFrame populateExecutionFrame(ExecutionFrame frame) throws CelEvaluation
     @VisibleForTesting
     ExecutionFrame newTestExecutionFrame(GlobalResolver resolver) {
       return newExecutionFrame(
-          RuntimeUnknownResolver.fromResolver(resolver),
-          Optional.empty(),
-          CelEvaluationListener.noOpListener());
+          RuntimeUnknownResolver.fromResolver(resolver), Optional.empty(), Optional.empty());
     }
 
     private ExecutionFrame newExecutionFrame(
         RuntimeUnknownResolver resolver,
         Optional<? extends FunctionResolver> functionResolver,
-        CelEvaluationListener listener) {
+        Optional<CelEvaluationListener> listener) {
       int comprehensionMaxIterations =
           celOptions.enableComprehension() ? celOptions.comprehensionMaxIterations() : 0;
       return new ExecutionFrame(listener, resolver, functionResolver, comprehensionMaxIterations);
@@ -244,7 +260,11 @@ private IntermediateResult evalInternal(ExecutionFrame frame, CelExpr expr)
             throw new IllegalStateException(
                 "unexpected expression kind: " + expr.exprKind().getKind());
         }
-        frame.getEvaluationListener().callback(expr, result.value());
+
+        frame
+            .getEvaluationListener()
+            .ifPresent(
+                listener -> listener.callback(expr, maybeAdaptToCelUnknownSet(result.value())));
         return result;
       } catch (CelRuntimeException e) {
         throw CelEvaluationExceptionBuilder.newBuilder(e).setMetadata(metadata, expr.id()).build();
@@ -257,7 +277,7 @@ private IntermediateResult evalInternal(ExecutionFrame frame, CelExpr expr)
     }
 
     private static boolean isUnknownValue(Object value) {
-      return value instanceof CelUnknownSet || InterpreterUtil.isUnknown(value);
+      return InterpreterUtil.isAccumulatedUnknowns(value);
     }
 
     private static boolean isUnknownOrError(Object value) {
@@ -552,18 +572,20 @@ private IntermediateResult mergeBooleanUnknowns(IntermediateResult lhs, Intermed
         throws CelEvaluationException {
       // TODO: migrate clients to a common type that reports both expr-id unknowns
       // and attribute sets.
-      if (lhs.value() instanceof CelUnknownSet && rhs.value() instanceof CelUnknownSet) {
+      Object lhsVal = lhs.value();
+      Object rhsVal = rhs.value();
+      if (lhsVal instanceof AccumulatedUnknowns && rhsVal instanceof AccumulatedUnknowns) {
         return IntermediateResult.create(
-            ((CelUnknownSet) lhs.value()).merge((CelUnknownSet) rhs.value()));
-      } else if (lhs.value() instanceof CelUnknownSet) {
+            ((AccumulatedUnknowns) lhsVal).merge((AccumulatedUnknowns) rhsVal));
+      } else if (lhsVal instanceof AccumulatedUnknowns) {
         return lhs;
-      } else if (rhs.value() instanceof CelUnknownSet) {
+      } else if (rhsVal instanceof AccumulatedUnknowns) {
         return rhs;
       }
 
       // Otherwise fallback to normal impl
       return IntermediateResult.create(
-          InterpreterUtil.shortcircuitUnknownOrThrowable(lhs.value(), rhs.value()));
+          InterpreterUtil.shortcircuitUnknownOrThrowable(lhsVal, rhsVal));
     }
 
     private enum ShortCircuitableOperators {
@@ -1050,7 +1072,7 @@ private LazyExpression(CelExpr celExpr) {
 
   /** This class tracks the state meaningful to a single evaluation pass. */
   static class ExecutionFrame {
-    private final CelEvaluationListener evaluationListener;
+    private final Optional<CelEvaluationListener> evaluationListener;
     private final int maxIterations;
     private final ArrayDeque<RuntimeUnknownResolver> resolvers;
     private final Optional<? extends FunctionResolver> lateBoundFunctionResolver;
@@ -1059,7 +1081,7 @@ static class ExecutionFrame {
     @VisibleForTesting int scopeLevel;
 
     private ExecutionFrame(
-        CelEvaluationListener evaluationListener,
+        Optional<CelEvaluationListener> evaluationListener,
         RuntimeUnknownResolver resolver,
         Optional<? extends FunctionResolver> lateBoundFunctionResolver,
         int maxIterations) {
@@ -1071,7 +1093,7 @@ private ExecutionFrame(
       this.maxIterations = maxIterations;
     }
 
-    private CelEvaluationListener getEvaluationListener() {
+    private Optional<CelEvaluationListener> getEvaluationListener() {
       return evaluationListener;
     }