Introduce Error and Exception base abstractions

[dieselxxx]

🧱 System Design / Architecture Pull Request

Related Issue

• Link the issue(s) this PR addresses:
  Closes Define Core Error & Exception Abstraction Layer #7

Description

• What architectural decision is being implemented?

  • This PR introduces a unified FireHub-native error and exception abstraction layer inside FireHub\Core\Error, defining two base classes: Error and Exception as the foundational contract for all framework-level failures.

• What system boundary or rule is being defined?

  • It establishes a strict architectural rule that all FireHub Core components MUST use FireHub-defined error abstractions instead of directly using PHP native \Error, \Exception, or generic \Throwable types.
  • It also defines a clear separation between system-level failures (Error) and runtime/domain-level failures (Exception).

• Why is this architecture required?

  • To decouple FireHub Core from PHP internal throwable hierarchy and create a consistent, framework-owned error model.
  • To ensure predictable error semantics across all layers of the ecosystem.
  • To enable future extensibility into structured error classification (Domain, Runtime, System, Validation).
  • To improve testability and enforceable architectural contracts across Core and dependent packages.

• What parts of Core / Runtime / Adapter / Capability are affected?

  • Core: Introduces the foundational error abstraction layer used by all core components.
  • Runtime: Will adopt this model for execution-time failures and runtime boundary handling.
  • Adapter: Will map external system/transport errors (HTTP, CLI, etc.) into FireHub error types.
  • Capability: Will use structured exceptions for feature-level failure handling and extension logic.

Architecture Overview

System Design

Introduces a foundational exception hierarchy for the FireHub Core layer. The architecture establishes a common base abstraction for all framework-defined exceptions and provides semantic categories for domain, runtime, and security concerns.

Design Decisions

Key architectural decisions made

• Introduce FireHubException as the single root exception abstraction.

• Categorize exceptions by responsibility:

  • Domain
  • Runtime
  • Security

• Allow specialized exceptions to extend semantic categories.

• Integrate future support for strongly typed error codes through the Code Value Object.

Why these decisions were chosen

• Establishes a consistent exception model across the FireHub ecosystem.
• Provides clear separation of failure categories.
• Enables future Runtime, Adapter, and Capability packages to build upon stable exception contracts.
• Avoids direct dependency on framework-external exception hierarchies.

Rejected alternatives

• Introducing a parallel FireHubError hierarchy.
• Using only PHP native exceptions without framework abstractions.
• Creating highly granular exception types at the Core level.
• Introducing exception factories or infrastructure-specific exceptions within Core.

System Boundaries

Included

• Exception contracts and hierarchy definitions.
• Framework-level exception categorization.
• Value Object validation exception support.
• Future extension points for error codes and exception metadata.

Excluded

• Runtime logic.
• Infrastructure concerns.
• Adapters and external integrations.
• HTTP-specific exceptions.
• Persistence-specific exceptions.
• Logging and monitoring concerns.
• Exception handling policies.

Implementation

Core Changes

Files / modules introduced or modified

• FireHub\Core\Exception\FireHubException
• FireHub\Core\Exception\DomainException
• FireHub\Core\Exception\RuntimeException
• FireHub\Core\Exception\SecurityException
• FireHub\Core\Exception\Domain\ValidationException
• FireHub\Core\Exception\Runtime\SystemException
• FireHub\Core\Exception\Runtime\InvariantException
• FireHub\Core\Exception\Code

Contracts

ValueObjects

• Code

Exceptions

• FireHubException
• DomainException
• RuntimeException
• SecurityException
• ValidationException
• SystemException
• InvariantException

Interfaces

• None

Dependencies

New dependencies introduced

• None

Impact on existing packages

• core-standard: Introduces foundational exception contracts.
• core-professional: May extend the hierarchy with advanced exception types.
• core-enterprise: May build enterprise-specific exception strategies on top of these contracts.

Validation

Architecture Compliance

• Matches defined Architecture issue
• No violation of Core / Runtime separation
• No unintended business logic introduced
• No infrastructure logic inside Core

Build & Stability

• Project builds successfully
• No breaking changes (or properly documented)
• Backward compatibility considered

Impact Analysis

Core Impact

Introduces the first standardized exception model for the FireHub ecosystem and establishes a stable contract for future framework extensions.

Runtime Impact

None immediately required. Runtime implementations may gradually migrate to the new exception hierarchy.

Future Extensions

• Standardized exception handling across all FireHub packages.
• Strongly typed error code support.
• Consistent error propagation mechanisms.
• Framework-wide exception categorization.
• Future adapter-level exception mapping.

Risks / Constraints

Risk Level

• None
• Low
• Medium
• High

Potential Risks

Architecture lock-in

Low. The hierarchy remains intentionally small and extensible.

Breaking changes for downstream packages

Minimal. Existing implementations may continue using native PHP exceptions until migration is desired.

Over-abstraction risks

Mitigated by limiting the number of exception categories introduced in Core.

Documentation

• Architecture documented in repository / docs
• Design decisions explained
• Examples provided (if applicable)
• Migration notes are added (if needed)

Checklist

• Architecture issue linked
• System boundaries are clearly defined
• Core/Runtime separation respected
• No experimental or temporary code included
• Implementation matches architectural design
• Reviewed for long-term maintainability

Notes

Technical Notes

This architecture intentionally relies on PHP's native Error hierarchy and introduces only framework-specific exception abstractions. Core remains responsible for contracts and categorization, while Runtime remains responsible for exception handling behavior.

Future Work

• Introduce framework-wide error code catalog.
• Add additional domain-specific exception types.
• Add adapter-level exception mapping strategies.
• Introduce structured exception metadata support.
• Introduce serialization contracts for exceptions.

Reviewer Guidance

• Focus on:
  • Architectural correctness.
  • Boundary enforcement.
  • Exception hierarchy design.
  • Future extensibility.
  • Long-term maintainability.

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment

Thanks for integrating Codecov - We've got you covered ☂️