WorkflowClient and Service Interaction

/**
 * Primary client interface for starting and managing workflows, creating activity completion clients, and interacting with the Temporal service.
 */
public interface WorkflowClient {
    // Query type constants
    String QUERY_TYPE_STACK_TRACE = "__stack_trace";
    String QUERY_TYPE_WORKFLOW_METADATA = "__temporal_workflow_metadata";
    String QUERY_TYPE_REPLAY_ONLY = "__replay_only";

    /**
     * Creates client with default options.
     * @param service workflow service stubs
     * @return workflow client instance
     */
    static WorkflowClient newInstance(WorkflowServiceStubs service);

    /**
     * Creates client with custom options.
     * @param service workflow service stubs
     * @param options client options
     * @return workflow client instance
     */
    static WorkflowClient newInstance(WorkflowServiceStubs service, WorkflowClientOptions options);

    /**
     * Returns client options.
     * @return workflow client options
     */
    WorkflowClientOptions getOptions();

    /**
     * Returns service stubs.
     * @return workflow service stubs
     */
    WorkflowServiceStubs getWorkflowServiceStubs();

    /**
     * Creates typed stub for new workflow.
     * @param workflowInterface workflow interface class
     * @param options workflow options
     * @return typed workflow stub
     */
    <T> T newWorkflowStub(Class<T> workflowInterface, WorkflowOptions options);

    /**
     * Creates typed stub for existing workflow.
     * @param workflowInterface workflow interface class
     * @param workflowId existing workflow ID
     * @return typed workflow stub
     */
    <T> T newWorkflowStub(Class<T> workflowInterface, String workflowId);

    /**
     * Creates typed stub with run ID.
     * @param workflowInterface workflow interface class
     * @param workflowId workflow ID
     * @param runId optional run ID
     * @return typed workflow stub
     */
    <T> T newWorkflowStub(Class<T> workflowInterface, String workflowId, Optional<String> runId);

    /**
     * Creates untyped stub for existing workflow.
     * @param workflowId workflow ID
     * @return untyped workflow stub
     */
    WorkflowStub newUntypedWorkflowStub(String workflowId);

    /**
     * Creates untyped stub for new workflow.
     * @param workflowType workflow type name
     * @param options workflow options
     * @return untyped workflow stub
     */
    WorkflowStub newUntypedWorkflowStub(String workflowType, WorkflowOptions options);

    /**
     * Creates untyped stub with optional run ID.
     * @param workflowId workflow ID
     * @param runId optional run ID
     * @param workflowType optional workflow type
     * @return untyped workflow stub
     */
    WorkflowStub newUntypedWorkflowStub(String workflowId, Optional<String> runId, Optional<String> workflowType);

    /**
     * Creates untyped stub from execution.
     * @param execution workflow execution
     * @param workflowType optional workflow type
     * @return untyped workflow stub
     */
    WorkflowStub newUntypedWorkflowStub(WorkflowExecution execution, Optional<String> workflowType);

    /**
     * Creates client for async activity completion.
     * @return activity completion client
     */
    ActivityCompletionClient newActivityCompletionClient();

    /**
     * Creates batch request for signal-with-start.
     * @return batch request builder
     */
    BatchRequest newSignalWithStartRequest();

    /**
     * Executes signal-with-start batch.
     * @param signalWithStartBatch batch request
     * @return workflow execution
     */
    WorkflowExecution signalWithStart(BatchRequest signalWithStartBatch);

    /**
     * Lists workflow executions with visibility query.
     * @param query visibility query
     * @return iterable of workflow executions
     */
    Iterable<WorkflowExecution> listExecutions(String query);

    /**
     * Counts workflow executions.
     * @param query visibility query
     * @return count result
     */
    CountWorkflowExecutionsResponse countWorkflows(String query);

    /**
     * Streams history events.
     * @param workflowId workflow ID
     * @return iterator of history events
     */
    Iterator<HistoryEvent> streamHistory(String workflowId);

