feat: add rollback-safe cutover keeping the monolith view consistent after rollback

Author: SAY-5

README.md

@@ -120,6 +120,24 @@ more than a 30 percent tolerance. The ratio is measured in the same run, so the
 gate catches a routing change that adds latency without being sensitive to how
 fast the runner is.
 
+## Migration safety
+
+Two mechanisms make the cutover safe, both in the gateway's
+`io.cloudshift.gateway.dualwrite` package:
+
+- Dual-write consistency. During the migration window a reservation write is
+  applied to both the monolith and the extracted service, and a consistency
+  check compares the two stored records on their business fields. Divergence is
+  counted and surfaced rather than silently accepted. The generated id is left
+  out of the comparison because the backends assign ids independently. Tests
+  prove that an injected divergence is detected and that a consistent dual-write
+  passes.
+- Rollback safety. The monolith receives every write in every phase, including
+  while the route is cut over to the service. Rolling back to the monolith
+  therefore finds a complete view with each record present exactly once. A test
+  cuts over, writes, rolls back, and asserts the monolith holds every write with
+  nothing lost and nothing duplicated.
+
 ## Cloud target
 
 The intended deployment target is Azure (Azure Container Apps or AKS), with the

docs/migration-runbook.md

@@ -66,9 +66,13 @@ Verification: a flipped route reaches the extracted service.
 ### Phase 4: rollback if needed
 
 If a problem appears after cutover, the target is flipped back to `MONOLITH`.
-Because reads and writes during the dual-write phase kept the monolith's view
-current, rolling back leaves a consistent monolith with no lost or duplicated
-records.
+Because the monolith receives every write in every phase, including while the
+route is cut over to the service, its view stays complete. Rolling back finds a
+monolith that holds each record exactly once, with nothing lost and nothing
+duplicated. The cutover coordinator
+(`io.cloudshift.gateway.dualwrite.CutoverCoordinator`) encodes this: it writes
+the monolith unconditionally and only adds the service once the migration window
+opens.
 
 ```bash
 RESERVATIONS_TARGET=MONOLITH docker compose up -d gateway

gateway/src/main/java/io/cloudshift/gateway/dualwrite/CutoverCoordinator.java

@@ -0,0 +1,52 @@
+package io.cloudshift.gateway.dualwrite;
+
+/**
+ * Drives a rollback-safe cutover for a single capability. The monolith receives every write in
+ * every phase, so its view stays complete and a rollback to the monolith never finds lost or
+ * duplicated records. The extracted service receives writes once the migration window opens, and
+ * serves reads only after the route is flipped.
+ */
+public class CutoverCoordinator {
+
+    private final ReservationWriter monolith;
+    private final ReservationWriter service;
+    private MigrationPhase phase = MigrationPhase.MONOLITH;
+
+    public CutoverCoordinator(ReservationWriter monolith, ReservationWriter service) {
+        this.monolith = monolith;
+        this.service = service;
+    }
+
+    public MigrationPhase phase() {
+        return phase;
+    }
+
+    public void beginDualWrite() {
+        phase = MigrationPhase.DUAL_WRITE;
+    }
+
+    public void cutOver() {
+        phase = MigrationPhase.SERVICE;
+    }
+
+    public void rollBack() {
+        phase = MigrationPhase.MONOLITH;
+    }
+
+    /**
+     * Applies a write according to the current phase. The monolith is written in every phase; the
+     * service is written once the migration window has opened. Writing the monolith unconditionally
+     * is what makes the rollback safe.
+     */
+    public void write(ReservationRecord request) {
+        monolith.write(request);
+        if (phase != MigrationPhase.MONOLITH) {
+            service.write(request);
+        }
+    }
+
+    /** The backend that currently serves reads for the capability. */
+    public ReservationWriter readBackend() {
+        return phase == MigrationPhase.SERVICE ? service : monolith;
+    }
+}

gateway/src/main/java/io/cloudshift/gateway/dualwrite/MigrationPhase.java

@@ -0,0 +1,18 @@
+package io.cloudshift.gateway.dualwrite;
+
+/**
+ * Phases a capability moves through during a rollback-safe cutover.
+ *
+ * <ul>
+ *   <li>{@code MONOLITH}: writes go only to the monolith.
+ *   <li>{@code DUAL_WRITE}: writes go to both backends so the monolith stays current and can be
+ *       rolled back to.
+ *   <li>{@code SERVICE}: reads are served by the extracted service while writes continue to mirror
+ *       to the monolith, keeping rollback safe.
+ * </ul>
+ */
+public enum MigrationPhase {
+    MONOLITH,
+    DUAL_WRITE,
+    SERVICE
+}

gateway/src/test/java/io/cloudshift/gateway/dualwrite/CutoverRollbackTest.java

@@ -0,0 +1,69 @@
+package io.cloudshift.gateway.dualwrite;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.time.LocalDate;
+import java.util.ArrayList;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+class CutoverRollbackTest {
+
+    /** In-memory backend that records every write so we can check for loss or duplication. */
+    private static final class RecordingStore implements ReservationWriter {
+        private final List<ReservationRecord> stored = new ArrayList<>();
+
+        @Override
+        public ReservationRecord write(ReservationRecord request) {
+            stored.add(request);
+            return request;
+        }
+
+        List<ReservationRecord> contents() {
+            return List.copyOf(stored);
+        }
+    }
+
+    private static ReservationRecord reservation(long roomId, String guest) {
+        return new ReservationRecord(
+                roomId, guest, LocalDate.of(2026, 1, 1), LocalDate.of(2026, 1, 2));
+    }
+
+    @Test
+    void cutoverThenRollbackLeavesTheMonolithConsistent() {
+        RecordingStore monolith = new RecordingStore();
+        RecordingStore service = new RecordingStore();
+        CutoverCoordinator coordinator = new CutoverCoordinator(monolith, service);
+
+        // Write before any migration.
+        coordinator.write(reservation(1, "before"));
+
+        // Open the migration window and write while dual-writing.
+        coordinator.beginDualWrite();
+        coordinator.write(reservation(2, "dual"));
+
+        // Flip reads to the service and write while cut over.
+        coordinator.cutOver();
+        coordinator.write(reservation(3, "cutover"));
+        assertThat(coordinator.readBackend()).isSameAs(service);
+
+        // Roll back to the monolith.
+        coordinator.rollBack();
+        coordinator.write(reservation(4, "after"));
+        assertThat(coordinator.readBackend()).isSameAs(monolith);
+
+        // The monolith saw every write exactly once: nothing lost, nothing duplicated.
+        List<ReservationRecord> monolithView = monolith.contents();
+        assertThat(monolithView)
+                .containsExactly(
+                        reservation(1, "before"),
+                        reservation(2, "dual"),
+                        reservation(3, "cutover"),
+                        reservation(4, "after"));
+        assertThat(monolithView).doesNotHaveDuplicates();
+
+        // The service only holds the writes made from the migration window onward.
+        assertThat(service.contents())
+                .containsExactly(reservation(2, "dual"), reservation(3, "cutover"));
+    }
+}