Pervaxis.Core.Exceptions 1.6.0

Pervaxis.Core.Exceptions

Structured exception handling with a structured exception envelope, compact exception IDs, and domain-specific exception types. Implements Section 15 of the Pervaxis Platform Spec.

Installation

dotnet add package Pervaxis.Core.Exceptions

Registration

builder.Services.AddPervaxisExceptions(options =>
{
    options.ServiceName = "order-service";
    options.Environment = builder.Environment.EnvironmentName;
});

Exception Envelope

Every exception carries a consistent envelope:

Exception Presentation

The package exposes typed contracts for transport-specific rendering:

• IExceptionPresenter
• ExceptionRestProblemDetails
• ExceptionGraphQlError
• ExceptionGrpcStatus

Usage

Infrastructure Exceptions

// Transient - retryable (database connectivity, timeout, etc.)
throw PervaxisInfrastructureException.Transient(
    serviceName, environment,
    customerMessage: "Service is temporarily unavailable. Please retry.",
    technicalDetail: "Connection refused on PostgreSQL port 5432.",
    innerException: ex);

// Critical - requires human intervention
throw PervaxisInfrastructureException.Critical(
    serviceName, environment,
    customerMessage: "A critical platform error occurred.",
    technicalDetail: "Primary database replica set is unreachable.");

Security Exceptions

// Unauthorized - generic customer message, technical detail preserved internally
throw PervaxisSecurityException.Unauthorized(
    serviceName, environment,
    technicalDetail: "JWT expired. iss claim mismatch with tenant abc-123.");

// Forbidden - with tenant/user context for audit
throw PervaxisSecurityException.Forbidden(
    serviceName, environment,
    technicalDetail: "User role=viewer attempted DELETE /tenants/abc.",
    tenantId: tenantId.Value,
    userId: userId.Value);

Agentic Exceptions

// Low confidence - always escalates to human review
throw PervaxisAgenticException.LowConfidence(
    serviceName, environment,
    agentName: "TriageAgent",
    technicalDetail: "Confidence score 0.42, threshold 0.85.");

// Guardrail violation - critical, always requires human intervention
throw PervaxisAgenticException.GuardrailViolation(
    serviceName, environment,
    agentName: "AutomationAgent",
    violatedGuardrail: "no-production-writes",
    technicalDetail: "Attempted DELETE /tenants/abc.");

Factory (DI-integrated)

public class OrderService(IExceptionEnvelopeFactory exceptionFactory)
{
    public void ProcessOrder()
    {
        try { /* ... */ }
        catch (Exception ex)
        {
            var envelope = exceptionFactory.Create(
                ex,
                ExceptionCategory.Domain,
                ExceptionSeverity.Medium,
                customerMessage: "Order processing failed.",
                correlationId: correlationId,
                traceId: traceId);

            throw PervaxisInfrastructureException.From(envelope);
        }
    }
}

Exception ID Format

ex_{Guid:N}[..16]

Example: ex_a1b2c3d4e5f67890

Pervaxis Platform · Clarivex Technologies · https://clarivex.tech