nebula-protocol 1.2.1

CRDT-based convergent state replication for heterogeneous multi-agent systems. Prevents phantom commitments via AS-CRDTs and A2A protocol extension.

Nebula Protocol

Nebula Convergence Engine (NCE) — CRDT-based convergent state replication for heterogeneous multi-agent systems, extending Google's A2A protocol.

Section	Description
Problem	Phantom commitments in multi-agent coordination
Solution	AS-CRDTs and observation proofs
Quick Start	Install, run, verify
Dashboard	Demo and Live modes
Architecture	NCE Core, ADRs, diagrams
API	REST + WebSocket reference
Reproducibility	Paper Table 5 reproduction
Benchmarks	Protocol comparison

The Problem

AI agents operating on the same shared resource (e.g., inventory) can act on stale state and make conflicting decisions - a phantom commitment. Two agents simultaneously read stock: 1 and both commit a sale, resulting in stock: -1. This occurs in any multi-agent system without real-time consensus, and consensus protocols sacrifice availability during network partitions.

The Solution

NCE provides AS-CRDTs (Agent-State CRDTs) with cryptographic observation proofs as a native A2A protocol extension. Three CRDT types - TaskStatus, ObservedBeliefRegister, and CapabilitySet - guarantee eventual consistency without a central coordinator. Every state mutation is logged as an EU AI Act Article 12 compliance event.

Quick Start

pip install nebula-protocol
# Or from source:
pip install -e ".[dev]"

# Run the full test suite (124 tests, including Hypothesis property tests)
make ci

# Run the e-commerce simulation (NCE vs 3 baselines)
python -m simulation.run_simulation --all --transactions 1000

# Launch the dashboard
cd dashboard && npm install && npm run dev

Dashboard

The NCE Simulation Dashboard visualizes the multi-agent e-commerce simulation in real time.

Mode	Use Case
Demo Mode	No server needed. Runs entirely in the browser. Ideal for presentations and paper review.
Live Mode	Connects to the FastAPI backend. Requires uvicorn api.main:app --port 8000 running.

What you see: 4 KPI cards (Phantom Commits, Conv p99, Token Saved, Art.12), convergence histogram, token cost comparison, agent fleet table, throughput chart, compliance log, and protocol comparison table.

📖 Dashboard Guide - Technical implementation details (12 agents, API contract, components).

Demo

Run simulation in Demo Mode; KPIs, charts, and agent fleet update in real time.

Architecture

See docs/architecture.md for full architecture diagrams and ADRs.

High-level flow: Dashboard (React) ↔ FastAPI (REST + WebSocket) ↔ Simulation (12 agents, 4 baselines) ↔ NCE Core (CRDTs, delta sync, compliance).

5-line usage example:

from nce.sync.state_bus import StateBus
from nce.crdt.task_status import StatusLevel

bus = StateBus(agent_id="order-agent-1")
await bus.update_belief("inventory:SKU-001", 42)
await bus.update_task("order-99", StatusLevel.COMPLETED)

state = bus.query_state()
print(state.beliefs["inventory:SKU-001"].value)  # 42

Architecture (NCE Core)

graph TD
    A2A[A2A Agent Card\nwith NCE Extension] --> Interceptor[TaskInterceptor]
    Interceptor --> Bus[StateBus]
    Bus --> CRDT[CompositeState\nCRDT Product Lattice]
    Bus --> Barrier[CausalBarrier]
    Bus --> Gossip[GossipProtocol\nAnti-entropy sync]
    CRDT --> TS[TaskStatus\nMonotone Lattice]
    CRDT --> BR[ObservedBeliefRegister\nLWW + ObservationProof]
    CRDT --> CS[CapabilitySet\nOR-Set add-wins]
    Bus --> Recorder[FlightRecorder\nArticle 12 Compliance]

Full solution diagram (Dashboard → API → Simulation → NCE): docs/architecture.md

API

REST + WebSocket backend for the NCE dashboard. See docs/api.md for full reference.

Endpoint	Description
POST /control/*	Start, stop, reset, chaos
POST /simulate	Run baseline (nce, no_sync, full_context, central_coordinator)
WS /ws/simulation	Stream simulation state updates to dashboard

uvicorn api.main:app --port 8000
# OpenAPI: http://localhost:8000/docs

Reproducibility

Reproduce paper benchmark tables (5,000 transactions × 3 seeds, 12 agents, adversarial network):

pip install -e ".[dev]"
make bench-paper

Output: docs/paper/tables/summary.md and CSVs. Python 3.11+. Seeds: 42, 7, 137 (Hypothesis property tests use seed 42).

Related Work

NCE builds on established distributed systems research and differentiates from adjacent tools:

System	CRDT Support	Agent-Aware	A2A Extension	Art.12 Coverage	Delta-sync
Automerge	✓ (document CRDTs)	✗	✗	✗	✓
Yjs	✓ (collaborative editing)	✗	✗	✗	✓
Riak	✓ (database CRDTs)	✗	✗	✗	partial
Ray Actors	✗	✓	✗	✗	✗
LangGraph	✗	✓	✗	✗	✗
NCE	✓ (AS-CRDTs)	✓	✓	✓	✓

NCE's novel contribution is the combination of: (1) CRDT types purpose-designed for agent state semantics (monotone task lifecycle, LWW beliefs with cryptographic provenance, OR-Set capabilities), (2) native Google A2A protocol extension for agent discoverability, and (3) structural Article 12 field coverage as a first-class design constraint. See Shapiro et al. 2011 for foundational CRDT theory.

CRDT Properties

All three CRDT types are property-based validated to satisfy:

• Commutative: merge(a, b) == merge(b, a)
• Associative: merge(merge(a, b), c) == merge(a, merge(b, c))
• Idempotent: merge(a, a) == a

Validated by 15+ Hypothesis property-based tests with 100–200 randomly-generated examples each. Property-based testing provides strong empirical evidence but is not equivalent to a formal mathematical proof (e.g., Coq/TLA+).

Benchmarks

Metric	No Sync	Full Context	Central	NCE
Phantom Commits	271 (5.4%)	0	0	7 (0.1%) ✓
Conv. p99 (ms)¹	N/A	1,053ms	250ms	737ms ✓
Tokens/sync	0	~26,114	~2,128	~697 ✓
Availability	100%	92%	90%	100% ✓
Art.12 Field Coverage²	0%	50%	70%	100% ✓

Mean of 3 independent runs (seeds 42, 7, 137), 5,000 transactions each, 12 agents, 2% partition probability.

¹ Convergence latency is modeled, not measured in-process. The simulation uses synchronous in-process delta sync (which converges in 0 ms). The reported p99 reflects one gossip round at the default 500 ms sync_interval_ms + Gaussian jitter (σ=100 ms), representing expected latency in a deployed NCE cluster. Theoretical O(log n) convergence: for n=12 peers, expected 4 rounds = ~2 s worst-case; p99 ≈ 1.7 s with jitter.

² Article 12 field coverage measures the fraction of EU AI Act Article 12–required fields (reference_database, input_data_match, state_before_hash, state_after_hash, vector_clock, agent_id, timestamp) populated in each ComplianceEvent. This is a structural coverage metric, not a legal compliance certification. Persistence across restarts and conformity-body certification are deployment responsibilities.

Contributing

1. Fork the repo and create a feature branch
2. Run make ci - all 124 tests must pass
3. Add property tests for any new CRDT operations
4. Submit a PR with a description of the change

License

Apache 2.0