docs: Add Idempotency and Correlation documentation and example

docs/modules/ROOT/examples/org/acme/IdempotencyExample.java

@@ -0,0 +1,13 @@
+package org.acme;
+
+import io.serverlessworkflow.impl.WorkflowContextData;
+
+public class IdempotencyExample {
+
+    public void demonstrateInstanceId(WorkflowContextData ctx) {
+        // tag::instance-id[]
+        // Every workflow instance has a globally unique, stable identifier
+        String instanceId = ctx.instanceData().id(); // e.g. "01K9GDCXJVN89V0N4CWVG40R7C"
+        // end::instance-id[]
+    }
+}

docs/modules/ROOT/examples/org/acme/OrderWorkflow.java

@@ -0,0 +1,26 @@
+package org.acme;
+
+import static io.serverlessworkflow.fluent.func.dsl.FuncDSL.*;
+
+import jakarta.enterprise.context.ApplicationScoped;
+
+import io.quarkiverse.flow.Flow;
+import io.serverlessworkflow.api.types.Workflow;
+import io.serverlessworkflow.fluent.func.FuncWorkflowBuilder;
+
+@ApplicationScoped
+public class OrderWorkflow extends Flow {
+
+    @Override
+    public Workflow descriptor() {
+        return FuncWorkflowBuilder.workflow("orderWorkflow")
+                .tasks(
+                        function("chargeCustomer", input -> input, Object.class),
+                        // This task writes to the outbox instead of sending the email directly
+                        call("queueNotification", http("/outbox/notifications")
+                                .method("POST")
+                                .body("{ \"to\": .customer.email, \"subject\": \"Order confirmed\", \"orderId\": .orderId }")),
+                        function("updateLedger", input -> input, Object.class))
+                .build();
+    }
+}

docs/modules/ROOT/examples/org/acme/UpdateInventoryWorkflow.java

@@ -0,0 +1,23 @@
+package org.acme;
+
+import static io.serverlessworkflow.fluent.func.dsl.FuncDSL.*;
+
+import jakarta.enterprise.context.ApplicationScoped;
+
+import io.quarkiverse.flow.Flow;
+import io.serverlessworkflow.api.types.Workflow;
+import io.serverlessworkflow.fluent.func.FuncWorkflowBuilder;
+
+@ApplicationScoped
+public class UpdateInventoryWorkflow extends Flow {
+
+    @Override
+    public Workflow descriptor() {
+        return FuncWorkflowBuilder.workflow("updateInventory")
+                .tasks(
+                        call("updateStock", http("/inventory/{sku}")
+                                .method("PUT")
+                                .body(".stockUpdate")))
+                .build();
+    }
+}

docs/modules/ROOT/nav.adoc

@@ -38,6 +38,7 @@
 ** xref:data-flow.adoc[Data Flow and Context Management]
 ** xref:concepts-agentic-langchain4j.adoc[Agentic AI Topology]
 ** xref:concepts-durable-workflow-k8s.adoc[Durable Workflows in Kubernetes]
+** xref:idempotency-correlation.adoc[Idempotency and Correlation]
 
 * Reference
 ** xref:dsl-cheatsheet.adoc[Java DSL cheatsheet]

docs/modules/ROOT/pages/concepts-architecture.adoc

@@ -30,7 +30,9 @@ Quarkus Flow is designed to be non-blocking. When a workflow hits a wait task (l
 === Event Filtering
 A major strength of the engine is its ability to route asynchronous events to the correct, paused workflow instance.
 
-When a workflow enters an event-waiting (listen) state, it defines an **Event Filter**. This allows you to describe exactly how you want to filter incoming events directly within the listen task. You can filter based on the CloudEvent type, specific CloudEvent extensions, or the underlying CloudEvent data. When a message arrives via your messaging broker (like Kafka) that matches your defined filter criteria, the engine routes the payload directly to the correct execution and wakes it up.
+When a workflow enters an event-waiting (listen) state, it defines an **Event Filter** that matches incoming events and wakes the paused instance when a message arrives through your messaging broker.
+
+For callback-driven resume flows, the workflow instance ID is usually captured from the outbound event and sent back on the callback CloudEvent so the paused instance can be resumed deterministically. See xref:idempotency-correlation.adoc#correlating-callbacks-to-a-waiting-instance[Correlating Callbacks to a Waiting Instance].
 
 == Agentic AI Topology
 Quarkus Flow treats LangChain4j Agents as native task workers. Conceptually, an AI orchestration is not a separate engine; it is integrated directly into the standard workflow lifecycle.
@@ -50,4 +52,4 @@ The engine relies on the broader Quarkus ecosystem to do the heavy lifting for e
 == What's next?
 
 * To see these concepts in action, head to xref:getting-started.adoc[Getting Started].
-* For a quick reference of the DSL methods mapping to these tasks, see the xref:dsl-cheatsheet.adoc[Java DSL Cheatsheet].
+* For a quick reference of the DSL methods mapping to these tasks, see the xref:dsl-cheatsheet.adoc[Java DSL Cheatsheet].