Add iteration limit control to planned comprehensions

common/exceptions/BUILD.bazel

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

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

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

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

@@ -0,0 +1,31 @@
+// 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 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.CelRuntimeException;
+import dev.cel.common.annotations.Internal;
+import java.util.Locale;
+
+/** Indicates that the iteration budget for a comprehension has been exceeded. */
+@Internal
+public final class CelIterationLimitExceededException extends CelRuntimeException {
+
+  public CelIterationLimitExceededException(int budget) {
+    super(
+        String.format(Locale.US, "Iteration budget exceeded: %d", budget),
+        CelErrorCode.ITERATION_BUDGET_EXCEEDED);
+  }
+}

runtime/BUILD.bazel

@@ -255,3 +255,11 @@ java_library(
     visibility = ["//:internal"],
     exports = ["//runtime/src/main/java/dev/cel/runtime:metadata"],
 )
+
+java_library(
+    name = "concatenated_list_view",
+    visibility = ["//:internal"],
+    exports = [
+        "//runtime/src/main/java/dev/cel/runtime:concatenated_list_view",
+    ],
+)

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

@@ -2,7 +2,7 @@
 //
 // 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
+// You may obtain a copy of the License at
 //
 //      https://www.apache.org/licenses/LICENSE-2.0
 //

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

@@ -1142,7 +1142,9 @@ java_library(
     name = "concatenated_list_view",
     srcs = ["ConcatenatedListView.java"],
     # used_by_android
-    visibility = ["//visibility:private"],
+    tags = [
+    ],
+    deps = ["//common/annotations"],
 )
 
 java_library(

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

@@ -2,7 +2,7 @@
 //
 // 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
+// You may obtain a copy of the License at
 //
 //      https://www.apache.org/licenses/LICENSE-2.0
 //
@@ -14,6 +14,7 @@
 
 package dev.cel.runtime;
 
+import dev.cel.common.annotations.Internal;
 import java.util.AbstractList;
 import java.util.ArrayList;
 import java.util.Collection;
@@ -27,16 +28,20 @@
  * comprehensions that dispatch `add_list` to concat N lists together).
  *
  * <p>This does not support any of the standard list operations from {@link java.util.List}.
+ *
+
+ * <p>CEL Library Internals. Do Not Use.
  */
