&labelColor=31373e)
-
+
&labelColor=31373e)
-
+
Development Branch
+## Core Value Object System – Development Branch
-⚠️ **This is the `develop` branch**
+⚠️ **This is the `development` branch**
- Unstable
- APIs may change without notice
- Not intended for production use
+### Related
+
+- Milestone: **Development v1**
+- Target Release: **v0.0.0**
+- Repository: FireHub Core Standard
+
+### Pull request
+
+
+
+### Milestone
+
+
+
+ 
Branch Purpose
-The `develop` branch is the **primary integration branch** for all ongoing development.
+This branch defines the **Core Value Object System** for the FireHub ecosystem.
-It serves as the staging area where:
-- Feature branches are merged
-- Bug fixes are integrated
-- Experimental work is stabilized
-- Code is prepared for upcoming releases
+It establishes the foundational rules for how immutable, strongly typed data structures are represented across:
-All **release branches** are created **from `develop`**.
+- Core Standard
+- Core Professional
+- Core Enterprise
+- Runtime Foundation (consumers only)
-## Stability Guarantee
+## Architectural Goal
-❌ No backward compatibility guarantee
-❌ APIs may change without notice
-❌ Behavior may be incomplete or inconsistent
-❌ Breaking changes are expected
+Introduce a **unified Value Object model** that:
-This branch is intended **only for contributors and advanced testers**.
+- Eliminates primitive obsession
+- Enforces immutability by design
+- Provides consistent equality semantics
+- Acts as a base language construct for the FireHub Core
-## Composer Usage (Not Recommended)
+## Core Concept
-For internal testing only:
+A Value Object in FireHub is:
-```json
-{
- "require": {
- "the-firehub-project/core-standard": "dev-develop"
- }
-}
-```
-⚠️ Never use dev-develop in production.
+> An immutable, identity-less object defined entirely by its value.
## Authors and Contributors
diff --git a/src/type/firehub.ValueObject.php b/src/type/firehub.ValueObject.php
new file mode 100644
index 0000000..617c680
--- /dev/null
+++ b/src/type/firehub.ValueObject.php
@@ -0,0 +1,101 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.2
+ * @package Core
+ */
+
+namespace FireHub\Core\Type;
+
+/**
+ * ### Base Value Object
+ *
+ * Defines the base abstraction for all Value Objects within the FireHub Core ecosystem.
+ *
+ * The ValueObject serves as a fundamental immutable contract for representing identity-less data structures based
+ * purely on their value semantics. It enforces consistency across the system by ensuring that all derived Value Objects
+ * follow strict immutability rules and structural equality behavior.
+ * @since 1.0.0
+ *
+ * @template TValue
+ */
+abstract readonly class ValueObject {
+
+ /**
+ * ### Returns the raw value of the Value Object
+ *
+ * Provides the underlying scalar or composite value represented by this Value Object.
+ *
+ * This value is used for structural comparison and domain-level equality checks.
+ * @since 1.0.0
+ *
+ * @return TValue Raw VO value.
+ */
+ abstract public function value ():mixed;
+
+ /**
+ * ### Determines structural equality between two Value Objects
+ *
+ * Compares this Value Object with another instance of the same type using strict
+ * class comparison and value equality semantics.
+ * @since 1.0.0
+ *
+ * @uses \FireHub\Core\Type\ValueObject::sameAs() To compare the VO types.
+ * @uses \FireHub\Core\Type\ValueObject::value() To compare the VO values.
+ *
+ * @param self+ * The Value Object to compare against. + *
+ * + * @return bool True if the VOs are equal, false otherwise. + */ + final public function equals (self $other):bool { + + return $this->sameAs($other) + && $this->value() === $other->value(); + + } + + /** + * ### Checks strict identity equality of a Value Object type + * + * Ensures both objects are of the same concrete class without comparing values. + * @since 1.0.0 + * + * @param \FireHub\Core\Type\ValueObject+ * The Value Object to compare against. + *
+ * + * @return bool True if the objects are of the same type, false otherwise. + */ + final public function sameAs (self $other):bool { + + return static::class === $other::class; + + } + + /** + * ### Enforces an invariant condition for the Value Object + * @since 1.0.0 + * + * @param callable():bool $condition+ * The validation condition to evaluate. + *
+ * @param callable():\Exception $exception+ * Exception to be thrown when the condition fails. + *
+ * @return void + */ + final protected function guard (callable $condition, callable $exception):void { + + if ($condition() === false) throw $exception(); + + } + +} \ No newline at end of file
