Introduce Core Constant Abstraction Layer for Framework Boundaries

[dieselxxx]

🧱 System Design / Architecture Pull Request

Related Issue

• Link the issue(s) this PR addresses:
  Closes Define Core Constant Abstraction Layer for Framework Boundaries #9

Description

• A Core Constants Layer is being introduced inside FireHub\Core\Constant to centralize all system-level constants (limits, boundaries, and framework invariants).

• This architectural decision defines a strict rule that all system-level constants must be:

  • namespaced
  • domain-grouped (System, Memory, Numeric, etc.)
  • immutable
  • isolated from runtime logic and Value Objects

• This architecture is required to eliminate scattered magic values across the Core layer and to establish a single source of truth for framework-level constraints. It improves discoverability, consistency, and long-term maintainability of system boundaries within FireHub.

• Affected parts of the ecosystem:

  • Core: introduces new Constant namespace and structure
  • Runtime: may consume constants for validation and execution rules (no direct structural changes required)
  • Adapter: no direct impact, but may reference constants for integration constraints
  • Capability: may use constants for enforcing feature-level limits and thresholds

Architecture Overview

System Design

• Describe the architecture being introduced or enforced:
  • Core structure:
  • Contracts:
  • Boundaries:
  • Dependencies:

Design Decisions

• Key architectural decisions made:
  • ...
• Why these decisions were chosen:
  • ...
• Rejected alternatives (if applicable):
  • ...

System Boundaries

Included

• What is part of this architecture:
  • ...

Excluded

• What is explicitly NOT part of this architecture:
  • Runtime logic
  • Infrastructure concerns (if applicable)
  • Adapters / external integrations (if applicable)

Implementation

Core Changes

• Files / modules introduced or modified:
  • ...

Contracts

• New or updated Core contracts:
  • ValueObjects:
  • Exceptions:
  • Interfaces:

Dependencies

• New dependencies introduced:
  • ...
• Impact on existing packages:
  • core-standard
  • core-professional
  • core-enterprise

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

• Impact on Core contracts:
  • ...

Runtime Impact

• Required runtime changes:
  • ...

Future Extensions

• How this architecture enables future development:
  • ...

Risks / Constraints

Risk Level

• None
• Low
• Medium
• High

Potential Risks

• Architecture lock-in:
  • ...
• Breaking changes for downstream packages:
  • ...
• Over-abstraction risks:
  • ...

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

• ...

Future Work

• Feature issues derived from this architecture:
  • ...

Reviewer Guidance

• Focus on:
  • architectural correctness
  • boundary enforcement
  • long-term scalability

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!