Introduce Core Value Object System

[danijelgalic]

🧱 System Design / Architecture Pull Request

Related Issue

• Link the issue(s) this PR addresses:
  Closes Core Value Object System #1

Description

This pull request implements the Core Value Object System, establishing it as the foundational data abstraction layer within the FireHub Core architecture.

The design introduces immutable, identity-less Value Objects as a strict Core contract, ensuring that domain representation is separated from runtime execution concerns. This enforces a clear architectural boundary where Core defines the structure and semantics of data, while Runtime and higher layers are limited to consumption without modification of these contracts.

This architecture is required to provide a consistent, type-safe, and predictable foundation for all subsequent Core-level systems, including Throwable handling, Type representation, and Identifier modeling. It eliminates primitive-driven design and ensures that all higher-level abstractions are built on explicit, strongly-defined value semantics.

The Core layer is directly affected by this change, as it defines the Value Object system itself. Runtime systems will depend on and consume these abstractions but must not extend or redefine them. Adapter and Capability layers remain structurally unaffected, as they operate above the Core contract boundary.

Architecture Overview

System Design

• Core structure:
  → Abstract ValueObject base class defines immutable contract and equality rules.
• Contracts:
  → ValueObject equality contract (class + value comparison)
  → Immutability contract (constructor-only state)
• Boundaries:
  → Core defines Value Objects
  → Runtime consumes Value Objects only
  → No infrastructure or execution logic inside Core VO layer
• Dependencies:
  → PHP native types only
  → No dependency on Runtime, Adapter, or external services

Design Decisions

• Key architectural decisions made:

  • Value Objects are identity-less and purely value-based abstractions
  • Equality is strictly structural (class + value)
  • All Value Objects must be immutable by design
  • Core layer owns definition; Runtime layer only consumes

• Why these decisions were chosen:

  • Ensures strong domain modeling aligned with DDD principles
  • Eliminates primitive obsession across the framework
  • Guarantees predictable behavior across Core/Pro/Enterprise layers
  • Prevents coupling between Core and Runtime execution logic

• Rejected alternatives (if applicable):

  • Using primitives (int/string) directly → rejected due to lack of semantic safety
  • No base ValueObject abstraction → rejected due to inconsistent behavior across VO implementations
  • Runtime-owned Value Objects → rejected due to architectural layering violation

System Boundaries

Included

• Abstract ValueObject base class
• Equality and immutability rules
• Core Value Object implementations (initial set)
• Core-level validation rules for VO integrity

Excluded

• Runtime execution logic
• DI container or kernel systems
• Adapter implementations (HTTP, Console, etc.)
• Infrastructure concerns (database, IO, filesystem)
• Builders / factories (handled in separate systems)

Implementation

Core Changes

• Files / modules introduced or modified:
  • FireHub\Core\Type\ValueObject (abstract base)
  • Supporting equality / guard logic inside Core layer

Contracts

• New or updated Core contracts:
  • ValueObjects:
    → ValueObject (base abstraction)
  • Exceptions:
    → None in this PR (handled in Throwable system)
  • Interfaces:
    → Optional internal contracts for future VO extensions

Dependencies

• New dependencies introduced:
  • None (pure Core layer implementation)
• Impact on existing packages:
  • core-standard → introduces foundational type system
  • core-professional → will extend and compose Core VOs
  • core-enterprise → will depend on stable Core VO 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

• Establishes foundational abstraction layer for all Core data modeling
• Introduces strict immutability and equality rules across system

Runtime Impact

• Runtime systems will consume Value Objects but must not define or modify them
• Prepares contract boundary for future Runtime Foundation packagea

Future Extensions

• Enables Throwable system (Code VO dependency)
• Enables Type system (framework-level abstraction)
• Enables Identifier system (identity modeling across layers)

Risks / Constraints

Risk Level

• None
• Low
• Medium
• High

Potential Risks

• Architecture lock-in:
  → Early design decisions may require careful evolution before v1.0.0 stabilization
• Breaking changes for downstream packages:
  → Minimal in v0 phase but must be carefully versioned before v1
• Over-abstraction risks:
  → Risk of introducing unnecessary VO complexity too early

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

• Value Object System is intentionally minimal in v0 phase to allow safe evolution before v1.0.0 lock.

Future Work

• Feature: Implement full ValueObject base API enhancements
• Feature: Add Type Value Object
• Feature: Add Identifier Value Object
• Architecture: Throwable System (depends on Code VO)

Reviewer Guidance

• Focus on:
  • correctness of Core/Runtime boundary
  • immutability guarantees
  • long-term extensibility of VO system