cel-expr · copybara-service · Aug 12, 2026 · Aug 12, 2026
diff --git a/optimizer/src/main/java/dev/cel/optimizer/BUILD.bazel b/optimizer/src/main/java/dev/cel/optimizer/BUILD.bazel
@@ -32,12 +32,14 @@ java_library(
     srcs = [
         "CelOptimizer.java",
         "CelOptimizerBuilder.java",
+        "CelOptimizerOptions.java",
     ],
     tags = [
     ],
     deps = [
         ":ast_optimizer",
         ":optimization_exception",
+        "//:auto_value",
         "//common:cel_ast",
         "@maven//:com_google_errorprone_error_prone_annotations",
     ],
@@ -57,6 +59,8 @@ java_library(
         "//bundle:cel",
         "//common:cel_ast",
         "//common:compiler_common",
+        "//common/ast",
+        "//common/navigation",
         "@maven//:com_google_guava_guava",
     ],
 )

diff --git a/optimizer/src/main/java/dev/cel/optimizer/CelOptimizerFactory.java b/optimizer/src/main/java/dev/cel/optimizer/CelOptimizerFactory.java
@@ -25,22 +25,48 @@
 /** Factory class for constructing an {@link CelOptimizer} instance. */
 public final class CelOptimizerFactory {
 
+  private static final CelOptimizerOptions DEFAULT_OPTIMIZER_OPTIONS =
+      CelOptimizerOptions.newBuilder().build();
+
   /** Create a new builder for constructing a {@link CelOptimizer} instance. */
   public static CelOptimizerBuilder standardCelOptimizerBuilder(Cel cel) {
-    return CelOptimizerImpl.newBuilder(cel);
+    return standardCelOptimizerBuilder(cel, DEFAULT_OPTIMIZER_OPTIONS);
+  }
+
+  /** Create a new builder for constructing a {@link CelOptimizer} instance with custom options. */
+  public static CelOptimizerBuilder standardCelOptimizerBuilder(
+      Cel cel, CelOptimizerOptions optimizerOptions) {
+    return CelOptimizerImpl.newBuilder(cel, optimizerOptions);
   }
 
   /** Create a new builder for constructing a {@link CelOptimizer} instance. */
   public static CelOptimizerBuilder standardCelOptimizerBuilder(
       CelCompiler celCompiler, CelRuntime celRuntime) {
-    return standardCelOptimizerBuilder(CelFactory.combine(celCompiler, celRuntime));
+    return standardCelOptimizerBuilder(celCompiler, celRuntime, DEFAULT_OPTIMIZER_OPTIONS);
+  }
+
+  /** Create a new builder for constructing a {@link CelOptimizer} instance with custom options. */
+  public static CelOptimizerBuilder standardCelOptimizerBuilder(
+      CelCompiler celCompiler, CelRuntime celRuntime, CelOptimizerOptions optimizerOptions) {
+    return standardCelOptimizerBuilder(
+        CelFactory.combine(celCompiler, celRuntime), optimizerOptions);
   }
 
   /** Create a new builder for constructing a {@link CelOptimizer} instance. */
   public static CelOptimizerBuilder standardCelOptimizerBuilder(
       CelParser celParser, CelChecker celChecker, CelRuntime celRuntime) {
     return standardCelOptimizerBuilder(
-        CelCompilerFactory.combine(celParser, celChecker), celRuntime);
+        celParser, celChecker, celRuntime, DEFAULT_OPTIMIZER_OPTIONS);
+  }
+
+  /** Create a new builder for constructing a {@link CelOptimizer} instance with custom options. */
+  public static CelOptimizerBuilder standardCelOptimizerBuilder(
+      CelParser celParser,
+      CelChecker celChecker,
+      CelRuntime celRuntime,
+      CelOptimizerOptions optimizerOptions) {
+    return standardCelOptimizerBuilder(
+        CelCompilerFactory.combine(celParser, celChecker), celRuntime, optimizerOptions);
   }
 
   private CelOptimizerFactory() {}

diff --git a/optimizer/src/main/java/dev/cel/optimizer/CelOptimizerImpl.java b/optimizer/src/main/java/dev/cel/optimizer/CelOptimizerImpl.java
@@ -20,16 +20,25 @@
 import dev.cel.bundle.Cel;
 import dev.cel.common.CelAbstractSyntaxTree;
 import dev.cel.common.CelValidationException;
+import dev.cel.common.ast.CelExpr;
+import dev.cel.common.ast.CelExpr.ExprKind.Kind;
+import dev.cel.common.navigation.CelNavigableAst;
+import dev.cel.common.navigation.CelNavigableExpr;
 import dev.cel.optimizer.CelAstOptimizer.OptimizationResult;
 import java.util.Arrays;
