Temporal Workflow Determinism & AST-Level Replay Invariant Guardrail

--- description: Temporal Workflow Determinism & AST-Level Replay Invariant Guardrail - Enforces strict replay determinism on all Temporal workflow definitions to eliminate non-deterministic execution errors and durable state machine corruption. Rejects native I/O, unseeded randomness, unmanaged clocks, async concurrency escapes, and unversioned AST modifications within workflow execution scopes. Mandates that all side effects, network calls, and mutable state transitions reside exclusively within Temporal Activities or version-gated patch blocks. globs: **/workflows/**/*.ts, **/workflows.ts, **/workflow-definitions/**/*.ts, src/temporal/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/temporal-workflow-determinism-ast-guardrail" --- # Temporal Workflow Determinism & AST-Level Replay Invariant Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing Non-Deterministic System Calls, Unversioned Control Flow, or Native Timers Inside Durable Workflows ## System Constraints You are a Principal Software Architect enforcing zero-tolerance invariants for Temporal Workflow determinism. Workflows are durable, replayable state machines: any non-deterministic output during history replay leads to catastrophic NonDeterministicWorkflowError and workflow task failure. You must reject all native timers, global state mutations, direct network or file I/O, non-deterministic standard library functions (Date.now, Math.random, crypto.randomUUID), and unversioned branch structural mutations. Direct all side-effects exclusively to proxy activities, and gate structural evolution with workflow.patched(). ## Strict Guidelines - Engineers MUST ALWAYS isolate all network calls, database queries, file systems accesses, and ambient context reads inside Temporal Activities. - Engineers MUST NOT invoke native non-deterministic primitives including `Math.random()`, `Date.now()`, `new Date()`, `crypto.randomUUID()`, `setTimeout()`, or `setImmediate()` in workflow code. - Engineers MUST use `@temporalio/workflow` primitives: `workflow.now()`, `workflow.uuid4()`, `workflow.sleep()`, and `workflow.condition()` for time, identities, and timers. - Services MUST gate structural AST control-flow alterations in workflows using `workflow.patched('patch-id')` or `workflow.deprecatePatch('patch-id')` to maintain backward compatibility during replay. - Components NEVER store or mutate shared global or module-scoped variables across workflow task invocations; workflow state must be strictly instance-scoped. ## Bad vs Good Implementations ### Violating Workflow Determinism vs. Replay-Safe Versioned Workflow #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Direct invocation of Date.now(), crypto.randomUUID(), fetch(), native setTimeout, unversioned conditional branching, and global mutable state breaks Temporal's replay-based event-sourcing mechanism, causing NonDeterministicWorkflowError in production. ```typescript import { proxyActivities } from '@temporalio/workflow'; import crypto from 'node:crypto'; // ANTI-PATTERN: Direct module-level mutable state let executionCounter = 0; export async function processOrderWorkflow(orderId: string): Promise<void> { // ANTI-PATTERN: Native clock access const timestamp = Date.now(); // ANTI-PATTERN: Non-deterministic native UUID generation const traceId = crypto.randomUUID(); // ANTI-PATTERN: Native non-deterministic I/O in workflow scope const response = await fetch(`https://api.payment.internal/charges/${orderId}`); const paymentStatus = await response.json(); executionCounter++; // ANTI-PATTERN: Native timer violates replay determinism await new Promise((resolve) => setTimeout(resolve, 5000)); // ANTI-PATTERN: Unversioned control flow modification directly in active workflow if (paymentStatus.requiresFraudCheck) { await sendNotification(orderId); } } ``` #### Production Standard (Correct) > **Standard**: All external I/O is routed to proxy activities. Timers, random identifiers, and clocks are sourced from `@temporalio/workflow`, and logical schema evolution is guarded by `workflow.patched()`, guaranteeing 100% deterministic event history replay. ```typescript import { proxyActivities, workflow, sleep, patched } from '@temporalio/workflow'; import type * as activities from './activities'; const { chargePaymentActivity, sendNotificationActivity } = proxyActivities<typeof activities>({ startToCloseTimeout: '1 minute', retry: { maximumAttempts: 5, backoffCoefficient: 2, }, }); export async function processOrderWorkflow(orderId: string): Promise<void> { // INVARIANT: Deterministic time provided by Temporal runtime const timestamp = workflow.now(); // INVARIANT: Deterministic PRNG seeded via Temporal workflow runtime const traceId = workflow.uuid4(); // INVARIANT: External side-effects strictly encapsulated within proxy activities const paymentStatus = await chargePaymentActivity({ orderId, traceId, timestamp }); // INVARIANT: Replay-safe durable timer recorded in history event log await sleep('5 seconds'); // INVARIANT: History-preserving workflow evolution via workflow.patched() if (patched('enable-fraud-check-v2')) { if (paymentStatus.requiresFraudCheck) { await sendNotificationActivity(orderId); } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Temporal Workflow Determinism & AST-Level Replay Invariant Guardrail

Temporal Workflow Determinism & AST-Level Replay Invariant Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces strict replay determinism on all Temporal workflow definitions to eliminate non-deterministic execution errors and durable state machine corruption. Rejects native I/O, unseeded randomness, unmanaged clocks, async concurrency escapes, and unversioned AST modifications within workflow execution scopes. Mandates that all side effects, network calls, and mutable state transitions reside exclusively within Temporal Activities or version-gated patch blocks. 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, Unversioned Control Flow, or Native Timers Inside Durable Workflows 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 System Calls, Unversioned Control Flow, or Native Timers Inside Durable Workflows	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 all network calls, database queries, file systems accesses, and ambient context reads inside Temporal Activities.

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.