Error Recovery System

The error recovery system provides a centralized, event-driven mechanism for handling domain exceptions while cleanly separating backend logic from frontend orchestration.

Exceptions are not propagated directly to the UI. Instead, they are:

  1. Modeled as domain exceptions

  2. Published as events

  3. Routed through a recovery service

  4. Interpreted and acted upon by discrete handlers

This architecture allows recovery policy to remain flexible and contextual.

Core Concepts

This system distinguishes workflow semantics from severity policy.

Workflow Classification

Exceptions are classified by whether the system can continue pursuing the current user goal.

  • RecoverableError The application must execute additional workflow in order to continue toward the same user goal.

  • NonRecoverableError The current workflow stops immediately. The user must re-initiate the action, even if the error itself is user-correctable.

Architecture Overview

Components:

  • TaviError - Base exception for all domain errors

  • RecoverableError - Requires additional system workflow

  • NonRecoverableError - Stops the current workflow

  • ExceptionEvent - Event wrapper for exceptions

  • RecoveryService - Central exception router

  • ErrorPresenter - Frontend error orchestration

  • TaviMessageBox - UI dialog wrapper

Flow:

Exception → ExceptionEvent → RecoveryService → handler → frontend/backend action

Exception Hierarchy

TaviError

Base class for all framework-level exceptions.

Attributes:

  • message - User-facing description

  • stack_trace - Captured traceback

Implements __deepcopy__ for safe event propagation.

All exceptions participating in recovery must inherit from TaviError.

RecoverableError

Represents an error where the application can continue toward the same user goal by executing additional workflow.

Examples:

  • Refreshing expired credentials

  • Resolving a missing dependency

  • Retrying a transient failure

  • Requesting additional information required to proceed

NonRecoverableError

Represents an error that stops the current workflow immediately.

Examples:

  • Validation failures

  • Invalid user input

  • Business rule violations

  • Preconditions not met

These errors may still be fatal depending on how they are handled.

RecoveryService

The RecoveryService is responsible for routing exceptions to handlers.

Responsibilities:

  • Subscribes to ExceptionEvent

  • Enforces TaviError-only participation

  • Routes exceptions by exact type

  • Fails fast when no handler is registered

Registration

recovery.register(MyErrorType, handler)

Constraints:

  • One handler per exception type

  • Exact type matching (no inheritance traversal)

  • Handler decides severity and outcome

Dispatch Semantics

When an exception event is published:

  1. The exception is extracted

  2. A handler is resolved

  3. The handler executes

  4. Outcome is entirely handler-defined

No assumptions are made by the recovery system about fatality, retries, or UI.

ErrorPresenter (Frontend Orchestration)

The ErrorPresenter is the frontend implementation of error handling policy.

Responsibilities:

  • Registering handlers with RecoveryService

  • Translating exceptions into UI actions

  • Logging errors

  • Determining whether the application continues or halts

Current Behavior

Currently, the presenter registers handling for NonRecoverableError and:

  • Logs the error

  • Displays a critical dialog

  • Stops the current workflow

Future Recoverable Workflow Example

A recoverable flow may:

  1. Intercept a RecoverableError

  2. Execute additional orchestration

  3. Resume the original operation

  4. Escalate to fatal if recovery fails

Design Characteristics

  • Event-driven and synchronous

  • Centralized policy definition

  • Explicit handler registration

  • Clear separation of domain errors and UX decisions