Lock Scope & Granularity Design

Pillar: lock-design-granularity | Date: May 2026
Scope: The design space for advisory lock granularity applied to code repositories: file-level vs directory-level vs module-level vs semantic-scope locks, hierarchical lock schemes (intention locks escalating from file to directory), adaptive granularity based on observed contention, advisory vs exclusive vs shared-read lock types, scope declaration protocols (how agents announce intent), and lock coarsening vs splitting tradeoffs.
Sources: 42 gathered, consolidated, synthesized.

Table of Contents

1. Foundational Theory: Multiple Granularity Locking (Gray 1976)
2. Intention Lock Protocol: IS, IX, SIX Mode Hierarchy
3. Coarse-Grained vs. Fine-Grained: Performance Tradeoffs
4. Lock Types: Advisory, Shared, Exclusive, and Opportunistic
5. Lock Coarsening, Splitting, and Escalation
6. Adaptive Lock Granularity
7. Filesystem and Directory-Level Locking
8. Scope Declaration Protocols for Multi-Agent Systems
9. Distributed Lock Implementation Mechanisms
10. Code Repository Lock Design Patterns
11. Repository Hierarchy Mapping
12. Design Recommendations Summary

Section 1: Foundational Theory — Multiple Granularity Locking (Gray 1976)

The canonical framework for hierarchical lock granularity originates in a 1976 paper by Gray, Lorie, Putzolu, and Traiger: "Granularity of Locks and Degrees of Consistency in a Shared Data Base."^[2] Multiple Granularity Locking (MGL) resolves the fundamental tension between two extremes: a single global lock permits only one transaction at a time regardless of which data it accesses, while field-level locking requires prohibitive per-field lock acquisition overhead on bulk operations.^[1][16]

The Core Granularity Problem

"Granularity refers to the size of the data item on which a lock is applied."^[16] The two axes of the tradeoff are directly opposed: small granularity (field-level) yields high concurrency but high overhead; large granularity (file-level or table-level) yields low overhead but low concurrency.^[1][2] No fixed granularity optimizes both simultaneously for mixed workloads.

Key finding: MGL resolves the granularity dilemma by allowing transactions to select the granularity level that matches their access pattern — bulk operations acquire coarse locks; fine-grained operations acquire targeted record locks — within a single shared tree hierarchy.^[1][31]

Resource Hierarchy

Resources organize into a tree structure: database → area/table → file/page → record/row. A lock on any node implicitly locks all descendants in that subtree.^[1][3][31] Conflict detection across granularity levels — detecting that a directory-level lock conflicts with a pending file-level lock — costs O(depth of tree) rather than O(N descendants) when intention locks are used.^[31][19]

Three-Version Evolution of MGL

Code Repository Mapping

The database hierarchy maps directly to code repositories: repository → directory/module → file → function/line-range.^[18][21] Agents with large-scope work (refactoring an entire module) acquire coarse directory locks; fine-grained agents (patching a single function) lock individual files. The same adaptive logic applies in both domains.

Section 2: Intention Lock Protocol — IS, IX, SIX Mode Hierarchy

The Gray 1976 framework extends standard Shared (S) and Exclusive (X) locks with three intention modes that signal locking intent at parent hierarchy levels, enabling efficient cross-granularity conflict detection without descendant traversal.^[1][2][16]

The Five Lock Modes

Lock Compatibility Matrix

(Source: Gray 1976 as reproduced via Wikipedia MGL article)^[16][29]

Seven Protocol Rules

All sources converge on the same seven mandatory rules for correct MGL operation:^[3][17][31]

1. Lock the root first (any mode)
2. S or IS locks require the parent to hold IS, IX, S, SIX, or X
3. X, IX, or SIX locks require the parent to hold IX or SIX
4. Acquire locks top-down (root → leaf)
5. Release locks bottom-up (leaf → root)
6. Unlock child nodes before unlocking parents
7. Follow 2-Phase Locking (2PL) protocol

Key Behavioral Properties

Why IX is Compatible with Itself

Two agents both holding IX on the same directory do not conflict at that level — their actual conflict (if any) resolves when they each acquire X locks on specific files below. The directory IX only signals "something exclusive is happening below," not which item.^[31] This property is essential for parallel agent work within the same module.

