Crate aura_agent 

Aura Agent - Layer 6: Runtime Composition

This crate provides runtime composition and effect system assembly for authority-based identity management in the Aura threshold identity platform.

Purpose

Layer 6 runtime composition crate providing:

• Authority-first runtime assembly and lifecycle management
• Effect registry and builder infrastructure
• Context management for multi-threaded agent coordination
• Choreography adapter for protocol execution
• Production, testing, and simulation execution modes

Architecture Constraints

This crate depends on:

• Layer 1-5: All lower layers (core, domain crates, effects, protocols, features)
• MUST NOT: Create new effect implementations (use aura-effects)
• MUST NOT: Implement multi-party coordination (use aura-protocol)
• MUST NOT: Be imported by Layer 1-5 crates (no circular dependencies)

What Belongs Here

• Effect registry and builder infrastructure
• Runtime system composition and lifecycle
• Authority context management and tracking
• Execution mode implementation (production, testing, simulation)
• Choreography protocol adapter for protocol execution
• Receipt and flow budget management
• Public API for agent creation and operation

What Does NOT Belong Here

• Effect handler implementations (belong in aura-effects)
• Effect composition rules (belong in aura-composition)
• Multi-party protocol logic (belong in aura-protocol)
• Feature protocol implementations (belong in Layer 5 crates)
• Testing harnesses and fixtures (belong in aura-testkit)

Design Principles

• Authority-first design: all operations scoped to specific authorities
• Lazy composition: effects are assembled on-demand, not eagerly
• Stateless handlers: runtime delegates state to journals and contexts
• Mode-aware execution: production, testing, and simulation use same API
• Lifecycle management: resource cleanup and graceful shutdown
• Zero coupling to Layer 5: runtime is agnostic to specific protocols

Key Components

• AgentBuilder: Fluent API for composing agents with authority context
• EffectRegistry: Dynamic registry of available effect handlers
• EffectSystemBuilder: Assembly infrastructure for effect combinations
• AuraAgent: Public API for agent operations
• RuntimeSystem: Internal runtime coordination

Usage

use aura_agent::{AgentBuilder, AuthorityId};

// Production agent with authority-first design
let agent = AgentBuilder::new()
    .with_authority(authority_id)
    .build_production()
    .await?;

// Testing agent
let agent = AgentBuilder::new()
    .with_authority(authority_id)
    .build_testing()?;

Re-exports

pub use core::AgentBuilder;

pub use core::AgentConfig;

pub use core::AgentError;

pub use core::AgentResult;

pub use core::AuraAgent;

pub use core::AuthorityContext;

pub use builder::BuildError;

pub use builder::CliPresetBuilder;

pub use builder::CustomPresetBuilder;

pub use handlers::SessionHandle;

pub use handlers::SessionServiceApi;

pub use handlers::SessionStats;

pub use handlers::AuthChallenge;

pub use handlers::AuthMethod;

pub use handlers::AuthResponse;

pub use handlers::AuthResult;

pub use handlers::AuthServiceApi;

pub use handlers::AuthenticationStatus;

pub use handlers::InvitationResult;

pub use handlers::InvitationServiceApi;

pub use handlers::GuardianApproval;

pub use handlers::RecoveryOperation;

pub use handlers::RecoveryRequest;

pub use handlers::RecoveryResult;

pub use handlers::RecoveryServiceApi;

pub use handlers::RecoveryState;

pub use handlers::ChannelResult;

pub use handlers::RendezvousHandler;

pub use handlers::RendezvousResult;

pub use handlers::RendezvousServiceApi;

pub use fact_registry::build_fact_registry;

Modules

adaptive_privacy_control

Telltale-native adaptive-privacy control-plane choreographies.

builder

Runtime Builder System

core

Layer 6: Agent Public API - Builder, Config, Context, Errors

database

Indexed Journal Handler - B-tree indexes, Bloom filters, and Merkle trees

fact_registry

Domain Fact Registry

fact_types

Central registry of domain fact type identifiers.

handlers

Agent Handlers - Domain-Specific Effect Handlers

reactive

Reactive Programming Infrastructure

Structs

AccountabilityWitness

Runtime-local accountability witness shape.

AuraChoreoEngine

VM-backed choreography engine with explicit session lifecycle hooks.

AuraEffectSystem

Concrete effect system combining all effects for runtime usage

AuraEnvelopeParityPolicy

Aura policy for admissible cross-runtime envelope differences.

AuraHandlerAdapter

Adapter for choreography integration

AuraProtocolAdapter

Runtime adapter used by generated Aura choreography runners.

AuraVmEffectHandler

Deterministic VM host effect handler for Aura integration work.

AuraVmProtocolExecutionPolicy

Canonical VM execution policy bound to one Aura protocol class.

AuraVmRuntimeSelector

Concrete runtime-selection input for one admitted protocol fragment.

AuraVmSchedulerControlInput

