Add aggregate semantics to Policy Compiler

Aggregate walks through all matching rules (including nested ones) and appends them into a list:

```yaml
rule:
  aggregate:
    - condition: "true"
      emit: "'FOO'"
    - condition: "true"
      emit: "'BAR'"

# Output: ['FOO', 'BAR']
```

Few noteworthy design decisions below. All examples assume all conditions matched:

1. For usability reasons, subrules under an aggregate ancestor will always have their **lists flattened**:

```YAML
name: aggregate_flat_flattening_example
rule:
  aggregate:
    - rule:
        match:
          - condition: "resource.is_admin == true"
            output: "['GDPR_STANDARD', 'EU_B2C_NOTICE']"
    - condition: "true"
      emit: "'FALLBACK'"
# Output: ['GDPR_STANDARD', 'EU_B2C_NOTICE', 'FALLBACK']
```

2. Base case of an aggregate rule is an empty list. Nested conditional rules within an aggregate rule which outputs `optional.none()` are pruned (except in cases where policy output explicitly emits an `optional.none()`):

```YAML
name: optional_pruning_example
rule:
  aggregate:
    - rule:
        match:
          - condition: "1 == 2"
            output: "'EU_NOTICE'"
    - condition: "true"
      emit: "'ALWAYS'"

# Output: ['ALWAYS']
```

```YAML
name: explicit_optional_none_example
rule:
  aggregate:
    - rule:
        match:
          - condition: "resource.is_b2c == true"
            output: "optional.none()"   # Explicitly authored by user

    - condition: "true"
      emit: "optional.of('ALWAYS')"

# Output: [optional.none(), optional.of('ALWAYS')]

Note: nesting aggregate is currently not allowed.
```
PiperOrigin-RevId: 913930387

Author: l46kok

optimizer/src/main/java/dev/cel/optimizer/AstMutator.java

@@ -664,8 +664,8 @@ private CelMutableSource mangleIdentsInMacroSource(
     return newSource;
   }
 