SIX Optimization Use Case

A transaction scanning an entire module (needs S) while modifying specific files (needs X) would otherwise require either S on every file (high overhead) or X on the whole directory (blocking all readers). SIX on the directory resolves both needs: scan concurrent with other readers, writes exclusive at file level.^[31]

Key finding: Despite hierarchical lock ordering, deadlock remains possible with MGL — it does not eliminate circular wait, only conflicts across granularity levels. Standard 2PL deadlock detection and prevention still apply.^[1][3]

Section 3: Coarse-Grained vs. Fine-Grained — Performance Tradeoffs

The granularity selection question is the central empirical and theoretical problem in lock design. Multiple independent sources converge on consistent findings about the performance envelope of each extreme.^[9][21][34]

Core Tradeoff Matrix

(Source: AlgoMaster.io Concurrency Interview series)^[9][21][34]

Empirical Performance Data

Key finding: "Theory often loses to practice" — hardware architecture (especially ARM vs. x86), JVM behavior, and OS scheduling make granularity performance difficult to predict analytically. Measurement on the target platform is mandatory.^[9]

Throughput and Latency Analysis

Throughput impact of coarse granularity: With file-granularity locking, an agent accessing only a few functions still locks the whole file, blocking other agents from accessing unrelated functions in that file. At directory granularity, one agent working on a single file blocks all agents from the entire module.^[9][21]

Overhead impact of fine granularity: Lock acquisition and release overhead can dominate at fine granularity. For large read operations, fine-grained locking generates thousands of lock operations — one per file accessed — versus a single coarse lock.^[9]

Granularity Levels for Code Repositories

"The reason so many different synchronization objects have been invented is to try to find a sweet spot where you have fine-grained locking so that performance is high, but it is easy enough to program so mistakes can be avoided."^[9][34] The optimal strategy for code repositories typically uses file-level locking as the default with directory-level intention locks to prevent structural conflicts.^[21]

Section 4: Lock Types — Advisory, Shared, Exclusive, and Opportunistic

Advisory vs. Mandatory Locking

Advisory locking requires all participating processes to cooperate — every agent must check and respect locks before accessing shared resources. The operating system does not prevent unauthorized access; it relies entirely on application-level cooperation. A single non-cooperative agent can ignore advisory locks and access files freely.^[10][24][25]

Mandatory locking enforces access control at the kernel level but is less common in Unix-like systems and has known reliability issues on some platforms.^[36] For multi-agent coding systems where all agents are under controlled deployment, advisory locks are appropriate — but any agent that bypasses the lock protocol breaks the entire system.^[10]

Readers-Writer Locks: Shared vs. Exclusive Access

The readers-writer lock (RW lock, MRSW lock) is the foundational pattern for differentiating read concurrency from write exclusivity.^{[11][26][38][39]}

Access Mode Compatibility

Priority Policy Tradeoffs

Write-preferring is generally recommended for code editing workloads — agent modifications must not be indefinitely blocked by concurrent readers (e.g., analysis agents).^[11][26]

Lock Upgrade Hazard

Converting a read lock to a write lock is a deadlock trap: two agents both holding read locks, both attempting upgrade, both waiting for the other to release — neither can proceed. The solution is to allow only one agent to hold "read with intent to upgrade to write" — structurally identical to the SIX lock mode in MGL.^[11]

Opportunistic Locks (Oplocks)

Windows implements oplocks — an optimistic advisory locking pattern for networked file servers — operating at file level (not byte-range).^[15] The protocol:

1. Client acquires oplock optimistically, assuming exclusive access
2. Client caches file locally and operates freely without round-trips
3. If another client requests conflicting access, the server sends an oplock break notification
4. Original client must flush dirty data and release the lock before the requesting client proceeds

The oplock break mechanism maps directly to lock preemption in multi-agent systems: a higher-priority agent can preempt a lower-priority agent's file lock with appropriate notification and flush protocol.^[15]

Oplock Types

POSIX Advisory Locks vs. BSD Locks (Linux)

Two distinct advisory lock APIs exist on Linux with critically different semantics relevant to multi-threaded agent processes:^[24][25][36]