    /**
     * Streams history for specific run.
     * @param workflowId workflow ID
     * @param runId run ID
     * @return iterator of history events
     */
    Iterator<HistoryEvent> streamHistory(String workflowId, String runId);

    /**
     * Downloads complete history.
     * @param workflowId workflow ID
     * @return workflow execution history
     */
    WorkflowExecutionHistory fetchHistory(String workflowId);

    /**
     * Downloads history for specific run.
     * @param workflowId workflow ID
     * @param runId run ID
     * @return workflow execution history
     */
    WorkflowExecutionHistory fetchHistory(String workflowId, String runId);

    /**
     * Updates worker build ID compatibility (Experimental).
     * @param taskQueue task queue name
     * @param operation build ID operation
     * @return update response
     */
    @Experimental
    UpdateWorkerBuildIdCompatabilityResponse updateWorkerBuildIdCompatability(String taskQueue, BuildIdOperation operation);

    /**
     * Gets worker build ID version sets (Experimental).
     * @param taskQueue task queue name
     * @return compatibility response
     */
    @Experimental
    GetWorkerBuildIdCompatabilityResponse getWorkerBuildIdCompatability(String taskQueue);

    /**
     * Checks task reachability (Experimental).
     * @param buildIds build IDs to check
     * @param taskQueues task queues to check
     * @param reachability reachability type
     * @return reachability response
     */
    @Experimental
    GetWorkerTaskReachabilityResponse getWorkerTaskReachability(Iterable<String> buildIds, Iterable<String> taskQueues, TaskReachability reachability);

    // Static workflow execution methods

    /**
     * Start zero argument void workflow.
     * @param workflow workflow function
     * @return workflow execution
     */
    static WorkflowExecution start(Proc workflow);

    /**
     * Start one argument void workflow.
     * @param workflow workflow function
     * @param arg1 workflow argument
     * @return workflow execution
     */
    static <A1> WorkflowExecution start(Proc1<A1> workflow, A1 arg1);

    /**
     * Start two argument void workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @return workflow execution
     */
    static <A1, A2> WorkflowExecution start(Proc2<A1, A2> workflow, A1 arg1, A2 arg2);

    /**
     * Start three argument void workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @return workflow execution
     */
    static <A1, A2, A3> WorkflowExecution start(Proc3<A1, A2, A3> workflow, A1 arg1, A2 arg2, A3 arg3);

    /**
     * Start four argument void workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @param arg4 fourth workflow argument
     * @return workflow execution
     */
    static <A1, A2, A3, A4> WorkflowExecution start(Proc4<A1, A2, A3, A4> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4);

    /**
     * Start five argument void workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @param arg4 fourth workflow argument
     * @param arg5 fifth workflow argument
     * @return workflow execution
     */
    static <A1, A2, A3, A4, A5> WorkflowExecution start(Proc5<A1, A2, A3, A4, A5> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5);

    /**
     * Start six argument void workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @param arg4 fourth workflow argument
     * @param arg5 fifth workflow argument
     * @param arg6 sixth workflow argument
     * @return workflow execution
     */
    static <A1, A2, A3, A4, A5, A6> WorkflowExecution start(Proc6<A1, A2, A3, A4, A5, A6> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5, A6 arg6);

    /**
     * Start zero argument returning workflow.
     * @param workflow workflow function
     * @return workflow execution
     */
    static <R> WorkflowExecution start(Func<R> workflow);

    /**
     * Start one argument returning workflow.
     * @param workflow workflow function
     * @param arg1 workflow argument
     * @return workflow execution
     */
    static <A1, R> WorkflowExecution start(Func1<A1, R> workflow, A1 arg1);

    /**
     * Start two argument returning workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @return workflow execution
     */
    static <A1, A2, R> WorkflowExecution start(Func2<A1, A2, R> workflow, A1 arg1, A2 arg2);

