Crate asupersync

Expand description

Asupersync: Spec-first, cancel-correct, capability-secure async runtime for Rust.

§Overview

Asupersync is an async runtime built on the principle that correctness should be structural, not conventional. Every task is owned by a region that closes to quiescence. Cancellation is a first-class protocol, not a silent drop. Effects require explicit capabilities.

§Core Guarantees

No orphan tasks: Every spawned task is owned by a region; region close waits for all children
Cancel-correctness: Cancellation is request → drain → finalize, never silent data loss
Bounded cleanup: Cleanup budgets are sufficient conditions, not hopes
No silent drops: Two-phase effects (reserve/commit) prevent data loss
Deterministic testing: Lab runtime with virtual time and deterministic scheduling
Capability security: All effects flow through explicit Cx; no ambient authority

§Module Structure

types: Core types (identifiers, outcomes, budgets, policies)
record: Internal records for tasks, regions, obligations
trace: Tracing infrastructure for deterministic replay
runtime: Scheduler and runtime state
cx: Capability context and scope API
combinator: Join, race, timeout combinators
lab: Deterministic lab runtime for testing
util: Internal utilities (deterministic RNG, arenas)
error: Error types
channel: Two-phase channel primitives (MPSC, etc.)
encoding: RaptorQ encoding pipeline
observability: Structured logging, metrics, and diagnostic context
security: Symbol authentication and security primitives
time: Sleep and timeout primitives for time-based operations
io: Async I/O traits and adapters
net: Async networking primitives (Phase 0: synchronous wrappers)
bytes: Zero-copy buffer types (Bytes, BytesMut, Buf, BufMut)
tracing_compat: Optional tracing integration (requires tracing-integration feature)
plan: Plan DAG IR for join/race/timeout rewrites

§API Stability

Asupersync is currently in the 0.x series. Unless explicitly noted in docs/api_audit.md, public items should be treated as unstable and subject to change. Core types like Cx, Outcome, and Budget are intended to stabilize first.

Re-exports§

pub use config::AdaptiveConfig;
pub use config::BackoffConfig;
pub use config::ConfigError;
pub use config::ConfigLoader;
pub use config::EncodingConfig;
pub use config::PathSelectionStrategy;
pub use config::RaptorQConfig;
pub use config::ResourceConfig;
pub use config::RuntimeProfile;
pub use config::SecurityConfig;
pub use config::TimeoutConfig;
pub use config::TransportConfig;
pub use cx::Cx;
pub use cx::Scope;
pub use decoding::DecodingConfig;
pub use decoding::DecodingError;
pub use decoding::DecodingPipeline;
pub use decoding::DecodingProgress;
pub use decoding::RejectReason;
pub use decoding::SymbolAcceptResult;
pub use encoding::EncodedSymbol;
pub use encoding::EncodingError;
pub use encoding::EncodingPipeline;
pub use encoding::EncodingStats;
pub use epoch::bulkhead_call_in_epoch;
pub use epoch::bulkhead_call_weighted_in_epoch;
pub use epoch::circuit_breaker_call_in_epoch;
pub use epoch::epoch_join2;
pub use epoch::epoch_race2;
pub use epoch::epoch_select;
pub use epoch::BarrierResult;
pub use epoch::BarrierTrigger;
pub use epoch::Epoch;
pub use epoch::EpochBarrier;
pub use epoch::EpochBulkheadError;
pub use epoch::EpochCircuitBreakerError;
pub use epoch::EpochClock;
pub use epoch::EpochConfig;
pub use epoch::EpochContext;
pub use epoch::EpochError;
pub use epoch::EpochId;
pub use epoch::EpochJoin2;
pub use epoch::EpochPolicy;
pub use epoch::EpochRace2;
pub use epoch::EpochScoped;
pub use epoch::EpochSelect;
pub use epoch::EpochSource;
pub use epoch::EpochState;
pub use epoch::EpochTransitionBehavior;
pub use epoch::SymbolValidityWindow;
pub use error::AcquireError;
pub use error::BackoffHint;
pub use error::Error;
pub use error::ErrorCategory;
pub use error::ErrorKind;
pub use error::Recoverability;
pub use error::RecoveryAction;
pub use error::RecvError;
pub use error::Result;
pub use error::ResultExt;
pub use error::SendError;
pub use lab::LabConfig;
pub use lab::LabRuntime;
pub use remote::spawn_remote;
pub use remote::CancelRequest;
pub use remote::CompensationResult;
pub use remote::ComputationName;
pub use remote::DedupDecision;
pub use remote::IdempotencyKey;
pub use remote::IdempotencyRecord;
pub use remote::IdempotencyStore;
pub use remote::Lease;
pub use remote::LeaseError;
pub use remote::LeaseRenewal;
pub use remote::LeaseState;
pub use remote::NodeId;
pub use remote::RemoteCap;
pub use remote::RemoteError;
pub use remote::RemoteHandle;
pub use remote::RemoteMessage;
pub use remote::RemoteOutcome;
pub use remote::RemoteTaskId;
pub use remote::ResultDelivery;
pub use remote::Saga;
pub use remote::SagaState;
pub use remote::SagaStepError;
pub use remote::SpawnAck;
pub use remote::SpawnAckStatus;
pub use remote::SpawnRejectReason;
pub use remote::SpawnRequest;
pub use types::join_outcomes;
pub use types::Budget;
pub use types::CancelKind;
pub use types::CancelReason;
pub use types::ObligationId;
pub use types::Outcome;
pub use types::OutcomeError;
pub use types::PanicPayload;
pub use types::Policy;
pub use types::RegionId;
pub use types::Severity;
pub use types::TaskId;
pub use types::Time;

