Add aggregate semantics to Policy Compiler

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

```yaml
rule:
  semantic: aggregate
  match:
    - condition: "true"
      output: "'FOO'"
    - condition: "true"
      output: "'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:
  semantic: aggregate
  match:
    - rule:
        semantic: first_match
        match:
          - condition: "resource.is_admin == true"
            rule:
              semantic: aggregate
              match:
                - condition: "resource.has_standard_pii == true"
                  output: "'GDPR_STANDARD'"
                - condition: "resource.is_b2c == true"
                  output: "'EU_B2C_NOTICE'"
    - condition: "true"
      output: "'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:
  semantic: aggregate
  match:
    - rule:
        semantic: first_match
        match:
          - condition: "1 == 2"
            output: "'EU_NOTICE'"
    - condition: "true"
      output: "'ALWAYS'"

# Output: ['ALWAYS']
```

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

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

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

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)
@@ -154,7 +164,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

@@ -39,6 +39,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();
@@ -143,12 +149,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. */
@@ -195,6 +204,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;
@@ -240,7 +241,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);
@@ -256,7 +262,16 @@ private void checkUnreachableCode(CelCompiledRule compiledRule, CompilerContext
       CelCompiledMatch compiledMatch = compiledMatches.get(i);
       boolean isTriviallyTrue = compiledMatch.isConditionTriviallyTrue();
 
-      if (isTriviallyTrue && !ruleHasOptional && i != matchCount - 1) {
+      // 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 (compiledRule.semantic() == EvaluationSemantic.FIRST_MATCH
+          && isTriviallyTrue
+          && !ruleHasOptional
+          && i != matchCount - 1) {
         if (compiledMatch.result().kind().equals(Kind.OUTPUT)) {
           compilerContext.addIssue(
               compiledMatch.sourceId(),
@@ -270,6 +285,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

@@ -27,6 +27,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.Match;
 import dev.cel.policy.CelPolicy.Match.Result;
@@ -223,6 +224,15 @@ public CelPolicy.Rule parseRule(
           case "match":
             ruleBuilder.addMatches(parseMatches(ctx, policyBuilder, value));
             break;
+          case "semantic":
+            long semanticId = ctx.collectMetadata(value);
+            if (!assertYamlType(ctx, semanticId, value, YamlNodeType.STRING, YamlNodeType.TEXT)) {
+              break;
+            }
+            String semanticStr = ((ScalarNode) value).getValue();
+            ruleBuilder.setSemantic(parseSemantic(ctx, semanticId, semanticStr));
+            break;
+
           default:
             tagVisitor.visitRuleTag(ctx, tagId, fieldName, value, policyBuilder, ruleBuilder);
             break;
@@ -409,6 +419,21 @@ private Variable parseVariableObject(
       return builder.build();
     }
 
+    private static EvaluationSemantic parseSemantic(
+        PolicyParserContext<Node> ctx, long semanticId, String semanticStr) {
+      switch (semanticStr) {
+        case "first_match":
+          return EvaluationSemantic.FIRST_MATCH;
+        case "aggregate":
+          return EvaluationSemantic.AGGREGATE;
+        default:
+          ctx.reportError(semanticId, "Invalid semantic: " + semanticStr);
+          // Just return FIRST_MATCH as a sentinel value. The end result is a compilation error
+          // anyway.
+          return EvaluationSemantic.FIRST_MATCH;
+      }
+    }
+
     private ParserImpl(
         TagVisitor<Node> tagVisitor,
         boolean enableSimpleVariables,