    /**
     * Start three argument returning workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @return workflow execution
     */
    static <A1, A2, A3, R> WorkflowExecution start(Func3<A1, A2, A3, R> workflow, A1 arg1, A2 arg2, A3 arg3);

    /**
     * Start four argument returning workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @param arg4 fourth workflow argument
     * @return workflow execution
     */
    static <A1, A2, A3, A4, R> WorkflowExecution start(Func4<A1, A2, A3, A4, R> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4);

    /**
     * Start five argument returning workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @param arg4 fourth workflow argument
     * @param arg5 fifth workflow argument
     * @return workflow execution
     */
    static <A1, A2, A3, A4, A5, R> WorkflowExecution start(Func5<A1, A2, A3, A4, A5, R> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5);

    /**
     * Start six argument returning workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @param arg4 fourth workflow argument
     * @param arg5 fifth workflow argument
     * @param arg6 sixth workflow argument
     * @return workflow execution
     */
    static <A1, A2, A3, A4, A5, A6, R> WorkflowExecution start(Func6<A1, A2, A3, A4, A5, A6, R> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5, A6 arg6);

    // Execute methods that return CompletableFuture

    /**
     * Execute zero argument void workflow.
     * @param workflow workflow function
     * @return completable future
     */
    static CompletableFuture<Void> execute(Proc workflow);

    /**
     * Execute one argument void workflow.
     * @param workflow workflow function
     * @param arg1 workflow argument
     * @return completable future
     */
    static <A1> CompletableFuture<Void> execute(Proc1<A1> workflow, A1 arg1);

    /**
     * Execute two argument void workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @return completable future
     */
    static <A1, A2> CompletableFuture<Void> execute(Proc2<A1, A2> workflow, A1 arg1, A2 arg2);

    /**
     * Execute three argument void workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @return completable future
     */
    static <A1, A2, A3> CompletableFuture<Void> execute(Proc3<A1, A2, A3> workflow, A1 arg1, A2 arg2, A3 arg3);

    /**
     * Execute four argument void workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @param arg4 fourth workflow argument
     * @return completable future
     */
    static <A1, A2, A3, A4> CompletableFuture<Void> execute(Proc4<A1, A2, A3, A4> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4);

    /**
     * Execute five argument void workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @param arg4 fourth workflow argument
     * @param arg5 fifth workflow argument
     * @return completable future
     */
    static <A1, A2, A3, A4, A5> CompletableFuture<Void> execute(Proc5<A1, A2, A3, A4, A5> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5);

    /**
     * Execute six argument void workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @param arg4 fourth workflow argument
     * @param arg5 fifth workflow argument
     * @param arg6 sixth workflow argument
     * @return completable future
     */
    static <A1, A2, A3, A4, A5, A6> CompletableFuture<Void> execute(Proc6<A1, A2, A3, A4, A5, A6> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5, A6 arg6);

    /**
     * Execute zero argument returning workflow.
     * @param workflow workflow function
     * @return completable future with result
     */
    static <R> CompletableFuture<R> execute(Func<R> workflow);

    /**
     * Execute one argument returning workflow.
     * @param workflow workflow function
     * @param arg1 workflow argument
     * @return completable future with result
     */
    static <A1, R> CompletableFuture<R> execute(Func1<A1, R> workflow, A1 arg1);

    /**
     * Execute two argument returning workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @return completable future with result
     */
    static <A1, A2, R> CompletableFuture<R> execute(Func2<A1, A2, R> workflow, A1 arg1, A2 arg2);

    /**
     * Execute three argument returning workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @return completable future with result
     */
    static <A1, A2, A3, R> CompletableFuture<R> execute(Func3<A1, A2, A3, R> workflow, A1 arg1, A2 arg2, A3 arg3);

    /**
     * Execute four argument returning workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @param arg4 fourth workflow argument
     * @return completable future with result
     */
    static <A1, A2, A3, A4, R> CompletableFuture<R> execute(Func4<A1, A2, A3, A4, R> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4);

