Real-World Use Cases

See ZeroLock in action with production-style AI agent systems. Each example uses real LLM agents (Google Gemini) and demonstrates measurable improvements over uncoordinated execution.

Prerequisites

bash

# Start the gateway
cd packages/gateway && pnpm dev
 
# Set API key for LLM-powered agents
export GOOGLE_API_KEY=your-gemini-api-key

PR Review Platform

Location: examples/use-cases/coding-agents/pr-review-platform/

What It Does

5 specialist reviewers analyze a pull request in parallel:

Security Reviewer — Looks for vulnerabilities
Performance Reviewer — Identifies slow code
Style Reviewer — Checks coding standards
Test Coverage Reviewer — Finds untested paths
Documentation Reviewer — Checks for missing docs

A synthesizer agent combines all findings into a final review.

The Problem Without ZeroLock

When reviewers submit findings concurrently, some get lost:

plaintext

❌ Without ZeroLock:
[reviewer-security] Found 3 issues, submitting...
[reviewer-performance] Found 2 issues, submitting...
 
Both try to update the findings list at once:
- Security reads: []
- Performance reads: []
- Security writes: [sec-1, sec-2, sec-3]
- Performance writes: [perf-1, perf-2]  ← Overwrites security!
 
Final findings: [perf-1, perf-2]  ← 3 security issues LOST!

The Solution With ZeroLock

Using CRDT append, all findings are preserved:

plaintext

✓ With ZeroLock:
[reviewer-security] Found 3 issues, appending...
[reviewer-performance] Found 2 issues, appending...
 
Both append concurrently (CRDT merge):
Final findings: [sec-1, sec-2, sec-3, perf-1, perf-2]  ← All 5 preserved!

Architecture

plaintext

┌────────────────────────────────────────────────────────────┐
│                    Pull Request                             │
│  src/auth.py: +45 lines, -12 lines                          │
└───────────────────────────┬────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
  ┌──────────┐        ┌──────────┐        ┌──────────┐
  │ Security │        │  Perf    │        │  Style   │
  │ Reviewer │        │ Reviewer │        │ Reviewer │
  └────┬─────┘        └────┬─────┘        └────┬─────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           ▼
             ┌────────────────────────┐
             │   Findings (CRDT)      │
             │  All findings merge    │
             └───────────┬────────────┘
                         ▼
                ┌───────────────┐
                │  Synthesizer  │
                │ (Final Report)│
                └───────────────┘

Run It

bash

cd examples/use-cases/coding-agents/pr-review-platform
pip install -r requirements.txt
GOOGLE_API_KEY=xxx python main.py

Results

Metric	Without ZeroLock	With ZeroLock
Categories covered	5/5	5/5
Total findings submitted	13	11
Findings lost	2	0
LLM calls	6	6

Key insight: The naive run silently lost 15% of findings. With ZeroLock, every finding is preserved.

Key Code

python

async def submit_findings_node(state: ReviewerState) -> ReviewerState:
    """Submit findings using CRDT append — never loses data."""
 
    for finding in state["findings"]:
        await client.append_item("pr-findings", {
            "category": state["category"],
            "severity": finding["severity"],
            "file": finding["file"],
            "line": finding["line"],
            "message": finding["message"],
            "reviewer": state["agent_id"]
        })
 
    return state

Codebase Migrator

Location: examples/use-cases/coding-agents/codebase-migrator/

What It Does

5 agents refactor files in parallel. The migration task: add new functions to existing files. Agents must claim tasks AND acquire file locks before editing.

The Problem Without ZeroLock

Multiple agents grab the same task and edit the same file:

plaintext

❌ Without ZeroLock:
[agent-1] Taking task: add-sqrt → editing math_utils.py
[agent-2] Taking task: add-sqrt → editing math_utils.py  ← DUPLICATE!
[agent-3] Taking task: add-sqrt → editing math_utils.py  ← DUPLICATE!
 
All 3 agents:
1. Read math_utils.py (original version)
2. Add their function
3. Write back
 
Only agent-3's changes survive (last writer wins).
Functions added: 1
Functions lost: 2 (from agent-1 and agent-2)

The Solution With ZeroLock

Task claiming ensures one owner. File locking ensures one editor at a time:

plaintext

✓ With ZeroLock:
[agent-1] Lost race for 'add-sqrt' (owner: agent-3)
[agent-3] Claimed task: add-sqrt
[agent-3] Acquired lock on math_utils.py
[agent-2] Claimed task: add-absolute
[agent-2] Waiting for lock on math_utils.py... (agent-3 has it)
[agent-3] Released lock on math_utils.py
[agent-2] Acquired lock on math_utils.py
 
All functions added correctly!

Architecture

plaintext

┌────────────────────────────────────────────────────────────┐
│                    Migration Tasks                          │
│  [add-sqrt] [add-absolute] [add-power] [add-log] ...       │
└───────────────────────────┬────────────────────────────────┘
                            │
                     Task Claiming
              (each task claimed by one agent)
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
  ┌──────────┐        ┌──────────┐        ┌──────────┐
  │ Agent 1  │        │ Agent 2  │        │ Agent 3  │
  └────┬─────┘        └────┬─────┘        └────┬─────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
                      File Locks
             (exclusive access per file)
                           │
                           ▼
┌────────────────────────────────────────────────────────────┐
│                    Codebase Files                           │
│  math_utils.py  string_utils.py  data_utils.py             │
└────────────────────────────────────────────────────────────┘

Run It

bash

cd examples/use-cases/coding-agents/codebase-migrator
pip install -r requirements.txt
GOOGLE_API_KEY=xxx python main.py