Modules§

actor: Actor abstraction for region-owned, message-driven concurrency.
app: SPORK Application layer: AppSpec + AppHandle.
audit: Ambient authority audit and hardening.
bytes: Bytes and Buffer Management
cancel: Symbol broadcast cancellation protocol.
channel: Two-phase channel primitives for cancel-safe communication.
cli: CLI utilities for Asupersync tools.
codec: Codec traits, built-in codecs, and framed transport adapters.
combinator: Combinators for structured concurrency.
config: Configuration, tuning, and runtime profiles for the RaptorQ-integrated runtime.
conformance: Conformance testing infrastructure for runtime implementations.
console: Console rendering primitives for terminal diagnostics and debugging.
cx: Capability context and scope API.
decoding: RaptorQ decoding pipeline (Phase 0).
distributed: Distributed region encoding, symbol distribution, and recovery.
encoding: RaptorQ encoding pipeline (Phase 0).
epoch: Epoch model types for time-bounded distributed operations.
error: Error types and error handling strategy for Asupersync.
evidence: Spork Evidence Ledger Schema + Deterministic Rendering (bd-2dfoo)
fs: Async filesystem operations.
gen_server: GenServer: typed request-response and actor-adjacent message loop.
grpc: gRPC protocol implementation.
http: HTTP protocol support for Asupersync.
io: Async I/O traits, adapters, and capability infrastructure.
lab: Deterministic lab runtime for testing.
link: Process links and bidirectional exit signal propagation (Spork).
messaging: Messaging clients for external services (Redis, NATS, Kafka).
migration: Migration path and backward compatibility layer.
monitor: Process monitors and deterministic down notifications.
net: Async networking primitives.
obligation: Obligation analysis: static leak checking, graded types, marking, and contracts.
observability: Comprehensive observability and logging infrastructure.
plan: Plan DAG IR for concurrency combinators.
process: Async child process management.
raptorq: RaptorQ integration layer.
record: Internal records for runtime entities.
remote: Remote task execution via named computations.
runtime: Runtime state and scheduling.
security: Symbol authentication and security infrastructure.
server: Server lifecycle and connection management.
service: Service abstractions and middleware layering.
session: Session types for protocol-safe communication.
signal: Async signal handling and graceful shutdown.
spork: SPORK: OTP-grade supervision, registry, and actor layer for Asupersync.
stream: Async stream processing primitives.
supervision: Supervision policies for actor failure handling.
sync: Synchronization primitives with two-phase semantics.
test_logging: Comprehensive test logging infrastructure for Asupersync.
test_ndjson: NDJSON event schema, trace file naming, and artifact bundle helpers (bd-1t58q).
test_utils: Test utilities for Asupersync.
time: Time primitives: sleep, timeout, and interval operations.
trace: Tracing infrastructure for deterministic replay.
tracing_compat: Tracing compatibility layer for structured logging and spans.
transport: Transport layer abstraction.
types: Core types for the Asupersync runtime.
util: Internal utilities for the Asupersync runtime.
web: Web application framework (axum-like).

Macros§

assert_eq_log: Assert equality, printing the full log on failure.
assert_has_leaks: Assert that an obligation body has exactly the specified number of leaks.
assert_log: Assert a condition, printing the full log on failure.
assert_no_leaks: Assert that an obligation body (or inline builder) has no leaks.
assert_outcome_cancelled: Assert that an outcome is Cancelled.
assert_outcome_err: Assert that an outcome is Err.
assert_outcome_ok: Assert that an outcome is Ok with a specific value.
assert_outcome_panicked: Assert that an outcome is Panicked.
assert_with_context: Assert a condition and, on failure, emit a structured dump with full context.
assert_with_log: Log before assertions for context.
conformance_test: Macro for defining conformance tests.
debug: No-op debug-level logging macro.
debug_span: No-op debug_span macro.
dump_test_failure: Emit a structured error dump with full context for failure triage.
error: No-op error-level logging macro.
error_span: No-op error_span macro.
event: No-op event macro.
first_ok: Tries operations sequentially until one succeeds.
harness_assert: Assert a condition within a TestHarness, recording the result.
harness_assert_eq: Assert equality within a TestHarness, recording the result.
harness_phase: Enter a hierarchical phase in a TestHarness.
harness_phase_exit: Exit the current phase in a TestHarness.
hedge: Macro for hedging an operation (placeholder).
info: No-op info-level logging macro.
info_span: No-op info_span macro.
instrument: No-op instrument attribute (does nothing). This is a placeholder - the actual #[instrument] attribute requires proc-macro.
join: Macro for joining multiple futures (placeholder).
obligation_body: Construct an obligation Body from a concise inline description.
pipeline: Macro for creating a sequential pipeline (placeholder).
quorum: Waits for N of M futures to complete successfully.
race: Macro for racing multiple futures.
retry: Retries an operation with configurable backoff.
span: No-op span macro that returns a NoopSpan.
test_complete: Log test completion with summary.
test_error: Log an error event to a test logger.
test_log: Log a custom event to a test logger.
test_phase: Log a test phase transition with a visual separator.
test_section: Log a section within a test phase.
test_structured: Emit a structured tracing event with standard test context fields.
test_warn: Log a warning event to a test logger.
timeout: Runs a future with a timeout.
trace: No-op trace-level logging macro.
trace_span: No-op trace_span macro.
try_join: Joins multiple futures, short-circuiting on the first error.
warn: No-op warn-level logging macro.
warn_span: No-op warn_span macro.