    /**
     * Execute five argument returning workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @param arg4 fourth workflow argument
     * @param arg5 fifth workflow argument
     * @return completable future with result
     */
    static <A1, A2, A3, A4, A5, R> CompletableFuture<R> execute(Func5<A1, A2, A3, A4, A5, R> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5);

    /**
     * Execute six argument returning workflow.
     * @param workflow workflow function
     * @param arg1 first workflow argument
     * @param arg2 second workflow argument
     * @param arg3 third workflow argument
     * @param arg4 fourth workflow argument
     * @param arg5 fifth workflow argument
     * @param arg6 sixth workflow argument
     * @return completable future with result
     */
    static <A1, A2, A3, A4, A5, A6, R> CompletableFuture<R> execute(Func6<A1, A2, A3, A4, A5, A6, R> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5, A6 arg6);
}

public class WorkflowClientExample {
    public static void main(String[] args) {
        // Create client
        WorkflowServiceStubs service = WorkflowServiceStubs.newLocalServiceStubs();
        WorkflowClient client = WorkflowClient.newInstance(service);

        // Create typed workflow stub
        OrderWorkflow workflow = client.newWorkflowStub(
            OrderWorkflow.class,
            WorkflowOptions.newBuilder()
                .setWorkflowId("order-123")
                .setTaskQueue("order-processing")
                .setWorkflowExecutionTimeout(Duration.ofHours(1))
                .build()
        );

        // Start workflow asynchronously
        WorkflowExecution execution = WorkflowClient.start(workflow::processOrder, orderRequest);

        // Execute workflow synchronously
        CompletableFuture<OrderResult> future = WorkflowClient.execute(workflow::processOrder, orderRequest);
        OrderResult result = future.get();

        // Connect to existing workflow
        OrderWorkflow existingWorkflow = client.newWorkflowStub(OrderWorkflow.class, "order-123");
        OrderStatus status = existingWorkflow.getStatus();

        // Send signal
        existingWorkflow.updateShipping(newShippingInfo);

        // List workflows
        Iterable<WorkflowExecution> executions = client.listExecutions("WorkflowType='OrderWorkflow'");
        for (WorkflowExecution exec : executions) {
            System.out.println("Found workflow: " + exec.getWorkflowId());
        }
    }
}

/**
 * Untyped client stub for workflow instances, supporting workflow lifecycle operations.
 */
public interface WorkflowStub {
    /**
     * Extracts untyped stub from typed workflow stub.
     * @param typed typed workflow stub
     * @return untyped workflow stub
     */
    static WorkflowStub fromTyped(Object typed);

    /**
     * Starts workflow execution.
     * @param args workflow arguments
     * @return workflow execution
     */
    WorkflowExecution start(Object... args);

    /**
     * Gets workflow result (blocking).
     * @param resultClass result class
     * @return workflow result
     */
    <R> R getResult(Class<R> resultClass);

    /**
     * Type-safe version with generics.
     * @param resultClass result class
     * @param resultType generic type information
     * @return workflow result
     */
    <R> R getResult(Class<R> resultClass, Type resultType);

    /**
     * Gets workflow result with timeout.
     * @param timeout timeout value
     * @param unit timeout unit
     * @param resultClass result class
     * @return workflow result
     */
    <R> R getResult(long timeout, TimeUnit unit, Class<R> resultClass);

    /**
     * Gets workflow result with timeout and generics.
     * @param timeout timeout value
     * @param unit timeout unit
     * @param resultClass result class
     * @param resultType generic type information
     * @return workflow result
     */
    <R> R getResult(long timeout, TimeUnit unit, Class<R> resultClass, Type resultType);

    /**
     * Returns CompletableFuture for workflow result.
     * @param resultClass result class
     * @return completable future with result
     */
    <R> CompletableFuture<R> getResultAsync(Class<R> resultClass);

