nebula-protocol 1.0.0

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).

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 Coverage	0%	50%	70%	100% ✓

Mean of 3 independent runs (seeds 42, 7, 137), 5,000 transactions each.

CRDT Properties

All three CRDT types are mathematically verified to be:

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

Verified by 15+ Hypothesis property-based tests with 100–200 random examples each.

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