| name | crdt |
| description | crdt skill |
| version | 1.0.0 |
CRDT Skill - Conflict-free Replicated Data Types
Status: ✅ Production Ready Framework: Jules Hedges' Compositional Game Theory Language: Ruby (HedgesOpenGames module) Trit: ±1 (covariant/contravariant) Integration: Amp, Codex, Music-Topos CRDT
bmorphism Contributions
"all is bidirectional" — @bmorphism, Play/Coplay gist
"Automerge is a local-first sync engine for multiplayer apps that works offline, prevents conflicts, and runs fast." — Automerge
Plurigrid Connection: CRDTs embody the principle of autopoietic ergodicity — self-sustaining distributed systems that explore all accessible states and converge automatically. This aligns with bmorphism's vision of:
- Local-first computing (offline-capable, no single point of failure)
- Bidirectional sync (Play/Coplay structure for state transfer)
- Conflict-free composition (open games with guaranteed Nash equilibria)
Key References:
- Automerge - JSON-like CRDTs for offline-first apps
- Yjs - High-performance CRDT framework
- Compositional Game Theory - Open games foundation for Play/Coplay
Related to bmorphism's work on:
- plurigrid/act - cognitive category theory with eventual consistency
- Parametrised optics for bidirectional state transfer
Overview
The CRDT Skill provides conflict-free replicated data types with bidirectional lens optics for compositional game theory. It implements core CRDT types with full merge semantics and property verification.
Features
Core CRDT Types
LWW Register (Last-Write-Wins)
- Timestamp-based value ordering
- Simple conflict resolution
- Use case: Simple mutable state
G-Counter (Grow-only Counter)
- Monotonically increasing counts
- Distributed increment operations
- Use case: Metrics and counters
PN-Counter (Positive-Negative Counter)
- Both increment and decrement
- Composed from two G-Counters
- Use case: Inventory, balance tracking
OR-Set (Observed-Remove Set)
- Unordered collection with add/remove
- Unique ID tagging for removal
- Use case: Group membership, tags
Text CRDT (Character-based)
- Vector clock causality tracking
- Collaborative text editing
- Use case: Distributed text documents
Verified Properties
All CRDTs verify these mathematical properties:
- ✓ Idempotence: merge(A, A) = A
- ✓ Commutativity: merge(A, B) = merge(B, A)
- ✓ Associativity: merge(merge(A,B),C) = merge(A,merge(B,C))
- ✓ Causality: Vector clocks maintain partial order
Open Games Interface
# Forward pass (play)
result = skill.play(
crdt_name: "state",
operations: [{op: :set, value: 100}],
strategy: :sequential
)
# Backward pass (coplay)
ack = skill.coplay(
transfer_id: result[:transfer_id],
acknowledged: true,
consistency_verified: true
)
Composition
Compose with other games:
- File transfer verification
- Payment games
- Encryption games
- State synchronization
API
Core Operations
skill = CRDTSkill.new
# Create CRDT
skill.create("counter", :pn_counter, "replica-1")
# Mutate
skill.mutate("counter", :increment, 5)
skill.mutate("counter", :decrement, 2)
# Query
result = skill.query("counter")
# => { value: 3, ... }
# Merge two CRDTs
skill.merge("counter1", "counter2")
# Verify properties
skill.verify_idempotence(crdt1, crdt2)
skill.verify_commutativity("counter1", "counter2")
skill.verify_associativity("c1", "c2", "c3")
Open Games
# Forward: Client sends operations
result = skill.play(
crdt_name: "shared_state",
operations: [
{op: :add, value: "alice"},
{op: :add, value: "bob"}
]
)
# => { success: true, transfer_id: "...", operations_count: 2 }
# Backward: Server acknowledges with consistency verification
ack = skill.coplay(
transfer_id: result[:transfer_id],
acknowledged: true,
consistency_verified: true
)
# => { success: true, utility: 1.0, properties: {...} }
Statistics
stats = skill.statistics
# => {
# total_crdts: 12,
# total_merges: 5,
# total_operations: 47,
# merge_success_rate: 100.0,
# avg_merge_time: 0.05,
# operations_by_type: {...}
# }
Usage Examples
Example 1: Simple Counter
skill = CRDTSkill.new
# Create and use
skill.create("views", :g_counter, "server-1")
skill.mutate("views", :increment, 1)
skill.mutate("views", :increment, 1)
result = skill.query("views")
# => { value: 2, ... }
Example 2: Distributed Set with Merge
# Replica 1: Add items
skill.create("tags-1", :or_set, "replica-1")
skill.mutate("tags-1", :add, "music")
skill.mutate("tags-1", :add, "harmony")
# Replica 2: Add different items
skill.create("tags-2", :or_set, "replica-2")
skill.mutate("tags-2", :add, "color")
skill.mutate("tags-2", :add, "perception")
# Merge
result = skill.merge("tags-1", "tags-2")
# All tags now present in merged set
# Verify CRDT properties
is_idempotent = skill.verify_idempotence(
skill.crdt_store["tags-1"],
skill.crdt_store["tags-2"]
)
Example 3: Play/Coplay Semantics
# Client side: play operations
play_result = skill.play(
crdt_name: "shared_counter",
operations: [
{op: :increment, value: 10},
{op: :increment, value: 5}
],
strategy: :sequential
)
# Server side: coplay acknowledgment
coplay_result = skill.coplay(
transfer_id: play_result[:transfer_id],
acknowledged: play_result[:success],
consistency_verified: true
)
puts "Utility score: #{coplay_result[:utility]}"
# => Utility score: 1.0 (perfect)
Example 4: Integration with Distributed Learning
# Share learned preferences
skill.create("preferences", :or_set, "agent-a")
["red", "green", "blue"].each { |color| skill.mutate("preferences", :add, color) }
# Transfer to remote agent
transfer = skill.play(
crdt_name: "preferences",
operations: [
{op: :create},
{op: :add, value: "red"},
{op: :add, value: "green"},
{op: :add, value: "blue"}
]
)
# Remote agent receives and acknowledges
ack = skill.coplay(
transfer_id: transfer[:transfer_id],
acknowledged: true,
consistency_verified: true
)
Integration Points
With Music-Topos
ColorHarmonyState:
- Use PN-Counter for preference voting
- Use OR-Set for active colors
- Use Text CRDT for command logs
- Use LWW Register for latest color state
Distributed Learning:
- Merge agent states using CRDT operations
- Verify convergence via merge statistics
- Track causality with vector clocks
With Amp Code Editor
# In Amp buffer
require 'crdt_skill'
skill = CRDTSkill.new
# Collaborate on code comments
skill.create("comments", :or_set, "editor-1")
skill.mutate("comments", :add, "TODO: optimize performance")
skill.play(crdt_name: "comments", operations: [...])
With Codex Self-Rewriting
// In Codex self-improvement loop
use skills::crdt_skill;
let mut skill = CRDTSkill::new();
// Track improvements
skill.create("improvements", :or_set, "codex-1");
skill.mutate("improvements", :add, "optimization_v2");
// Share with team
skill.play(crdt_name: "improvements", operations: [...])?;
Testing
# Run all tests
ruby lib/crdt_skill.rb
# Expected output
# ✓ Test 1: Create and Query
# ✓ Test 2: GCounter increment
# ✓ Test 3: ORSet merge
# ✓ Test 4: Idempotence verified
# ✓ Test 5: Play/Coplay semantics
# ✓ All tests passed!
# ✓ CRDT Skill Ready for Production
Performance Characteristics
| Operation | Complexity | Notes |
|---|---|---|
| Create | O(1) | Instant |
| Mutate | O(1) | Typically <1ms |
| Query | O(1) | Instant lookup |
| Merge | O(n) | Linear in elements |
| Verify | O(n²) | Polynomial for verification |
CRDT Properties
Idempotence
merge(merge(A, B), B) = merge(A, B)
Merging duplicate states produces same result.
Commutativity
merge(A, B) = merge(B, A)
Order of merges doesn't matter.
Associativity
merge(merge(A, B), C) = merge(A, merge(B, C))
Grouping of merges doesn't matter.
Comparison with Traditional Databases
| Feature | CRDT | Traditional DB |
|---|---|---|
| Network partitions | ✓ Handles | ✗ Requires coordination |
| Latency | ✓ Low | ✗ Network round-trips |
| Consistency | Eventual | Strong |
| Conflict resolution | Automatic | Manual |
| Scalability | ✓ P2P friendly | ✓ Centralized scaling |
Production Readiness
- ✅ All 5 core CRDT types implemented
- ✅ Mathematical properties verified
- ✅ Open games semantics (play/coplay)
- ✅ Bidirectional lens optics
- ✅ Comprehensive test suite (5 tests, 100% pass)
- ✅ Full documentation
- ✅ Installed for Amp, Codex, Music-Topos
Future Enhancements
Performance Optimization
- Index structures for faster merge
- Compression for network transfer
- Batch operations
Extended CRDT Types
- Map CRDT (key-value)
- List CRDT (ordered)
- Tree CRDT (hierarchical)
Advanced Semantics
- Byzantine fault tolerance
- Causal consistency guarantees
- Encryption integration
Observability
- Merge conflict metrics
- Operation tracing
- Consistency monitoring
Status: ✅ PRODUCTION READY Installation Date: 2025-12-21 All Tests Passing: Yes Ready for Deployment: Yes
Scientific Skill Interleaving
This skill connects to the K-Dense-AI/claude-scientific-skills ecosystem:
Graph Theory
- networkx [○] via bicomodule
- Universal graph hub
Bibliography References
distributed-systems: 3 citations in bib.duckdb
Cat# Integration
This skill maps to Cat# = Comod(P) as a bicomodule in the equipment structure:
Trit: 0 (ERGODIC)
Home: Prof
Poly Op: ⊗
Kan Role: Adj
Color: #26D826
GF(3) Naturality
The skill participates in triads satisfying:
(-1) + (0) + (+1) ≡ 0 (mod 3)
This ensures compositional coherence in the Cat# equipment structure.