arch: Standardized error classification across all bridges

[bbopen]

Overview

Multiple issues relate to inconsistent error handling and classification across bridges. This tracking issue proposes standardized error handling.

Related Issues

• HttpBridge should handle JSON.stringify failures with BridgeProtocolError #120 - HttpBridge should handle JSON.stringify failures with BridgeProtocolError
• HttpBridge should classify timeouts and protocol errors with Bridge* errors #118 - HttpBridge should classify timeouts and protocol errors with Bridge* errors
• Map Python ProtocolError responses to BridgeProtocolError #94 - Map Python ProtocolError responses to BridgeProtocolError
• HTTP runtime should handle error payloads, timeouts, and invalid JSON explicitly #56 - HTTP runtime should handle error payloads, timeouts, and invalid JSON
• Instance handle lifecycle errors should be explicit #49 - Instance handle lifecycle errors should be explicit
• Validate protocol error payload shapes #47 - Validate protocol error payload shapes

Proposed Architecture

Error Hierarchy

BridgeError (base)
├── BridgeProtocolError    - Invalid protocol, malformed responses
├── BridgeTimeoutError     - Request timeouts
├── BridgeDisposedError    - Operations after dispose
├── BridgeSerializationError - JSON.stringify/parse failures (NEW)
└── BridgeInstanceError    - Instance handle lifecycle errors (NEW)

Error Factory Functions

// src/runtime/errors.ts
export function createProtocolError(message: string, cause?: unknown): BridgeProtocolError {
  return new BridgeProtocolError(message, { cause });
}

export function createTimeoutError(operation: string, timeoutMs: number): BridgeTimeoutError {
  return new BridgeTimeoutError(`${operation} timed out after ${timeoutMs}ms`);
}

export function createSerializationError(direction: 'request' | 'response', cause: unknown): BridgeSerializationError {
  return new BridgeSerializationError(`Failed to serialize ${direction}`, { cause });
}

export function normalizeError(error: unknown): BridgeError {
  if (error instanceof BridgeError) return error;
  // Map Python ProtocolError, timeouts, etc.
}

Python-side Error Mapping

# Map Python exceptions to protocol error types
ERROR_TYPE_MAP = {
    'ProtocolError': 'protocol',
    'TimeoutError': 'timeout',
    'ValueError': 'validation',
}

Acceptance Criteria

• All bridges use consistent Bridge* error types
• JSON serialization failures throw BridgeSerializationError
• Timeouts throw BridgeTimeoutError with duration info
• Python ProtocolError maps to BridgeProtocolError
• Instance handle errors are explicit
• Protocol error payloads are validated
• All 6 related issues can be closed

Scope

This fix touches:

• src/runtime/errors.ts - new error types and factories
• src/runtime/node.ts - error normalization
• src/runtime/http.ts - error classification
• src/runtime/pyodide.ts - error classification
• runtime/python_bridge.py - error type mapping

[bbopen]

Superseded by #149

This issue is addressed by the unified BoundedContext abstraction proposed in #149.

The error classification concerns here will be implemented via:

• classifyError(error) method that maps all errors to appropriate Bridge* types
• Automatic classification based on error message patterns and context state
• Consistent error types across all bridges (NodeBridge, PyodideBridge, HttpBridge)

The base class handles: BridgeDisposedError, BridgeTimeoutError, BridgeProtocolError, BridgeExecutionError.

[bbopen]

Resolved by PR #150 (BoundedContext implementation).

Standardized error classification is now available via BoundedContext.classifyError():

• Timeout patterns → BridgeTimeoutError
• Protocol patterns → BridgeProtocolError
• Disposed state → BridgeDisposedError
• Unknown errors → BridgeExecutionError
• Original error preserved as cause

Verified by test suite in PR #151.