Critical POSIX lock flaw: Closing any file descriptor to a locked file releases all locks held by the process on that file — even locks acquired on different fds. Library functions that internally open and close files silently destroy in-flight agent locks. This makes POSIX fcntl locks dangerous for multi-threaded agent processes that use standard library calls.^[24][25]

NFS reliability warning: Many NFS implementations improperly implement fcntl lock semantics. There is no reliable way to detect whether file locking works on a specific NFS mount. Advisory locks on NFS-mounted repositories are unreliable. NFSv4 introduces stateful locking with seqid to prevent retry inconsistencies but is not universally deployed.^[10]

Key finding: Application-level advisory locks (PostgreSQL advisory locks, Redis, etcd) avoid all OS lock API pitfalls and work across network boundaries. For most multi-agent repository systems, OS-level file locks are an inferior choice.^[24][25]

Section 5: Lock Coarsening, Splitting, and Escalation

Three runtime mechanisms exist for dynamically adjusting lock granularity within a running system. Each addresses a different performance pathology.

Lock Coarsening

Lock coarsening merges adjacent synchronized blocks that have no observable operations between them into a single larger critical section, eliminating repeated acquire/release overhead.^[13][40]

• JIT compilers detect patterns where a lock is released and immediately reacquired with no side-effecting operations between
• Merged into a single acquire/release pair covering the entire sequence
• JVM benchmark: ~4x throughput improvement from 4x loop unrolling enabling 4 adjacent lock pairs to merge into 1^[13]
• Loops are not coarsened to span the entire loop body — would create excessively long critical sections. Loop unrolling enables coarsening within the unrolled segment.^[13]
• Trade-off: larger critical sections cause other threads to stall longer — reduced responsiveness at high concurrency

Repository application: If an agent repeatedly locks/unlocks the same directory for multiple sequential file operations, coarsen to a single directory lock for the entire operation batch.^[13]

Lock Splitting and Striping

Lock splitting breaks one coarse lock into multiple finer-grained locks to increase parallelism when the coarse lock becomes a bottleneck.^[13]

Java ConcurrentHashMap (pre-JDK 1.8): Array of Segment objects, each with its own ReentrantLock. A put operation locks only the relevant Segment, leaving all others available concurrently.^[13]

Lock Striping Effectiveness by Contention Level

(Source: Aleksey Shipilev, JVM Anatomy Quarks)^[13]

Repository application: If one broad directory lock is always contended, split by subdirectory or file-type grouping (e.g., separate lock ranges for src/, tests/, config/).

Lock Elision

JIT compilers remove locks entirely via escape analysis — if the lock object provably cannot escape to other threads, the lock is a no-op and is eliminated. Common with JDK APIs: StringBuffer, Vector, Hashtable.^[13][40] Repository application: If an agent has an assigned worktree and provably has exclusive access to a set of files, skip lock acquisition entirely — isolation already guarantees exclusivity.

Lock Escalation (Database Pattern)

Lock escalation converts many fine-grained locks into fewer coarse-grained locks when threshold conditions are met, reducing lock table memory consumption and management overhead.^[42]

SQL Server Escalation Thresholds

Escalation process: Attempts to convert the Intent lock (IX/IS) on the parent to a full lock (X/S). If blocked by another transaction, escalation is deferred — it does not wait.^[42] SQL Server also supports HoBT (heap/B-tree partition) escalation for partitioned tables as an intermediate between row and table level.^[42]

Lock De-escalation (Patent Approach)

US Patent 6144983 describes the reverse process — de-escalating a coarse-grained bucket lock into fine-grained member locks when a conflicting request arrives for a specific member.^[20] Rather than a static tree hierarchy, locks are assigned to hash buckets based on empirical access patterns. The system learns which files are frequently co-modified and groups them into buckets for efficient coarse locking. When a conflict is detected on a single bucket member, the bucket lock is split into per-member locks to restore parallelism.^[20]

Key finding: SQL Server's escalation design insight for repository lock managers: track file lock count per directory. If an agent holds >N file locks within a directory, automatically escalate to a single directory lock to reduce lock table overhead. Use both lock count and memory pressure as dual escalation signals.^[42][20]

Section 6: Adaptive Lock Granularity

