Temporal

This specification defines the operational requirements for building distributed, durable systems using Temporal Java. Agents must follow these principles to ensure system reliability and execution safety.

Architecture Overview

A Temporal application must maintain strict isolation between three distinct layers: the Server, the Worker, and the Application Logic.

1. Worker Configuration

Constraint: Workers must remain stateless. They function strictly as compute resources polling the Temporal Server.

• Rules:
  • Horizontal scaling of workers must not affect business logic.
  • All workflow and activity implementations must be registered with the WorkerFactory.

WorkerFactory factory = WorkerFactory.newInstance(client);
Worker worker = factory.newWorker("order-processing-queue");

worker.registerWorkflowImplementationTypes(OrderWorkflowImpl.class);
worker.registerActivitiesImplementations(
    new PaymentActivityImpl(stripeClient),
    new InventoryActivityImpl(warehouseClient),
    new NotificationActivityImpl(emailService)
);

factory.start();

2. Workflow Specification

Constraint: Workflows define the orchestration logic and must be strictly deterministic.

• Negative Constraints:
  • No direct use of System.currentTimeMillis().
  • No use of random number generators (java.util.Random).
  • No direct HTTP or database calls.
  • No local state that isn't serializable.
• Rules:
  • Use Workflow.currentTimeMillis() for time-based logic.
  • Use Workflow.newActivityStub() to delegate side-effects.

@WorkflowInterface
public interface OrderWorkflow {
    @WorkflowMethod
    OrderResult processOrder(Order order);

    @SignalMethod
    void cancelOrder(String reason);

    @QueryMethod
    OrderStatus getStatus();
}

3. Activity Specification

Constraint: Activities handle all non-deterministic side-effects.

• Rules:
  • Encapsulate all I/O operations (REST, SQL, File System).
  • Implement idempotent logic where possible to support retries.
  • Activities are the primary unit of failure management and should be granular.

The Execution Protocol

Agents must understand the replay-based execution model to avoid "Non-deterministic Exception" errors.

Replay Safety: If a worker fails, Temporal restarts the workflow. The worker re-executes the code but "skips" already completed activities by returning the cached results from the server. All code paths must produce the exact same sequence of commands during replay.

Core Integration Patterns

1. The Saga Pattern (Compensating Transactions)

Used for distributed consistency across multiple services. Every forward action must have a corresponding compensation action.

2. Activity Retry Policy

Retry policies must be tuned per-operation. Blindly using defaults is forbidden.

private final PaymentActivity paymentActivity = Workflow.newActivityStub(
    PaymentActivity.class,
    ActivityOptions.newBuilder()
        .setRetryOptions(RetryOptions.newBuilder()
            .setInitialInterval(Duration.ofSeconds(1))
            .setMaximumInterval(Duration.ofSeconds(30))
            .setBackoffCoefficient(2.0)
            .setMaximumAttempts(3) // Constraint: Limit retries for monetary transactions
            .build())
        .build()
);

Architectural Constraints (Negative Requirements)

• Non-deterministic Leaks: Never use standard library randomness or clock calls within a workflow. Use Temporal-provided Workflow.* equivalents.
• Fat Activities: Activities performing multiple orchestrated steps are prohibited. If an activity makes multiple API calls, it should likely be refactored into a sequence of granular activities within a workflow.
• Implicit Versioning: Updates to running workflows must use Workflow.getVersion(). Failure to version changes in workflow logic will result in non-determinism errors for in-flight executions. sing to debug.