Temporal Durable Execution Determinism and Replay Versioning Invariants

--- description: Temporal Durable Execution Determinism and Replay Versioning Invariants - Enforces strict static determinism barriers prohibiting non-deterministic system clocks, random generators, native timers, and direct I/O inside Temporal workflow scopes. Mandates deterministic Temporal SDK primitives and structural versioning via workflow.patched() to guarantee identical event history replays across multi-year long-running workflows. globs: src/**/workflows/**/*.ts, src/**/workflows/*.ts, workflows/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/temporal-workflow-determinism-and-patch-versioning" --- # Temporal Durable Execution Determinism and Replay Versioning Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing Non-Deterministic Host Runtime Calls and Unversioned Workflow DAG Mutations ## System Constraints You are a Principal Software Architect enforcing Temporal durable execution invariants. Workflow functions must remain purely deterministic state machines whose exact execution path can be identically reconstructed from event history. Never introduce native timers, host clocks, non-deterministic random generators, direct network/database I/O, or unversioned control flow transitions in workflow files. ## Strict Guidelines - Engineers MUST NOT invoke non-deterministic runtime primitives such as `Date.now()`, `new Date()`, `Math.random()`, or `crypto.randomUUID()` inside workflow logic. - Workflows MUST ALWAYS use Temporal SDK deterministic equivalents, including `workflow.now()`, `workflow.uuid4()`, and `workflow.sleep()` instead of host language built-ins. - Workflow functions MUST NEVER execute direct network I/O, database access, or file system modifications; all external side effects MUST be encapsulated in Activities via `proxyActivities`. - Engineers MUST ALWAYS gate any control-flow alterations, activity sequence shifts, or parameter transformations in existing workflows using `workflow.patched(patchId)` to maintain backward replay compatibility for running executions. - Workflows MUST NOT use mutable module-scoped global state, native thread primitives, or floating Promises detached from Temporal's cancellation scopes. - Deprecation of version patches MUST ONLY proceed via `workflow.deprecatePatch(patchId)` after telemetry guarantees zero in-flight executions remain on the legacy event history schema. ## Bad vs Good Implementations ### Workflow Non-Determinism and Broken Replay vs. Deterministic Patched Flow #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using Date.now(), crypto.randomUUID(), axios, native setTimeout, and mutable global state inside a workflow breaches the fundamental Temporal determinism contract. On worker recovery or event replay, the values diverge and the workflow fails with a NonDeterministicWorkflowError. Adding 'sendWelcomeEmailV2' directly without a patch breaks history replay for in-flight workflows that expected the V1 activity. ```typescript import { proxyActivities } from '@temporalio/workflow'; import axios from 'axios'; const activities = proxyActivities<any>({ startToCloseTimeout: '1m' }); let globalAttemptCounter = 0; // Anti-pattern: Shared mutable module state export async function subscriptionWorkflow(userId: string): Promise<void> { // Anti-pattern: Non-deterministic host timestamp breaks replay verification const timestamp = Date.now(); // Anti-pattern: Non-deterministic host UUID generation const idempotencyKey = crypto.randomUUID(); // Anti-pattern: Direct I/O in workflow definition causes runtime panic await axios.post('https://api.billing.com/v1/charge', { userId }); // Anti-pattern: Native setTimeout breaks Temporal durable timer scheduler await new Promise((resolve) => setTimeout(resolve, 86400000)); // Anti-pattern: Structural mutation without workflow.patched() corrupts in-flight history await activities.sendWelcomeEmailV2({ userId, timestamp, idempotencyKey }); } ``` #### Production Standard (Correct) > **Standard**: Adheres to Temporal execution determinism by replacing native clocks with now(), UUIDs with uuid4(), and timers with sleep(). External communication is strictly handled via proxyActivities. Changes to the DAG are gated with patched('use-welcome-email-v2'), allowing existing executions to replay historical V1 paths while routing new workflows through V2 safely. ```typescript import { proxyActivities, sleep, patched, now, uuid4 } from '@temporalio/workflow'; import type * as activities from './activities'; const { chargeSubscription, sendWelcomeEmailV1, sendWelcomeEmailV2 } = proxyActivities<typeof activities>({ startToCloseTimeout: '1 minute', retry: { initialInterval: '2 seconds', maximumAttempts: 5, }, }); export async function subscriptionWorkflow(userId: string): Promise<void> { // Invariant: Deterministic clock derived from workflow event timestamp const timestamp = now(); // Invariant: Deterministic pseudo-random UUID seeded by workflow execution const idempotencyKey = uuid4(); // Invariant: Side-effects exclusively isolated in Activity execution await chargeSubscription({ userId, idempotencyKey, timestamp }); // Invariant: Durable, replayable timer handled by Temporal cluster await sleep('24 hours'); // Invariant: Structural changes guarded by deterministic patch markers if (patched('use-welcome-email-v2')) { await sendWelcomeEmailV2({ userId, timestamp, idempotencyKey }); } else { await sendWelcomeEmailV1({ userId }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Temporal Durable Execution Determinism and Replay Versioning Invariants

Temporal Durable Execution Determinism and Replay Versioning Invariants defines an industrial-grade behavioral standard for backend engineering. Enforces strict static determinism barriers prohibiting non-deterministic system clocks, random generators, native timers, and direct I/O inside Temporal workflow scopes. Mandates deterministic Temporal SDK primitives and structural versioning via workflow.patched() to guarantee identical event history replays across multi-year long-running workflows. 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 Host Runtime Calls and Unversioned Workflow DAG Mutations 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	Executing Non-Deterministic Host Runtime Calls and Unversioned Workflow DAG Mutations	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 NOT invoke non-deterministic runtime primitives such as `Date.now()`, `new Date()`, `Math.random()`, or `crypto.randomUUID()` inside workflow logic.

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.