Temporal Durable Workflow Determinism and History Drift Invariant

--- description: Temporal Durable Workflow Determinism and History Drift Invariant - Enforces strict static execution-path determinism and version-gated branching within Temporal workflows. Prevents fatal NonDeterministicWorkflowError panics and corrupted event-history replay states during hot deployments of long-running executions. globs: src/workflows/**/*.ts, src/**/workflows/**/*.ts, workflows/**/*.ts, lib/workflows/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/temporal-workflow-determinism-drift-invariant" --- # Temporal Durable Workflow Determinism and History Drift Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unversioned Execution Graph Mutation and Non-Deterministic Primitives in Flight Paths ## System Constraints You are a Principal Software Architect enforcing Temporal durable execution invariants. Temporal workflows reconstruct runtime state by replaying historical event logs against code. Any divergence between persisted history and code execution paths triggers fatal NonDeterministicWorkflowError exceptions. You must mandate strict determinism: ban non-deterministic built-ins (Math.random, Date.now, crypto.randomUUID), ban direct I/O or network requests, require workflow.patched() for any logic alterations, and enforce temporal workflow replay test suites on historical payloads. ## Strict Guidelines - Engineers MUST ALWAYS isolate side effects, network I/O, database access, and non-deterministic logic inside Temporal Activities, never directly within Workflow definitions. - Engineers MUST ALWAYS gate structural logic additions, sequence shifts, or task deletions using workflow.patched() or workflow.deprecatePatch() to support backward-compatible event replay. - Engineers MUST NOT invoke native non-deterministic runtime functions such as Math.random(), Date.now(), new Date(), setTimeout(), or external UUID libraries within workflow code; use deterministic workflow APIs (e.g., workflow.now(), workflow.sleep(), workflow.uuid4()) instead. - Services MUST run workflow replay validation tests (WorkflowReplayer) against real-world production history JSON exports before deploying workflow definition updates. - Components NEVER mutate shared global or module-scoped state across workflow executions, as worker threads reuse isolate contexts across tasks. ## Bad vs Good Implementations ### Workflow Evolution via Version-Gated Patching vs Unversioned Execution Drift #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using 'randomUUID()' and 'Date.now()' yields different values during event replay, causing variable drift. Adding 'runFraudCheck' unconditionally alters the expected sequence of scheduled activities, causing Temporal's replay engine to fail with NonDeterministicWorkflowError for any workflow already past that point. ```typescript import { proxyActivities, sleep } from '@temporalio/workflow'; import { randomUUID } from 'crypto'; import type * as activities from './activities'; const { chargeCard, sendReceipt, runFraudCheck } = proxyActivities<typeof activities>({ startToCloseTimeout: '1 minute', }); // ANTI-PATTERN: Direct code modification breaks active in-flight executions. // Native crypto/UUID and Date mutate determinism during replay. export async function checkoutWorkflow(orderId: string, amount: number): Promise<void> { const idempotencyKey = randomUUID(); // Non-deterministic: generates new ID on replay! const timestamp = Date.now(); // Non-deterministic: diverges on replay! // BUG: Introducing this activity unpatched causes NonDeterministicWorkflowError // for workflows currently awaiting chargeCard in production. await runFraudCheck(orderId, timestamp); await chargeCard(orderId, amount, idempotencyKey); await sleep('1 day'); await sendReceipt(orderId); } ``` #### Production Standard (Correct) > **Standard**: Workflow determinism is maintained using Temporal's built-in 'uuid4()' and 'workflowInfo()'. The 'patched(FRAUD_CHECK_PATCH_ID)' function guarantees that existing workflow replays follow the old path, while newly instantiated workflows execute the new fraud check, preventing history drift panics. ```typescript import { proxyActivities, sleep, patched, uuid4, workflowInfo } from '@temporalio/workflow'; import type * as activities from './activities'; const { chargeCard, sendReceipt, runFraudCheck } = proxyActivities<typeof activities>({ startToCloseTimeout: '1 minute', }); const FRAUD_CHECK_PATCH_ID = 'fraud-check-step-v1'; export async function checkoutWorkflow(orderId: string, amount: number): Promise<void> { // Deterministic primitives provided by Temporal SDK const idempotencyKey = uuid4(); const { workflowStartTime } = workflowInfo(); // Deterministic evolution: check if this workflow execution has or should apply the patch if (patched(FRAUD_CHECK_PATCH_ID)) { await runFraudCheck(orderId, workflowStartTime.getTime()); } await chargeCard(orderId, amount, idempotencyKey); await sleep('1 day'); await sendReceipt(orderId); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Temporal Durable Workflow Determinism and History Drift Invariant

Temporal Durable Workflow Determinism and History Drift Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict static execution-path determinism and version-gated branching within Temporal workflows. Prevents fatal NonDeterministicWorkflowError panics and corrupted event-history replay states during hot deployments of long-running executions. 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: Unversioned Execution Graph Mutation and Non-Deterministic Primitives in Flight Paths 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 Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unversioned Execution Graph Mutation and Non-Deterministic Primitives in Flight Paths	Critical	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 Inconsistency	AI 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:

Engineers MUST ALWAYS isolate side effects, network I/O, database access, and non-deterministic logic inside Temporal Activities, never directly within Workflow definitions.

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.