+import java.util.HashMap;
+import java.util.Map;
 
 final class CelOptimizerImpl implements CelOptimizer {
   private final Cel cel;
   private final ImmutableSet<CelAstOptimizer> astOptimizers;
+  private final CelOptimizerOptions optimizerOptions;
 
-  CelOptimizerImpl(Cel cel, ImmutableSet<CelAstOptimizer> astOptimizers) {
+  CelOptimizerImpl(
+      Cel cel, ImmutableSet<CelAstOptimizer> astOptimizers, CelOptimizerOptions optimizerOptions) {
     this.cel = cel;
     this.astOptimizers = astOptimizers;
+    this.optimizerOptions = optimizerOptions;
   }
 
   @Override
@@ -52,6 +61,9 @@ public CelAbstractSyntaxTree optimize(CelAbstractSyntaxTree ast) throws CelOptim
                   .build();
         }
         optimizedAst = celOptimizerEnv.check(result.optimizedAst()).getAst();
+        if (optimizerOptions.enableAstValidation()) {
+          assertAstIdCorrectness(optimizedAst);
+        }
       }
     } catch (CelValidationException e) {
       throw new CelOptimizationException(
@@ -63,18 +75,78 @@ public CelAbstractSyntaxTree optimize(CelAbstractSyntaxTree ast) throws CelOptim
     return optimizedAst;
   }
 
+  private static void assertAstIdCorrectness(CelAbstractSyntaxTree ast) {
+    Map<Long, CelExpr> allExprs = new HashMap<>();
+    CelNavigableAst.fromAst(ast)
+        .getRoot()
+        .allNodes()
+        .forEach(
+            navExpr -> {
+              CelExpr expr = navExpr.expr();
+              CelExpr existing = allExprs.put(expr.id(), expr);
+              if (existing != null) {
+                throw new IllegalStateException(
+                    String.format("Duplicate expr ID %d detected in the AST.", expr.id()));
+              }
+            });
+
+    for (CelExpr macroCall : ast.getSource().getMacroCalls().values()) {
+      if (macroCall.id() != 0) {
+        throw new IllegalStateException(
+            String.format("Expected macro call root ID to be 0, but was %d.", macroCall.id()));
+      }
+      CelNavigableExpr.fromExpr(macroCall)
+          .descendants()
+          .forEach(
+              navExpr -> {
+                CelExpr macroExpr = navExpr.expr();
+                CelExpr astExpr = allExprs.get(macroExpr.id());
+                // A node may not exist in the AST if it is a synthetic macro node or was eliminated
+                // during optimization passes.
+                if (astExpr == null) {
+                  return;
+                }
+
+                if (astExpr.exprKind().getKind().equals(Kind.COMPREHENSION)) {
+                  if (!macroExpr.exprKind().getKind().equals(Kind.NOT_SET)) {
+                    throw new IllegalStateException(
+                        String.format(
+                            "Expected macro call node %d to be NOT_SET for comprehension, but"
+                                + " was %s.",
+                            macroExpr.id(), macroExpr.exprKind().getKind()));
+                  }
+                } else if (!macroExpr.exprKind().getKind().equals(astExpr.exprKind().getKind())) {
+                  throw new IllegalStateException(
+                      String.format(
+                          "Macro call node %d kind mismatch: expected %s (from AST), but was %s"
+                              + " (in macro call).",
+                          macroExpr.id(),
+                          astExpr.exprKind().getKind(),
+                          macroExpr.exprKind().getKind()));
+                }
+              });
+    }
+  }
+
   /** Create a new builder for constructing a {@link CelOptimizer} instance. */
   static CelOptimizerImpl.Builder newBuilder(Cel cel) {
-    return new CelOptimizerImpl.Builder(cel);
+    return newBuilder(cel, CelOptimizerOptions.newBuilder().build());
+  }
+
+  /** Create a new builder for constructing a {@link CelOptimizer} instance with custom options. */
+  static CelOptimizerImpl.Builder newBuilder(Cel cel, CelOptimizerOptions optimizerOptions) {
+    return new CelOptimizerImpl.Builder(cel, optimizerOptions);
   }
 
   /** Builder class for {@link CelOptimizerImpl}. */
   static final class Builder implements CelOptimizerBuilder {
     private final Cel cel;
+    private final CelOptimizerOptions optimizerOptions;
     private final ImmutableSet.Builder<CelAstOptimizer> astOptimizers;
 
-    private Builder(Cel cel) {
+    private Builder(Cel cel, CelOptimizerOptions optimizerOptions) {
       this.cel = cel;
+      this.optimizerOptions = checkNotNull(optimizerOptions);
       this.astOptimizers = ImmutableSet.builder();
     }
 
@@ -93,7 +165,7 @@ public CelOptimizerBuilder addAstOptimizers(Iterable<CelAstOptimizer> astOptimiz
 
     @Override
     public CelOptimizer build() {
-      return new CelOptimizerImpl(cel, astOptimizers.build());
+      return new CelOptimizerImpl(cel, astOptimizers.build(), optimizerOptions);
     }
   }
 }
diff --git a/optimizer/src/main/java/dev/cel/optimizer/CelOptimizerOptions.java b/optimizer/src/main/java/dev/cel/optimizer/CelOptimizerOptions.java
@@ -0,0 +1,51 @@
+// 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.optimizer;
+
+import com.google.auto.value.AutoValue;
+
+/** Options to configure how {@link CelOptimizer} behaves. */
+@AutoValue
+public abstract class CelOptimizerOptions {
+
+  /**
+   * Returns true if AST validation is enabled. When enabled, each optimizer pass verifies AST
+   * invariants (such as expression ID uniqueness and macro source consistency) after type-checking.
+   */
+  public abstract boolean enableAstValidation();
+
+  /** Builder for configuring the {@link CelOptimizerOptions}. */
+  @AutoValue.Builder
+  public abstract static class Builder {
+
+    /**
+     * Enables or disables post-pass AST validation. When enabled, each optimizer pass verifies that
+     * expression IDs are unique and macro calls in the AST source are consistent with the
+     * expression nodes.
+     */
+    public abstract Builder enableAstValidation(boolean value);
+
+    public abstract CelOptimizerOptions build();
+
+    Builder() {}
+  }
+
+  /** Returns a new options builder with recommended defaults pre-configured. */
+  public static Builder newBuilder() {
+    return new AutoValue_CelOptimizerOptions.Builder().enableAstValidation(false);
+  }
+
+  CelOptimizerOptions() {}
+}
diff --git a/optimizer/src/test/java/dev/cel/optimizer/CelOptimizerFactoryTest.java b/optimizer/src/test/java/dev/cel/optimizer/CelOptimizerFactoryTest.java
@@ -39,6 +39,19 @@ public void standardCelOptimizerBuilder_withParserCheckerAndRuntime() {
     assertThat(builder.build()).isNotNull();
   }
 
+  @Test
+  public void standardCelOptimizerBuilder_withParserCheckerRuntimeAndOptions() {
+    CelOptimizerBuilder builder =
+        CelOptimizerFactory.standardCelOptimizerBuilder(
+            CelParserFactory.standardCelParserBuilder().build(),
+            CelCompilerFactory.standardCelCheckerBuilder().build(),
+            CelRuntimeFactory.standardCelRuntimeBuilder().build(),
+            CelOptimizerOptions.newBuilder().enableAstValidation(true).build());
+
+    assertThat(builder).isNotNull();
+    assertThat(builder.build()).isNotNull();
+  }
+
   @Test
   public void standardCelOptimizerBuilder_withCompilerAndRuntime() {
     CelOptimizerBuilder builder =
@@ -50,6 +63,18 @@ public void standardCelOptimizerBuilder_withCompilerAndRuntime() {
     assertThat(builder.build()).isNotNull();
   }
 
+  @Test
+  public void standardCelOptimizerBuilder_withCompilerRuntimeAndOptions() {
+    CelOptimizerBuilder builder =
+        CelOptimizerFactory.standardCelOptimizerBuilder(
+            CelCompilerFactory.standardCelCompilerBuilder().build(),
+            CelRuntimeFactory.standardCelRuntimeBuilder().build(),
+            CelOptimizerOptions.newBuilder().enableAstValidation(true).build());
+
+    assertThat(builder).isNotNull();
+    assertThat(builder.build()).isNotNull();
+  }
+
   @Test
   public void standardCelOptimizerBuilder_withCel() {
     CelOptimizerBuilder builder =
@@ -58,4 +83,15 @@ public void standardCelOptimizerBuilder_withCel() {
     assertThat(builder).isNotNull();
     assertThat(builder.build()).isNotNull();
   }
+
+  @Test
+  public void standardCelOptimizerBuilder_withCelAndOptions() {
+    CelOptimizerBuilder builder =
+        CelOptimizerFactory.standardCelOptimizerBuilder(
+            CelFactory.standardCelBuilder().build(),
+            CelOptimizerOptions.newBuilder().enableAstValidation(true).build());
+
+    assertThat(builder).isNotNull();
+    assertThat(builder.build()).isNotNull();
+  }
 }