Crate aura_effects

Expand description

§Aura Effects - Layer 3: Implementation (Stateless Effect Handlers)

Purpose: Production-grade stateless effect handlers that delegate to OS services.

This crate provides the Implementation Layer of the Aura architecture, containing context-free, single-operation effect handlers that work in ANY execution context (production, testing, simulation, choreographic).

§Architecture Constraints

Layer 3 depends only on aura-core and external libraries (foundation + libraries).

MUST implement infrastructure effect traits defined in aura-core
MUST be stateless (no shared mutable state between calls)
MUST be single-party (each handler works independently)
MUST be context-free (no assumptions about caller’s context)
MUST NOT depend on other Aura crates (domain crates, aura-protocol, etc.)
MUST NOT do multi-handler coordination
MUST NOT do multi-party protocol logic

§Stateful Boundary (compile-fail example)

Handlers in Layer 3 are stateless. Stateful caches belong in Layer 6 services.

use std::sync::RwLock;

struct BadHandler {
    cache: RwLock<Vec<u8>>,
}

compile_error!("Stateful caches must live in Layer 6 handlers, not aura-effects.");

§Required Infrastructure Effects

This crate MUST provide handlers for:

CryptoEffects: Ed25519 signing, hashing, key derivation
NetworkEffects: TCP connections, message sending
StorageEffects: File I/O, chunk operations
TimeEffects: Current time, delays
RandomEffects: Cryptographically secure randomness

§What Belongs Here

Basic effect implementations (RealCryptoHandler, ProductionLeakageHandler) Storage backends (FilesystemStorageHandler, EncryptedStorage) Network transports (TcpTransportHandler, WebSocketTransportHandler) Time providers (RealTimeHandler), System handlers (LoggingSystemHandler)

§What Does NOT Belong Here

✗ Multi-handler coordination (→ aura-protocol) ✗ Choreographic bridges (→ aura-protocol) ✗ Stateful orchestration (→ aura-protocol) ✗ Complete protocols (→ feature crates)

§Usage

use aura_effects::crypto::RealCryptoHandler;
use aura_effects::storage::FilesystemStorageHandler;
use aura_core::effects::{CryptoEffects, StorageEffects};

// Use handlers directly for single operations
let crypto = RealCryptoHandler::new();
let signature = crypto.sign(&key, &message).await?;

// Or compose into a runtime (done by aura-agent or aura-protocol)
let runtime = EffectSystemBuilder::production()
    .with_crypto(crypto)
    .with_storage(storage)
    .build();

Re-exports§

pub use crate::storage::FilesystemStorageHandler;
pub use biometric::FallbackBiometricHandler;
pub use console::RealConsoleHandler;
pub use context::StandardContextHandler;
pub use crypto::RealCryptoHandler;
pub use database::query::AuraQuery;
pub use database::query::FactTerm;
pub use database::query::QueryError;
pub use database::query::QueryResult;
pub use encrypted_storage::EncryptedStorage;
pub use encrypted_storage::EncryptedStorageConfig;
pub use error::Layer3Error;
pub use guard_interpreter::ProductionEffectInterpreter;
pub use identifiers::new_account_id;
pub use identifiers::new_authority_id;
pub use identifiers::new_context_id;
pub use identifiers::new_device_id;
pub use identifiers::new_event_id;
pub use identifiers::new_guardian_id;
pub use identifiers::new_operation_id;
pub use identifiers::new_session_id;
pub use leakage::ProductionLeakageHandler;
pub use network_monitor::NetworkMonitorHandler;
pub use noise::RealNoiseHandler;
pub use query::format_rule;
pub use query::format_value;
pub use query::parse_arg_to_value;
pub use query::parse_fact_to_row;
pub use query::CapabilityPolicy;
pub use query::QueryHandler;
pub use random::RealRandomHandler;
pub use reactive::ReactiveHandler;
pub use reactive::SignalGraph;
pub use reactive::SignalGraphStats;
pub use route_crypto::RealRouteCryptoHandler;
pub use runtime_capability::RuntimeCapabilityHandler;
pub use secure::RealSecureStorageHandler;
pub use time::LogicalClockHandler;Deprecated
pub use time::OrderClockHandler;
pub use time::PhysicalTimeHandler;
pub use time::TimeComparisonHandler;
pub use udp::RealUdpEffectsHandler;
pub use system::LoggingSystemHandler;
pub use system::MetricsSystemHandler;
pub use system::MonitoringSystemHandler;
pub use transport_effects::FramingHandler;
pub use transport_effects::RealTransportHandler;
pub use transport_effects::TcpTransportHandler;
pub use transport_effects::TransportError;
pub use transport_effects::WebSocketTransportHandler;

