Python 3.13 Free-Threaded Shared State Race Barrier and Memory Safety Invariant

--- description: Python 3.13 Free-Threaded Shared State Race Barrier and Memory Safety Invariant - Enforces strict immutability, thread synchronization barriers, and thread-safe data structures across un-GILed worker threads in Python 3.13 free-threaded (PEP 703) runtimes. Prevents silent data tearing, stale reads, and race conditions in FastAPI applications handling concurrent requests across multi-threaded thread pools. globs: **/app/**/*.py, **/api/**/*.py, **/services/**/*.py, **/core/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-python313-freethreaded-shared-state-race-barrier" --- # Python 3.13 Free-Threaded Shared State Race Barrier and Memory Safety Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unsynchronized Mutable Module-Level State and Non-Atomic Cache Updates Under Free-Threaded Python 3.13 ## System Constraints You are a Principal Backend Architect enforcing strict thread safety and lock-free synchronization under Python 3.13 free-threaded (no-GIL, PEP 703) execution. Without the Global Interpreter Lock, operations like dictionary assignments, in-place increments, list modifications, and lazy singletons are vulnerable to data tearing, memory corruption, and stale memory reads. Mandate immutable domain models, explicit lock boundaries, atomic references, or thread-safe primitives for all shared memory spaces. ## Strict Guidelines - Engineers MUST NOT rely on standard Python dictionaries, lists, sets, or bare class attributes for cross-request shared mutable state in free-threaded mode. - Engineers MUST encapsulate shared mutable state using explicit synchronization primitives (threading.Lock, threading.RLock) or persistent immutable data structures. - Engineers MUST declare cross-thread data transfer objects and configuration instances as immutable frozen dataclasses (frozen=True) or Pydantic models with frozen=True. - Singletons and lazy initializers MUST use double-checked locking patterns with explicit memory-barrier-equivalent lock acquires to prevent duplicate instantiation or partial reference visibility. - Background worker tasks in FastAPI dispatching to `run_in_threadpool` or `concurrent.futures` MUST exchange state only via thread-safe queues (`queue.Queue`) or thread-safe channels, never raw global variables. ## Bad vs Good Implementations ### Cross-Thread In-Memory Metric Counter and Cache Synchronization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Without the GIL in Python 3.13, in-place additions and standard dict lookups/insertions across worker threads are subject to data races. Multiple worker threads executing `+=` concurrently will drop increments, produce split reads, or corrupt internal hash table structures during concurrent re-hashing. ```python from fastapi import FastAPI from typing import Dict app = FastAPI() # Anti-pattern: Under Python 3.13t (no-GIL), bare dicts and primitives are NOT atomic. # Concurrent requests from un-GILed worker threads cause race conditions and data tearing. REQUEST_COUNTS: Dict[str, int] = {} GLOBAL_CONFIG = {"active_tier": "standard"} @app.get("/track/{endpoint}") def track(endpoint: str): # Race Condition: In-place addition (+=) translates to separate read-modify-store bytecodes if endpoint not in REQUEST_COUNTS: REQUEST_COUNTS[endpoint] = 0 REQUEST_COUNTS[endpoint] += 1 return {"endpoint": endpoint, "count": REQUEST_COUNTS[endpoint], "tier": GLOBAL_CONFIG["active_tier"]} ``` #### Production Standard (Correct) > **Standard**: Guarantees race-free mutations using an encapsulated `threading.Lock` barrier for all reads and writes. Encapsulates application configuration within a frozen, immutable dataclass with slots, ensuring that state cannot be mutated or torn across un-GILed execution contexts. ```python from dataclasses import dataclass import threading from typing import Mapping from fastapi import FastAPI @dataclass(frozen=True, slots=True) class AppConfig: active_tier: str class AtomicEndpointMetrics: def __init__(self) -> None: self._lock = threading.Lock() self._counts: dict[str, int] = {} def increment_and_get(self, endpoint: str) -> int: with self._lock: current = self._counts.get(endpoint, 0) + 1 self._counts[endpoint] = current return current def snapshot(self) -> Mapping[str, int]: with self._lock: return dict(self._counts) app = FastAPI() METRICS = AtomicEndpointMetrics() IMMUTABLE_CONFIG = AppConfig(active_tier="standard") @app.get("/track/{endpoint}") def track(endpoint: str): count = METRICS.increment_and_get(endpoint) return {"endpoint": endpoint, "count": count, "tier": IMMUTABLE_CONFIG.active_tier} ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Python 3.13 Free-Threaded Shared State Race Barrier and Memory Safety Invariant

Python 3.13 Free-Threaded Shared State Race Barrier and Memory Safety Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict immutability, thread synchronization barriers, and thread-safe data structures across un-GILed worker threads in Python 3.13 free-threaded (PEP 703) runtimes. Prevents silent data tearing, stale reads, and race conditions in FastAPI applications handling concurrent requests across multi-threaded thread pools. 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: Unsynchronized Mutable Module-Level State and Non-Atomic Cache Updates Under Free-Threaded Python 3.13 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	Unsynchronized Mutable Module-Level State and Non-Atomic Cache Updates Under Free-Threaded Python 3.13	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 rely on standard Python dictionaries, lists, sets, or bare class attributes for cross-request shared mutable state in free-threaded mode.

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.