Define Core Error & Exception Abstraction Layer

[dieselxxx]

Affected Version

v0.0.0

Pre-check

• I understand this is a final or near-final architectural decision, not an open discussion
• I have reviewed existing architecture decisions, RFCs, and related issues

Context

FireHub Core-Standard is introducing a foundational error handling abstraction layer that will define how all failures, exceptions, and system-level errors are represented across the entire FireHub ecosystem.

This includes Core, Runtime Foundation, Adapters, Capabilities, and Testing infrastructure.

The goal is to introduce a unified and consistent error model that is independent of direct PHP internal exception usage.

Architectural Decision

Introduce a dedicated error handling namespace within Core:

FireHub\Core\Error

containing two primary abstract base classes:

• FireHub\Core\Error\Error
• FireHub\Core\Error\Exception

These classes define the FireHub-native abstraction over PHP's internal Error and Exception hierarchy.

All framework-level errors and exceptions MUST extend these base classes instead of using PHP native \Error or \Exception directly.

Rationale

• Ensures consistent error handling semantics across all FireHub layers
• Decouples framework logic from PHP internal Throwable hierarchy
• Enables future extension into structured error classification (Domain, Runtime, System, Validation)
• Improves observability and testability of failure states
• Establishes a clear contract for how failures propagate through Core, Runtime, and Adapters

System Boundaries

INCLUDED:

• Base abstractions for FireHub error handling
• Core definitions of Error and Exception types
• Contract for all framework-level failure states

EXCLUDED:

• Runtime-specific error handling strategies (handled in Runtime Foundation)
• Adapter-specific error mapping (HTTP, Console, etc.)
• Business/domain-specific exceptions (handled in higher-level packages or applications)
• Direct usage of PHP \Error and \Exception inside framework code

Rejected Alternatives

• Using only PHP native \Exception and \Error directly → rejected due to lack of framework-level abstraction and future extensibility limitations
• Single unified Exception class only → rejected because it hides system-level vs domain-level error semantics
• Using Core\Throwable namespace → rejected due to naming collision with PHP's Throwable interface and conceptual ambiguity

Impact Analysis

Core:

• Introduces foundational error abstraction layer

Runtime:

• Will adopt FireHub error hierarchy for execution failures

Adapters:

• Will map external errors into FireHub Error/Exception types

Capabilities:

• Will use structured exception handling for feature extensions

Backwards Compatibility:

• No impact on existing runtime systems (initial introduction phase)
• Future enforcement may deprecate direct PHP Throwable usage

Implementation Guidelines

• All framework-level failures MUST extend FireHub\Core\Error\Error or Exception
• Direct usage of \Throwable types in Core is discouraged
• Error types must be semantically separated (system vs domain vs runtime in future evolution)
• This layer must remain independent of Runtime and Adapter implementations
• No business logic should be placed in Core error classes

Follow-up Work

• Introduce DomainException, ValidationException, RuntimeException subclasses
• Integrate guard()/require() helpers with Exception layer
• Add PHPStan rules enforcing FireHub error hierarchy usage
• Migrate Core components to new error abstraction layer

Additional Context

FireHub Core-Standard repository: https://github.com/The-FireHub-Project/Core-Standard
Related architecture discussion: FireHub layered model (Core / Runtime / Adapter / Capability)