Modules§

agent: Agent-Specific Effect Traits
amp: AMP channel lifecycle effect traits (Layer 1 interface)
authority: Authority Effects Trait
authorization: Authorization Effects
availability: Layer 1: Data Availability Effect Trait Definitions
biometric: Layer 3: Biometric Authentication Effect Handlers
bloom: Bloom Filter Data Structures
capability: Capability Token Effects Trait Definitions
choreographic: Choreographic effect interface
console: Console effect handlers
context: Context propagation handlers
crypto: Cryptographic effect handlers for signing, verification, and key derivation Cryptographic Effect Handlers
database: Indexed journal handler with B-tree indexes, Bloom filters, and Merkle trees Query Layer - Datalog queries using Biscuit’s engine
encrypted_storage: Unified encrypted storage wrapper for transparent encryption at rest Layer 3: Unified Encrypted Storage Handler
error: Error types for Layer 3 handler implementations. Error types for Layer 3 effect handlers.
fact: Fact Effect Traits
flood: Layer 1: Rendezvous Flooding Effect Trait Definitions
flow: Layer 1: Flow Budget Effect Trait Definitions
guard: Pure guard evaluation with effect commands
guard_interpreter: Guard Effect Interpreter
guardian: Guardian relationship effect trait
identifiers: Effect-backed identifier generation helpers.
indexed: Indexed Journal Effects - Extension trait for efficient fact lookups
intent: Intent Effect Traits
journal: Journal effect interface for CRDT operations
leakage: Layer 3: Leakage Effect Handlers
ledger: Effect API interface
network: Network effects trait definitions
network_monitor: Debounced network-change monitoring handler.
noise: Noise Protocol Implementation
query: Query Effect Handler
random: Random effect handlers
reactive: Reactive Effect Handlers
registry: Canonical operation mappings for effect types.
relay: Layer 1: Relay Selection Effect Trait Definitions
reliability: Reliability Effects
route_crypto: Route-layer hop crypto implementation.
runtime_capability: Runtime capability inventory handler.
secure: Layer 3: Secure Storage Effect Handlers - Production Only
storage: Layer 3: Storage Effect Handlers - Production Only
supertraits: Sealed supertraits for common effect combinations
sync: Sync Metrics - Shared types for synchronization operations
system: Layer 3: System Effect Handlers - Logging, Metrics, Monitoring
task: Runtime-agnostic task spawning traits.
terminal: Terminal effect interface for deterministic TUI/CLI testing
threshold: Threshold Signing Effects
time: Domain time handlers (Layer 3).
trace: Trace effect handler implementations.
transport: Layer 3: Transport Effect Handlers - Production Only
transport_effects: Transport effect implementations - Layer 3 stateless handlers
tree: Tree Operations Effects for Commitment Tree Operations
udp: UDP effect handlers (Layer 3)
vm_bridge: Session-local bridge effects for the Aura and Telltale runtime boundary.

Structs§