Host-side scheduler selection input for one admitted VM session.

AuraVmSchedulerExecutionPolicy

Canonical scheduler decision selected by the host for one VM session.

AuthorityId

Authority identifier - primary identifier for authorities in the new model

BootstrapBrokerConfig

Broker configuration for mixed native/browser bootstrap discovery.

ContextId

Context identifier for RelationalContexts

CoverTrafficGenerator

CoverTrafficGeneratorConfig

EffectContext

Operation-scoped context threaded through effectful calls.

EffectExecutor

Executor for effect operations

EffectOperation

Typed operation identifier for registry keys.

EffectRegistry

Dynamic registry for effect handlers

EffectSystemBuilder

Authority-first runtime system builder

EffectTraceBundle

Fault-aware effect trace bundle used for replay/debug artifacts.

EffectTraceCapture

Trace-capture utility with canonicalization + granularity filtering.

EffectTraceCaptureOptions

Capture options used by EffectTraceCapture.

FlowBudgetManager

Flow budget manager service

HoldBudgetSnapshot

Provider-budget snapshot updated only after witness verification.

HoldDepositOutcome

Result of a hold deposit.

HoldGcOutcome

Result of local hold GC.

HoldLocalIndexEntry

Runtime-local local-index projection kept separate from held objects.

HoldManager

Actor-owned shared hold substrate.

HoldManagerConfig

Configuration for the shared Hold substrate.

HoldProjection

Summary projection for hold runtime state.

HoldRetrievalOutcome

Result of a hold retrieval.

HoldSelectionPlan

Result of holder selection under bounded residency.

HoldSyncBatch

Sync-blended retrieval/reply window.

Invitation

Cached invitation record

LifecycleManager

Lifecycle manager for coordinating system startup and shutdown

LocalHealthObserver

LocalHealthObserverConfig

MessageRequest

Request passed to dynamic message providers.

OperationSessionId

Operation-scoped session identity for EffectContext.

QueuedAccountabilityReply

Queue entry for sync-blended accountability replies.

QueuedSyncRetrieval

Queue entry for sync-blended retrieval.

ReceiptManager

Receipt manager service

ReceivedMessage

Metadata captured for received choreography messages.

ReconfigurationManager

Runtime-owned reconfiguration state and lifecycle methods.

RendezvousManager

Manager for rendezvous operations

RendezvousManagerConfig

Configuration for the rendezvous service manager

RuntimeChoreographySessionId

Runtime choreography session identity bound to one active protocol execution.

RuntimeServiceContext

Shared runtime context provided to services during lifecycle operations.

SelectionManager

SelectionManagerConfig

ServiceError

Error from a service operation

SessionDelegationOutcome

Typed result for one successful runtime delegation.

SessionDelegationTransfer

Typed runtime delegation request for one session ownership transfer.

SessionId

Session identifier for protocol sessions and coordination

SharedTransport

Shared transport state for multi-agent simulations.

SocialManager

Manager for social topology and related services

SocialManagerConfig

Configuration for the social topology manager

SyncManagerConfig

Configuration for the sync service manager

SyncServiceManager

Manager for background journal synchronization

TaskSupervisor

ThresholdSigningService

Unified service for all threshold signing operations

VerifiedServiceWitness

Verified witness token required before local budget or scoring changes.

Enums

AccountabilityWitnessKind

Witness kinds handled by the hold/runtime accountability path.

AuraChoreoEngineError

Errors raised by AuraChoreoEngine.

AuraEffectTraceEncoding

Trace payload encoding for persisted replay artifacts.

AuraEffectTraceGranularity

Capture granularity mapped to Telltale protocol-machine capture modes.

AuraEnvelopeParityError

Validation error for AuraEnvelopeParityPolicy.

AuraVmDeterminismProfileError

Determinism profile parse/validation error.

AuraVmEffectEvent

Structured event emitted by AuraVmEffectHandler for debugging/replay hooks.

AuraVmGuardLayer

Typed guard-layer identifiers reserved by Aura runtime profiles.

AuraVmHardeningProfile

Profile-level VM hardening in Aura runtime contexts.

AuraVmParityProfile

Cross-target parity lane profile.

AuraVmRuntimeMode

Host-selected runtime execution mode for one admitted protocol.

AuraVmSchedulerEnvelopeClass

Scheduler envelope class declared by Aura for one protocol runtime mode.

CoherenceStatus

Coherence result for session footprints.

EffectRegistryError

Errors that can occur during registry operations

EffectTraceCaptureError

File/serialization errors from trace capture and replay tooling.

EffectType

Typed effect categories for registry keys.

ExecutionMode

Execution mode controlling effect handler selection across all system layers

HoldRetrievalStatus

Retrieval result classification.

InvitationStatus

Invitation status

InvitationType

Type of invitation

ReconfigurationError

Reconfiguration controller errors.

ReconfigurationManagerError

Typed runtime errors for reconfiguration and delegation.

