Module error 

M2M Protocol error types with epistemic classification.

Epistemic Error Taxonomy

This module organizes errors by their epistemic nature - what they tell us about the state of knowledge at the time of failure. This classification helps developers understand:

1. Whether the error was predictable (and thus should be handled gracefully)
2. What remediation is appropriate (retry, fail-fast, degrade gracefully)
3. Where defensive code is needed (validation boundaries, I/O edges)

Categories

B_i Falsified (Belief Proven Wrong)

The caller held a belief about validity that was proven false at runtime. These are “expected” errors in the sense that the system was designed to detect and report them. Examples:

• Invalid input format (caller believed input was valid)
• Session not established (caller believed session was ready)
• Capability mismatch (caller believed peers were compatible)

Handling: Validate early, return descriptive errors, don’t retry.

I^B (Bounded Ignorance Materialized)

The system could not know the outcome at compile time - it depends on external state (network, filesystem, RNG, upstream services). These errors represent the inherent uncertainty of distributed systems.

• Network errors (connectivity is I^B until we try)
• Upstream service errors (availability is I^B)
• RNG failures (entropy availability is I^B)

Handling: Timeouts, retries with backoff, circuit breakers, fallbacks.

K_i Violated (Invariant Broken)

A known invariant that “should never happen” was violated. These indicate bugs in the code or corruption. They are NOT expected in normal operation.

• Internal state corruption
• Logic errors (unreachable code reached)

Handling: Log extensively, fail fast, alert operators.

Usage Example

use m2m::error::{M2MError, Result};

fn process_message(session: &Session, data: &[u8]) -> Result<Response> {
    // B_i: Caller believes session is established
    if !session.is_established() {
        return Err(M2MError::SessionNotEstablished);
    }
     
    // B_i: Caller believes data is valid JSON
    let parsed = serde_json::from_slice(data)?;
     
    // I^B: Network availability unknown until we try
    let response = send_upstream(parsed).await?;
     
    Ok(response)
}

Enums

M2MError

M2M Protocol errors, organized by epistemic category.

Type Aliases

Result

Result type alias for M2M operations.