Web Locks API State Synchronization and Concurrency Control Guardrail

--- description: Web Locks API State Synchronization and Concurrency Control Guardrail - Enforces deterministic cross-tab synchronization and prevents IndexedDB write-skew anomalies during high-frequency optimistic state mutations and queue drains. Mandates atomic, scoped synchronization via the native Web Locks API (`navigator.locks.request`) paired with cross-context invalidation signals across concurrent browsing contexts (tabs, dedicated workers, and service workers). globs: src/**/*.{ts,tsx}, src/workers/**/*.{ts,js}, src/storage/**/*.{ts,js}, public/sw.js alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/web-locks-client-state-sync-standard" --- # Web Locks API State Synchronization and Concurrency Control Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unsynchronized Read-Modify-Write Cycles and Optimistic Queue Drains Across Concurrent Tabs Causing IndexedDB Write-Skew and State Regression ## System Constraints You are a Principal Software Architect enforcing the Web Locks API Client-State Cross-Tab Synchronization Standard. You must mandate strict lock scoping, prevent deadlocks, enforce fallback guards for unsupported environments, and eliminate lost updates during concurrent client-side mutations across independent browsing contexts. ## Strict Guidelines - Engineers MUST ALWAYS wrap multi-step IndexedDB read-modify-write sequences and offline mutation queue processing inside `navigator.locks.request` with an explicit resource identifier and mode (`exclusive` or `shared`). - Engineers MUST NOT rely on IndexedDB internal transaction locks alone for cross-step application workflows; IndexedDB transactions close between asynchronous macro/micro-tasks, allowing interleaved concurrent writes across different tabs. - Code MUST pass an `AbortSignal` with a deterministic timeout (e.g., `AbortSignal.timeout(ms)`) to `navigator.locks.request` options to prevent orphan lock acquisition freezes if an execution context hangs or terminates abruptly. - Services MUST implement hierarchical, granular lock naming conventions (e.g., `sync:entity:${domain}:${id}`) to prevent coarse global bottlenecks while avoiding cyclic cross-lock dependencies that introduce deadlocks. - Components NEVER execute uncoordinated direct local state writes after an external lock release; state managers MUST verify monotonic revision sequence vectors or emit cross-context events (e.g., via `BroadcastChannel`) alongside lock completion to notify peer execution contexts. ## Bad vs Good Implementations ### Uncoordinated Concurrent IndexedDB Read-Modify-Write Queue Mutation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Opening an IDB transaction asynchronously across separate async calls does not protect the composite read-modify-write cycle across different browser tabs. Two tabs reading simultaneously will both observe version N and increment to N+1, causing the last writer to overwrite the previous writer's delta without detection. ```typescript import { openDB } from 'idb'; interface MutationRecord { id: string; version: number; delta: Record<string, unknown>; } export async function appendMutation(entityId: string, delta: Record<string, unknown>): Promise<void> { const db = await openDB('AppStore', 1); // VULNERABLE: Multiple tabs simultaneously read the same version // and write disparate state, overwriting sibling tab mutations (write-skew). const currentRecord = await db.get('entities', entityId) as MutationRecord | undefined; const nextVersion = (currentRecord?.version ?? 0) + 1; const updated: MutationRecord = { id: entityId, version: nextVersion, delta: { ...(currentRecord?.delta ?? {}), ...delta } }; await db.put('entities', updated); } ``` #### Production Standard (Correct) > **Standard**: Mutations are synchronized using `navigator.locks.request` with an exclusive lock keyed specifically to the target entity, an explicit abort timeout, and an internal scoped IndexedDB readwrite transaction. Peer contexts are informed immediately via BroadcastChannel to prevent stale cache displays. ```typescript import { openDB } from 'idb'; interface MutationRecord { id: string; version: number; delta: Record<string, unknown>; } const LOCK_TIMEOUT_MS = 5000; const channel = new BroadcastChannel('app-state-sync'); export async function appendMutation(entityId: string, delta: Record<string, unknown>): Promise<void> { if (!('locks' in navigator)) { throw new Error('Web Locks API is required for consistent state mutations.'); } const lockKey = `locks:entity:${entityId}`; const options: LockOptions = { mode: 'exclusive', signal: AbortSignal.timeout(LOCK_TIMEOUT_MS) }; await navigator.locks.request(lockKey, options, async () => { const db = await openDB('AppStore', 1); const tx = db.transaction('entities', 'readwrite'); const store = tx.objectStore('entities'); const currentRecord = await store.get(entityId) as MutationRecord | undefined; const nextVersion = (currentRecord?.version ?? 0) + 1; const updated: MutationRecord = { id: entityId, version: nextVersion, delta: { ...(currentRecord?.delta ?? {}), ...delta } }; await store.put(updated); await tx.done; channel.postMessage({ type: 'ENTITY_MUTATED', entityId, version: nextVersion }); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Web Locks API State Synchronization and Concurrency Control Guardrail

Web Locks API State Synchronization and Concurrency Control Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic cross-tab synchronization and prevents IndexedDB write-skew anomalies during high-frequency optimistic state mutations and queue drains. Mandates atomic, scoped synchronization via the native Web Locks API (`navigator.locks.request`) paired with cross-context invalidation signals across concurrent browsing contexts (tabs, dedicated workers, and service workers). 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 Read-Modify-Write Cycles and Optimistic Queue Drains Across Concurrent Tabs Causing IndexedDB Write-Skew and State Regression 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 Read-Modify-Write Cycles and Optimistic Queue Drains Across Concurrent Tabs Causing IndexedDB Write-Skew and State Regression	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 wrap multi-step IndexedDB read-modify-write sequences and offline mutation queue processing inside `navigator.locks.request` with an explicit resource identifier and mode (`exclusive` or `shared`).

Engineers MUST ALWAYS wrap multi-step IndexedDB read-modify-write sequences and offline mutation queue processing inside `navigator.locks.request` with an explicit resource identifier and mode (`exclusive` or `shared`).

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.