AgentHealthStatus: Agent health status information
AmpCiphertext: Result of a send operation (ciphertext + header)
AmpHeader: AMP message header (additional authenticated data)
AuthenticationResult: Authentication result from device unlock
AuthorizationDecision: Authorization decision result
BiometricCapability: Information about available biometric capabilities
BiometricConfig: Configuration for biometric enrollment and verification
BiometricEnrollmentResult: Result of biometric enrollment operation
BiometricStatistics: Statistics about biometric authentication usage
BiometricVerificationResult: Result of biometric verification operation
BloomConfig: Configuration for Bloom filter parameters
BloomFilter: Bloom filter data structure
CapabilityConfig: Configuration for capability token operations
CapabilityKey: Stable key for a runtime capability contract.
CapabilityStatistics: Statistics about capability token usage
CapabilityTokenInfo: Information about a capability token
CapabilityTokenRequest: Capability token creation request
CapabilityVerificationResult: Result of capability token verification
Cell: A single cell in the terminal
ChannelCloseParams: Channel close parameters
ChannelCreateParams: Optional parameters for channel creation
ChannelJoinParams: Channel join parameters
ChannelLeaveParams: Channel leave parameters
ChannelSendParams: Send parameters (plaintext provided by caller)
CheckpointInfo: Information about a checkpoint
ChoreographicRole: Role in a choreographic protocol
ChoreographyMetrics: Performance metrics for choreography execution
ConfigValidationError: Configuration validation error
CredentialBackup: Credential backup structure
CursorPosition: Cursor position and state
Cut: Defines a cut point for snapshotting (effect interface version)
DeviceConfig: Device configuration structure
DeviceInfo: Device information structure
EffectContext: Operation-scoped context threaded through effectful calls.
FactId: A fact identifier for indexing purposes.
FloodBudget: Budget for rendezvous packet flooding.
FlowBudgetView: Read-only view of flow budgets
FlowHint: Hint describing which flow bucket should be charged before a send.
GuardOutcome: Outcome of pure guard evaluation
GuardSnapshot: Immutable snapshot of state for pure guard evaluation
GuardianAcceptInput: Consensus inputs required to finalize a guardian binding
GuardianRequestInput: Input for requesting or cancelling a guardian relationship
HandshakeState: Opaque wrapper for implementation-specific handshake state (e.g., snow::HandshakeState)
IndexStats: Statistics about the journal index.
IndexedFact: An indexed fact entry containing both the key and value.
JournalEntry: Journal entry for effect commands
KeyEvent: Keyboard event
LayeredBudget: Layered budget for the progressive disclosure model.
LeakageBudget: Leakage budget state
LeakageEvent: Leakage event for privacy tracking
MetadataView: Read-only view of metadata
Modifiers: Key modifiers (bitflags-style)
MouseEvent: Mouse event
NetworkAddress: Network address for peer communication
NetworkChange: Network change signal with monotonic generation.
NoiseParams: Parameters for initializing a Noise handshake
Partial: Partial signature share for snapshot approval (effect interface version)
ProposalId: Unique identifier for a snapshot proposal.
QuerySubscription: A subscription to query results that updates when facts change.
RateLimit: Rate limit for a specific context
RateLimitConfig: Rate limiter configuration
RateLimiter: Rate limiter for operations
RateLimiterStatistics: Rate limiter statistics
RelayCandidate: A candidate relay peer.
RelayContext: Context for relay selection decisions.
RendezvousPacket: Rendezvous packet for flooding through the network.
RetryContext: Context for tracking retry state
RetryPolicy: Retry policy configuration
RetryResult: Result of a retry operation with statistics
RouteHopKeyMaterial: Per-hop route-layer key material.
SecureStorageLocation: Location within secure storage
SessionHandle: Session handle for ongoing operations
SessionInfo: Session information
SessionMessage: Message within a session
Signal: A typed signal representing a time-varying value.
SignalId: Unique identifier for a signal.
SignalStream: A stream of signal value changes.
Snapshot: Immutable snapshot containing compacted tree state (effect interface version)
StorageLocation: Storage location wrapper (kept for backwards compatibility)
StorageStats: Storage statistics
Style: Text style modifiers (bitflags-style)
SyncMetrics: Metrics returned from a sync operation
TemporalFact: A fact with temporal metadata for query results.
TerminalFrame: A captured terminal frame - the output of a render cycle
TraceEvent: Structured trace event payload.
TraceSpanId: Opaque span identifier returned from trace_span.
TransportEnvelope: Envelope containing the actual message data and metadata for transport
TransportReceipt: Receipt produced by successful guard chain execution
TransportState: Opaque wrapper for implementation-specific transport state (e.g., snow::TransportState)
TransportStats: Statistics about transport layer operations
UdpEndpoint: Opaque UDP endpoint wrapper to keep core effects runtime-agnostic.
VmBridgeBlockedEdge: One blocked receive edge observed at the synchronous VM boundary.
VmBridgeLeaseMetadataSnapshot: Snapshot of lease-related metadata visible at the bridge boundary.
VmBridgePendingSend: One pending outbound send emitted by the synchronous VM boundary.
VmBridgeSchedulerSignals: Host-visible scheduler pressure and contention signals for one VM fragment.
VmBridgeTransferMetadataSnapshot: Snapshot of transfer-related metadata visible at the bridge boundary.

