Define Core Constant Abstraction Layer for Framework Boundaries

[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 currently lacks a unified and structured way of defining system-level constants such as:

• integer boundaries
• memory limits
• numeric precision constraints
• system-level configuration boundaries

Constants are currently either scattered or implicitly defined inside implementation logic, which violates Core clarity and DDD separation principles.

Architectural Decision

Introduce a dedicated Core Constants Layer under FireHub\Core\Constant.

Constants must be:

• grouped by domain responsibility (System, Memory, Numeric, String, etc.)
• immutable and stateless
• explicitly namespaced
• never mixed with Value Objects or runtime logic

Example structure:

FireHub\Core\Constant\System\IntegerLimits
FireHub\Core\Constant\Memory\MemoryLimits
FireHub\Core\Constant\Numeric\NumericLimits

Rationale

• Ensures clear separation between static system rules and runtime logic
• Improves discoverability of framework-level constraints
• Prevents duplication of magic numbers across Core modules
• Provides stable contract layer for Runtime, Adapter, and Capability packages
• Aligns with DDD principles by isolating domain constraints at framework level

System Boundaries

INCLUDED:

• System-level constants (limits, boundaries, constraints)
• Namespaced constant classes
• Domain-grouped constant definitions

EXCLUDED:

• Any runtime logic or computation
• Value Objects (e.g. Code VO)
• Exception handling logic
• Infrastructure configuration
• Adapter-specific constants (HTTP, Console, etc.)

Rejected Alternatives

• Global PHP constants: rejected due to namespace pollution and lack of structure
• Enums for constants: rejected due to semantic misuse (enums represent state, not static system limits)
• Embedding constants inside Value Objects: rejected due to mixing immutable state with system rules
• Distributed constants across modules: rejected due to lack of discoverability and maintainability

Impact Analysis

Core Impact:

• Introduces new structural layer in Core namespace
• Improves clarity of system-level constraints

Runtime Impact:

• No immediate runtime changes required
• Future runtime logic may rely on these constants

Adapter Impact:

• No direct impact

Capability Impact:

• May use constants for validation thresholds and limits

Backwards Compatibility:

• Fully backward compatible (no breaking changes)

Future Extensions:

• Extension into Memory, Numeric, and System constraint domains
• Potential introduction of typed limit groups

Implementation Guidelines

• All constants must be final classes with public const values
• No logic or methods inside constant classes
• Classes must be grouped by domain responsibility
• No mixing of runtime behavior and constant definitions
• Naming must reflect domain meaning, not implementation details

Follow-up Work

• Introduce MemoryLimits constant group
• Introduce NumericPrecision constants
• Refactor existing magic numbers in Core into Constant layer
• Document Constant layer in Core architecture docs

Additional Context

This architecture aligns with FireHub Core principle:
"Core defines truth, Runtime executes truth."

Constants represent immutable system truth and therefore belong in Core layer.