-  private static CelMutableSource combine(
-      CelMutableSource celSource1, CelMutableSource celSource2) {
+  /** Combines two {@link CelMutableSource} instances into a single new instance. */
+  public static CelMutableSource combine(CelMutableSource celSource1, CelMutableSource celSource2) {
     return CelMutableSource.newInstance()
         .setDescription(
             Strings.isNullOrEmpty(celSource1.getDescription())
@@ -677,6 +677,7 @@ private static CelMutableSource combine(
         .addAllMacroCalls(celSource2.getMacroCalls());
   }
 
+
   /**
    * Stabilizes the incoming AST by ensuring that all of expr IDs are consistently renumbered
    * (monotonically increased) from the starting seed ID. If the AST contains any macro calls, its

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

@@ -179,6 +179,7 @@ java_library(
     name = "compiled_rule",
     srcs = ["CelCompiledRule.java"],
     deps = [
+        ":policy",
         "//:auto_value",
         "//bundle:cel",
         "//common:cel_ast",
@@ -246,6 +247,7 @@ java_library(
     srcs = ["RuleComposer.java"],
     deps = [
         ":compiled_rule",
+        ":policy",
         "//bundle:cel",
         "//common:cel_ast",
         "//common:compiler_common",
@@ -256,11 +258,13 @@ java_library(
         "//common/ast:mutable_expr",
         "//common/formats:value_string",
         "//common/navigation:mutable_navigation",
+        "//common/types",
         "//common/types:cel_types",
         "//common/types:type_providers",
         "//extensions:optional_library",
         "//optimizer:ast_optimizer",
         "//optimizer:mutable_ast",
         "@maven//:com_google_guava_guava",
+        "@maven//:org_jspecify_jspecify",
     ],
 )

policy/src/main/java/dev/cel/policy/CelCompiledRule.java

@@ -23,6 +23,7 @@
 import dev.cel.common.ast.CelConstant;
 import dev.cel.common.ast.CelExpr;
 import dev.cel.common.formats.ValueString;
+import dev.cel.policy.CelPolicy.EvaluationSemantic;
 import java.util.Optional;
 
 /**
@@ -43,11 +44,20 @@ public abstract class CelCompiledRule {
 
   public abstract Cel cel();
 
+  public abstract EvaluationSemantic semantic();
+
   /**
    * HasOptionalOutput returns whether the rule returns a concrete or optional value. The rule may
    * return an optional value if all match expressions under the rule are conditional.
    */
   public boolean hasOptionalOutput() {
+    // AGGREGATE rules always return a concrete list (falling back to an empty list rather than
+    // optional.none()), meaning they are never optional structurally. This also prevents dead
+    // code evasion inside parent FIRST_MATCH rules.
+    if (semantic() == EvaluationSemantic.AGGREGATE) {
+      return false;
+    }
+
     boolean isOptionalOutput = false;
     for (CelCompiledMatch match : matches()) {
       if (match.result().kind().equals(CelCompiledMatch.Result.Kind.RULE)
@@ -157,7 +167,8 @@ static CelCompiledRule create(
       Optional<ValueString> ruleId,
       ImmutableList<CelCompiledVariable> variables,
       ImmutableList<CelCompiledMatch> matches,
-      Cel cel) {
-    return new AutoValue_CelCompiledRule(sourceId, ruleId, variables, matches, cel);
+      Cel cel,
+      CelPolicy.EvaluationSemantic semantic) {
+    return new AutoValue_CelCompiledRule(sourceId, ruleId, variables, matches, cel, semantic);
   }
 }

policy/src/main/java/dev/cel/policy/CelPolicy.java

@@ -40,6 +40,12 @@
 @AutoValue
 public abstract class CelPolicy {
 
+  /** Evaluation semantic for a rule. */
+  public enum EvaluationSemantic {
+    FIRST_MATCH,
+    AGGREGATE
+  }
+
   public abstract ValueString name();
 
   public abstract Optional<ValueString> description();
@@ -176,12 +182,15 @@ public abstract static class Rule {
 
     public abstract ImmutableSet<Match> matches();
 
+    public abstract EvaluationSemantic semantic();
+
     /** Builder for {@link Rule}. */
     public static Builder newBuilder(long id) {
       return new AutoValue_CelPolicy_Rule.Builder()
           .setId(id)
           .setVariables(ImmutableSet.of())
-          .setMatches(ImmutableSet.of());
+          .setMatches(ImmutableSet.of())
+          .setSemantic(EvaluationSemantic.FIRST_MATCH);
     }
 
     /** Creates a new builder to construct a {@link Rule} instance. */
@@ -228,6 +237,8 @@ public Builder addMatches(Iterable<Match> matches) {
 
       abstract Rule.Builder setMatches(ImmutableSet<Match> matches);
 
+      public abstract Rule.Builder setSemantic(EvaluationSemantic semantic);
+
       public abstract Rule build();
     }
   }

policy/src/main/java/dev/cel/policy/CelPolicyCompilerImpl.java

@@ -44,6 +44,7 @@
 import dev.cel.policy.CelCompiledRule.CelCompiledMatch.Result;
 import dev.cel.policy.CelCompiledRule.CelCompiledMatch.Result.Kind;
 import dev.cel.policy.CelCompiledRule.CelCompiledVariable;
+import dev.cel.policy.CelPolicy.EvaluationSemantic;
 import dev.cel.policy.CelPolicy.Import;
 import dev.cel.policy.CelPolicy.Match;
 import dev.cel.policy.CelPolicy.Variable;
@@ -91,7 +92,8 @@ public CelCompiledRule compileRule(CelPolicy policy) throws CelPolicyValidationE
       extendedCel = extendedCel.toCelBuilder().setContainer(containerBuilder.build()).build();
     }
 
-    CelCompiledRule compiledRule = compileRuleImpl(policy.rule(), extendedCel, compilerContext);
+    CelCompiledRule compiledRule =
+        compileRuleImpl(policy.rule(), extendedCel, compilerContext, false);
     if (compilerContext.hasError()) {
       throw new CelPolicyValidationException(compilerContext.getIssueString());
     }
@@ -172,7 +174,14 @@ private void assertAstDepthIsSafe(CelAbstractSyntaxTree ast, Cel cel)
   }
 
   private CelCompiledRule compileRuleImpl(
-      CelPolicy.Rule rule, Cel ruleCel, CompilerContext compilerContext) {
+      CelPolicy.Rule rule,
+      Cel ruleCel,
+      CompilerContext compilerContext,
+      boolean hasAggregateAncestor) {
+    if (hasAggregateAncestor && rule.semantic().equals(EvaluationSemantic.AGGREGATE)) {
+      compilerContext.addIssue(
+          rule.id(), CelIssue.formatError(1, 0, "nested aggregate rules are not allowed"));
+    }
     // A local CEL environment used to compile a single rule. This temporary environment
     // is used to declare policy variables iteratively in a given policy, ensuring proper scoping
     // across a single / nested rule.
@@ -227,8 +236,11 @@ private CelCompiledRule compileRuleImpl(
           matchResult = Result.ofOutput(output.id(), outputAst);
           break;
         case RULE:
+          boolean nextHasAggregateAncestor =
+              hasAggregateAncestor || rule.semantic().equals(EvaluationSemantic.AGGREGATE);
           CelCompiledRule nestedRule =
-              compileRuleImpl(match.result().rule(), localCel, compilerContext);
+              compileRuleImpl(
+                  match.result().rule(), localCel, compilerContext, nextHasAggregateAncestor);
           matchResult = Result.ofRule(nestedRule);
           break;
         default:
@@ -240,7 +252,12 @@ private CelCompiledRule compileRuleImpl(
 
     CelCompiledRule compiledRule =
         CelCompiledRule.create(
-            rule.id(), rule.ruleId(), variableBuilder.build(), matchBuilder.build(), ruleCel);
+            rule.id(),
+            rule.ruleId(),
+            variableBuilder.build(),
+            matchBuilder.build(),
+            ruleCel,
+            rule.semantic());
 
     // Validate that all branches in the policy are reachable
     checkUnreachableCode(compiledRule, compilerContext);
@@ -255,6 +272,12 @@ private void checkUnreachableCode(CelCompiledRule compiledRule, CompilerContext
       CelCompiledMatch compiledMatch = compiledMatches.get(i);
       boolean isTriviallyTrue = compiledMatch.isConditionTriviallyTrue();
 
+      // Flag literally false conditions as dead code regardless of semantic
+      if (isConditionLiterallyFalse(compiledMatch.condition())) {
+        compilerContext.addIssue(
+            compiledMatch.sourceId(), CelIssue.formatError(1, 0, "Condition is always false"));
+      }
+
       // If the match is a single output or a nested rule that always returns a value, it is
       // exhaustive. If the condition is trivially true, then all subsequent branches are
       // unreachable.
@@ -263,7 +286,9 @@ private void checkUnreachableCode(CelCompiledRule compiledRule, CompilerContext
               && (compiledMatch.result().kind().equals(Kind.OUTPUT)
                   || !compiledMatch.result().rule().hasOptionalOutput());
 
-      if (isExhaustive && i != matchCount - 1) {
+      if (compiledRule.semantic() == EvaluationSemantic.FIRST_MATCH
+          && isExhaustive
+          && i != matchCount - 1) {
         if (compiledMatch.result().kind().equals(Kind.OUTPUT)) {
           compilerContext.addIssue(
               compiledMatch.sourceId(),
@@ -277,6 +302,12 @@ private void checkUnreachableCode(CelCompiledRule compiledRule, CompilerContext
     }
   }
 
+  private static boolean isConditionLiterallyFalse(CelAbstractSyntaxTree condition) {
+    CelExpr celExpr = condition.getExpr();
+    return celExpr.constantOrDefault().getKind().equals(CelConstant.Kind.BOOLEAN_VALUE)
+        && !celExpr.constant().booleanValue();
+  }
+
   private static CelAbstractSyntaxTree newErrorAst() {
     return CelAbstractSyntaxTree.newParsedAst(
         CelExpr.ofConstant(0, CelConstant.ofValue("*error*")), CelSource.newBuilder().build());

policy/src/main/java/dev/cel/policy/CelPolicyYamlParser.java

@@ -28,6 +28,7 @@
 import dev.cel.common.formats.YamlHelper.YamlNodeType;
 import dev.cel.common.formats.YamlParserContextImpl;
 import dev.cel.common.internal.CelCodePointArray;
+import dev.cel.policy.CelPolicy.EvaluationSemantic;
 import dev.cel.policy.CelPolicy.Import;
 import dev.cel.policy.CelPolicy.Invariant;
 import dev.cel.policy.CelPolicy.Match;
@@ -271,6 +272,8 @@ public CelPolicy.Rule parseRule(
         return ruleBuilder.build();
       }
 
+      boolean hasMatch = false;
+      boolean hasAggregate = false;
       for (NodeTuple nodeTuple : ((MappingNode) node).getValue()) {
         Node key = nodeTuple.getKeyNode();
         long tagId = ctx.collectMetadata(key);
@@ -290,8 +293,24 @@ public CelPolicy.Rule parseRule(
             ruleBuilder.addVariables(parseVariables(ctx, policyBuilder, value));
             break;
           case "match":
-            ruleBuilder.addMatches(parseMatches(ctx, policyBuilder, value));
+            if (hasAggregate) {
+              ctx.reportError(tagId, "Only one of 'match' or 'aggregate' may be set in a rule");
+            }
+            hasMatch = true;
+            ruleBuilder
+                .addMatches(parseMatches(ctx, policyBuilder, value, false))
+                .setSemantic(EvaluationSemantic.FIRST_MATCH);
+            break;
+          case "aggregate":
+            if (hasMatch) {
+              ctx.reportError(tagId, "Only one of 'match' or 'aggregate' may be set in a rule");
+            }
+            hasAggregate = true;
+            ruleBuilder
+                .addMatches(parseMatches(ctx, policyBuilder, value, true))
+                .setSemantic(EvaluationSemantic.AGGREGATE);
             break;
+
           default:
             tagVisitor.visitRuleTag(ctx, tagId, fieldName, value, policyBuilder, ruleBuilder);
             break;
@@ -301,7 +320,10 @@ public CelPolicy.Rule parseRule(
     }
 
     private ImmutableSet<CelPolicy.Match> parseMatches(
-        PolicyParserContext<Node> ctx, CelPolicy.Builder policyBuilder, Node node) {
+        PolicyParserContext<Node> ctx,
+        CelPolicy.Builder policyBuilder,
+        Node node,
+        boolean isAggregate) {
       long valueId = ctx.collectMetadata(node);
       ImmutableSet.Builder<CelPolicy.Match> matchesBuilder = ImmutableSet.builder();
       if (!assertYamlType(ctx, valueId, node, YamlNodeType.LIST)) {
@@ -310,7 +332,7 @@ private ImmutableSet<CelPolicy.Match> parseMatches(
 
       SequenceNode matchListNode = (SequenceNode) node;
       for (Node elementNode : matchListNode.getValue()) {
-        matchesBuilder.add(parseMatch(ctx, policyBuilder, elementNode));
+        matchesBuilder.add(parseMatchInternal(ctx, policyBuilder, elementNode, isAggregate));
       }
 
       return matchesBuilder.build();
@@ -319,6 +341,14 @@ private ImmutableSet<CelPolicy.Match> parseMatches(
     @Override
     public CelPolicy.Match parseMatch(
         PolicyParserContext<Node> ctx, CelPolicy.Builder policyBuilder, Node node) {
+      return parseMatchInternal(ctx, policyBuilder, node, false);
+    }
+
+    private CelPolicy.Match parseMatchInternal(
+        PolicyParserContext<Node> ctx,
+        CelPolicy.Builder policyBuilder,
+        Node node,
+        boolean isAggregate) {
       long nodeId = ctx.collectMetadata(node);
       if (!assertYamlType(ctx, nodeId, node, YamlNodeType.MAP)) {
         return ERROR_MATCH;
@@ -339,6 +369,20 @@ public CelPolicy.Match parseMatch(
             matchBuilder.setCondition(ctx.newSourceString(value));
             break;
           case "output":
+            if (isAggregate) {
+              ctx.reportError(tagId, "Rule aggregate requires 'emit' tag instead of 'output'");
+            }
+            matchBuilder
+                .result()
+                .filter(result -> result.kind().equals(Match.Result.Kind.RULE))
+                .ifPresent(
+                    result -> ctx.reportError(tagId, "Only the rule or the output may be set"));
+            matchBuilder.setResult(Match.Result.ofOutput(ctx.newSourceString(value)));
+            break;
+          case "emit":
+            if (!isAggregate) {
+              ctx.reportError(tagId, "Rule match requires 'output' tag instead of 'emit'");
+            }
             matchBuilder
                 .result()
                 .filter(result -> result.kind().equals(Match.Result.Kind.RULE))