Results

Metric	Without ZeroLock	With ZeroLock
Tasks completed	8	8
Functions lost	5	0
Duplicate tasks	2	0
File overwrites	11	0
LLM calls	13	8

Key insight: The naive run reported 100% task completion while silently losing 5 of 8 functions. Completion rate ≠ correctness.

Key Code: File Locking

python

async def acquire_file_lock(client, file_name, agent_id, locks_shard):
    """Acquire exclusive lock on a file using OCC."""
 
    for attempt in range(60):  # Max 60 attempts
        shard = await client.get_shard(locks_shard)
        locks = shard.value or {}
        holder = locks.get(file_name)
 
        if holder and holder != agent_id:
            # Someone else has the lock, wait
            await asyncio.sleep(0.5)
            continue
 
        # Try to acquire lock
        locks[file_name] = agent_id
        try:
            await client.commit_shard(locks_shard, locks, shard.version)
            return True  # Lock acquired!
        except StaleCommitError:
            await asyncio.sleep(0.1)
            continue
 
    return False  # Timeout

Deep Research Desk

Location: examples/use-cases/research-agents/deep-research-desk/

What It Does

Multi-source research with three categories:

Academic Papers — Scholarly research
Market Reports — Industry analysis
Technical Docs — Implementation details

Multiple researchers claim sources, research them with Gemini, and submit findings. A synthesizer creates a comprehensive analysis.

Architecture

plaintext

┌─────────────────────────────────────────────────────────────┐
│                    Research Sources                          │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐    │
│  │   Academic    │  │    Market     │  │   Technical   │    │
│  │    Papers     │  │   Reports     │  │     Docs      │    │
│  └───────┬───────┘  └───────┬───────┘  └───────┬───────┘    │
│          │                  │                  │             │
│          └──────────────────┼──────────────────┘             │
│                             ▼                                │
│              ┌────────────────────────┐                      │
│              │   Sources Queue        │                      │
│              │  (Task Claiming)       │                      │
│              └───────────┬────────────┘                      │
│       ┌──────────────────┼──────────────────┐                │
│       ▼                  ▼                  ▼                │
│  ┌──────────┐       ┌──────────┐       ┌──────────┐         │
│  │Researcher│       │Researcher│       │Researcher│         │
│  │    1     │       │    2     │       │    3     │         │
│  └────┬─────┘       └────┬─────┘       └────┬─────┘         │
│       │                  │                  │                │
│       └──────────────────┼──────────────────┘                │
│                          ▼                                   │
│         ┌────────────────────────────┐                       │
│         │     Findings (CRDT)        │                       │
│         │ academic | market | tech   │                       │
│         └────────────┬───────────────┘                       │
│                      ▼                                       │
│              ┌──────────────┐                                │
│              │  Synthesizer │                                │
│              │(Final Report)│                                │
│              └──────────────┘                                │
└─────────────────────────────────────────────────────────────┘

Run It

bash

cd examples/use-cases/research-agents/deep-research-desk
pip install -r requirements.txt
GOOGLE_API_KEY=xxx python main.py

Key Features

Multi-category sources: Different research types need different handling
Task claiming: Each source researched exactly once
Separate CRDT shards: Findings organized by category
Cross-category synthesis: Final report combines all findings

Shards Used

Shard	Type	Purpose
`sources`	Decision	Task queue with claiming
`academic_findings`	Additive	Academic research results
`market_findings`	Additive	Market research results
`technical_findings`	Additive	Technical documentation notes
`final_report`	Decision	Synthesized analysis

Coming Soon: Order Execution

Location: examples/use-cases/trading-agents/order-execution/

What It Will Demonstrate

Trade order processing with Layer 4 Approval Gates — mandatory human review for irreversible financial operations.

Key Concept: Irreversible Shards

Some operations should never auto-execute:

Financial transactions
Production deployments
Email sends
API key rotations

Layer 4 puts a protocol-level gate on these operations. The gateway itself refuses to execute until an authorized approver signs off.

Preview

python

# Create irreversible shard for orders
await client.create_shard("orders", CreateShardOptions(
    type="decision",
    initial_value={"pending": [], "executed": []},
    reversible=False  # Layer 4: Requires approval
))
 
# Executor requests approval (cannot commit directly)
approval = await approvals.request_approval(
    shard_id="orders",
    proposed_value=new_state_with_order,
    description="Execute BUY 150 AAPL @ $182.45",
    ttl_seconds=300  # 5 minute timeout
)
 
# Wait for risk officer decision
result = await approvals.wait_for_approval(approval.id)
 
if result.status == "approved":
    print("Order executed")
else:
    print(f"Order rejected: {result.rejection_reason}")

Feature Matrix

Use Case	Task Claim	OCC	CRDT	Lock	Approval
PR Review	✓		✓	✓
Codebase Migrator	✓	✓		✓
Deep Research	✓	✓	✓
Order Execution	✓	✓	✓		✓

Why These Examples Matter

Each example demonstrates a failure mode that's invisible without ZeroLock:

Example	Silent Failure	Visible Symptom
PR Review	Lost findings	Security bugs slip through
Codebase Migrator	Overwritten edits	"I added that function, where did it go?"
Deep Research	Duplicate research	Wasted LLM costs, inconsistent coverage
Order Execution	Unauthorized trades	Financial loss, compliance violations

ZeroLock makes these failures impossible at the protocol level.

Next Steps

Quickstart Examples — Core patterns in isolation
Framework Integrations — LangGraph, CrewAI, AutoGen
Advanced Patterns — Task claiming, file locking, approval gates deep dives