Enums§

AdaptiveMode: Adaptive rate limiting mode
AdmissionError: Admission errors for theorem-pack/runtime capability checks.
AmpChannelError: AMP channel error
AuraError: Unified error type for all Aura operations
AuthMethod: Available authentication methods
AuthorizationError: Errors that can occur during authorization operations
AuthorizationLevel: Authorization levels for intent dispatch.
AvailabilityError: Error type for data availability operations.
BackoffStrategy: Backoff strategy for retry delays
BiometricSecurityLevel: Security level classification for biometric authentication
BiometricType: Types of biometric authentication supported
CapabilityTokenFormat: Types of capability token formats supported
ChoreographyError: Choreography-related errors
ChoreographyEvent: Choreography events for debugging and visualization
Color: Terminal colors
ConfigError: Configuration operation error
CursorShape: Cursor shape
Decision: Decision from guard evaluation
EffectApiError: Effect API-related errors
EffectApiEvent: Effect API events
EffectCommand: Minimal, domain-agnostic effect commands
EffectType: Effect type enumeration for all effects in the Aura system
ExecutionMode: Execution mode controlling effect handler selection across all system layers
FactError: Error type for fact operations
FloodAction: Action to take after receiving a flooded packet.
FloodError: Error type for flood operations.
HealthStatus
IntentDispatchError: Base error type for intent dispatch.
JitterMode: Jitter mode for retry delays
KeyCode: Key code - matches crossterm/iocraft key codes
KeyEventKind: Key event kind
MouseButton: Mouse button
MouseEventKind: Mouse event kind
NetworkError: Network operation errors
NetworkUsability: Network usability signal emitted by platform monitors.
ObserverClass: Observer classes for privacy leakage analysis
PeerEvent: Peer connection events
RateLimitResult: Result of a rate limit check
ReactiveError: Error type for reactive operations.
RelayError: Error type for relay operations.
RelayRelationship: How we know a potential relay peer.
ReliabilityError: Errors that can occur during reliability operations
SecureStorageCapability: Capabilities required for secure storage operations
SessionRole: Role in a session
SessionStatus: Session status
SessionType: Types of sessions the agent can participate in
SimulationEvent: Simulation events for deterministic replay
StorageError: Storage operation errors
SystemError: System effect operations error
TerminalError: Terminal operation error
TerminalEvent: Terminal event - the input to the TUI state machine
TimeError: Error type for time operations.
TokenStatus: Status of a capability token
VerificationLevel: Capability token verification level
WakeCondition: Wake conditions for cooperative scheduling.

Traits§

