Record a child enqueue's deduplication collision as the parent's step (#625)

Closes #602.

When a workflow enqueued a child whose deduplication ID another workflow
held, `DBOSQueueDuplicatedException` reached the parent with nothing
recorded at the parent's step. A parent that caught it and took another
path, then was recovered after the holder finished, enqueued the child
for real on replay, and its later steps diverged from their checkpoints.

#602's second problem, the child's insert and the parent's step
committing separately, was already fixed by #616:
`initChildWorkflowStatus` writes both in one transaction.

## Changes

**1. The collision is the parent's step result.** When a child enqueue
collides, the parent records `DBOSQueueDuplicatedException` as its
step's result, with no child ID, then rethrows it. The record is fenced
on the parent's execution: a parent that no longer owns its workflow is
refused, and stops. If recording fails, that failure is thrown with the
collision attached as suppressed; throwing the collision unrecorded
would let the parent take a path its replay can't repeat.

**2. A replay rethrows it.** The replay checks before a child start or
enqueue (`executeWorkflow`, `enqueueWorkflowByName`, `enqueueDebounced`)
go through one helper, `recordedChild`. `checkChildWorkflow` now returns
the recorded step rather than only its child ID, so a recorded collision
is thrown again instead of looking like an empty slot.

**3. The recorded step must be this call's.** A replay accepts what is
recorded at the slot only when it was recorded under the name of the
workflow being started; otherwise the step is a different one and the
replay throws `DBOSUnexpectedStepException`, as `checkStepResult` does
for any other step. This applies to a recorded child as well as a
recorded collision. Every release so far recorded a child under the
workflow's name, so their histories still replay.
- **Exemption:** releases before 1.2 recorded the debouncer workflow
they started in a debounced enqueue's slot, under
`Constants.DEBOUNCER_WORKFLOW_NAME`. `enqueueDebounced` accepts that
name there, and returns the recorded child itself rather than leave it
to `executeWorkflow`. The exemption is kept until 2.0, which can drop
replay support for workflows that debounced before 1.2.
- **Behaviour change:** a slot holding a different step is now reported
as `DBOSUnexpectedStepException` when the replay reads it, rather than
as `DBOSStepNondeterminismException` when the child's start writes it.

**4. Debouncer's own replay of a collision stays.** It throws the
collision again when the slot recorded nothing and the next slot is
`DBOS.lookupDebouncer`. New histories record the collision, so the
general replay handles them, but histories recorded before this change
still need it.

Matches Python (`_init_workflow` and `_check_recorded_enqueue` in
`_core.py`) and TypeScript (`enqueue_workflow.ts`), which record the
collision as the parent's step and rethrow it on replay. They also
record a rejected workflow-ID reuse the same way; Java has no ID reuse
policy yet.

## Tests

`ChildEnqueueErrorTest`:
- A parent that catches a deduplicated child enqueue records the
collision as its step, and when recovered after the holder finishes,
still falls back and enqueues no child. Fails without the recording.
- A collision recorded under another step's name, and a child recorded
under another step's name, each make the recovered parent throw
`DBOSUnexpectedStepException`. Each fails without its name check.

`DebouncerTest.replaysADebounceThatStartedADebouncerWorkflow`, which
seeds the pre-1.2 slot, covers the exemption; it fails without it.

Run locally: the queue, child-workflow, debouncer, ownership-fence,
ownership and invocation tests. The full suite has not been run locally;
this PR's CI run is that pass.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: devhawk

transact/src/main/java/dev/dbos/transact/database/SystemDatabase.java

@@ -1530,7 +1530,8 @@ public List<String> startQueuedPartitionedWorkflows(
                 ownerXid));
   }
 
-  public Optional<String> checkChildWorkflow(String workflowUuid, int functionId) {
+  /** See {@link WorkflowDAO#checkChildWorkflow}. */
+  public Optional<StepResult> checkChildWorkflow(String workflowUuid, int functionId) {
     return dbRetry(() -> WorkflowDAO.checkChildWorkflow(ctx, workflowUuid, functionId));
   }
 

transact/src/main/java/dev/dbos/transact/database/dao/WorkflowDAO.java

@@ -2110,12 +2110,17 @@ public static <T> Result<T> awaitWorkflowResult(
     }
   }
 