-final class ConcatenatedListView<E> extends AbstractList<E> {
+@Internal
+public final class ConcatenatedListView<E> extends AbstractList<E> {
   private final List<List<? extends E>> sourceLists;
   private int totalSize = 0;
 
   ConcatenatedListView() {
     this.sourceLists = new ArrayList<>();
   }
 
-  ConcatenatedListView(Collection<? extends E> collection) {
+  public ConcatenatedListView(Collection<? extends E> collection) {
     this();
     addAll(collection);
   }

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

@@ -20,7 +20,7 @@
 /** Represents a resolvable symbol or path (such as a variable or a field selection). */
 @Immutable
 interface Attribute {
-  Object resolve(GlobalResolver ctx);
+  Object resolve(GlobalResolver ctx, ExecutionFrame frame);
 
   Attribute addQualifier(Qualifier qualifier);
 }

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

@@ -22,7 +22,9 @@ java_library(
         ":eval_create_list",
         ":eval_create_map",
         ":eval_create_struct",
+        ":eval_fold",
         ":eval_or",
+        ":eval_test_only",
         ":eval_unary",
         ":eval_var_args_call",
         ":eval_zero_arity",
@@ -35,6 +37,7 @@ java_library(
         "//common:cel_ast",
         "//common:container",
         "//common:operator",
+        "//common:options",
         "//common/annotations",
         "//common/ast",
         "//common/types",
@@ -57,11 +60,14 @@ java_library(
     srcs = ["PlannedProgram.java"],
     deps = [
         ":error_metadata",
+        ":execution_frame",
         ":planned_interpretable",
         ":strict_error_exception",
         "//:auto_value",
+        "//common:options",
         "//common:runtime_exception",
         "//common/values",
+        "//runtime",
         "//runtime:activation",
         "//runtime:evaluation_exception",
         "//runtime:evaluation_exception_builder",
@@ -76,11 +82,10 @@ java_library(
     name = "eval_const",
     srcs = ["EvalConstant.java"],
     deps = [
+        ":execution_frame",
         ":planned_interpretable",
         "//common/values",
         "//common/values:cel_byte_string",
-        "//runtime:evaluation_listener",
-        "//runtime:function_resolver",
         "//runtime:interpretable",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
@@ -109,6 +114,7 @@ java_library(
     ],
     deps = [
         ":eval_helpers",
+        ":execution_frame",
         ":planned_interpretable",
         ":qualifier",
         "//common:container",
@@ -131,6 +137,16 @@ java_library(
     ],
 )
 
+java_library(
+    name = "presence_test_qualifier",
+    srcs = ["PresenceTestQualifier.java"],
+    deps = [
+        ":attribute",
+        ":qualifier",
+        "//common/values",
+    ],
+)
+
 java_library(
     name = "string_qualifier",
     srcs = ["StringQualifier.java"],
@@ -146,24 +162,36 @@ java_library(
     srcs = ["EvalAttribute.java"],
     deps = [
         ":attribute",
+        ":execution_frame",
         ":interpretable_attribute",
         ":qualifier",
-        "//runtime:evaluation_listener",
-        "//runtime:function_resolver",
         "//runtime:interpretable",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
     ],
 )
 
+java_library(
+    name = "eval_test_only",
+    srcs = ["EvalTestOnly.java"],
+    deps = [
+        ":execution_frame",
+        ":interpretable_attribute",
+        ":presence_test_qualifier",
+        ":qualifier",
+        "//runtime:evaluation_exception",
+        "//runtime:interpretable",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+    ],
+)
+
 java_library(
     name = "eval_zero_arity",
     srcs = ["EvalZeroArity.java"],
     deps = [
+        ":execution_frame",
         ":planned_interpretable",
         "//runtime:evaluation_exception",
-        "//runtime:evaluation_listener",
-        "//runtime:function_resolver",
         "//runtime:interpretable",
         "//runtime:resolved_overload",
     ],
@@ -174,10 +202,9 @@ java_library(
     srcs = ["EvalUnary.java"],
     deps = [
         ":eval_helpers",
+        ":execution_frame",
         ":planned_interpretable",
         "//runtime:evaluation_exception",
-        "//runtime:evaluation_listener",
-        "//runtime:function_resolver",
         "//runtime:interpretable",
         "//runtime:resolved_overload",
     ],
@@ -188,10 +215,9 @@ java_library(
     srcs = ["EvalVarArgsCall.java"],
     deps = [
         ":eval_helpers",
+        ":execution_frame",
         ":planned_interpretable",
         "//runtime:evaluation_exception",
-        "//runtime:evaluation_listener",
-        "//runtime:function_resolver",
         "//runtime:interpretable",
         "//runtime:resolved_overload",
     ],
@@ -202,10 +228,9 @@ java_library(
     srcs = ["EvalOr.java"],
     deps = [
         ":eval_helpers",
+        ":execution_frame",
         ":planned_interpretable",
         "//common/values",
-        "//runtime:evaluation_listener",
-        "//runtime:function_resolver",
         "//runtime:interpretable",
         "@maven//:com_google_guava_guava",
     ],
@@ -216,10 +241,9 @@ java_library(
     srcs = ["EvalAnd.java"],
     deps = [
         ":eval_helpers",
+        ":execution_frame",
         ":planned_interpretable",
         "//common/values",
-        "//runtime:evaluation_listener",
-        "//runtime:function_resolver",
         "//runtime:interpretable",
         "@maven//:com_google_guava_guava",
     ],
@@ -229,10 +253,9 @@ java_library(
     name = "eval_conditional",
     srcs = ["EvalConditional.java"],
     deps = [
+        ":execution_frame",
         ":planned_interpretable",
         "//runtime:evaluation_exception",
-        "//runtime:evaluation_listener",
-        "//runtime:function_resolver",
         "//runtime:interpretable",
         "@maven//:com_google_guava_guava",
     ],
@@ -242,13 +265,12 @@ java_library(
     name = "eval_create_struct",
     srcs = ["EvalCreateStruct.java"],
     deps = [
+        ":execution_frame",
         ":planned_interpretable",
         "//common/types",
         "//common/values",
         "//common/values:cel_value_provider",
         "//runtime:evaluation_exception",
-        "//runtime:evaluation_listener",
-        "//runtime:function_resolver",
         "//runtime:interpretable",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
@@ -259,10 +281,9 @@ java_library(
     name = "eval_create_list",
     srcs = ["EvalCreateList.java"],
     deps = [
+        ":execution_frame",
         ":planned_interpretable",
         "//runtime:evaluation_exception",
-        "//runtime:evaluation_listener",
-        "//runtime:function_resolver",
         "//runtime:interpretable",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
@@ -273,20 +294,46 @@ java_library(
     name = "eval_create_map",
     srcs = ["EvalCreateMap.java"],
     deps = [
+        ":execution_frame",
         ":planned_interpretable",
         "//runtime:evaluation_exception",
-        "//runtime:evaluation_listener",
-        "//runtime:function_resolver",
         "//runtime:interpretable",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
     ],
 )
 
+java_library(
+    name = "eval_fold",
+    srcs = ["EvalFold.java"],
+    deps = [
+        ":execution_frame",
+        ":planned_interpretable",
+        "//runtime:concatenated_list_view",
+        "//runtime:evaluation_exception",
+        "//runtime:interpretable",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:com_google_guava_guava",
+        "@maven//:org_jspecify_jspecify",
+    ],
+)
+
+java_library(
+    name = "execution_frame",
+    srcs = ["ExecutionFrame.java"],
+    deps = [
+        "//common:options",
+        "//common/exceptions:iteration_budget_exceeded",
+        "//runtime:interpretable",
+        "@maven//:org_jspecify_jspecify",
+    ],
+)
+
 java_library(
     name = "eval_helpers",
     srcs = ["EvalHelpers.java"],
     deps = [
+        ":execution_frame",
         ":planned_interpretable",
         ":strict_error_exception",
         "//common:error_codes",
@@ -319,6 +366,8 @@ java_library(
     name = "planned_interpretable",
     srcs = ["PlannedInterpretable.java"],
     deps = [
+        ":execution_frame",
+        "//runtime:evaluation_exception",
         "//runtime:interpretable",
         "@maven//:com_google_errorprone_error_prone_annotations",
     ],