Fixed granularity is rarely optimal across all workloads. Four distinct approaches to runtime granularity adaptation have been documented in the literature.

IEEE Adaptive-Granularity Algorithm (Collaborative Authoring)

An IEEE-published adaptive-granularity algorithm designed for collaborative authoring systems is structurally analogous to multi-agent code editing.^[5] The algorithm:

• Monitors access patterns in real time to determine optimal granularity
• High contention on specific sections → transitions to fine-grained section locks
• Low overall contention → coarsens locks to cover larger content units
• Dynamically transitions between levels based on real-time feedback without downtime

The document hierarchy used mirrors code hierarchy exactly: Document → Chapter/Section → Paragraph → Sentence maps to Repository → Directory → File → Function.^[5]

Adaptive Spinning (JVM)

Two-phase spin-then-block strategy where spin duration is determined by recent success/failure rates and the current lock owner's CPU state.^[40] "Adaptive" here means the granularity of wait behavior adjusts based on observed lock hold durations — avoids expensive OS context switches for short critical sections while falling back to blocking for long ones.

ML-Driven Adaptive Granularity

A Random Forest-based adaptive system documented in TD Commons continuously monitors workload patterns and selects granularity levels to minimize total cost (wait time + overhead):^[32]

• Analyzes contention rates per granularity level (row/page/table)
• Monitors: average lock wait time, transaction abort rates, conflict patterns
• Operates on-the-fly without system restart
• Feedback loop recalibrates lock durations and timeout thresholds continuously
• Uses ML models (Random Forest) to predict workload patterns and pre-select granularity

Hash-based adaptive escalation (US Patent 6144983), where locks are de-escalated from coarse bucket locks into per-member locks on conflict, is covered in Section 5 (Lock De-escalation).^[20]

Adaptive Granularity Design Principles

Key finding: The ML-driven adaptive approach (Random Forest on contention metrics) is the most general solution — it does not require pre-defining a hierarchy or static thresholds. However, threshold-based escalation (lock count + memory pressure) is simpler to implement correctly and well-validated in production database systems.^[32][42]

Section 7: Filesystem and Directory-Level Locking

Linux Kernel Directory Locking Architecture

The Linux kernel implements a two-tier locking scheme for directory operations separating content locks from topology locks:^[14]

• Per-inode lock (->i_rwsem): Protects individual directory inodes
• Per-filesystem lock (->s_vfs_rename_mutex): Protects tree topology changes (renames, directory moves)

Six Operation Classes and Lock Requirements

Deadlock Prevention Protocol

The Linux kernel prevents lock-order deadlocks through strict hierarchical acquisition:^[14]

1. Filesystem lock first (coarsest — prevents topology changes)
2. Directory locks in ancestor-first order (parent before child)
3. Non-directory locks in increasing inode pointer address order

For code repositories, use file path hash or alphabetical ordering as the canonical lock acquisition order when acquiring multiple same-level file locks simultaneously.^[14]

Cross-directory rename exception: After taking the filesystem lock, verify the common ancestor relationship — this relationship cannot change until the filesystem lock drops, eliminating the specific deadlock scenario for cross-directory moves.^[14]

Two-tier principle for code repositories: Separate topology locks (branch/repo structure modifications, directory creation, module moves) from content locks (file modifications within stable directories). These can be held independently, increasing parallel agent throughput.^[14]

Git-Level File Locking

Git uses file-based locks to protect repository integrity. Three lock files are relevant to parallel agent execution:^[41][27]

The .git/config.lock Race Condition

GitHub Issue #34645 documents a real-world granularity failure in Claude Code: when 3+ agents are launched in parallel with isolation: "worktree", concurrent git worktree add commands race for .git/config.lock, causing agent failures with orphaned branches.^[27][41]

Root cause: The config lock is too coarse — it serializes all worktree creation even for agents that will work on entirely independent files. The granularity mismatch is between the creation-time lock (repository-wide) and the execution-time lock (per-worktree).

Proposed Fixes (in order of preference)

Key finding: Git worktree provides coarse branch-level isolation (one worktree per branch, enforced by Git) but its creation mechanism introduces a repository-wide config lock bottleneck for parallel agent launch. Worktree creation must be serialized; worktree execution is fully parallel.^[41][27]