    /**
     * Async with generics.
     * @param resultClass result class
     * @param resultType generic type information
     * @return completable future with result
     */
    <R> CompletableFuture<R> getResultAsync(Class<R> resultClass, Type resultType);

    /**
     * Async with timeout.
     * @param timeout timeout value
     * @param unit timeout unit
     * @param resultClass result class
     * @return completable future with result
     */
    <R> CompletableFuture<R> getResultAsync(long timeout, TimeUnit unit, Class<R> resultClass);

    /**
     * Async with timeout and generics.
     * @param timeout timeout value
     * @param unit timeout unit
     * @param resultClass result class
     * @param resultType generic type information
     * @return completable future with result
     */
    <R> CompletableFuture<R> getResultAsync(long timeout, TimeUnit unit, Class<R> resultClass, Type resultType);

    /**
     * Sends signal to workflow.
     * @param signalName signal name
     * @param args signal arguments
     */
    void signal(String signalName, Object... args);

    /**
     * Queries workflow.
     * @param queryType query type
     * @param resultClass result class
     * @param args query arguments
     * @return query result
     */
    <R> R query(String queryType, Class<R> resultClass, Object... args);

    /**
     * Type-safe query.
     * @param queryType query type
     * @param resultClass result class
     * @param resultType generic type information
     * @param args query arguments
     * @return query result
     */
    <R> R query(String queryType, Class<R> resultClass, Type resultType, Object... args);

    /**
     * Synchronous update.
     * @param updateName update name
     * @param resultClass result class
     * @param args update arguments
     * @return update result
     */
    <R> R update(String updateName, Class<R> resultClass, Object... args);

    /**
     * Async update.
     * @param updateName update name
     * @param waitForStage wait stage
     * @param resultClass result class
     * @param args update arguments
     * @return update handle
     */
    <R> WorkflowUpdateHandle<R> startUpdate(String updateName, WorkflowUpdateStage waitForStage, Class<R> resultClass, Object... args);

    /**
     * Async update with options.
     * @param options update options
     * @param args update arguments
     * @return update handle
     */
    <R> WorkflowUpdateHandle<R> startUpdate(UpdateOptions<R> options, Object... args);

    /**
     * Get handle to existing update.
     * @param updateId update ID
     * @param resultClass result class
     * @return update handle
     */
    <R> WorkflowUpdateHandle<R> getUpdateHandle(String updateId, Class<R> resultClass);

    /**
     * Type-safe version.
     * @param updateId update ID
     * @param resultClass result class
     * @param resultType generic type information
     * @return update handle
     */
    <R> WorkflowUpdateHandle<R> getUpdateHandle(String updateId, Class<R> resultClass, Type resultType);

    /**
     * Update with start.
     * @param updateOptions update options
     * @param updateArgs update arguments
     * @param startArgs start arguments
     * @return update handle
     */
    <R> WorkflowUpdateHandle<R> startUpdateWithStart(UpdateOptions<R> updateOptions, Object[] updateArgs, Object[] startArgs);

    /**
     * Sync update with start.
     * @param updateOptions update options
     * @param updateArgs update arguments
     * @param startArgs start arguments
     * @return update result
     */
    <R> R executeUpdateWithStart(UpdateOptions<R> updateOptions, Object[] updateArgs, Object[] startArgs);

    /**
     * Signal with start.
     * @param signalName signal name
     * @param signalArgs signal arguments
     * @param startArgs start arguments
     * @return workflow execution
     */
    WorkflowExecution signalWithStart(String signalName, Object[] signalArgs, Object[] startArgs);

    /**
     * Requests workflow cancellation.
     */
    void cancel();

    /**
     * Cancellation with reason.
     * @param reason cancellation reason
     */
    void cancel(String reason);

    /**
     * Terminates workflow execution.
     * @param reason termination reason
     * @param details termination details
     */
    void terminate(String reason, Object... details);

    /**
     * Gets workflow execution description.
     * @return workflow description
     */
    WorkflowExecutionMetadata describe();

