Conversation
… introduce Core/Foundation concepts **Details:** - Updated all badge links, URLs, and branch references in `README.md` to align with the new `architecture/foundation-support` branch. - Introduced detailed descriptions of Core/Foundation architectural layers, including dependency direction and separation of development responsibilities (Core → Foundation → Runtime). - Added milestones and pull request metadata to improve visibility of ongoing development efforts. - Expanded documentation to clarify goals for the Core layer: define stable architectural contracts while delegating developer-facing APIs to the Foundation layer. - Removed outdated or redundant sections for improved clarity and relevance. This update improves the consistency, readability, and alignment of the README with the FireHub project's evolving architecture and development practices.
dieselxxx
added
the
type: Architecture
2 tasks
2 tasks
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
dieselxxx
changed the title
architecture/foundation-support branch and…**Details:** - Introduced an abstract `Str` class in `Core-Standard/src/Type/Str.php` to define the foundational string-based Value Object type within the FireHub ecosystem. - Implements immutable string value semantics while serving as the base for domain-specific string extensions in higher-level layers (e.g., Foundation). - Provides a clear contract for string handling with its abstract `value(): string` method. - Aligns with the Core layer's goal of ensuring stable architectural contracts and PHP compatibility (`>=8.2`). This addition enhances the modularity and type safety of Core string operations, ensuring future extensibility and clear separation of responsibilities.
…h encoding support **Details:** - Added `Str::encoding()` and `Str::withEncoding()` methods in `Core-Standard/src/Type/Str.php` to provide string encoding introspection and mutation via an `Encoding` value object. Improves versatility for handling internationalization and character encoding scenarios. - Updated `ValueObject::equals()` in `Core-Standard/src/Type/ValueObject.php` to utilize `comparisonValue()` for equality checks, ensuring consistency in comparison logic across all Value Object subclasses. - Introduced protected `comparisonValue()` method in `ValueObject` to centralize comparison logic by delegating to the underlying value representation. - Adjusted `@uses` annotations in `ValueObject` doc comments for better clarity and alignment with new comparison logic. These updates enhance both the flexibility of the `Str` class for encoding management and the reliability of `ValueObject` comparison semantics, contributing to a more robust Core layer architecture.
**Details:** - Extended `Str` base Value Object to implement PHP's native `Stringable` interface, ensuring compatibility with type hints requiring `Stringable` in PHP `>=8.0`. - Introduced the `__toString()` method in `Str` to provide a native string representation of its value. This method utilizes `value()` for consistent output. - Updated class imports and doc comments to reflect the addition of the `Stringable` dependency and enhanced functionality. These changes enhance the interoperability of the `Str` class with both internal and external PHP components, improving compatibility and usability within the FireHub ecosystem.
…d `Char` type **Details:** - Extracted encoding-aware functionality from `Str` into a new `StringValue` abstract class in `Core-Standard/src/Type/StringValue.php`, preserving the immutable string value semantics. - Updated `Str` in `Core-Standard/src/Type/Str.php` to extend `StringValue`, simplifying its structure for domain-specific usage and aligning with Core's modular architecture. - Added `Char` abstract class in `Core-Standard/src/Type/Char.php` to define the base for character-based Value Objects. Ensures support for handling single characters with encoding awareness. - Updated class hierarchy to establish clear separation of concerns between general `StringValue` contracts and domain-specific `Str` and `Char` implementations. These changes enhance the modularity and extensibility of the Core layer, simplifying future extensions and reinforcing separation of architectural responsibilities.
…ar` objects **Details:** - Introduced an abstract `toChars(): array` method in the `Str` class within `Core-Standard/src/Type/Str.php`. - Provides a mechanism to split the immutable string value into a list of `Char<non-empty-string>` objects. - Enhances the extensibility of the `Str` class for character-level operations, aligning with the FireHub ecosystem's focus on modularity and type safety. This update lays the groundwork for fine-grained string manipulations, improving support for encoding-aware scenarios and future extensions.
**Details:** - Introduced an abstract `Boolean` class in `Core-Standard/src/Type/Boolean.php` to define the foundational boolean-based Value Object type within the FireHub ecosystem. - Implements immutable boolean value semantics while serving as the base for domain-specific boolean extensions in higher-level layers (e.g., Foundation). - Provides a clear contract for boolean handling with its abstract `value(): bool` method. - Aligns with the Core layer's focus on defining stable architectural contracts and PHP type safety (`>=8.2`). This addition strengthens the modularity, type safety, and extensibility of the Core layer, ensuring clarity and consistency for boolean-related operations within the FireHub project.
**Details:** - Deleted the `Decimal` abstract class in `Core-Standard/src/Type/Number/Decimal.php`, initially designed as an immutable floating-point value object. - The removal reflects a decision to streamline numeric type abstractions, reducing redundancy while aligning Core's scope with clearer architectural priorities. - Cleans up unused functionality and simplifies the Core layer's numeric type hierarchy. This change eliminates unnecessary complexity, ensuring a leaner and more focused Core architecture within the FireHub ecosystem.
**Details:** - Introduced abstract `isTrue(): bool` and `isFalse(): bool` methods in the `Boolean` class within `Core-Standard/src/Type/Boolean.php`. - Provides explicit contracts for checking boolean value states, improving clarity and semantic expressiveness in boolean handling. - Reinforces the immutability and type safety principles of the `Boolean` Value Object, aligning with the FireHub Core's design philosophy. This update enhances the usability and readability of the `Boolean` base class while paving the way for consistent boolean state-checking operations.
**Details:** - Introduced an abstract `codepoint(): int` method in the `Char` class within `Core-Standard/src/Type/Char.php`. - Defines a contract for retrieving the Unicode code point of a character, returning a non-negative integer. - Enhances the extensibility of the `Char` class for character-level operations, aligning with the modular and type-safe design principles of the FireHub Core. This addition improves support for fine-grained character processing while maintaining the immutability and clarity of the `Char` Value Object.
…ar` contract **Details:** - Added a new `Codepoint` class (`Core-Standard/src/Type/Char/Codepoint.php`) to represent immutable Unicode code points, incorporating validation for valid scalar values within the range of U+0000 to U+10FFFF (excluding surrogates). - Created an `InvalidCodepointException` class for handling invalid Unicode code point scenarios. - Updated the `Char` class (`Core-Standard/src/Type/Char.php`) to return a `Codepoint` object through its `codepoint()` method, enhancing the type safety and extensibility of the `Char` Value Object. - Removed unnecessary `final` keyword from the `Code` class definition to ensure alignment with extensibility policies. These changes provide robust Unicode handling within the Core layer while reinforcing the immutability and clarity principles of value object design in the FireHub ecosystem.
**Details:** - Added `isPositive(): bool`, `isNegative(): bool`, and `isZero(): bool` methods to the `Number` base class in `Core-Standard/src/Type/Number.php` for checking numeric states. - Introduced abstract methods `isFinite(): bool`, `isInfinite(): bool`, and `isNaN(): bool` to the `Real` class in `Core-Standard/src/Type/Number/Real.php`. - Enhances the extensibility and semantic clarity of numeric value objects, ensuring robust type-safe contracts for numeric state evaluations in the FireHub Core. These enhancements align with the FireHub ecosystem's focus on immutability, clarity,
**Details:** - Introduced the `MutationOutcome` enum in `Core-Standard/src/Meta/Enum/MutationOutcome.php` to standardize results for create, update, remove, and not-found mutation operations. - Includes four cases: `CREATED`, `UPDATED`, `REMOVED`, and `NOT_FOUND`, with comprehensive PHPDoc annotations for clarity and consistency. - Targets PHP 8.1+ to align with modern language standards and enhance type safety. This addition provides a clear, extensible mechanism to represent mutation outcomes, promoting standardization and clarity across the FireHub Core ecosystem.
**Details:** - Introduced the `Iteration` interface in `Core-Standard/src/Boundary/Capability/Iteration.php` to define a contract for accessing an iterable sequence of values without dictating storage or traversal mechanisms. Includes the `iterate()` method for returning an iterable sequence. - Added the `Traversal` interface in `Core-Standard/src/Boundary/Capability/Traversal.php` to specify a traversal mechanism for iterable values with controlled semantics and an optional `$limit` parameter in the `traverse()` method. - Both interfaces are designed with PHP generics (`@template`) for type safety and extensibility. These additions establish foundational contracts for iterable value management, aligning with FireHub's principles of clarity, modularity, and type safety.
…ort` branch **Details:** - Updated branch references in the PHPStan, PHPUnit, and Codecov badges from `architecture/error-exception-base` to `architecture/foundation-support`. - Ensures that badges reflect the latest workflow and coverage for the active branch.
**Details:** - Added a new `module_meta` component to `.github/codecov.yaml` with a target coverage of 80%. - Configured paths to include `src/Meta/**` for code coverage tracking. - Aligns with the existing structure for modular coverage configuration in the Core-Standard repository.
…enhanced sequence manipulation
…urement in Core-Standard **Details:** - Introduced mutation interfaces: - `BackInsertion`, `BackRemoval`, `BackMutation` - `FrontInsertion`, `FrontRemoval`, `FrontMutation` - `DequeMutation`, `IndexMutation`, and `KeyMutation` These interfaces define contracts for mutating data at specific boundaries, by indices, or by keys while adhering to FireHub's principles of clarity and immutability. - Added access interfaces: - `IndexAccess`, `KeyAccess`, and `BoundaryAccess` These provide contracts for read-only access to values by index, by key, or at the front and back of sequences. - Added measurement interfaces: - `Metrics` and `Capacity` These define contracts for size metrics and bounded capacity awareness. These additions establish a robust framework for structured data access, manipulation, and measurement, fostering consistency and modularity across the FireHub Core ecosystem.
**Details:** - Updated `@extends` PHPDoc annotations in `BackMutation`, `FrontMutation`, and `DequeMutation` interfaces to reference `FireHub\Core\Boundary\Capability\Mutation` instead of `FireHub\Foundation\DataStructure\Storage\Capability`. - Ensures consistent namespace usage across Core-Standard components, aligning with the modular structure of the FireHub ecosystem.
…s for access and measurement **Details:** - Updated `Vector` interface: - Extended from `IndexAccess` to formalize positional access capabilities. - Enhanced PHPDoc annotations for clarity on vector semantics, including ordered, indexed access and value mutability independence. - Updated `Collection` interface: - Extended from `Metrics` to establish a contract for collection size measurement. - Refined PHPDoc to align with FireHub's modular conventions. These improvements ensure precise, consistent contracts for collections, enhancing clarity, extensibility, and modularity across the FireHub Core ecosystem.
…upport **Details:** - Updated `Vector` interface to extend `BoundaryAccess`, formalizing read-only access to boundary elements alongside existing `IndexAccess` capabilities. - Reflected the change in PHPDoc annotations for both `Vector` interface and its extended contracts. - Ensures consistency with FireHub's access capability interfaces, enhancing modularity and clarity in data structure semantics.
…ption` for absence handling **Details:** - Updated `Maybe` abstract type to include a `value()` method, enabling retrieval of the contained value. - Added `NoValueException` in `Core-Standard/src/Type/Exception/NoValueException.php` to handle attempts to access a value from a `Maybe` instance representing the absence of data. - Ensures clearer and more robust handling of optional values, adhering to FireHub's principles of immutability, type safety, and modern PHP standards.
… conversion contracts **Details:** - Introduced the `Arrayable` interface in `Core-Standard/src/Boundary/Capability/Conversion/Arrayable.php` to define a contract for converting objects to array representations via the `toArray()` method. - Added the `Jsonable` interface in `Core-Standard/src/Boundary/Capability/Conversion/Jsonable.php` to specify a contract for JSON conversion using the `toJson()` method. - Incorporated PHP generics (`@template`) in `Arrayable` for enhanced type safety in array key and value definitions. - Both interfaces emphasize clarity, modularity, and extensibility while adhering to FireHub's principles of modern PHP standards and ecosystem consistency. These additions establish foundational conversion contracts for object interoperability, ensuring seamless integration across the FireHub ecosystem.
**Details:** - Enhanced PHPDoc for the `set` method in `IndexMutation` to document the new `NOT_FOUND` outcome when the index does not exist. - Improves clarity and completeness of the mutation contract, aligning with FireHub's principles of robust and explicit documentation.
…instances **Details:** - Introduced the `Forkable` interface in `Core-Standard/src/Boundary/Capability/Forkable.php` to define a contract for creating independently mutable forks of instances via the `fork()` method. - Documented the contract's semantics, including initial state sharing, divergence through mutation, and copy-on-write strategies. - Enhances modularity and immutability principles in the FireHub Core ecosystem, providing a reusable mechanism for safe instance duplication.
…ce for double-ended collections **Details:** - Updated `Vector` interface to extend `Linear`, refining its classification as a linear data structure. - Added a new `Deque` interface to represent double-ended collections, supporting access to both front and back boundaries. - Documented `Deque`'s semantics, ensuring clarity on its linear, ordered, and boundary-accessible nature. These changes enhance the FireHub Core ecosystem with clearer data structure contracts, adhering to modularity and extensibility principles.
…in annotations **Details:** - Modified the `Deque` interface's PHPDoc to correctly extend `BoundaryAccess` instead of `IndexAccess`. - Ensures accurate documentation of the `Deque` interface, highlighting its focus on boundary-based access operations. - Aligns with FireHub's principles of clear, precise, and consistent type contracts.
**Details:** - Extracted `last()` into a new `BackAccess` interface to define back boundary access. - Extracted `first()` into a new `FrontAccess` interface to define front boundary access. - Updated `BoundaryAccess` to extend `FrontAccess` and `BackAccess` for modular composition. - Ensures clearer separation of concerns and enhanced flexibility in boundary access capabilities, adhering to FireHub's principles of modularity and extensibility.
**Details:** - Introduced the `Stack` interface for last-in, first-out collections with clear, annotated semantics about its linear structure and top-bound access. - Adjusted import ordering in `Vector` and `Deque` to align with FireHub's namespace conventions. - Enhances the Core ecosystem by extending modularity and clarifying type contracts for stack-based data structures.
…ions **Details:** - Introduced a new `Queue` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Queue.php` to define a contract for first-in, first-out (FIFO) linear collections. - Extended `Linear`, `Collection`, and `FrontAccess` interfaces to integrate linearity, collection semantics, and front-bound access capabilities. - Documented `Queue` semantics, emphasizing its ordered value preservation and deterministic front-access behavior. - Enhances the FireHub Core ecosystem with a modular, extensible type contract for FIFO-based data structures, adhering to the project's principles of clarity and robust design.
…ifications **Details:** - Introduced the `Unordered` interface to classify data structures without positional order semantics, documenting characteristics like membership testing, uniqueness, and multiplicity support. - Added the `Associative` interface to classify data structures that organize values by key-value association, emphasizing keyed access and mutation capabilities. - Both interfaces enhance the FireHub Core ecosystem by defining modular and extensible type contracts for structural classification while adhering to project standards of clarity and robust design.
…efactor generic type annotations across data structures **Details:** - Introduced the `Map` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Map.php` to describe associative collections maintaining key-value pairs. Documented its semantics with a focus on deterministic access via keys and constraints on key-value associations. - Updated generic type annotations in `Collection`, `Queue`, `Stack`, `Deque`, `Vector`, and `DataStructure` to include the `TKey` template parameter, enabling support for typed keys in collections. - Adjusted `Collection` to extend `DataStructure<TKey, TValue>` and `Enumerable<TKey, TValue>` for consistency in hierarchical type contracts. - Enhances the FireHub Core ecosystem by enabling clearer type safety, extensibility, and modularity while maintaining alignment with project principles of robust design and modern PHP standards.
…ntract **Details:** - Removed the `BoundaryAccess` import and inheritance from the `Map` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Map.php`. - Streamlined `Map` to focus solely on `KeyAccess` for key-based associative collections, aligning with its primary purpose. - Improves clarity and reduces unnecessary complexity in the `Map` interface, adhering to FireHub's principles of modularity and precise type contracts.
**Details:** - Eliminated the unnecessary `BoundaryAccess` inheritance from the `Map` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Map.php`. - Streamlines the `Map` contract to focus exclusively on `KeyAccess` for clarity and reduced complexity. - Enhances modularity and precision of type definitions, adhering to FireHub's principles of clear and robust design.
…tationOutcome` enum **Details:** - Introduced the `Set` interface in `Core-Standard/src/Boundary/Type/DataStructure/Collection/Set.php` to define a contract for unique value collections, documenting membership semantics and enforcing value equality without prescribing internal implementation. - Added the `ValueAccess` interface to provide a capability for membership testing, ensuring modularity in value retrieval operations. - Implemented the `ValueMutation` interface for value-based mutation capabilities, defining operations for adding and removing values with clear outcome semantics. - Extended the `MutationOutcome` enum to include the `ALREADY_EXISTS` case, enhancing mutation result granularity for operations like `add`. - Enhances the FireHub Core ecosystem by introducing modular and extensible core concepts, adhering to project principles of robust design, clarity, and modern PHP standards.
…tMetrics` interfaces for multiplicity and distinct value operations **Details:** - Introduced the `MultiplicityAccess` interface to provide multiplicity-based value access, enabling frequency counting of specific values in objects. - Added the `MultiplicityMutation` interface to define mutation operations, including adding, removing, and clearing occurrences of values. - Defined the `Bag` interface as an unordered data structure supporting multiple occurrences of logically equal values, integrating `MultiplicityAccess`, `Unordered`, and `Collection` capabilities. - Implemented the `DistinctMetrics` interface for measuring the count of distinct values in data structures. - These additions enrich the FireHub Core ecosystem with modularity, extensibility, and contracts for working with data structures that distinguish between occurrences and distinct values, adhering to project standards of robust design and modern PHP practices.
**Details:** - Updated the `add`, `remove`, and `removeAll` methods in `MultiplicityMutation` to return `MutationOutcome` instead of primitive types for consistent mutation results. - Enhanced method documentation with detailed descriptions of possible enum values (`CREATED`, `ALREADY_EXISTS`, `REMOVED`, `UPDATED`, `NOT_FOUND`) for precise outcome semantics. - Added a `use` statement for the `MutationOutcome` enum to improve code clarity and maintainability. - Aligns with FireHub Core's design principles of modern PHP practices, robust type safety, and meaningful return types.
**Details:** - Updated PHPDoc for the `add` method in `MultiplicityMutation` to replace the outcome `ALREADY_EXISTS` with `UPDATED` for scenarios where an existing value is updated with a new occurrence. - Aligns outcome terminology with the `MutationOutcome` enum semantics for greater precision and consistency in mutation operations.
**Details:** - Introduced the `Stream` interface in `Core-Standard/src/Boundary/Type/DataStructure/Stream.php` to define a contract for sequences of values that can be produced lazily and consumed incrementally. - Documented `Stream` characteristics, including support for finite, unbounded, or externally produced sequences without requiring full materialization in memory. - Extended `DataStructure` and `Enumerable` interfaces, specifying that a `Stream` does not guarantee reusable iteration, known size, or random access. - Enhances the FireHub Core ecosystem by enabling modular and extensible support for lazy and on-demand data streams, adhering to principles of clarity, robust design, and modern PHP practices.
…presentations **Details:** - Introduced the `Record` interface in `Core-Standard/src/Boundary/Type/DataStructure/Record.php` to define a contract for composite values made of logically related components, distinguishing it from collections. - Added the `Struct` interface in `Core-Standard/src/Boundary/Type/DataStructure/Record/Struct.php` to represent fixed-size keyed records with immutable key sets, extending `Record` and `KeyAccess`. - Implemented the `Tuple` interface in `Core-Standard/src/Boundary/Type/DataStructure/Record/Tuple.php` to define a fixed-size positional record with zero-based integer indexing, extending `Record`, `Linear`, and access-related interfaces. - Enhances the FireHub Core ecosystem by providing modular and extensible structures for logically grouped data, adhering to robust design and clarity principles.
**Details:** - Added the `Unordered` interface to the `Struct` contract in `Core-Standard/src/Boundary/Type/DataStructure/Record/Struct.php`, aligning its definition with unordered classification semantics. - Removed the redundant `Linear` inheritance from the `Tuple` interface in `Core-Standard/src/Boundary/Type/DataStructure/Record/Tuple.php` to simplify its type hierarchy. - Enhances the FireHub Core ecosystem by refining structural classifications and ensuring adherence to clear and robust design principles.
**Details:** - Eliminated the unnecessary `BoundaryAccess` import and inheritance from the `Tuple` interface in `Core-Standard/src/Boundary/Type/DataStructure/Record/Tuple.php`. - Streamlined the `Tuple` contract to focus solely on `IndexAccess` and other relevant classifications for fixed-size positional records. - Improves clarity and reduces complexity, aligning with FireHub's principles of modularity and precise type definitions.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🧱 System Design / Architecture Pull Request
Related Issue
Closes Introduce runtime foundation architectural support #12
Description
Define the architectural support required for the FireHub Foundation layer by introducing Core-level contracts for high-level abstractions.
Establish the system boundary between Core, Runtime, and Foundation:
This architecture is required to prevent Core components from depending directly on Foundation implementations while still allowing Core Value Objects, contracts, and framework components to reference fundamental high-level concepts.
The decision ensures that FireHub maintains a clean dependency direction:
Application
↓
Foundation
↓
Core Contracts
↑
Runtime
Affected Components
Core
Runtime
Foundation
Adapter
Capability
Architectural Rule
Core contracts MUST define only the minimum required behavior of an abstraction.
High-level APIs, fluent methods, transformations, and developer conveniences MUST remain in Foundation.
This separation allows FireHub to evolve Core, Runtime, and Foundation independently while preserving a stable architectural foundation.
Architecture Overview
System Design
Design Decisions
System Boundaries
Included
Excluded
Implementation
Core Changes
Contracts
Dependencies
Validation
Architecture Compliance
Build & Stability
Impact Analysis
Core Impact
Runtime Impact
Future Extensions
Risks / Constraints
Risk Level
Potential Risks
Documentation
Checklist
Notes
Technical Notes
Future Work
Reviewer Guidance