Temporal Workflow Deterministic Replay & Patch-Fencing Standard

--- description: Temporal Workflow Deterministic Replay & Patch-Fencing Standard - Enforces strict determinism constraints and explicit event-history patch fencing for distributed state workflows. Prevents non-deterministic workflow execution corruption, deadlocks, and worker crashes caused by modifying active replay execution graphs without proper Temporal SDK patch primitives. globs: 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-deterministic-replay-patch-fencing" --- # Temporal Workflow Deterministic Replay & Patch-Fencing Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unfenced Workflow Mutation Inducing NonDeterministicWorkflowError During History Replay ## System Constraints You are a Principal Software Architect enforcing absolute determinism and backward-compatible replay safety in Temporal workflows. You must reject any direct workflow code mutation that lacks Temporal patch fencing (patched / deprecatePatch) or relies on non-deterministic host runtime constructs (native timers, I/O, crypto random, unseeded UUIDs). Mandate automated workflow replayer integration tests for every workflow code modification. ## Strict Guidelines - Engineers MUST ALWAYS gate any logic modification, activity addition, or sequence alteration in active workflows using `workflow.patched(patchId)` or `workflow.deprecatePatch(patchId)`. - Engineers MUST NOT introduce non-deterministic JavaScript/Node.js primitives (such as `Date.now()`, `Math.random()`, `crypto.randomUUID()`, or direct network I/O) within workflow context. - Code SHOULD enforce deterministic execution validation using `WorkflowReplayer` against persisted production event history JSON files in CI pipelines before worker deployments. - Services MUST follow the two-phase patch retirement lifecycle: code MUST transition from `patched()` to `deprecatePatch()` once historical executions with old code paths drain, and only remove fences after retention expiration. - Components NEVER execute raw Node promises or untracked background threads inside workflow scopes without proxying through Temporal Activities or Deterministic Workflow Timers (`workflow.sleep()`). ## Bad vs Good Implementations ### Safe Workflow Version Fencing with Temporal patched() vs Direct Mutation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly injecting `sendInvoiceNotification` before `chargeCreditCard` changes the event emission sequence. When workers replay historical execution histories generated before this change, the event sequence does not match the generated commands, crashing the worker with a NonDeterministicWorkflowError and halting the workflow execution. ```typescript import { proxyActivities } from '@temporalio/workflow'; import type * as activities from '../activities'; const { validateUser, chargeCreditCard, sendInvoiceNotification } = proxyActivities<typeof activities>({ startToCloseTimeout: '1 minute', }); export async function subscriptionRenewalWorkflow(userId: string, amount: number): Promise<void> { await validateUser(userId); // BUG: Modifying execution flow directly without patch fencing. // In-flight workflows replaying past histories will encounter an unexpected // ActivityTaskScheduled event or miss an expected event, throwing NonDeterministicWorkflowError. await sendInvoiceNotification(userId, amount); await chargeCreditCard(userId, amount); } ``` #### Production Standard (Correct) > **Standard**: Wrapping the behavioral change with `patched(patchId)` ensures that replaying historical workflows retains their original execution path, while new executions safely record the patch marker in the workflow history and execute the new flow without breaking determinism. ```typescript import { proxyActivities, patched, deprecatePatch } from '@temporalio/workflow'; import type * as activities from '../activities'; const { validateUser, chargeCreditCard, sendInvoiceNotification } = proxyActivities<typeof activities>({ startToCloseTimeout: '1 minute', }); const NOTIFY_BEFORE_CHARGE_PATCH = 'notify-before-charge-v1'; export async function subscriptionRenewalWorkflow(userId: string, amount: number): Promise<void> { await validateUser(userId); // Invariant Fix: Use workflow.patched to fence the new sequence. // During replay of legacy histories, patched() evaluates to false (event not recorded in history), // preserving deterministic execution. New executions record the patch marker and execute the branch. if (patched(NOTIFY_BEFORE_CHARGE_PATCH)) { await sendInvoiceNotification(userId, amount); await chargeCreditCard(userId, amount); } else { await chargeCreditCard(userId, amount); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Temporal Workflow Deterministic Replay & Patch-Fencing Standard

Temporal Workflow Deterministic Replay & Patch-Fencing Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict determinism constraints and explicit event-history patch fencing for distributed state workflows. Prevents non-deterministic workflow execution corruption, deadlocks, and worker crashes caused by modifying active replay execution graphs without proper Temporal SDK patch primitives. 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: Unfenced Workflow Mutation Inducing NonDeterministicWorkflowError During History Replay 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	Unfenced Workflow Mutation Inducing NonDeterministicWorkflowError During History Replay	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 gate any logic modification, activity addition, or sequence alteration in active workflows using `workflow.patched(patchId)` or `workflow.deprecatePatch(patchId)`.

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.