Docs: describe ID reuse policies and start request IDs as the server implements them (#1584)

Proto comments for IdReusePolicy, FlowAlreadyStartedOptions, and StartFlowRequest.request_id (with the retry rule from #1559), regenerated code; the abnormal-close policy now documents Failed, Canceled, and Terminated across the five SDKs, the Developer reference, and skills; the default reuse value is documented as Disallow with no server setting. No behavior change. Skills 1.0.13.

Author: longquanzheng

docs/reference/go/start-flow-options.mdx

@@ -149,7 +149,7 @@ rejects the start:
 | **IDReusePolicy** | Existing active Flow | Existing closed Flow |
 |-------------------|----------------------|----------------------|
 | **IDReuseDefault** | Rejects the start. | Rejects the start. |
-| **IDReuseAllowIfPreviousFailed** | Rejects the start. | Starts a new run only after a failed run; otherwise rejects it. |
+| **IDReuseAllowIfPreviousFailed** | Rejects the start. | Starts a new run when the latest run failed, was canceled, or was terminated. A Flow timeout closes a run as failed or canceled under the fail or cancel timeout policy; under the handler policy, the handler's outcome decides. Rejects the start after a completed run. |
 | **IDReuseAllowIfNotRunning** | Rejects the start. | Starts a new run. |
 | **IDReuseDisallow** | Rejects the start. | Rejects the start. |
 | **IDReuseTerminateIfRunning** | Terminates the active run and starts a replacement. It does not produce an already-started error. | Starts a new run. |

docs/reference/java/start-flow-options.mdx

@@ -142,7 +142,7 @@ rejects the start:
 | **IDReusePolicy** | Existing active Flow | Existing closed Flow |
 |-------------------|----------------------|----------------------|
 | **IDReuseDefault** | Rejects the start. | Rejects the start. |
-| **IDReuseAllowIfPreviousFailed** | Rejects the start. | Starts a new run only after a failed run; otherwise rejects it. |
+| **IDReuseAllowIfPreviousFailed** | Rejects the start. | Starts a new run when the latest run failed, was canceled, or was terminated. A Flow timeout closes a run as failed or canceled under the fail or cancel timeout policy; under the handler policy, the handler's outcome decides. Rejects the start after a completed run. |
 | **IDReuseAllowIfNotRunning** | Rejects the start. | Starts a new run. |
 | **IDReuseDisallow** | Rejects the start. | Rejects the start. |
 | **IDReuseTerminateIfRunning** | Terminates the active run and starts a replacement. It does not produce an already-started error. | Starts a new run. |

docs/reference/python/start-flow-options.mdx

@@ -135,7 +135,7 @@ rejects the start:
 | **IDReusePolicy** | Existing active Flow | Existing closed Flow |
 |-------------------|----------------------|----------------------|
 | **IDReuseDefault** | Rejects the start. | Rejects the start. |
-| **IDReuseAllowIfPreviousFailed** | Rejects the start. | Starts a new run only after a failed run; otherwise rejects it. |
+| **IDReuseAllowIfPreviousFailed** | Rejects the start. | Starts a new run when the latest run failed, was canceled, or was terminated. A Flow timeout closes a run as failed or canceled under the fail or cancel timeout policy; under the handler policy, the handler's outcome decides. Rejects the start after a completed run. |
 | **IDReuseAllowIfNotRunning** | Rejects the start. | Starts a new run. |
 | **IDReuseDisallow** | Rejects the start. | Rejects the start. |
 | **IDReuseTerminateIfRunning** | Terminates the active run and starts a replacement. It does not produce an already-started error. | Starts a new run. |

docs/reference/rust/start-flow-options.mdx

@@ -145,7 +145,7 @@ rejects the start:
 | **IDReusePolicy** | Existing active Flow | Existing closed Flow |
 |-------------------|----------------------|----------------------|
 | **IDReuseDefault** | Rejects the start. | Rejects the start. |
-| **IDReuseAllowIfPreviousFailed** | Rejects the start. | Starts a new run only after a failed run; otherwise rejects it. |
+| **IDReuseAllowIfPreviousFailed** | Rejects the start. | Starts a new run when the latest run failed, was canceled, or was terminated. A Flow timeout closes a run as failed or canceled under the fail or cancel timeout policy; under the handler policy, the handler's outcome decides. Rejects the start after a completed run. |
 | **IDReuseAllowIfNotRunning** | Rejects the start. | Starts a new run. |
 | **IDReuseDisallow** | Rejects the start. | Rejects the start. |
 | **IDReuseTerminateIfRunning** | Terminates the active run and starts a replacement. It does not produce an already-started error. | Starts a new run. |

docs/reference/typescript/start-flow-options.mdx

@@ -140,7 +140,7 @@ rejects the start:
 | **IDReusePolicy** | Existing active Flow | Existing closed Flow |
 |-------------------|----------------------|----------------------|
 | **IDReuseDefault** | Rejects the start. | Rejects the start. |
-| **IDReuseAllowIfPreviousFailed** | Rejects the start. | Starts a new run only after a failed run; otherwise rejects it. |
+| **IDReuseAllowIfPreviousFailed** | Rejects the start. | Starts a new run when the latest run failed, was canceled, or was terminated. A Flow timeout closes a run as failed or canceled under the fail or cancel timeout policy; under the handler policy, the handler's outcome decides. Rejects the start after a completed run. |
 | **IDReuseAllowIfNotRunning** | Rejects the start. | Starts a new run. |
 | **IDReuseDisallow** | Rejects the start. | Rejects the start. |
 | **IDReuseTerminateIfRunning** | Terminates the active run and starts a replacement. It does not produce an already-started error. | Starts a new run. |

protos/dex.proto

@@ -487,15 +487,28 @@ message FlowTimeoutHandlerOptions {
   repeated string load_channel_map_instances = 11;
 }
 
+// Decides whether StartFlow may start a new run for a Flow ID that already has a run.
+// Dex checks the latest run only. A Flow ID without runs always starts.
+// A retry of the latest run's start request skips this policy; see StartFlowRequest.request_id.
 enum IdReusePolicy {
+  // Same as ID_REUSE_POLICY_DISALLOW_REUSE.
   ID_REUSE_POLICY_UNSPECIFIED = 0;
+  // Starts a new run when the latest run closed as FAILED, CANCELED, or TERMINATED.
+  // Rejects the start when the latest run is RUNNING or COMPLETED.
+  // A Flow timeout closes a run as FAILED or CANCELED under FAIL or CANCEL; under HANDLER, the handler decides.
   ID_REUSE_POLICY_ALLOW_IF_PREVIOUS_EXISTS_ABNORMALLY = 1;
+  // Starts a new run when the latest run is closed, whatever its status.
   ID_REUSE_POLICY_ALLOW_IF_NO_RUNNING = 2;
+  // Rejects the start whenever the Flow ID has a run.
   ID_REUSE_POLICY_DISALLOW_REUSE = 3;
+  // Terminates a running latest run, then starts a new run. Never rejects a new request.
   ID_REUSE_POLICY_ALLOW_TERMINATE_IF_RUNNING = 4;
 }
 
+// Chooses the StartFlow result when Dex does not start a new run.
 message FlowAlreadyStartedOptions {
+  // True returns the latest run's ID when the request ID matches that run's start request ID.
+  // Otherwise, and whenever this is false, StartFlow fails with ALREADY_EXISTS (FLOW_ALREADY_STARTED).
   bool ignore_already_started_error = 1;
 }
 
@@ -626,6 +639,9 @@ message StartFlowRequest {
   Value step_input = 8;
   StepOptions step_options = 9;
   FlowStartOptions flow_start_options = 10;
+  // Required. Identifies one logical start; Dex records it on the run it starts.
+  // A request with the latest run's request ID is a retry: Dex never applies the ID reuse policy.
+  // flow_already_started_options then chooses the result. Dex compares only the ID, not input or options.
   string request_id = 11;
 }
 

sdk-go/dex/options.go

@@ -466,9 +466,14 @@ func defaultSubFlowOptions() SubFlowOptions {
 type IDReusePolicy uint8
 
 const (
-	// IDReuseDefault uses the server default, which rejects every previously used Flow ID.
+	// IDReuseDefault rejects the start whenever the Flow ID has a run, the same as IDReuseDisallow.
+	// The server does not make this default configurable.
 	IDReuseDefault IDReusePolicy = iota
-	// IDReuseAllowIfPreviousFailed permits reuse only after a failed run.
+	// IDReuseAllowIfPreviousFailed starts a new run only when the latest run closed abnormally:
+	// failed, canceled, or terminated.
+	// A Flow timeout closes a run as failed or canceled under the fail or cancel timeout policy.
+	// Under the handler policy, the timeout handler's outcome decides.
+	// A running or completed latest run rejects the start.
 	IDReuseAllowIfPreviousFailed
 	// IDReuseAllowIfNotRunning permits reuse when no run is active.
 	IDReuseAllowIfNotRunning

sdk-go/gen/dexpb/dex.pb.go

@@ -17,10 +17,18 @@
  * the server against prior and currently running executions with the same Flow ID.
  */
 public enum IdReusePolicy {
-    /** Uses the Dex server default, which rejects every previously used Flow ID. */
+    /**
+     * Rejects the start whenever the Flow ID has a run, the same as {@link #DISALLOW}. The server
+     * does not make this default configurable.
+     */
     DEFAULT,
 
-    /** Allows reuse only when the previous execution ended abnormally. */
+    /**
+     * Starts a new run only when the latest run closed abnormally: failed, canceled, or terminated.
+     * A Flow timeout closes a run as failed or canceled under the fail or cancel timeout policy.
+     * Under the handler policy, the timeout handler's outcome decides. A running or completed latest
+     * run rejects the start.
+     */
     ALLOW_IF_PREVIOUS_FAILED,
 
     /** Allows reuse when no execution with the ID is currently running. */