AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
backendcritical PriorityID: temporal-workflow-determinism-replay-invariants

Temporal.io Deterministic Workflow Execution & Replay Safety Guardrails

Enforces strict determinism constraints within Temporal workflow execution contexts to prevent non-deterministic history corruption during workflow replays. Mandates isolated side-effect delegation to Temporal Activities, deterministic runtime primitives, and versioned code-path branching via patching APIs for long-running orchestration sagas.

Prohibited Anti-Pattern: Executing Non-Deterministic System Calls, Native Timers, or Unversioned Logic Mutations in Workflow Scopes

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Temporal.io Deterministic Workflow Execution & Replay Safety Guardrails - Enforces strict determinism constraints within Temporal workflow execution contexts to prevent non-deterministic history corruption during workflow replays. Mandates isolated side-effect delegation to Temporal Activities, deterministic runtime primitives, and versioned code-path branching via patching APIs for long-running orchestration sagas.
globs: src/workflows/**/*.{ts,js}, workflows/**/*.{ts,js}, **/*.workflow.{ts,js}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/temporal-workflow-determinism-replay-invariants"
---

# Temporal.io Deterministic Workflow Execution & Replay Safety Guardrails

> **Severity**: CRITICAL | **Category**: backend
> **Anti-Pattern Warning**: Executing Non-Deterministic System Calls, Native Timers, or Unversioned Logic Mutations in Workflow Scopes

## System Constraints
You are a Principal Distributed Systems Architect enforcing Temporal.io Deterministic Workflow Execution & Replay Safety Invariants. Temporal workflows achieve fault tolerance by replaying event histories from persistent storage; any divergent execution path, uncoordinated random number generation, unversioned branch, or external I/O invocation during replay results in catastrophic workflow failure (NonDeterministicWorkflowPolicy / WorkflowExecutionFailed). You must reject any workflow logic that violates replay safety and mandate zero-side-effect determinism.

## Strict Guidelines
- Engineers MUST NEVER invoke native system clocks (e.g., `Date.now()`, `new Date()`), native entropy generators (`Math.random()`, `crypto.getRandomValues()`), or native timers (`setTimeout()`, `setInterval()`) inside workflow code.
- Engineers MUST use workflow runtime abstractions provided by `@temporalio/workflow` (e.g., `workflow.now()`, `workflow.sleep()`, `workflow.uuid4()`) for temporal and random operations.
- Engineers MUST NOT execute arbitrary external I/O (database transactions, HTTP/gRPC requests, filesystem operations) inside workflow logic; all side effects MUST be delegated to Temporal Activities via `proxyActivities`.
- Engineers MUST ALWAYS guard structural modifications to running workflow code using `workflow.patched(patchId)` or `workflow.deprecatePatch(patchId)` to preserve backwards compatibility across existing event histories.
- Engineers MUST NOT iterate over nondeterministic collections (e.g., unsorted object keys, unseeded random permutations) where the iteration order dictates the scheduling sequence of activities or timers.
- Workflow definitions MUST NEVER mutate mutable shared state outside the execution fiber; state must remain strictly local to the workflow instance.
- Engineers MUST execute unit tests using the Temporal TestEnv replay runner (`WorkflowCoverage` / `TestWorkflowEnvironment`) against historical JSON execution histories before deploying workflow code alterations.

## Bad vs Good Implementations
### Anti-Pattern: Native System Primitives and Unversioned Logic Modification

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Direct usage of Date.now(), Math.random(), and native setTimeout produces inconsistent results across replayed histories. Adding the notifyCustomer activity directly without a patch check causes a NonDeterministicWorkflowError during replay of previously generated history traces.
```typescript
import { proxyActivities } from '@temporalio/workflow';
import type * as activities from './activities';

const { chargeCustomer, notifyCustomer } = proxyActivities<typeof activities>({
  startToCloseTimeout: '1 minute',
});

export async function subscriptionSaga(customerId: string): Promise<void> {
  // FAILS DETERMINISM: native Date.now() changes on replay
  const timestamp = Date.now();
  // FAILS DETERMINISM: native Math.random() produces disparate tokens
  const idempotencyKey = `${customerId}-${Math.random()}`;

  await chargeCustomer({ customerId, idempotencyKey, timestamp });

  // FAILS REPLAY: Direct insertion of new activity step without versioning breaks existing history
  await notifyCustomer(customerId);

  // FAILS DETERMINISM: Native setTimeout blocks worker thread and breaks virtual clock
  await new Promise((resolve) => setTimeout(resolve, 86400000));
}
```

#### Production Standard (Correct)
> **Standard**: Replaces system nondeterminism with Temporal runtime primitives (now, uuid4, sleep) and gates newly introduced sequential activity calls with patched('add-customer-notification-v1') to guarantee flawless event history replay.
```typescript
import { proxyActivities, sleep, now, uuid4, patched } from '@temporalio/workflow';
import type * as activities from './activities';

const { chargeCustomer, notifyCustomer } = proxyActivities<typeof activities>({
  startToCloseTimeout: '1 minute',
  retry: {
    maximumAttempts: 5,
    backoffCoefficient: 2,
  },
});

export async function subscriptionSaga(customerId: string): Promise<void> {
  // DETERMINISTIC: now() returns the recorded event timestamp during replay
  const timestamp = now();
  // DETERMINISTIC: uuid4() is backed by Temporal's pseudo-random seed in history
  const idempotencyKey = `${customerId}-${uuid4()}`;

  await chargeCustomer({ customerId, idempotencyKey, timestamp });

  // DETERMINISTIC: Versioned history branching for live workflow upgrades
  if (patched('add-customer-notification-v1')) {
    await notifyCustomer(customerId);
  }

  // DETERMINISTIC: sleep() schedules a durable workflow timer in history
  await sleep('1 day');
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Temporal CLI MCP
MCP wrapper enabling workflow state inspection, event history extraction, and offline replay validation against Temporal Clusters.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Temporal History Replay Verifier
Validates proposed workflow file modifications against downloaded production execution history JSON files via Worker.runReplayHistory.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Temporal.io Deterministic Workflow Execution & Replay Safety Guardrails

Temporal.io Deterministic Workflow Execution & Replay Safety Guardrails defines an industrial-grade behavioral standard for backend engineering. Enforces strict determinism constraints within Temporal workflow execution contexts to prevent non-deterministic history corruption during workflow replays. Mandates isolated side-effect delegation to Temporal Activities, deterministic runtime primitives, and versioned code-path branching via patching APIs for long-running orchestration sagas. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Executing Non-Deterministic System Calls, Native Timers, or Unversioned Logic Mutations in Workflow Scopes Without an explicit system instruction file, developers spend hours debugging silent failures.
Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftExecuting Non-Deterministic System Calls, Native Timers, or Unversioned Logic Mutations in Workflow ScopesCritical
Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production.
Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture InconsistencyAI assistants produce mixed paradigms across files, creating fragmented codebase conventions.Medium
Increases cognitive load during code reviews and leads to maintenance debt across engineering teams.
Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.
Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

1

Engineers MUST NEVER invoke native system clocks (e.g., `Date.now()`, `new Date()`), native entropy generators (`Math.random()`, `crypto.getRandomValues()`), or native timers (`setTimeout()`, `setInterval()`) inside workflow code.

Engineers MUST NEVER invoke native system clocks (e.g., `Date.now()`, `new Date()`), native entropy generators (`Math.random()`, `crypto.getRandomValues()`), or native timers (`setTimeout()`, `setInterval()`) inside workflow code.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST use workflow runtime abstractions provided by `@temporalio/workflow` (e.g., `workflow.now()`, `workflow.sleep()`, `workflow.uuid4()`) for temporal and random operations.

Engineers MUST use workflow runtime abstractions provided by `@temporalio/workflow` (e.g., `workflow.now()`, `workflow.sleep()`, `workflow.uuid4()`) for temporal and random operations.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Engineers MUST NOT execute arbitrary external I/O (database transactions, HTTP/gRPC requests, filesystem operations) inside workflow logic

Engineers MUST NOT execute arbitrary external I/O (database transactions, HTTP/gRPC requests, filesystem operations) inside workflow logic; all side effects MUST be delegated to Temporal Activities via `proxyActivities`.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Engineers MUST ALWAYS guard structural modifications to running workflow code using `workflow.patched(patchId)` or `workflow.deprecatePatch(patchId)` to preserve backwards compatibility across existing event histories.

Engineers MUST ALWAYS guard structural modifications to running workflow code using `workflow.patched(patchId)` or `workflow.deprecatePatch(patchId)` to preserve backwards compatibility across existing event histories.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Engineers MUST NOT iterate over nondeterministic collections (e.g., unsorted object keys, unseeded random permutations) where the iteration order dictates the scheduling sequence of activities or timers.

Engineers MUST NOT iterate over nondeterministic collections (e.g., unsorted object keys, unseeded random permutations) where the iteration order dictates the scheduling sequence of activities or timers.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
6

Workflow definitions MUST NEVER mutate mutable shared state outside the execution fiber

Workflow definitions MUST NEVER mutate mutable shared state outside the execution fiber; state must remain strictly local to the workflow instance.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
7

Engineers MUST execute unit tests using the Temporal TestEnv replay runner (`WorkflowCoverage` / `TestWorkflowEnvironment`) against historical JSON execution histories before deploying workflow code alterations.

Engineers MUST execute unit tests using the Temporal TestEnv replay runner (`WorkflowCoverage` / `TestWorkflowEnvironment`) against historical JSON execution histories before deploying workflow code alterations.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Temporal.io Deterministic Workflow Execution & Replay Safety Guardrails critical for AI coding assistants?

Enforces strict determinism constraints within Temporal workflow execution contexts to prevent non-deterministic history corruption during workflow replays. Mandates isolated side-effect delegation to Temporal Activities, deterministic runtime primitives, and versioned code-path branching via patching APIs for long-running orchestration sagas. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Executing Non-Deterministic System Calls, Native Timers, or Unversioned Logic Mutations in Workflow Scopes) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related BACKEND Rules

View all rules →
backend
42

Fastify 5 Schema Compilers & Encapsulation Production Standard

Fastify relies on lexical encapsulation contexts to sandbox decorators, hooks, and compiled validation/serialization schemas without memory leaks or cross-tenant bleed. In Fastify 5, misuse of global compilers or failing to encapsulate plugin boundaries causes compiled `fast-json-stringify` serializers and Ajv validators to either crash on duplicate IDs, leak private data across sibling scopes, or bypass JIT compilation optimizations. Production services must enforce strict encapsulation hierarchies and type-safe schema compilation across every routing subtree.

backend
68

Bun Embedded SQLite WAL Mode & Transaction Synchronization Standard

Production database standard for bun:sqlite. Mandates enabling Write-Ahead Logging (PRAGMA journal_mode = WAL), busy timeouts, and using db.transaction() for atomic operations without lock starvation.

backend
68

Drizzle ORM Batch API & Interactive Transaction Isolation Standard

Production database standard for Drizzle ORM (PostgreSQL & MySQL). Mandates using db.batch() over HTTP drivers to prevent round-trip waterfalls, explicit db.transaction() with serializable/read-committed isolation, and strictly avoids unawaited query promises.

1 Rule in Stack

Temporal.io