AgentEffects: High-level agent effects that compose core system capabilities into device-specific workflows
AmpChannelEffects
AntiEntropyEffects: Sealed supertrait for anti-entropy synchronization
AuthenticationEffects: Authentication effects for device unlock and biometric operations
AuthorityEffects: Effect trait for authority management operations
AuthorityRelationalEffects: Combined authority and relational effects
AuthorizationEffects: Authorization operations for capability-based access control
BiometricEffects: Biometric effects interface
BiscuitAuthorizationEffects: Biscuit token-based authorization effects
CapabilityEffects: Capability token effects interface
ChoreographicEffects: Choreographic effects for distributed protocol coordination
ChoreographyEffects: Sealed supertrait for choreography coordination
ConfigurationEffects: Configuration management effects for device settings
ConsoleEffects: Pure trait for console/logging operations
CrdtEffects: Sealed supertrait for CRDT synchronization operations
CryptoCoreEffects: Core cryptographic effects interface
CryptoEffects: Combined cryptographic effects surface (core + extended).
CryptoExtendedEffects: Optional cryptographic effects that build on the core interface.
DataAvailability: Effect trait for data availability within a replication unit.
DeviceStorageEffects: Device-specific secure storage effects that enhance core storage with biometric protection and device-specific security features
EffectApiEffects: Effect API effects for event sourcing and audit trails
EffectInterpreter: Asynchronous effect interpreter trait
FactEffects: Effects for temporal database mutations.
FlowBudgetEffects: Effect trait for flow budget management operations.
GuardianEffects
IndexedJournalEffects: Extension trait for indexed journal lookups.
IntentEffects: Effect trait for dispatching intents.
IntentMetadata: Metadata about an intent for authorization and auditing.
JournalEffects: Pure trait for journal/CRDT operations
LeakageChoreographyExt: Extension trait for choreography integration
LeakageEffects: Effect trait for leakage tracking
LogicalClockEffects
MinimalEffects: Sealed supertrait for minimal effect operations
NetworkChangeEffects: Optional network change subscription surface.
NetworkChangeStream: Runtime-agnostic stream of network change notifications.
NetworkCoreEffects: Core network effects interface for communication operations.
NetworkEffects: Combined network effects surface (core + extended).
NetworkExtendedEffects: Optional network effects that build on the core interface.
NoiseEffects: Noise Protocol Effects Trait
OrderClockEffects
PhysicalTimeEffects
QueryEffects: Effects for executing typed Datalog queries.
RandomCoreEffects: Core random effects for generating random values.
RandomEffects: Combined random effects surface (core + extended).
RandomExtendedEffects: Optional random effects that build on the core RNG.
ReactiveDeriveEffects: Extension trait for derived signals.
ReactiveEffects: Reactive effects for FRP-style state management.
RelationalEffects: Effect trait for relational context operations
RelaySelector: Strategy for selecting relay nodes.
ReliabilityEffects: Reliability operations for fault tolerance and graceful degradation
RendezvousFlooder: Effect trait for rendezvous packet flooding.
RouteCryptoEffects: Stateless route-layer hop cryptography.
RuntimeCapabilityEffects: Runtime capability query/admission interface.
SecureStorageEffects: Secure storage effects interface
SessionManagementEffects: Session management effects for device-side session coordination
SigningEffects: Sealed supertrait for FROST threshold signing operations
SimpleIntentEffects: Simplified intent effects trait with a fixed error type.
SnapshotEffects: Sealed supertrait for snapshot coordination
StorageCoreEffects: Core storage effects interface for key-value operations.
StorageEffects: Combined storage effects surface (core + extended).
StorageExtendedEffects: Optional storage effects that build on core storage.
SystemEffects: System effects interface for logging, monitoring, and configuration
TerminalEffects: Combined terminal effects
TerminalInputEffects: Terminal input effects - abstracts reading events from terminal
TerminalOutputEffects: Terminal output effects - abstracts rendering to terminal
ThresholdSigningEffects: Threshold signing effects interface
TimeComparison
TimeEffects: Convenience trait for common timestamp accessors.
TraceEffects
TransportEffects: Transport effects trait for network packet emission
TreeEffects: Sealed supertrait for tree operations
TreeOperationEffects: Tree operations effect interface
UdpEffects: UDP effect surface for binding sockets.
UdpEndpointEffects: UDP endpoint operations for Aura effects.
VmBridgeEffects: Synchronous session-local bridge operations used by the Telltale host boundary.

Type Aliases§

BiometricError: Biometric authentication operation error
BloomError: Bloom filter operation error
CapabilityError: Capability token operation error
CryptoError: Cryptographic operation error
EffectApiEventStream: Stream of effect_api events
NoiseError: Error type for Noise operations
PeerEventStream: Stream type for peer connection events
PublicKeyPackage: Public key package bytes (serialized FROST group public key)
RouteCryptoError: Error type for route-layer cryptographic operations.
SecureStorageError: Secure storage operation error
ThresholdSigningError: Threshold signing operation error
TimeoutHandle: Handle for timeout operations.