Section 8: Scope Declaration Protocols for Multi-Agent Systems

Intent Declaration Pattern

When a coding agent is about to modify a shared component, it posts a lock or intent declaration in a shared coordination context: "Coder1: editing AuthModule." Other agents see this and either wait or negotiate.^[12]

Five-Step Protocol

1. Agent declares write intent to acquire a scope
2. System checks for conflicts with existing declarations
3. If clear, agent proceeds and holds the lock
4. On completion, agent releases and notifies dependents
5. Atomic operations ("INSERT IF NOT EXISTS") implement the underlying lock state

Contention handling: Exponential backoff — agent waits and doubles the delay on each retry attempt. Scheduling protocols: FIFO, priority queues by task importance, synchronization ordering (Agent B cannot start until Agent A completes).^[12]

Agent Control Protocol (ACP) and Agent Cards

The Agent Control Protocol (ACP), published as arxiv preprint (2603.18829v5), defines a formal scope declaration standard via Agent Cards at /.well-known/agent.json — public declarations of agent capabilities, supported modes, authentication requirements, and capability scope.^[37]

ACP validates all of the following simultaneously (not sequentially) before execution:^[37]

• Identity verification
• Capability scope authorization
• Delegation chain validation
• Policy compliance checking

ACP messages are tagged using Speech Act Theory: REQUEST, INFORM, PROPOSE, or REFUSE. Agents send intent, not just data. This is structurally analogous to IS/IX intention locks: agents declare intent before acting, and admission control validates scope before execution is permitted.^[37]

Non-transitivity of trust: A trusts B, B trusts C does not imply A trusts C. This is relevant for multi-agent file access chains where intermediate agents act as coordinators.^[37]

Squad's Drop-Box Pattern (GitHub Copilot)

GitHub Copilot's Squad system uses a drop-box pattern for coordination: every architectural choice is appended as a structured block to a versioned decisions.md file. This is advisory locking at the semantic/decision level rather than the file level.^[7]

Squad's bet: asynchronous knowledge sharing inside the repository scales better than real-time synchronization.^[7] The tradeoff is lower coordination overhead at the cost of potential inconsistency windows during concurrent writes to the decisions file.

Reviewer exclusivity protocol: The reviewer protocol prevents the original author from revising their own rejected work — a different agent must step in. This implements mutual exclusion at "authorship scope" — the original author cannot hold the "revise" lock on their own rejected output.^[7]

Assignment as Implicit Lock Declaration

Task assignment serves as scope declaration — agents implicitly claim files when assigned a task. The shared task list coordinates work through dependency tracking with statuses: pending, in_progress, completed, blocked.^[8][33]

Multi-Agent Coordination Protocols

Byzantine Fault Tolerance constraint: Multi-agent lock protocols tolerate up to (n-1)/3 faulty agents. When agents crash holding locks, dead-agent lock release protocols (TTL, ephemeral node deletion) are essential — not an edge case.^[12]

Key finding: "In production systems, coordination failures almost always originate in communication, not reasoning quality. Agents may be individually capable, yet collectively incoherent, because they do not share a common interaction protocol."^[22] Scope declaration protocols are the communication layer that prevents this.

Section 9: Distributed Lock Implementation Mechanisms

For multi-agent systems operating across processes or machines, OS-level file locks are insufficient. Three distributed locking infrastructure options have distinct tradeoff profiles.^[23][35]

Core Five-Stage Acquisition Workflow

All distributed lock implementations share the same logical flow:^[23]

1. Request exclusive access to a named resource
2. Attempt acquisition — succeed if no existing lock record, fail with retry if blocked
3. Execute critical operations while holding the lock
4. Explicit release upon completion
5. Automatic cleanup via TTL expiry or ephemeral mechanism on agent crash

Implementation Comparison

PostgreSQL advisory lock advantage for repositories: File path hash as lock key enables per-file advisory locks without creating actual lock records in a file table. Connection-scoped auto-release provides agent crash safety without TTL management.^[23]

Partitioned Locks for Scale

When multiple agents compete for a single lock covering a large resource, the system becomes effectively single-threaded through that lock.^[35] Solution: partition locks so each partition is independently lockable — analogous to lock splitting at the infrastructure level rather than the application level.