    /**
     * Returns workflow type name.
     * @return workflow type
     */
    Optional<String> getWorkflowType();

    /**
     * Gets workflow execution info.
     * @return workflow execution
     */
    WorkflowExecution getExecution();

    /**
     * Gets workflow options.
     * @return workflow options
     */
    WorkflowOptions getOptions();

    /**
     * Creates new stub instance with different options.
     * @param options new workflow options
     * @return new workflow stub instance
     */
    WorkflowStub newInstance(WorkflowOptions options);
}

public class WorkflowStubExample {
    public void demonstrateWorkflowStub() {
        WorkflowClient client = WorkflowClient.newInstance(service);

        // Create untyped stub
        WorkflowStub stub = client.newUntypedWorkflowStub(
            "OrderWorkflow",
            WorkflowOptions.newBuilder()
                .setWorkflowId("order-456")
                .setTaskQueue("orders")
                .build()
        );

        // Start workflow
        OrderRequest request = new OrderRequest("customer-123", items);
        WorkflowExecution execution = stub.start(request);

        // Send signal
        stub.signal("addItem", new OrderItem("item-789", 1));

        // Query workflow
        OrderStatus status = stub.query("getStatus", OrderStatus.class);

        // Update workflow
        Address newAddress = new Address("123 Main St", "Seattle", "WA");
        stub.update("updateShippingAddress", Void.class, newAddress);

        // Get result asynchronously
        CompletableFuture<OrderResult> future = stub.getResultAsync(OrderResult.class);
        future.thenAccept(result -> {
            System.out.println("Order completed: " + result.getOrderId());
        });

        // Cancel if needed
        if (shouldCancel) {
            stub.cancel("Customer requested cancellation");
        }
    }
}

/**
 * Client for completing activities asynchronously outside the activity execution context.
 */
public interface ActivityCompletionClient {
    /**
     * Completes activity successfully by task token.
     * @param taskToken activity task token
     * @param result activity result
     */
    <R> void complete(byte[] taskToken, R result);

    /**
     * Completes with failure by task token.
     * @param taskToken activity task token
     * @param result failure exception
     */
    void completeExceptionally(byte[] taskToken, Exception result);

    /**
     * Reports successful cancellation by task token.
     * @param taskToken activity task token
     * @param details cancellation details
     */
    <V> void reportCancellation(byte[] taskToken, V details);

    /**
     * Records heartbeat by task token.
     * @param taskToken activity task token
     * @param details heartbeat details
     */
    <V> void heartbeat(byte[] taskToken, V details);

    /**
     * Complete by workflow and activity IDs.
     * @param workflowId workflow ID
     * @param runId optional run ID
     * @param activityId activity ID
     * @param result activity result
     */
    <R> void complete(String workflowId, Optional<String> runId, String activityId, R result);

    /**
     * Fail by workflow and activity IDs.
     * @param workflowId workflow ID
     * @param runId optional run ID
     * @param activityId activity ID
     * @param result failure exception
     */
    void completeExceptionally(String workflowId, Optional<String> runId, String activityId, Exception result);

    /**
     * Cancel by workflow and activity IDs.
     * @param workflowId workflow ID
     * @param runId optional run ID
     * @param activityId activity ID
     * @param details cancellation details
     */
    <V> void reportCancellation(String workflowId, Optional<String> runId, String activityId, V details);

    /**
     * Heartbeat by workflow and activity IDs.
     * @param workflowId workflow ID
     * @param runId optional run ID
     * @param activityId activity ID
     * @param details heartbeat details
     */
    <V> void heartbeat(String workflowId, Optional<String> runId, String activityId, V details);

    /**
     * Context-aware client (Experimental).
     * @param context serialization context
     * @return context-aware activity completion client
     */
    @Experimental
    ActivityCompletionClient withContext(ActivitySerializationContext context);
}

public class AsyncActivityExample {
    private final ActivityCompletionClient completionClient;

