Crate aura_sync 

Aura Sync - Layer 5: Feature/Protocol Implementation

This crate provides complete end-to-end synchronization protocol implementations.

Purpose

Layer 5 feature crate providing reusable protocol building blocks for:

• Journal state synchronization using CRDT semilattice semantics
• Anti-entropy protocols for state reconciliation between peers
• Snapshot creation and restoration for efficient sync initialization
• OTA upgrade coordination with threshold approval
• Receipt verification for distributed protocol commitment

Architecture Constraints

This crate depends on:

• Layer 1 (aura-core): Core types, effects, errors, session management
• Layer 2 (aura-journal): CRDT semantics and fact storage
• Layer 3 (aura-effects): Effect handler implementations
• Layer 4 (aura-protocol): Orchestration and guard chain

What Belongs Here

• Complete protocol implementations (anti-entropy, journal sync, snapshots, OTA, receipts)
• Protocol coordination for multi-party synchronization
• Configuration and policy for sync strategies
• Metrics collection and health monitoring
• Session management for protocol coordination
• Infrastructure utilities (peer management, retry logic, caching, rate limiting)
• MPST protocol definitions for sync ceremonies

What Does NOT Belong Here

• Effect handler implementations (belong in aura-effects)
• Handler composition or registry (belong in aura-composition)
• Low-level multi-party coordination (belong in aura-protocol)
• Journal implementations (belong in aura-journal)
• Storage backend implementations

Design Principles

• All protocols parameterized by effect traits: generic over effect implementations
• Protocols are effect-driven: composition, testing, and deployment flexibility
• CRDT semantics ensure idempotent, convergent synchronization
• Anti-entropy ensures eventual consistency without coordination overhead
• Session-based coordination allows stateless protocol implementation
• Integration with guard chain ensures authorization before synchronization
• Metrics collection enables observability and performance tuning

Authority vs Device Model

This crate uses Aura’s authority-centric identity model:

• AuthorityId: Represents the owner of state and operations. Authorities are cryptographic identities that own journals, create attestations, and authorize actions. State is synchronized per authority, not per device.

• DeviceId: Represents a connection endpoint for network communication. Devices connect to each other to exchange state, but state ownership is always attributed to authorities, not devices.

In sync protocols:

• Peers are identified by DeviceId for network addressing
• Journal operations and facts are attributed to AuthorityId
• Authorization decisions use AuthorityId via Biscuit tokens
• State merges resolve conflicts using authority-attributed timestamps

See docs/102_authority_and_identity.md for the complete authority model.

Time System

This crate uses the unified time system from aura-core:

• PhysicalTime: Wall-clock timestamps with optional uncertainty bounds. Used for timestamps, timeouts, and coordination deadlines.
• All time access goes through PhysicalTimeEffects trait, never direct SystemTime calls
• Time is passed explicitly to methods, enabling deterministic testing

See docs/103_effect_system.md for the unified time architecture.

Usage

use aura_sync::{
    protocols::{AntiEntropyProtocol, JournalSyncProtocol},
    core::{SyncConfig, MetricsCollector, SessionManager},
};
use aura_core::effects::{NetworkEffects, JournalEffects, CryptoEffects};

// Create sync configuration
let config = SyncConfig::for_production();

// Set up metrics collection
let metrics = MetricsCollector::new();

// Create session manager for protocol coordination
let session_manager = SessionManager::new(config.sessions());

// Use protocols with any effect implementation
async fn sync_with_peer<E>(
    effects: &E,
    peer: DeviceId,
) -> SyncResult<()>
where
    E: NetworkEffects + JournalEffects + CryptoEffects,
{
    let protocol = AntiEntropyProtocol::new(&config);
    protocol.sync_with_peer(effects, peer).await
}

Re-exports

pub use core::MetricsCollector;

pub use core::SessionManager;

pub use core::SessionResult;

pub use core::SessionState;

pub use core::SyncConfig;

pub use core::SyncResult;

pub use protocols::WriterFence;

pub use protocols::WriterFenceGuard;

pub use services::maintenance;

pub use verification::MerkleComparison;

pub use verification::MerkleVerifier;

pub use verification::VerificationResult;

pub use verification::VerificationStats;

Modules

capabilities

Typed capability families owned by sync protocols.

core

Core abstractions and unified patterns for sync protocols

infrastructure

Infrastructure utilities for sync operations

integration_docs

Integration documentation and patterns.

protocols

Protocol implementations for synchronization

services

Service layer for sync operations

verification

Verification module for Merkle-based fact verification

Structs

SessionId

Session identifier for protocol sessions and coordination

Enums

AuraError

Unified error type for all Aura operations

Constants

OPERATION_CATEGORIES

Operation category map (A/B/C) for protocol gating and review.

Functions

operation_category

Lookup the operation category (A/B/C) for a given operation.

Type Aliases

AuraResult

Standard Result type for Aura operations