Failure Mode Analysis

Key finding: "Try to avoid distributed locking if you can" — validate the necessity of distributed coordination before implementing it. Partitioning, idempotency, and event sourcing can eliminate the need for distributed locks in many scenarios, removing an entire class of failure modes.^[35]

Section 10: Code Repository Lock Design Patterns

File-Level vs. Semantic Conflicts

File-level locking addresses physical conflicts (two agents writing the same bytes) but not semantic conflicts (two agents holding different files but producing incompatible interfaces).^[22][6]

"Semantic locks (locking by API surface, module interface, or dependency graph edges) would address design-level conflicts that file locks miss. Scope declaration protocols must be expressive enough to capture design intent, not just file access."^[22]

FLP Impossibility applied to multi-agent coding: The FLP Theorem states that in any distributed system with arbitrary delays and potential crashes, no deterministic protocol can ensure all non-faulty nodes reach consensus in bounded time. File-level locks help with physical correctness but do not solve the fundamental consensus problem for semantic correctness.^[6][22]

Byzantine Generals bound: With more than (n-1)/3 agents misinterpreting requirements, consensus becomes impossible regardless of model capability. External validation (tests, static analysis) converts misinterpretations into detectable failures rather than silent semantic divergence.^[6]

Six Git Worktree Conflict Types and Their Granularity

Hotspot files (routes, type registries, configuration files) are the primary source of merge conflicts — multiple features inevitably touch them. Prevention: designate single owners, merge early and often, use additive-only changes (add to new files rather than modifying shared ones).^[28][41]

Complete Granularity Hierarchy for AI Agents

Six Practical Conflict Prevention Strategies

From real-world multi-agent deployment experience:^[28][41][8]

1. Non-overlapping file assignment at task-design time: More reliable than runtime lock negotiation — prevents conflict rather than detecting it
2. Additive-only changes: Add new files rather than modifying shared ones — enforces coarser isolation through architectural convention
3. Merge early and often: Reduces the window during which semantic conflicts can accumulate silently
4. Worktree isolation: Each agent in a separate git worktree — prevents filesystem conflicts but not semantic conflicts
5. Automated quality gates before merge: Tests and static analysis as implicit synchronization points — external validation converts misinterpretations to detectable failures
6. Stale worktree cleanup: Periodic git worktree list and git worktree prune to prevent stale reference accumulation that blocks new worktree creation

Key finding: "A multi-agent coding workspace functions only when coordination is treated as infrastructure: explicit task boundaries, isolated execution, and evidence-based merges. Lock scope design is therefore not merely a performance concern — it is a foundational correctness requirement for any serious multi-agent code repository system."^[33]

Section 11: Repository Hierarchy Mapping

The MGL database hierarchy translates directly to code repository structures, enabling the full MGL protocol — with all five lock modes and the compatibility matrix — to apply to agent coordination:^[18][21][31]

Topology vs. Content Lock Separation

Drawing from the Linux kernel's two-tier design:^[14] repository lock systems should separate:

• Topology locks (branch creation, module directory moves, rename): Require filesystem-level coarse lock — held briefly, serialized
• Content locks (file modification within stable directories): Per-file or per-directory locks — held for work duration, parallel

This two-tier design ensures that an agent restructuring a module tree does not block other agents modifying files within stable directories, and vice versa.

Context Scope Architecture

Not all agents require global context, and broad context can degrade performance:^[33]

• Execution agents perform better with narrowly scoped, highly relevant context rather than full repository history
• Deciding what context is global vs. local is a core architectural decision, not an implementation detail
• Peer-to-peer communication between agents prevents the lead agent from becoming a coordination bottleneck
• Scope visibility restrictions serve as implicit locks — agents cannot modify what they cannot see

Section 12: Design Recommendations Summary

Key finding: The five-mode MGL protocol (NL/IS/IX/S/SIX/X) with the compatibility matrix and seven protocol rules is directly applicable to multi-agent code repositories, mapping database hierarchy levels to repository → module → file → function. The primary gap between database MGL and repository MGL is the semantic layer: file locks address physical correctness but cannot enforce API surface compatibility across agent boundaries.^[1][22][31]

Home