refactor: cloud api reporting (#928)

Author: dieppa

build.gradle.kts

@@ -19,7 +19,7 @@ plugins {
 
 allprojects {
     group = "io.flamingock"
-    val declaredVersion = "1.4.1-SNAPSHOT"
+    val declaredVersion = "1.5.0-SNAPSHOT"
     version = VersionManager.resolveVersion(declaredVersion, project.hasProperty("release"))
 
     extra["generalUtilVersion"] = "1.5.3"

cloud/flamingock-cloud-api/src/main/java/io/flamingock/cloud/api/request/ChangeRequest.java

@@ -16,6 +16,8 @@
 package io.flamingock.cloud.api.request;
 
 
+import com.fasterxml.jackson.annotation.JsonInclude;
+import io.flamingock.cloud.api.vo.CloudChangeStatus;
 import io.flamingock.cloud.api.vo.CloudTargetSystemAuditMarkType;
 
 //TODO add recoveryStrategy, so we can determin the acction in the server
@@ -25,26 +27,51 @@ public class ChangeRequest {
 
     private CloudTargetSystemAuditMarkType ongoingStatus;
 
+    /**
+     * Per-change status reported by the client — mirrors the operation-side
+     * {@code ChangeResult.status} currently held on the client's {@code PipelineRun}. The
+     * server uses this as informational input when synthesising the response: it never
+     * contradicts the client's positive report (e.g. {@code APPLIED} stays {@code APPLIED},
+     * not downgraded to {@code ALREADY_APPLIED}), and it respects {@code FAILED} /
+     * {@code ROLLED_BACK} reports so it doesn't ask the client to retry indefinitely.
+     *
+     * <p>{@code null} on the wire means the operation has nothing to report yet
+     * (equivalent to {@code NOT_REACHED}). Serialised as field-absence so the wire shape is
+     * forward-compatible with older mocks/expectations that don't set this field.
+     */
+    @JsonInclude(JsonInclude.Include.NON_NULL)
+    private CloudChangeStatus currentStatus;
+
     private boolean transactional;
 
     public ChangeRequest() {
     }
 
     public static ChangeRequest change(String id, boolean transactional) {
-        return new ChangeRequest(id, CloudTargetSystemAuditMarkType.NONE, transactional);
+        return new ChangeRequest(id, CloudTargetSystemAuditMarkType.NONE, null, transactional);
     }
 
     public static ChangeRequest ongoingExecution(String id, boolean transactional) {
-        return new ChangeRequest(id, CloudTargetSystemAuditMarkType.APPLIED, transactional);
+        return new ChangeRequest(id, CloudTargetSystemAuditMarkType.APPLIED, null, transactional);
     }
 
     public static ChangeRequest ongoingRollback(String id, boolean transactional) {
-        return new ChangeRequest(id, CloudTargetSystemAuditMarkType.ROLLED_BACK, transactional);
+        return new ChangeRequest(id, CloudTargetSystemAuditMarkType.ROLLED_BACK, null, transactional);
+    }
+
+    public ChangeRequest(String id,
+                         CloudTargetSystemAuditMarkType ongoingStatus,
+                         boolean transactional) {
+        this(id, ongoingStatus, null, transactional);
     }
 
-    public ChangeRequest(String id, CloudTargetSystemAuditMarkType ongoingStatus, boolean transactional) {
+    public ChangeRequest(String id,
+                         CloudTargetSystemAuditMarkType ongoingStatus,
+                         CloudChangeStatus currentStatus,
+                         boolean transactional) {
         this.id = id;
         this.ongoingStatus = ongoingStatus;
+        this.currentStatus = currentStatus;
         this.transactional = transactional;
     }
 
@@ -56,6 +83,10 @@ public CloudTargetSystemAuditMarkType getOngoingStatus() {
         return ongoingStatus;
     }
 
+    public CloudChangeStatus getCurrentStatus() {
+        return currentStatus;
+    }
+
     public boolean isTransactional() {
         return transactional;
     }
@@ -68,6 +99,10 @@ public void setOngoingStatus(CloudTargetSystemAuditMarkType ongoingStatus) {
         this.ongoingStatus = ongoingStatus;
     }
 
+    public void setCurrentStatus(CloudChangeStatus currentStatus) {
+        this.currentStatus = currentStatus;
+    }
+
     public void setTransactional(boolean transactional) {
         this.transactional = transactional;
     }
@@ -79,11 +114,12 @@ public boolean equals(Object o) {
         ChangeRequest that = (ChangeRequest) o;
         return transactional == that.transactional
                 && java.util.Objects.equals(id, that.id)
-                && java.util.Objects.equals(ongoingStatus, that.ongoingStatus);
+                && java.util.Objects.equals(ongoingStatus, that.ongoingStatus)
+                && java.util.Objects.equals(currentStatus, that.currentStatus);
     }
 
     @Override
     public int hashCode() {
-        return java.util.Objects.hash(id, ongoingStatus, transactional);
+        return java.util.Objects.hash(id, ongoingStatus, currentStatus, transactional);
     }
 }

cloud/flamingock-cloud-api/src/main/java/io/flamingock/cloud/api/response/ChangeResultResponse.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2026 Flamingock (https://www.flamingock.io)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.flamingock.cloud.api.response;
+
+import io.flamingock.cloud.api.vo.CloudChangeStatus;
+
+import java.util.Objects;
+
+/**
+ * Result-side per-change payload. Sibling of the operation-side {@link ChangeResponse} (which
+ * carries {@code action}); this class carries the server's synthesised {@code status} so the
+ * client can write rich per-change records into {@code PipelineRun} via
+ * {@code markStageAlreadyAppliedFromAudit} (and downstream renderers).
+ */
+public class ChangeResultResponse {
+
+    private String id;
+
+    private CloudChangeStatus status;
+
+    public ChangeResultResponse() {
+    }
+
+    public ChangeResultResponse(String id, CloudChangeStatus status) {
+        this.id = id;
+        this.status = status;
+    }
+
+    public String getId() {
+        return id;
+    }
+
+    public void setId(String id) {
+        this.id = id;
+    }
+
+    public CloudChangeStatus getStatus() {
+        return status;
+    }
+
+    public void setStatus(CloudChangeStatus status) {
+        this.status = status;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        ChangeResultResponse that = (ChangeResultResponse) o;
+        return Objects.equals(id, that.id) && status == that.status;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(id, status);
+    }
+}

cloud/flamingock-cloud-api/src/main/java/io/flamingock/cloud/api/response/ExecutionPlanResponse.java

@@ -28,8 +28,21 @@ public class ExecutionPlanResponse {
 
     private LockInfoResponse lock;
 
+    /**
+     * Operation side: the stages the executor should act on this round. Sparse — only
+     * stages with actionable changes appear here.
+     */
     private List<StageResponse> stages;
 
+    /**
+     * Result side: server's synthesised per-stage verdict + per-change status for the
+     * <strong>entire</strong> submitted pipeline (not just stages with work). The client
+     * iterates this uniformly to feed {@code PipelineRun.markStageVerdict} and
+     * {@code PipelineRun.markStageAlreadyAppliedFromAudit}. Required on {@code EXECUTE}
+     * and {@code CONTINUE} responses; absent on {@code AWAIT} / {@code ABORT}.
+     */
+    private PipelineResultResponse pipelineResult;
+
     private boolean synchronizedMarks;
 
 
@@ -54,10 +67,20 @@ public ExecutionPlanResponse(CloudExecutionAction action,
                                  LockInfoResponse lock,
                                  List<StageResponse> stages,
                                  boolean synchronizedMarks) {
+        this(action, executionId, lock, stages, null, synchronizedMarks);
+    }
+
+    public ExecutionPlanResponse(CloudExecutionAction action,
+                                 String executionId,
+                                 LockInfoResponse lock,
+                                 List<StageResponse> stages,
+                                 PipelineResultResponse pipelineResult,
+                                 boolean synchronizedMarks) {
         this.action = action;
         this.executionId = executionId;
         this.lock = lock;
         this.stages = stages;
+        this.pipelineResult = pipelineResult;
         this.synchronizedMarks = synchronizedMarks;
     }
 
@@ -89,6 +112,14 @@ public void setStages(List<StageResponse> stages) {
         this.stages = stages;
     }
 
+    public PipelineResultResponse getPipelineResult() {
+        return pipelineResult;
+    }
+
+    public void setPipelineResult(PipelineResultResponse pipelineResult) {
+        this.pipelineResult = pipelineResult;
+    }
+
     public boolean isContinue() {
         return action == CloudExecutionAction.CONTINUE;
     }
@@ -128,6 +159,15 @@ public void validate() {
         if (isAwait() && getLock() == null) {
             throw new RuntimeException("ExecutionPlan is await, but not lock information returned");
         }
+
+        // pipelineResult is required on EXECUTE and CONTINUE so the client can write
+        // per-stage verdict and per-change records uniformly. AWAIT / ABORT carry none.
+        if ((isExecute() || isContinue()) && pipelineResult == null) {
+            throw new RuntimeException(
+                    "ExecutionPlan is " + action
+                            + ", but no pipelineResult returned — the server must populate the result side"
+                            + " so the client can write verdict and per-change status into PipelineRun.");
+        }
     }
 
 }

cloud/flamingock-cloud-api/src/main/java/io/flamingock/cloud/api/response/PipelineResultResponse.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2026 Flamingock (https://www.flamingock.io)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.flamingock.cloud.api.response;
+
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Result-side sibling of {@code ExecutionPlanResponse.stages}. Carries the server's
+ * synthesised per-stage {@code verdict} and per-change {@code status} for the entire
+ * submitted pipeline, in a shape the client iterates uniformly to feed
+ * {@code PipelineRun.markStageVerdict} and
+ * {@code PipelineRun.markStageAlreadyAppliedFromAudit}.
+ *
+ * <p>The two halves of the response mirror the two halves of the core-side
+ * {@code PipelineRun} two-writer model: the operation side ({@code stages[]}) tells the
+ * executor what to do; the result side (this class) tells the client's planner what facts
+ * to record.
+ */
+public class PipelineResultResponse {
+
+    private List<StageResultResponse> stages;
+
+    public PipelineResultResponse() {
+    }
+
+    public PipelineResultResponse(List<StageResultResponse> stages) {
+        this.stages = stages;
+    }
+
+    public List<StageResultResponse> getStages() {
+        return stages;
+    }
+
+    public void setStages(List<StageResultResponse> stages) {
+        this.stages = stages;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        PipelineResultResponse that = (PipelineResultResponse) o;
+        return Objects.equals(stages, that.stages);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(stages);
+    }
+}