Add version to bdd trait and syntax elements

We can now track what version an endpointBdd trait uses and attach
minimum version requirements to all syntax elements of the rules engine,
include functions. Now the coalesce function is available since version
1.1. Next, I'll add validation to ensure the version requirements of
every syntax element of an endpointRuleSet or endpointBdd meet the
version of the trait.

Author: mtdowling

smithy-rules-engine/src/main/java/software/amazon/smithy/rulesengine/language/syntax/SyntaxElement.java

@@ -22,6 +22,15 @@
  */
 @SmithyInternalApi
 public abstract class SyntaxElement implements ToCondition, ToExpression {
+    /**
+     * Get the rules engine version that this syntax element is available since.
+     *
+     * @return the version this is available since.
+     */
+    public String availableSince() {
+        return "1.0";
+    }
+
     /**
      * Returns a BooleanEquals expression comparing this expression to the provided boolean value.
      *

smithy-rules-engine/src/main/java/software/amazon/smithy/rulesengine/language/syntax/expressions/functions/Coalesce.java

@@ -37,6 +37,8 @@
  *
  * <p>Supports chaining:
  * {@code coalesce(opt1, coalesce(opt2, coalesce(opt3, default)))}
+ *
+ * <p>Available since: rules engine 1.1.
  */
 @SmithyUnstableApi
 public final class Coalesce extends LibraryFunction {
@@ -67,6 +69,11 @@ public static Coalesce ofExpressions(ToExpression arg1, ToExpression arg2) {
         return DEFINITION.createFunction(FunctionNode.ofExpressions(ID, arg1, arg2));
     }
 
+    @Override
+    public String availableSince() {
+        return "1.1";
+    }
+
     @Override
     public <R> R accept(ExpressionVisitor<R> visitor) {
         List<Expression> args = getArguments();

smithy-rules-engine/src/main/java/software/amazon/smithy/rulesengine/logic/bdd/EndpointBddTrait.java

@@ -8,6 +8,7 @@
 import java.io.DataOutputStream;
 import java.io.IOException;
 import java.io.UncheckedIOException;
+import java.math.BigDecimal;
 import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
 import java.util.ArrayList;
@@ -37,25 +38,34 @@
 public final class EndpointBddTrait extends AbstractTrait implements ToSmithyBuilder<EndpointBddTrait> {
     public static final ShapeId ID = ShapeId.from("smithy.rules#endpointBdd");
 
+    private static final BigDecimal MIN_VERSION = new BigDecimal("1.1");
     private static final Set<String> ALLOWED_PROPERTIES = SetUtils.of(
+            "version",
             "parameters",
             "conditions",
             "results",
             "root",
             "nodes",
             "nodeCount");
 
+    private final String version;
     private final Parameters parameters;
     private final List<Condition> conditions;
     private final List<Rule> results;
     private final Bdd bdd;
 
     private EndpointBddTrait(Builder builder) {
         super(ID, builder.getSourceLocation());
+        this.version = SmithyBuilder.requiredState("version", builder.version);
         this.parameters = SmithyBuilder.requiredState("parameters", builder.parameters);
         this.conditions = SmithyBuilder.requiredState("conditions", builder.conditions);
         this.results = SmithyBuilder.requiredState("results", builder.results);
         this.bdd = SmithyBuilder.requiredState("bdd", builder.bdd);
+
+        BigDecimal v = new BigDecimal(version);
+        if (v.compareTo(MIN_VERSION) < 0) {
+            throw new IllegalArgumentException("Rules engine version for endpointBdd trait must be >= " + MIN_VERSION);
+        }
     }
 
     /**
@@ -72,7 +82,14 @@ public static EndpointBddTrait from(Cfg cfg) {
             throw new IllegalStateException("Mismatch between BDD var count and orderedConditions size");
         }
 
+        // Automatically convert 1.0 versions of the decision tree to 1.1 for the minimum version of the BDD trait.
+        String version = cfg.getVersion();
+        if (version.equals("1.0")) {
+            version = "1.1";
+        }
+
         return builder()
+                .version(version)
                 .parameters(cfg.getParameters())
                 .conditions(compiler.getOrderedConditions())
                 .results(compiler.getIndexedResults())
@@ -116,6 +133,15 @@ public Bdd getBdd() {
         return bdd;
     }
 
+    /**
+     * Get the endpoint ruleset version.
+     *
+     * @return the rules engine version
+     */
+    public String getVersion() {
+        return version;
+    }
+
     /**
      * Transform this BDD using the given function and return the updated BddTrait.
      *
@@ -129,6 +155,7 @@ public EndpointBddTrait transform(Function<EndpointBddTrait, EndpointBddTrait> t
     @Override
     protected Node createNode() {
         ObjectNode.Builder builder = ObjectNode.builder();
+        builder.withMember("version", version);
         builder.withMember("parameters", parameters.toNode());
 
         ArrayNode.Builder conditionBuilder = ArrayNode.builder();
@@ -167,6 +194,7 @@ protected Node createNode() {
     public static EndpointBddTrait fromNode(Node node) {
         ObjectNode obj = node.expectObjectNode();
         obj.warnIfAdditionalProperties(ALLOWED_PROPERTIES);
+        String version = obj.expectStringMember("version").getValue();
         Parameters params = Parameters.fromNode(obj.expectObjectMember("parameters"));
         List<Condition> conditions = obj.expectArrayMember("conditions").getElementsAs(Condition::fromNode);
 
@@ -182,6 +210,7 @@ public static EndpointBddTrait fromNode(Node node) {
         Bdd bdd = decodeBdd(nodesBase64, nodeCount, rootRef, conditions.size(), results.size());
 
         EndpointBddTrait trait = builder()
+                .version(version)
                 .sourceLocation(node)
                 .parameters(params)
                 .conditions(conditions)
@@ -241,6 +270,7 @@ public static Builder builder() {
     @Override
     public Builder toBuilder() {
         return builder()
+                .version(version)
                 .sourceLocation(getSourceLocation())
                 .parameters(parameters)
                 .conditions(conditions)
@@ -252,13 +282,25 @@ public Builder toBuilder() {
      * Builder for BddTrait.
      */
     public static final class Builder extends AbstractTraitBuilder<EndpointBddTrait, Builder> {
+        private String version = "1.1";
         private Parameters parameters;
         private List<Condition> conditions;
         private List<Rule> results;
         private Bdd bdd;
 
         private Builder() {}
 
+        /**
+         * Sets the rules engine version.
+         *
+         * @param version Version to set (e.g., 1.1).
+         * @return this builder
+         */
+        public Builder version(String version) {
+            this.version = version;
+            return this;
+        }
+
         /**
          * Sets the parameters.
          *

smithy-rules-engine/src/main/java/software/amazon/smithy/rulesengine/logic/cfg/Cfg.java

@@ -15,6 +15,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.NoSuchElementException;
+import java.util.Objects;
 import java.util.Set;
 import software.amazon.smithy.rulesengine.language.EndpointRuleSet;
 import software.amazon.smithy.rulesengine.language.syntax.parameters.Parameters;
@@ -45,13 +46,18 @@ public final class Cfg implements Iterable<CfgNode> {
     // Lazily computed condition data
     private Condition[] conditions;
     private Map<Condition, Integer> conditionToIndex;
+    private final String version;
 
     Cfg(EndpointRuleSet ruleSet, CfgNode root) {
-        this(ruleSet == null ? Parameters.builder().build() : ruleSet.getParameters(), root);
+        this(
+                ruleSet == null ? Parameters.builder().build() : ruleSet.getParameters(),
+                root,
+                ruleSet == null ? "1.1" : ruleSet.getVersion());
     }
 
-    Cfg(Parameters parameters, CfgNode root) {
+    Cfg(Parameters parameters, CfgNode root, String version) {
         this.root = SmithyBuilder.requiredState("root", root);
+        this.version = version;
         this.parameters = parameters;
     }
 
@@ -69,6 +75,15 @@ public static Cfg from(EndpointRuleSet ruleSet) {
         return builder.build(root);
     }
 
+    /**
+     * Get the endpoint ruleset version of the CFG.
+     *
+     * @return endpoint ruleset version.
+     */
+    public String getVersion() {
+        return version;
+    }
+
     /**
      * Gets all unique conditions in the CFG, in the order they were discovered.
      *
@@ -141,13 +156,14 @@ public boolean equals(Object object) {
         } else if (object == null || getClass() != object.getClass()) {
             return false;
         } else {
-            return root.equals(((Cfg) object).root);
+            Cfg o = (Cfg) object;
+            return root.equals(o.root) && version.equals(o.version);
         }
     }
 
     @Override
     public int hashCode() {
-        return root.hashCode();
+        return Objects.hash(root, version);
     }
 
     /**

smithy-rules-engine/src/main/java/software/amazon/smithy/rulesengine/logic/cfg/CfgBuilder.java

@@ -66,9 +66,12 @@ public final class CfgBuilder {
     private int convergenceNodesCreated = 0;
     private int phiVariableCounter = 0;
 
+    private String version = "1.1";
+
     public CfgBuilder(EndpointRuleSet ruleSet) {
         // Apply SSA transform to ensure globally unique variable names
         this.ruleSet = SsaTransform.transform(ruleSet);
+        this.version = ruleSet.getVersion();
 
         // Analyze results and create convergence nodes
         analyzeAndCreateConvergenceNodes();
@@ -84,6 +87,17 @@ public Cfg build(CfgNode root) {
         return new Cfg(ruleSet, Objects.requireNonNull(root));
     }
 
+    /**
+     * Set the version of the endpoint rules engine (e.g., 1.1).
+     *
+     * @param version Version to set.
+     * @return the builder;
+     */
+    public CfgBuilder version(String version) {
+        this.version = Objects.requireNonNull(version);
+        return this;
+    }
+
     /**
      * Creates a condition node, reusing existing nodes when possible.
      *

smithy-rules-engine/src/main/resources/META-INF/smithy/smithy.rules.smithy

@@ -11,6 +11,10 @@ document endpointRuleSet
 @unstable
 @trait(selector: "service")
 structure endpointBdd {
+    /// The rules engine version. Must be set to 1.1 or higher.
+    @required
+    version: String
+
     /// A map of zero or more endpoint parameter names to their parameter configuration.
     @required
     parameters: Parameters
@@ -35,15 +39,12 @@ structure endpointBdd {
 
     /// Base64-encoded array of BDD nodes representing the decision graph structure.
     ///
+    /// All integers are encoded in big-endian.
+    ///
     /// The first node (index 0) is always the terminal node `[-1, 1, -1]` and is included in the nodeCount.
     /// User-defined nodes start at index 1.
     ///
-    /// Zig-zag encoding transforms signed integers to unsigned:
-    /// - 0 -> 0, -1 → 1, 1 → 2, -2 → 3, 2 → 4, etc.
-    /// - Formula: `(n << 1) ^ (n >> 31)`
-    /// - This ensures small negative numbers use few bytes
-    ///
-    /// Each node consists of three varint-encoded integers written sequentially:
+    /// Each node is written one after the other and consists of three integers written sequentially:
     /// 1. variable index
     /// 2. high reference (when condition is true)
     /// 3. low reference (when condition is false)
@@ -69,17 +70,6 @@ structure endpointBdd {
     /// boolean function and its complement; instead of creating separate nodes for `condition AND other` and
     /// `NOT(condition AND other)`, we can reuse the same nodes with complement edges. Complement edges cannot be
     /// used on result terminals.
-    ///
-    /// Example (before encoding):
-    /// ```
-    /// nodes = [
-    ///   [ -1,       1, -1],        // 0: terminal node
-    ///   [  0,       3,  2],          // 1: if condition[0] then node 3, else node 2
-    ///   [  1, 2000001, -1],   // 2: if condition[1] then result[1], else FALSE
-    /// ]
-    /// ```
-    ///
-    /// After zig-zag + varint + base64: `"AQEBAAYEBAGBwOgPAQ=="`
     @required
     nodes: String
 }

smithy-rules-engine/src/test/resources/software/amazon/smithy/rulesengine/traits/errorfiles/bdd/bdd-invalid-base64.smithy

@@ -5,6 +5,7 @@ namespace smithy.example
 use smithy.rules#endpointBdd
 
 @endpointBdd({
+    version: "1.1"
     parameters: {
         Region: {
             type: "string"

smithy-rules-engine/src/test/resources/software/amazon/smithy/rulesengine/traits/errorfiles/bdd/bdd-invalid-node-data.smithy

@@ -5,6 +5,7 @@ namespace smithy.example
 use smithy.rules#endpointBdd
 
 @endpointBdd({
+    version: "1.1"
     parameters: {
         Region: {
             type: "string"

smithy-rules-engine/src/test/resources/software/amazon/smithy/rulesengine/traits/errorfiles/bdd/bdd-invalid-root-reference.smithy

@@ -5,6 +5,7 @@ namespace smithy.example
 use smithy.rules#endpointBdd
 
 @endpointBdd({
+    version: "1.1"
     parameters: {}
     conditions: []
     results: []

smithy-rules-engine/src/test/resources/software/amazon/smithy/rulesengine/traits/errorfiles/bdd/bdd-valid.smithy

@@ -10,6 +10,7 @@ use smithy.rules#endpointBdd
     UseFips: {type: "boolean", documentation: "docs"}
 )
 @endpointBdd({
+    version: "1.1"
     "parameters": {
         "Region": {
             "required": true,