RuntimeShutdownError

ServiceErrorKind

Error kinds for service operations

ServiceHealth

Health status of a runtime service

SessionFootprintClass

Target footprint class for lifecycle session updates.

SessionOwnerCapabilityScope

Scope granted to one current runtime session owner capability.

SocialManagerState

State of the social manager

SyncManagerState

State of the sync service manager

VerifierRole

Explicit verifier roles for accountability consequences.

Constants

AURA_OUTPUT_PREDICATE_CHOICE

Output predicate used for choice/branch visibility.

AURA_OUTPUT_PREDICATE_GUARD_ACQUIRE

Output predicate used for guard acquire visibility.

AURA_OUTPUT_PREDICATE_GUARD_RELEASE

Output predicate used for guard release visibility.

AURA_OUTPUT_PREDICATE_OBSERVABLE

Default output predicate when no operation-specific hint is provided.

AURA_OUTPUT_PREDICATE_STEP

Output predicate used for invoke/step visibility.

AURA_OUTPUT_PREDICATE_TRANSPORT_RECV

Output predicate used for transport receive visibility.

AURA_OUTPUT_PREDICATE_TRANSPORT_SEND

Output predicate used for transport send visibility.

AURA_VM_POLICY_CONSENSUS_FALLBACK

Production determinism policy reference for consensus fallback protocols.

AURA_VM_POLICY_CONSENSUS_FAST_PATH

Production determinism policy reference for consensus fast-path protocols.

AURA_VM_POLICY_DKG_CEREMONY

Production determinism policy reference for DKG protocols.

AURA_VM_POLICY_PROD_DEFAULT

Production determinism policy reference for generic short-running protocols.

AURA_VM_POLICY_RECOVERY_GRANT

Production determinism policy reference for recovery-grant style protocols.

AURA_VM_POLICY_SYNC_ANTI_ENTROPY

Production determinism policy reference for sync/anti-entropy protocols.

AURA_VM_SCHED_PRIORITY_AGING

Scheduler policy reference for contention/budget-constrained workloads.

AURA_VM_SCHED_PROGRESS_AWARE

Scheduler policy reference for token-biased heavy workloads.

AURA_VM_SCHED_ROUND_ROBIN

Scheduler policy reference for fair low-pressure workloads.

CHOREO_BACKEND

Selected choreography backend label.

Traits

AuraVmSchedulerSignalsProvider

Host handlers that can surface scheduler-control signals at admission time.

EffectRegistryExt

Extension trait for EffectRegistry with convenience methods

RuntimeService

Trait for runtime services with unified lifecycle management

Functions

apply_protocol_execution_policy

Apply the selected protocol execution policy onto a VM config.

apply_scheduler_execution_policy

Apply the selected scheduler execution policy onto a VM config.

aura_flow_policy_predicate

Serializable flow-policy predicate for Aura role/category constraints.

aura_output_predicate_allow_list

Output predicates accepted by Aura hardening policies.

build_envelope_diff_artifact_for_policy

Build an envelope diff artifact from cooperative and threaded replay fragments.

build_vm_config

Build a VM config with explicit hardening and parity profiles.

configured_guard_capacity

Effective guard capacity available in this VM config.

create_production_agent

Create a production agent (convenience function)

create_simulation_agent

Create a simulation agent (convenience function)

create_testing_agent

Create a testing agent (convenience function)

parse_communication_replay_mode

Parse CommunicationReplayMode from a stable textual identifier.

parse_determinism_mode

Parse DeterminismMode from a stable textual identifier.

parse_effect_determinism_tier

Parse EffectDeterminismTier from a stable textual identifier.

policy_for_protocol

Canonical execution policy for one protocol id plus optional manifest selector.

policy_for_ref

Canonical execution policy for one stable policy selector.

policy_requires_envelope_artifact

Whether the selected policy requires an envelope-diff artifact.

required_runtime_capabilities_for_policy

Derived runtime capabilities required by the selected runtime mode.

scheduler_control_input_for_image

Compute scheduler-selection input for one admitted code image.

scheduler_control_input_for_protocol_machine_image

Compute scheduler-selection input for one admitted protocol-machine code image.

scheduler_policy_for_input

Canonical scheduler policy for one admitted session.

scheduler_policy_ref

Stable textual identifier for one scheduler policy.

validate_determinism_profile

Validate determinism/profile requirements encoded in VM config.

validate_envelope_artifact_for_policy

Validate that an envelope artifact stays within the policy-defined runtime envelope.

validate_protocol_execution_policy

Validate that a VM config matches the selected protocol execution policy.

validate_scheduler_execution_policy

Validate that a VM config matches the selected scheduler execution policy.

vm_config_for_profile

Build a VM config from hardening profile only.

Type Aliases

AuraVmSchedulerSignals

Runtime signals that influence scheduler selection without bypassing the VM scheduler.

ServiceRegistry