    public AsyncActivityExample(WorkflowClient client) {
        this.completionClient = client.newActivityCompletionClient();
    }

    // In activity implementation
    @Override
    public void startLongRunningProcess(String processId) {
        ActivityExecutionContext context = Activity.getExecutionContext();
        byte[] taskToken = context.getTaskToken();
        context.doNotCompleteOnReturn();

        // Start async process
        CompletableFuture.runAsync(() -> {
            try {
                String result = performLongRunningOperation(processId);
                completionClient.complete(taskToken, result);
            } catch (Exception e) {
                completionClient.completeExceptionally(taskToken, e);
            }
        });
    }

    // External completion by IDs
    public void completeExternalActivity(String workflowId, String activityId, String result) {
        completionClient.complete(workflowId, Optional.empty(), activityId, result);
    }

    // Heartbeat from external service
    public void sendActivityHeartbeat(String workflowId, String activityId, ProgressInfo progress) {
        completionClient.heartbeat(workflowId, Optional.empty(), activityId, progress);
    }
}

/**
 * Configuration options for workflow execution.
 */
public final class WorkflowOptions {
    /**
     * Creates new builder.
     * @return new WorkflowOptions builder
     */
    public static Builder newBuilder();

    /**
     * Creates builder from existing options.
     * @param options existing options to copy
     * @return new builder with copied options
     */
    public static Builder newBuilder(WorkflowOptions options);

    /**
     * Returns default instance.
     * @return default WorkflowOptions
     */
    public static WorkflowOptions getDefaultInstance();

    /**
     * Merges annotation and options.
     * @param methodRetry method retry annotation
     * @param cronSchedule cron schedule annotation
     * @param options workflow options
     * @return merged workflow options
     */
    public static WorkflowOptions merge(MethodRetry methodRetry, CronSchedule cronSchedule, WorkflowOptions options);

    /**
     * Builder for WorkflowOptions.
     */
    public static final class Builder {
        /**
         * Sets workflow ID (defaults to UUID).
         * @param workflowId workflow ID
         * @return this builder
         */
        public Builder setWorkflowId(String workflowId);

        /**
         * Behavior for completed workflows with same ID.
         * @param workflowIdReusePolicy reuse policy
         * @return this builder
         */
        public Builder setWorkflowIdReusePolicy(WorkflowIdReusePolicy workflowIdReusePolicy);

        /**
         * Behavior for running workflows with same ID.
         * @param workflowIdConflictPolicy conflict policy
         * @return this builder
         */
        public Builder setWorkflowIdConflictPolicy(WorkflowIdConflictPolicy workflowIdConflictPolicy);

        /**
         * Time before run is automatically terminated.
         * @param workflowRunTimeout run timeout
         * @return this builder
         */
        public Builder setWorkflowRunTimeout(Duration workflowRunTimeout);

        /**
         * Time before entire execution is terminated.
         * @param workflowExecutionTimeout execution timeout
         * @return this builder
         */
        public Builder setWorkflowExecutionTimeout(Duration workflowExecutionTimeout);

        /**
         * Maximum workflow task execution time.
         * @param workflowTaskTimeout task timeout
         * @return this builder
         */
        public Builder setWorkflowTaskTimeout(Duration workflowTaskTimeout);

        /**
         * Task queue for workflow tasks.
         * @param taskQueue task queue name
         * @return this builder
         */
        public Builder setTaskQueue(String taskQueue);

        /**
         * Workflow retry configuration.
         * @param retryOptions retry options
         * @return this builder
         */
        public Builder setRetryOptions(RetryOptions retryOptions);

        /**
         * Cron schedule for periodic execution.
         * @param cronSchedule cron expression
         * @return this builder
         */
        public Builder setCronSchedule(String cronSchedule);

        /**
         * Additional non-indexed information.
         * @param memo memo map
         * @return this builder
         */
        public Builder setMemo(Map<String, Object> memo);

