Add BDD test suite covering V2 SDK functionality

Ports the TypeScript SDK's BDD coverage to Java, mirroring scenarios
across aggregator communication, token minting/transfer/verification,
splits, payments, sharding, CBOR envelope strictness, and inclusion
proofs. Covers the V2 PR chain (#53, #54, #59, #61, #62, #63, #65)
end-to-end against both the hermetic in-process aggregator and the
real BFT-shard topology via subscription proxy.

- 49 Cucumber feature files (~149 scenario declarations)
- 33 step-definition classes wired through PicoContainer
- Test-only support clients: StrictTestAggregatorClient,
  ForgivingTestAggregatorClient, ShardAwareAggregatorClient,
  SimulatedShardPool, NametagRegistry, TokenTree(Builder)
- Tag-based runtime gating: @hermetic-only, @bft-shard-only,
  @multi-shard-only, @pending-src-cleanup, @stateful,
  @fresh-aggregator, @slow
- Env wiring: AGGREGATOR_URL, AGGREGATOR_API_KEY, TRUST_BASE_PATH
- JUnit Platform Suite runner with package selection

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: b3y0urs3lf

build.gradle.kts

@@ -68,6 +68,7 @@ dependencies {
     // ✅ Cucumber for BDD
     testImplementation("io.cucumber:cucumber-java:7.27.2")
     testImplementation("io.cucumber:cucumber-junit-platform-engine:7.27.2")
+    testImplementation("io.cucumber:cucumber-picocontainer:7.27.2")
 
     // JUnit 5 Suite annotations
     testImplementation("org.junit.platform:junit-platform-suite:1.13.4")
@@ -180,6 +181,112 @@ tasks.register<Test>("allCucumberTests") {
     shouldRunAfter(tasks.test)
 }
 
+// ─── BDD tasks (Phase 0 of BDD migration plan) ───────────────────────────────
+// Default BDD run: defers to CucumberTestRunner's static-init default tag
+// filter, which is "not @nametag and not @slow and not @wip and not @ignore"
+// but yields to an explicit -Dcucumber.filter.tags=<expr> override.
+tasks.register<Test>("bddTest") {
+    useJUnitPlatform()
+    maxHeapSize = "1024m"
+    systemProperty("cucumber.junit-platform.naming-strategy", "long")
+    systemProperties = System.getProperties().toMap() as Map<String, Any>
+
+    // Make BDD env vars part of the task's up-to-date cache key so that
+    // switching AGGREGATOR_URL / TRUST_BASE_PATH / tag filter actually forces a
+    // re-run. Without this, Gradle sees unchanged source+classpath and serves
+    // a cached pass in ~3 seconds.
+    inputs.property("AGGREGATOR_URL", System.getenv("AGGREGATOR_URL") ?: "")
+    inputs.property("AGGREGATOR_API_KEY", System.getenv("AGGREGATOR_API_KEY") ?: "")
+    inputs.property("TRUST_BASE_PATH", System.getenv("TRUST_BASE_PATH") ?: "")
+    inputs.property(
+        "cucumber.filter.tags",
+        System.getProperty("cucumber.filter.tags") ?: ""
+    )
+
+    // Stream Cucumber's `pretty` formatter output live to the console.
+    // Without this, Gradle captures the test JVM's stdout and you only see a
+    // progress bar + pass/fail totals at the end.
+    testLogging {
+        showStandardStreams = true
+        events("passed", "skipped", "failed")
+        exceptionFormat = org.gradle.api.tasks.testing.logging.TestExceptionFormat.FULL
+    }
+
+    filter {
+        includeTestsMatching("*CucumberTestRunner*")
+    }
+    shouldRunAfter(tasks.test)
+}
+
+// Nametag-gated scenarios: expected to be reported as SKIPPED until UnicityId
+// is ported to Java v2. See BDD_MIGRATION_PLAN.md Phase 8.
+tasks.register<Test>("bddNametag") {
+    useJUnitPlatform()
+    maxHeapSize = "1024m"
+    systemProperty("cucumber.junit-platform.naming-strategy", "long")
+    systemProperties = System.getProperties().toMap() as Map<String, Any>
+    systemProperty("cucumber.filter.tags", "@nametag")
+
+    filter {
+        includeTestsMatching("*CucumberTestRunner*")
+    }
+    shouldRunAfter(tasks.test)
+}
+
+// Performance / load scenarios — needs sharded aggregator topology.
+tasks.register<Test>("bddSlow") {
+    useJUnitPlatform()
+    maxHeapSize = "4096m"
+    systemProperty("cucumber.junit-platform.naming-strategy", "long")
+    systemProperties = System.getProperties().toMap() as Map<String, Any>
+    systemProperty("cucumber.filter.tags", "@slow or @shard-load")
+
+    filter {
+        includeTestsMatching("*CucumberTestRunner*")
+    }
+    shouldRunAfter(tasks.test)
+}
+
+// Fast subset — excludes @tree (the ~136-row 4-level-tree family that dominates
+// live-aggregator runtime) in addition to the default exclusions. Use this for
+// quick live-aggregator smoke runs. Full coverage: use bddTest (slow on live).
+tasks.register<Test>("bddTestFast") {
+    useJUnitPlatform()
+    maxHeapSize = "1024m"
+    systemProperty("cucumber.junit-platform.naming-strategy", "long")
+    systemProperties = System.getProperties().toMap() as Map<String, Any>
+    systemProperty(
+        "cucumber.filter.tags",
+        "not @nametag and not @slow and not @wip and not @ignore and not @tree"
+    )
+    inputs.property("AGGREGATOR_URL", System.getenv("AGGREGATOR_URL") ?: "")
+    inputs.property("TRUST_BASE_PATH", System.getenv("TRUST_BASE_PATH") ?: "")
+    testLogging {
+        showStandardStreams = true
+        events("passed", "skipped", "failed")
+        exceptionFormat = org.gradle.api.tasks.testing.logging.TestExceptionFormat.FULL
+    }
+    filter {
+        includeTestsMatching("*CucumberTestRunner*")
+    }
+    shouldRunAfter(tasks.test)
+}
+
+// Everything — used for coverage sweeps. Expect nametag scenarios to skip until
+// UnicityId is ported.
+tasks.register<Test>("bddAll") {
+    useJUnitPlatform()
+    maxHeapSize = "2048m"
+    systemProperty("cucumber.junit-platform.naming-strategy", "long")
+    systemProperties = System.getProperties().toMap() as Map<String, Any>
+    systemProperty("cucumber.filter.tags", "not @ignore")
+
+    filter {
+        includeTestsMatching("*CucumberTestRunner*")
+    }
+    shouldRunAfter(tasks.test)
+}
+
 // Create separate JARs for each platform
 tasks.register<Jar>("androidJar") {
     archiveClassifier.set("android")

src/test/java/org/unicitylabs/sdk/e2e/CucumberTestRunner.java

@@ -0,0 +1,39 @@
+package org.unicitylabs.sdk.e2e;
+
+import io.cucumber.junit.platform.engine.Constants;
+import org.junit.platform.suite.api.ConfigurationParameter;
+import org.junit.platform.suite.api.IncludeEngines;
+import org.junit.platform.suite.api.SelectPackages;
+import org.junit.platform.suite.api.Suite;
+
+@Suite
+@IncludeEngines("cucumber")
+@SelectPackages("org.unicitylabs.sdk.features")
+@ConfigurationParameter(
+    key = Constants.GLUE_PROPERTY_NAME,
+    value = "org.unicitylabs.sdk.e2e.steps,"
+        + "org.unicitylabs.sdk.e2e.steps.shared,"
+        + "org.unicitylabs.sdk.e2e.config")
+@ConfigurationParameter(
+    key = Constants.PLUGIN_PROPERTY_NAME,
+    value = "pretty,"
+        + "html:build/cucumber-reports/cucumber.html,"
+        + "json:build/cucumber-reports/cucumber.json")
+@ConfigurationParameter(
+    key = Constants.EXECUTION_DRY_RUN_PROPERTY_NAME,
+    value = "false")
+@ConfigurationParameter(
+    key = Constants.PLUGIN_PUBLISH_QUIET_PROPERTY_NAME,
+    value = "true")
+// Default tag filter — excludes nametag-gated scenarios (blocked until UnicityId
+// lands), load/perf scenarios, and work-in-progress. Overridable by passing
+// -Dcucumber.filter.tags=<expr> on the command line; system properties take
+// precedence over @ConfigurationParameter defaults per JUnit Platform spec.
+@ConfigurationParameter(
+    key = Constants.FILTER_TAGS_PROPERTY_NAME,
+    value = "not @slow and not @wip and not @ignore "
+        + "and not @bft-shard-only and not @multi-shard-only "
+        + "and not @pending-src-cleanup "
+        + "and not @stateful and not @fresh-aggregator")
+public class CucumberTestRunner {
+}

src/test/java/org/unicitylabs/sdk/e2e/config/CucumberConfiguration.java

@@ -0,0 +1,37 @@
+package org.unicitylabs.sdk.e2e.config;
+
+import io.cucumber.java.After;
+import io.cucumber.java.Before;
+import io.cucumber.java.Scenario;
+import org.unicitylabs.sdk.e2e.context.TestContext;
+
+/**
+ * Cucumber lifecycle hooks. Cucumber's PicoContainer creates one instance per scenario and
+ * injects the shared {@link TestContext}, ensuring the same context reaches every step class
+ * that takes it as a constructor parameter.
+ */
+public class CucumberConfiguration {
+
+  private final TestContext testContext;
+
+  public CucumberConfiguration(TestContext testContext) {
+    this.testContext = testContext;
+  }
+
+  @Before
+  public void beforeScenario(Scenario scenario) {
+    testContext.clearTestState();
+    System.out.println("[BDD] >>> " + scenario.getName());
+  }
+
+  @After
+  public void afterScenario(Scenario scenario) {
+    System.out.println(
+        "[BDD] <<< " + scenario.getName() + " — " + scenario.getStatus());
+  }
+
+  @After("@reset")
+  public void fullReset() {
+    testContext.reset();
+  }
+}