CB-521: make the AMQP contract test runnable locally and in CI

bridged/src/test/java/dev/ltms/bridged/msg/AmqpReplyInboxContractTest.java

@@ -1,5 +1,6 @@
 package dev.ltms.bridged.msg;
 
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
 import org.testcontainers.containers.RabbitMQContainer;
@@ -19,19 +20,46 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
  * excluded from {@code mvn test}/{@code mvn clean install} (which stay hermetic and need no Docker);
  * run it with Docker present via {@code mvn test -Pcontract}.
  *
+ * <p>Two broker modes:
+ * <ul>
+ *   <li><b>Locally</b> ({@code AMQP_URI} unset): Testcontainers spins a RabbitMQ container. Requires
+ *       a working Docker engine; see the "Running the contract tests" note in
+ *       {@code docs/CB-307-Reliable-Delivery.md} for the {@code api.version} engine-compat pin.</li>
+ *   <li><b>In CI</b> ({@code AMQP_URI} set): a RabbitMQ service container provisions the broker and
+ *       {@code AMQP_URI} points at it, so the contract job needs <em>no</em> Docker on the runner.</li>
+ * </ul>
+ *
  * <p>It proves the port contract on genuine infrastructure: eventual visibility of a published reply,
  * ack removal, msgId dedup, and — the reason Stage 2 exists — cross-restart durability: an unacked
  * reply survives closing the inbox and is redelivered to a fresh connection.
  */
 @Tag("contract")
-@Testcontainers
+// disabledWithoutDocker=false on purpose: on the CI path (AMQP_URI set) no container is started and
+// the class must still RUN against the external broker even though the runner has no Docker — a
+// disabled-without-docker check would silently skip the whole contract suite there.
+@Testcontainers(disabledWithoutDocker = false)
 class AmqpReplyInboxContractTest {
 
-    @Container
-    static final RabbitMQContainer BROKER =
+    // When a broker is provisioned out-of-band (CI service container), AMQP_URI takes us straight to
+    // it and we never touch Testcontainers. Unset locally → Testcontainers starts the container below.
+    private static final String EXTERNAL_URI = System.getenv("AMQP_URI");
+
+    private static final RabbitMQContainer BROKER =
             new RabbitMQContainer(DockerImageName.parse("rabbitmq:3.13-management"));
 
+    // No @Container on BROKER: the JUnit 5 extension would force-start it even when AMQP_URI is set.
+    // Start it manually only on the local (no-external-broker) path; Ryuk reaps it on JVM exit.
+    @BeforeAll
+    static void startBrokerUnlessExternal() {
+        if (EXTERNAL_URI == null) {
+            BROKER.start();
+        }
+    }
+
     private static String uri() {
+        if (EXTERNAL_URI != null) {
+            return EXTERNAL_URI;
+        }
         // guest/guest against the mapped AMQP port. No trailing slash: an empty path is vhost "",
         // which does not exist — omitting it selects the default vhost "/".
         return "amqp://guest:guest@" + BROKER.getHost() + ":" + BROKER.getAmqpPort();