        /**
         * Type-safe search attributes.
         * @param searchAttributes typed search attributes
         * @return this builder
         */
        public Builder setTypedSearchAttributes(SearchAttributes searchAttributes);

        /**
         * Context propagation overrides.
         * @param contextPropagators context propagators list
         * @return this builder
         */
        public Builder setContextPropagators(List<ContextPropagator> contextPropagators);

        /**
         * Disable local eager execution.
         * @param disableEagerExecution true to disable
         * @return this builder
         */
        public Builder setDisableEagerExecution(boolean disableEagerExecution);

        /**
         * Delay before first workflow task.
         * @param startDelay start delay duration
         * @return this builder
         */
        public Builder setStartDelay(Duration startDelay);

        /**
         * Fixed summary for UI (Experimental).
         * @param staticSummary workflow summary
         * @return this builder
         */
        @Experimental
        public Builder setStaticSummary(String staticSummary);

        /**
         * Fixed details for UI (Experimental).
         * @param staticDetails workflow details
         * @return this builder
         */
        @Experimental
        public Builder setStaticDetails(String staticDetails);

        /**
         * Unique start request ID (Experimental).
         * @param requestId request ID
         * @return this builder
         */
        @Experimental
        public Builder setRequestId(String requestId);

        /**
         * Terminal state callbacks (Experimental).
         * @param completionCallbacks callback list
         * @return this builder
         */
        @Experimental
        public Builder setCompletionCallbacks(List<Callback> completionCallbacks);

        /**
         * Associated links (Experimental).
         * @param links link list
         * @return this builder
         */
        @Experimental
        public Builder setLinks(List<Link> links);

        /**
         * Conflict handling options (Experimental).
         * @param onConflictOptions conflict options
         * @return this builder
         */
        @Experimental
        public Builder setOnConflictOptions(OnConflictOptions onConflictOptions);

        /**
         * Task priority settings (Experimental).
         * @param priority task priority
         * @return this builder
         */
        @Experimental
        public Builder setPriority(Priority priority);

        /**
         * Versioning override (Experimental).
         * @param versioningOverride versioning override
         * @return this builder
         */
        @Experimental
        public Builder setVersioningOverride(VersioningOverride versioningOverride);

        /**
         * Build the WorkflowOptions.
         * @return configured WorkflowOptions
         */
        public WorkflowOptions build();
    }
}

/**
 * Configuration options for the WorkflowClient.
 */
public final class WorkflowClientOptions {
    /**
     * Creates new builder.
     * @return new WorkflowClientOptions builder
     */
    public static Builder newBuilder();

    /**
     * Creates builder from existing options.
     * @param options existing options to copy
     * @return new builder with copied options
     */
    public static Builder newBuilder(WorkflowClientOptions options);

    /**
     * Builder for WorkflowClientOptions.
     */
    public static final class Builder {
        /**
         * Workflow client namespace.
         * @param namespace namespace name
         * @return this builder
         */
        public Builder setNamespace(String namespace);

        /**
         * Data converter for payload serialization.
         * @param dataConverter data converter
         * @return this builder
         */
        public Builder setDataConverter(DataConverter dataConverter);

        /**
         * Context propagators for tracing/logging.
         * @param contextPropagators context propagators
         * @return this builder
         */
        public Builder setContextPropagators(List<ContextPropagator> contextPropagators);

        /**
         * Interceptors for workflow calls.
         * @param interceptors workflow interceptors
         * @return this builder
         */
        public Builder setInterceptors(WorkflowClientInterceptor... interceptors);

        /**
         * Identity for workflow client.
         * @param identity client identity
         * @return this builder
         */
        public Builder setIdentity(String identity);

        /**
         * Binary checksum for workflow compatibility.
         * @param binaryChecksum binary checksum
         * @return this builder
         */
        public Builder setBinaryChecksum(String binaryChecksum);

        /**
         * Build the WorkflowClientOptions.
         * @return configured WorkflowClientOptions
         */
        public WorkflowClientOptions build();
    }
}