Enum FinalizeError 

#[non_exhaustive]
pub enum FinalizeError {
    Task(JoinError),
    Invariant(String),
    Receipt {
        context: String,
        source: Option<ErrorSource>,
    },
    Atif {
        context: String,
        source: Option<ErrorSource>,
    },
    Promotion(String),
    CaptureIncomplete,
    ToolEvidence(String),
    Bridge {
        context: String,
        source: Option<ErrorSource>,
    },
    BridgeConfig {
        context: String,
        source: Option<ErrorSource>,
    },
}

Lifecycle errors.

Variants that wrap an underlying failure carry it as a typed std::error::Error::source instead of a pre-rendered String, so callers can branch on the concrete cause (e.g. io::ErrorKind) via source().downcast_ref::<std::io::Error>() and tracing subscribers receive the full chain. context keeps the exact text the old String payloads rendered, so Display output (which operators grep and HTTP error bodies embed) is unchanged.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Task(JoinError)

Blocking task failed or panicked.

Invariant(String)

Internal finalization invariant violated (no underlying error exists to attach, e.g. a recovery path found the session still referenced elsewhere). Shares the Task Display prefix so operator log greps for “finalization task failed:” keep matching the messages this variant absorbed from Task.

Receipt

Receipt issuance failed.

Fields

context: String

Human-readable description (Display-compatible with the old Receipt(String) payload).

source: Option<ErrorSource>

Underlying typed error, when one exists.

Atif

ATIF persistence or parsing failed.

Fields

context: String

Human-readable description (Display-compatible with the old Atif(String) payload).

source: Option<ErrorSource>

Underlying typed error, when one exists.

Promotion(String)

Promotion is invalid for this session. Genuinely semantic refusals — there is never an underlying error to attach.

CaptureIncomplete

One or more upstream actions were not captured.

ToolEvidence(String)

Tool evidence is unresolved or temporarily unreadable. Leave the finalization claim retryable without discarding execution evidence.

Bridge

Lifecycle event could not be durably published.

Fields

context: String

Human-readable description (Display-compatible with the old Bridge(String) payload).

source: Option<ErrorSource>

Underlying typed error, when one exists.

BridgeConfig

Lifecycle bridge failed due to a PERMANENT misconfiguration (e.g. BusError::UnknownTopic — the topic was not provisioned via the manifest). SDKs should NOT retry this; the operator must fix the config. Historically this collapsed into Bridge(_) and mapped to HTTP 503 + Retry-After, so clients retried pointlessly. Kept as a distinct variant so finalize_error_response can route it to 400 (no Retry-After) while genuine transient failures keep 503 semantics.

Fields

context: String

Human-readable description (Display-compatible with the old BridgeConfig(String) payload).

source: Option<ErrorSource>

Underlying typed error, when one exists.

Implementations

impl FinalizeError

pub fn receipt(context: impl Into<String>) -> Self

Semantic receipt failure with no underlying typed error.

pub fn receipt_source<E>(error: E) -> Self

where E: Error + Send + Sync + 'static,

Receipt failure caused by a typed error. The error text is kept in context so Display matches the old stringified payload, while the value itself stays reachable via Error::source().

pub fn atif(context: impl Into<String>) -> Self

Semantic ATIF failure with no underlying typed error.

pub fn atif_source<E>(error: E) -> Self

where E: Error + Send + Sync + 'static,

ATIF failure caused by a typed error (see Self::receipt_source).

pub fn bridge(context: impl Into<String>) -> Self

Semantic bridge failure with no underlying typed error.

pub fn bridge_source<E>(error: E) -> Self

where E: Error + Send + Sync + 'static,

Bridge failure caused by a typed error (see Self::receipt_source).

pub fn is_transient_io(&self) -> bool

True iff this error is caused by a transient I/O condition (spool disk full, read-only filesystem, spool storage temporarily unreachable). The response layer maps these to 503 Service Unavailable + Retry-After rather than the default 500 Internal Server Error, matching the /readyz probe policy that already treats ENOSPC/EROFS as transient. Same permanence-split discipline as Bridge vs BridgeConfig.

Walks the source chain via std::error::Error::source so an av_atif::WriteError { source: io::Error } or an av_receipts::SignError { source: io::Error } are both detected regardless of how deep the wrap is.

Trait Implementations

impl Debug for FinalizeError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for FinalizeError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for FinalizeError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<BusError> for FinalizeError

fn from(error: BusError) -> Self

Preserve the permanence classification when converting a bridge error into a Finalize error. Permanent causes (unknown topic, serde) route to BridgeConfig so clients see a 4xx status without Retry-After; transient causes (I/O, backend outage) stay Bridge and keep 503 with Retry-After. The BusError itself is retained as the typed source so its own chain (e.g. io::Error) survives.

impl From<JoinError> for FinalizeError

fn from(source: JoinError) -> Self

Converts to this type from the input type.