Core Value Object System

[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

This issue defines the foundational Value Object System for FireHub Core.
Value Objects are the base semantic building blocks of the framework and are used across Core, Professional, and Enterprise layers.

Architectural Decision

FireHub Core will implement a strict Value Object system based on the following rules:

• A single abstract ValueObject base class will define the contract for all Value Objects.
• Value Objects must be immutable and state-representative only.
• Equality is determined by value comparison and class type.
• Each Value Object must explicitly define its underlying scalar or structured value.
• Core Value Objects must not depend on Runtime, Adapter, or Capability layers.

Rationale

The Value Object System is introduced to enforce strict type safety, immutability, and semantic clarity across the FireHub ecosystem.

It eliminates primitive obsession and ensures consistent data representation across Core, Runtime, and higher-level packages.

This design supports:

• Domain-driven design principles
• Strong type safety across layers
• Predictable equality and comparison logic
• A unified framework language model

System Boundaries

INCLUDED:

• Abstract ValueObject base class
• Equality and immutability contracts
• Core-level validation rules

EXCLUDED:

• Runtime execution logic
• Exception handling strategies
• Factories, builders, and service containers
• UUID generation or infrastructure identifiers
• Any adapter or I/O layer concerns

Rejected Alternatives

1. Using primitive types (int, string) directly:
   Rejected due to lack of semantic clarity and type safety.

2. Using separate ValueObject implementations per domain without a base class:
   Rejected due to inconsistent behavior and duplication of equality logic.

3. Using PHP built-in types with validation layers:
   Rejected because validation alone does not enforce semantic guarantees.

4. Making Value Objects part of Runtime layer:
   Rejected because they represent Core language constructs, not execution logic.

Impact Analysis

Core Impact:

• Establishes foundational type system for all Core modules
• Introduces strict immutability and equality rules

Runtime Impact:

• Runtime systems will consume Value Objects but must not define them

Adapters Impact:

• No direct dependency changes, but input/output mapping will use Value Objects

Future Impact:

• Enables consistent domain modeling across Pro and Enterprise layers

Backwards Compatibility:

• N/A (initial Core architecture definition)

Implementation Guidelines

• All Value Objects must be immutable
• No Value Object may depend on Runtime or infrastructure layers
• Equality must always include class type comparison
• All Value Objects must expose a single canonical value representation
• No side effects allowed in constructors

Follow-up Work

• Feature: Implement ValueObject base class
• Feature: Implement Code Value Object
• Architecture: Core Throwable Model (Exception & Error System)
• Feature: Implement Type Value Object (maybe in future)
• Feature: Implement Identifier Value Object (maybe in future)

Additional Context

No response