-  public static Optional<String> checkChildWorkflow(
+  /**
+   * What a parent's step recorded for a child it started or enqueued: the child's ID, or the
+   * deduplication collision its enqueue failed with. Empty when nothing is recorded at that step.
+   */
+  public static Optional<StepResult> checkChildWorkflow(
       DbContext ctx, String workflowUuid, int functionId) throws SQLException {
 
     final String sql =
         """
-          SELECT child_workflow_id FROM "%s".operation_outputs WHERE workflow_uuid = ? AND function_id = ?
+          SELECT function_name, child_workflow_id, error, serialization
+          FROM "%s".operation_outputs WHERE workflow_uuid = ? AND function_id = ?
         """
             .formatted(ctx.schema());
 
@@ -2127,8 +2132,15 @@ public static Optional<String> checkChildWorkflow(
 
       try (ResultSet rs = stmt.executeQuery()) {
         if (rs.next()) {
-          String childWorkflowId = rs.getString("child_workflow_id");
-          return childWorkflowId != null ? Optional.of(childWorkflowId) : Optional.empty();
+          return Optional.of(
+              new StepResult(
+                  workflowUuid,
+                  functionId,
+                  rs.getString("function_name"),
+                  null,
+                  SystemDatabase.errorOrNull(rs.getString("error")),
+                  rs.getString("child_workflow_id"),
+                  rs.getString("serialization")));
         }
         return Optional.empty();
       }

transact/src/main/java/dev/dbos/transact/execution/DBOSExecutor.java

@@ -530,10 +530,11 @@ public Object debounceDelayedWorkflow(
    * that slot recorded -- which, for a debounce recorded before debounced workflows, is the
    * debouncer workflow, not {@code workflowId}.
    *
-   * <p>An enqueue that collided records nothing in its slot, so a replay alone cannot tell it from
-   * one that never ran. A collision is always followed by the {@code DBOS.lookupDebouncer} step in
-   * the next slot, in this release and the ones before it, so when that step is recorded the replay
-   * throws the collision again rather than enqueue for real: the key may be free by now, or held on
+   * <p>An enqueue that collides records the collision in its slot, and a replay throws it again.
+   * Releases before 1.3 recorded nothing there, so a replay alone cannot tell their collision from
+   * an enqueue that never ran. A collision is always followed by the {@code DBOS.lookupDebouncer}
+   * step in the next slot, so when that step is recorded and the slot is empty, the replay throws
+   * the collision again rather than enqueue for real: the key may be free by now, or held on
    * another queue than the one it collided on.
    *
    * <p>The workflow takes {@code timeout}, timed from its dequeue, and no deadline: it may start
@@ -554,10 +555,16 @@ public <T, E extends Exception> WorkflowHandle<T, E> enqueueDebounced(
       @Nullable Map<String, Object> attributes) {
     var ctx = DBOSContextHolder.get();
     var parent = getParent(ctx);
-    if (parent != null
-        && systemDatabase.checkChildWorkflow(parent.workflowId(), parent.functionId()).isEmpty()
-        && lookupDebouncerRecordedAfter(parent)) {
-      throw new DBOSQueueDuplicatedException(workflowId, queueName, deduplicationId);
+    if (parent != null) {
+      // Returned here rather than left to executeWorkflow, which would not accept the debouncer
+      // workflow a release before 1.2 recorded in this slot.
+      var childId = recordedChild(parent, workflow.workflowName(), true);
+      if (childId != null) {
+        return retrieveWorkflow(childId);
+      }
+      if (lookupDebouncerRecordedAfter(parent)) {
+        throw new DBOSQueueDuplicatedException(workflowId, queueName, deduplicationId);
+      }
     }
     var options =
         debouncedOptions(
@@ -2166,9 +2173,9 @@ public <T, E extends Exception> WorkflowHandle<T, E> enqueueWorkflowByName(
                     ctx.getNextWorkflowId(childWorkflowId), () -> UUID.randomUUID().toString()));
 
     if (parent != null) {
-      var childId = systemDatabase.checkChildWorkflow(parent.workflowId(), parent.functionId());
-      if (childId.isPresent()) {
-        return retrieveWorkflow(childId.get());
+      var childId = recordedChild(parent, options.workflowName(), false);
+      if (childId != null) {
+        return retrieveWorkflow(childId);
       }
     }
 
@@ -2373,6 +2380,42 @@ private void validateQueue(String queueName, String queuePartitionKey) {
     }
   }
 
+  /**
+   * The child the parent's current step recorded when it first ran, or null when it recorded none.
+   * When the step recorded a deduplication collision for this start or enqueue, throws it again, so
+   * a replay sees what the original call saw.
+   *
+   * <p>The step is this call's only if it was recorded under the same workflow name; otherwise it
+   * is another one, and the replay is not deterministic. One exception, for a debounced enqueue
+   * ({@code debounced}): releases before 1.2 recorded the debouncer workflow they started in its
+   * slot, under that workflow's name.
+   */
+  private @Nullable String recordedChild(
+      WorkflowInfo parent, String workflowName, boolean debounced) {
+    var recorded = systemDatabase.checkChildWorkflow(parent.workflowId(), parent.functionId());
+    if (recorded.isEmpty()) {
+      return null;
+    }
+    var step = recorded.get();
+    var debouncerWorkflow =
+        debounced
+            && step.error() == null
+            && step.childWorkflowId() != null
+            && Constants.DEBOUNCER_WORKFLOW_NAME.equals(step.stepName());
+    if (!debouncerWorkflow && !workflowName.equals(step.stepName())) {
+      throw new DBOSUnexpectedStepException(
+          parent.workflowId(), parent.functionId(), workflowName, step.stepName());
+    }
+    if (step.error() != null) {
+      var t = SerializationUtil.deserializeError(step.error(), step.serialization(), serializer);
+      if (t instanceof RuntimeException re) {
+        throw re;
+      }
+      throw new RuntimeException(t.getMessage(), t);
+    }
+    return step.childWorkflowId();
+  }
+
   // execute or enqueue a worklow
   private <T, E extends Exception> WorkflowHandle<T, E> executeWorkflow(
       RegisteredWorkflow workflow, Object[] args, ExecutionOptions options, WorkflowInfo parent) {
@@ -2384,9 +2427,9 @@ private <T, E extends Exception> WorkflowHandle<T, E> executeWorkflow(
     }
 
     if (parent != null) {
-      var childId = systemDatabase.checkChildWorkflow(parent.workflowId(), parent.functionId());
-      if (childId.isPresent()) {
-        return retrieveWorkflow(childId.get());
+      var childId = recordedChild(parent, workflow.workflowName(), false);
+      if (childId != null) {
+        return retrieveWorkflow(childId);
       }
     }
 
@@ -2702,6 +2745,7 @@ public static void enqueueWorkflow(
         RegisteredWorkflow.fullyQualifiedName(
             workflowName, Objects.requireNonNullElse(className, ""), instanceName));
 
+    var startTime = System.currentTimeMillis();
     try {
       persistWorkflow(
           systemDatabase,
@@ -2719,6 +2763,32 @@ public static void enqueueWorkflow(
     } catch (DBOSQueueDuplicatedException e) {
       logger.debug(
           "Workflow queue {} reused deduplicationId {}", e.queueName(), e.deduplicationId());
+      // A parent records the collision as its step, so a replay throws it again even after the
+      // holder has finished and the enqueue would succeed. Only while the parent's execution still
+      // owns the parent: one that does not is refused here, and stops.
+      // A failure to record it is thrown instead, with the collision attached: thrown unrecorded,
+      // the collision would let the parent take a path its replay cannot repeat.
+      if (parent != null) {
+        // In the native format whatever serializer is configured: a replay must rebuild the exact
+        // type the parent and Debouncer catch, which a custom serializer need not preserve.
+        var error = SerializationUtil.serializeError(e, SerializationUtil.NATIVE, null);
+        try {
+          systemDatabase.recordStepResult(
+              new StepResult(
+                  parent.workflowId(),
+                  parent.functionId(),
+                  workflowName,
+                  null,
+                  error.serializedValue(),
+                  null,
+                  error.serialization()),
+              startTime,
+              parent.ownerXid());
+        } catch (RuntimeException recordFailure) {
+          recordFailure.addSuppressed(e);
+          throw recordFailure;
+        }
+      }
       throw e;
     } catch (DBOSWorkflowExecutionConflictException e) {
       // A parent that no longer owns its workflow was refused: the fence working, not a failure.